> ## 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

> Connect CLI to an AI agent skill so the agent can generate Typecast speech on demand.

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 theme={null}
# 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

```text theme={null}
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

<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>