Agent skill integration - Typecast Documentation

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.

Claude Skills integration

Use Typecast with Claude Skills and agent workflows.

CLI configuration

Set default voice, model, format, and environment variables.

​Skill instruction template

​Minimal command set

​Agent prompt pattern

​Capability routing

​Recommended safeguards