| name | augment |
| description | Augment Kokoro TTS engine — upgrade dependencies and model. Renamed from 'upgrade' to avoid clashing with Claude Code's built-in. |
| allowed-tools | Read, Bash, Glob, AskUserQuestion |
Augment Kokoro TTS
Upgrade MLX-Audio dependencies, re-download the model, and update bundled scripts.
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.
Workflow
Step 1: Pre-upgrade health check
ROOT="$(cc-plugin-root kokoro-tts)"
bash "$ROOT/scripts/kokoro-install.sh" --health
cat ~/.local/share/kokoro/version.json
Step 2: Execute upgrade
ROOT="$(cc-plugin-root kokoro-tts)"
bash "$ROOT/scripts/kokoro-install.sh" --upgrade
This upgrades:
- Python packages:
mlx-audio, soundfile, numpy
- Model weights: re-downloaded from
mlx-community/Kokoro-82M-bf16
- Bundled scripts:
kokoro_common.py and tts_generate.py re-copied from plugin
version.json: rewritten with new versions
Step 3: Post-upgrade verification
ROOT="$(cc-plugin-root kokoro-tts)"
bash "$ROOT/scripts/kokoro-install.sh" --health
cat ~/.local/share/kokoro/version.json
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
--text "Upgrade verification" --voice af_heart --lang en-us --speed 1.0 \
--output /tmp/kokoro-upgrade-test.wav && echo "OK"
Rollback
If upgrade breaks TTS, do a clean reinstall:
ROOT="$(cc-plugin-root kokoro-tts)"
bash "$ROOT/scripts/kokoro-install.sh" --uninstall
bash "$ROOT/scripts/kokoro-install.sh" --install
Model cache is preserved across uninstall, so reinstall reuses the cached model.
Troubleshooting
| Issue | Cause | Solution |
|---|
| Upgrade fails | No internet or PyPI down | Check connectivity, retry |
| Import error after | mlx-audio incompatibility | Clean reinstall: --uninstall then --install |
| Model download slow | Large download | Wait for HuggingFace download to complete |
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.
