| name | long-task-voice-progress |
| description | Emit clear progress updates by default for most non-trivial tasks and speak milestone status. Use whenever work has multiple phases, may include long-running commands or tests, involves waiting on tools or agents, or benefits from hands-free audible status. |
| version | 1.0.0 |
| author | hbmartin |
| license | Apache-2.0 |
| metadata | {"hermes":{"tags":["Progress","Voice","Text-to-Speech","Notifications","UX"]}} |
| prerequisites | {"commands":["bash"]} |
Long Task Voice Progress
Overview
Emit concise milestone updates aligned to real execution state so progress reports stay trustworthy.
This skill is agent-agnostic: it works the same in Claude Code, Codex, and any
other agent that can run shell commands. Agent-specific tool names below are
examples — substitute whatever equivalent your agent provides.
Trigger Heuristics
Use this skill by default for non-trivial work, especially when any of the following are true:
- The task has
>=2 phases (for example: discovery, implementation, validation, completion).
- You are about to run commands or tests that may take
>30s.
- You are waiting on tools, background jobs, or sub-agents and progress may otherwise appear stalled.
Workflow
- Announce the interpreted task and first action.
- Announce each major phase transition (context, implementation, validation, completion).
- Announce blockers with the blocked step and immediate recovery action.
- When user input is required, emit a spoken "input needed" cue before prompting.
- Announce completion with what changed and what verification ran.
Mode Compatibility
This skill is valid in both direct-execution and planning collaboration modes.
- In direct-execution mode (Claude Code default mode, Codex
Default mode), ask the user directly when input is required.
- In planning mode (Claude Code Plan mode, Codex
Plan mode), use your agent's structured-input tool for choices when one is available (AskUserQuestion in Claude Code, request_user_input in Codex).
- In both modes, emit the same voice/text progress milestones.
Input Needed Cues
Whenever you need the user to decide or provide missing information:
- Announce the need first:
bash scripts/say-progress.sh "Input needed: choose deployment target"
- Then request the input using the active mode:
- Planning mode: call your agent's structured-input tool (
AskUserQuestion in Claude Code, request_user_input in Codex).
- Direct-execution mode: ask a concise direct question in chat.
- If waiting may exceed 60 seconds, emit a brief waiting update every 60 seconds.
Message Rules
- Keep spoken messages short (target under 18 words).
- Use present-tense action verbs and include the next concrete action.
- Mention concrete artifacts when relevant (
file, service, test suite, migration).
- Avoid filler or generic status text.
Invocation
Run the helper script via Bash to emit an audible progress update:
bash scripts/say-progress.sh "Starting test suite for auth module"
The script path is relative to this skill directory. Use the full path when invoking from elsewhere:
The script always emits a [progress] text line to stdout regardless of audio availability, so progress is visible even when muted or on a headless machine.
