The CLI works well inside agent skills because it exposes Typecast speech generation as a shell command. The agent can draft text, choose filenames, call cast, and return playable audio assets.
Skill instruction template
# Typecast speech skill
Use the CLI when the user asks for voiceover, narration, dialogue, or audio preview.
Rules:
- Never expose the API key.
- Prefer `--out` so generated audio is saved as a file.
- Use descriptive filenames.
- Use `--emotion smart` for natural narration.
- Use preset emotion when the user specifies a tone.
- Use `--timestamps-out` when the user asks for captions, subtitles, timing, or lip-sync.
- Use `cast voices clone` only when the user provides or approves a voice sample.
- Report the output path after generation.
Minimal command set
| Task | Command |
|---|---|
| Check authentication | cast "test" --out typecast-test.wav |
| Generate narration | cast "$(cat script.txt)" --emotion smart --out narration.wav |
| Generate MP3 | cast "$(cat script.txt)" --format mp3 --out narration.mp3 |
| Generate captions | cast "$(cat script.txt)" --out narration.wav --timestamps-out narration.srt |
| Pick a voice | cast voices pick |
| Clone a voice | cast voices clone sample.wav --name "Project Voice" |
| Save a default voice | cast config set voice-id tc_xxx |
Agent prompt pattern
Use the Typecast speech skill.
Create three voiceover takes from script.txt:
- neutral
- energetic
- soft
Save them under ./voiceover and tell me the filenames.
Capability routing
Teach the agent to choose the smallest CLI feature that satisfies the request:
| User asks for | Agent should use |
|---|---|
| "Say this out loud" | cast "..." without --out |
| "Make a voiceover file" | cast "$(cat script.txt)" --out narration.wav |
| "Make captions too" | Add --timestamps-out narration.srt |
| "I want this sample voice" | cast voices clone sample.wav --name ... then --voice-id uc_xxx |
| "Preview a few voices" | cast voices pick or cast voices tournament |
Recommended safeguards
Keep secrets out of prompts
Store the API key with cast login or TYPECAST_API_KEY. Do not paste the key into a shared prompt or generated document.
Use files for long scripts
Prefer cast "$(cat script.txt)" for scripts that are too long to safely quote in a single command.
Preserve approved takes
Tell the agent to create new filenames for revisions instead of overwriting audio that has already been reviewed.