> ## Documentation Index
> Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent skill integration

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

```markdown
# 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 `--timestamp-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 --timestamp-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

```text
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 `--timestamp-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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>
  <Accordion title="Use files for long scripts">
    Prefer `cast "$(cat script.txt)"` for scripts that are too long to safely quote in a single command.
  </Accordion>
  <Accordion title="Preserve approved takes">
    Tell the agent to create new filenames for revisions instead of overwriting audio that has already been reviewed.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Claude Skills integration" icon="wand-magic-sparkles" href="/integrations/claude-skills">
    Use Typecast with Claude Skills and agent workflows.
  </Card>
  <Card title="CLI configuration" icon="gear" href="/cli-reference/configuration">
    Set default voice, model, format, and environment variables.
  </Card>
</CardGroup>