| name | install |
| description | Install Kokoro TTS engine on Apple Silicon. TRIGGERS - install kokoro, setup tts, kokoro install, tts setup. |
| allowed-tools | Read, Bash, Glob, AskUserQuestion |
Prerequisite — cc-plugin-root. This skill resolves its scripts with cc-plugin-root <plugin>
(the CLAUDE_PLUGIN_ROOT placeholder is not a shell variable and expands to empty). If the command is missing, run
/itp:setup (its first step installs it), or link it directly:
mkdir -p ~/.local/bin && ln -sfn \
~/.claude/plugins/marketplaces/cc-skills/scripts/cc-plugin-root ~/.local/bin/cc-plugin-root
Install Kokoro TTS
Install the Kokoro TTS engine: Apple Silicon verification, Python 3.14 venv, MLX-Audio dependencies, model download, and verification synthesis.
Platform: macOS Apple Silicon (M1+) only. Fails fast on Intel/Linux.
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
Prerequisites
| Component | Required | Check |
|---|
| Apple Silicon | Yes | uname -m = arm64 |
| uv | Yes | uv --version |
| Python 3.14 | Yes | uv python list |
Workflow
Step 1: Preflight
[[ "$(uname -m)" == "arm64" ]] && echo "OK: Apple Silicon" || echo "FAIL: Requires Apple Silicon (M1+)"
command -v uv && echo "OK: uv found" || echo "FAIL: Install with 'brew install uv'"
Step 2: Install
ROOT="$(cc-plugin-root kokoro-tts)"
bash "$ROOT/scripts/kokoro-install.sh" --install
This performs:
- Verifies Apple Silicon (fails fast on Intel/Linux)
- Creates Python 3.14 venv at
~/.local/share/kokoro/.venv via uv
- Installs MLX-Audio dependencies (mlx-audio, soundfile, numpy)
- Copies
kokoro_common.py, tts_generate.py from plugin bundle
- Downloads Kokoro-82M-bf16 MLX model from HuggingFace
- Writes
version.json with mlx_audio version and model ID
- Runs verification synthesis ("Warm up.")
Step 3: Verify
ROOT="$(cc-plugin-root kokoro-tts)"
bash "$ROOT/scripts/kokoro-install.sh" --health
All 6 checks should pass. Print "Installation complete — run /kokoro-tts:health to verify".
Troubleshooting
| Issue | Cause | Solution |
|---|
| Not Apple Silicon | Intel Mac or Linux | MLX-Audio requires M1+ Mac |
| uv not found | Not installed | brew install uv |
| Model download slow | Large first download | Wait for HuggingFace download |
| Permission denied | Script not +x | chmod +x scripts/kokoro-install.sh |
| Venv already exists | Previous install | Run --uninstall then --install |
Post-Execution Reflection
After this skill completes, reflect before closing the task:
- Locate yourself. — Find this SKILL.md's canonical path before editing.
- What failed? — Fix the instruction that caused it.
- What worked better than expected? — Promote to recommended practice.
- What drifted? — Fix any script, reference, or dependency that no longer matches reality.
- Log it. — Evolution-log entry with trigger, fix, and evidence.
Do NOT defer. The next invocation inherits whatever you leave behind.