Cc-skills component-version-upgrade

Upgrade Kokoro model, bot dependencies, or TTS components. TRIGGERS - upgrade kokoro, update model, upgrade bot, update dependencies, version bump, component update.

install

source · Clone the upstream repo

git clone https://github.com/terrylica/cc-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/terrylica/cc-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/tts-tg-sync/skills/component-version-upgrade" ~/.claude/skills/terrylica-cc-skills-component-version-upgrade && rm -rf "$T"

manifest: plugins/tts-tg-sync/skills/component-version-upgrade/SKILL.md

source content

Component Version Upgrade

Upgrade individual components of the TTS + Telegram bot stack without rebuilding the entire system.

Platform: macOS (Apple Silicon)

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.

When to Use This Skill

User wants to upgrade Kokoro TTS engine, Python dependencies, or the model
User wants to update bot dependencies (Bun packages)
User wants to refresh
```
tts_generate.py
```
from the plugin bundle
User wants to bump the Bun runtime version

Requirements

```
uv
```
installed (
```
brew install uv
```
)
```
mise
```
installed and configured
Internet connectivity for package downloads
Existing installation (run
```
full-stack-bootstrap
```
first if not installed)

Upgradeable Components

Component	Command	What It Does
Kokoro TTS engine	`kokoro-install.sh --upgrade`	Upgrades Python deps, re-downloads model, updates version.json
Bot dependencies	`cd ~/.claude/automation/claude-telegram-sync && bun update`	Updates Bun packages per package.json
tts_generate.py	Re-copy from plugin `scripts/` to `~/.local/share/kokoro/`	Updates the TTS generation script
Bun runtime	`mise use bun@latest`	Updates the Bun version in mise.toml

Workflow Phases

Phase 1: Component Selection

Ask the user which component to upgrade using AskUserQuestion. Present the four options above.

Phase 2: Pre-Upgrade Health Check

# Run health check to establish baseline
~/.local/share/kokoro/../../eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --health

# Record current versions
cat ~/.local/share/kokoro/version.json

Phase 3: Execute Upgrade

Run the appropriate upgrade command for the selected component.

Phase 4: Post-Upgrade Verification

# Health check again
kokoro-install.sh --health

# Generate test audio to verify TTS still works
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
  --text "Upgrade verification test" --voice af_heart --lang en-us --speed 1.0 \
  --output /tmp/kokoro-tts-upgrade-test.wav

Phase 5: Bot Restart (if needed)

If bot dependencies or Bun runtime were upgraded, restart the bot:

pkill -f 'bun.*src/main.ts' || true
cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts

TodoWrite Task Templates

1. [Identify] Present upgradeable components via AskUserQuestion
2. [Preflight] Run health check on target component
3. [Backup] Note current versions (version.json, package.json)
4. [Upgrade] Execute upgrade command
5. [Verify] Run post-upgrade health check
6. [Test] Generate test audio to verify TTS still works
7. [Restart] Restart bot if needed
8. [Report] Show before/after versions

Post-Change Checklist

Health check passes (all 6 checks OK)
version.json updated with new versions
Test audio generates and plays correctly
Bot is running if it was restarted

Troubleshooting

Problem	Likely Cause	Fix
Upgrade fails	No internet or PyPI issue	Check connectivity, retry
Model download slow	First-time ~400MB, subsequent cached	Wait for download to complete
Version mismatch	Stale version.json	Re-run `kokoro-install.sh --health` to check, `--upgrade` to fix
MLX-Audio import fails	mlx-audio version incompatibility	`kokoro-install.sh --upgrade` reinstalls mlx-audio
Bot won't start after upgrade	Dependency conflict	`cd ~/.claude/automation/claude-telegram-sync && bun install`

Reference Documentation

Upgrade Procedures -- Step-by-step upgrade instructions with rollback for each component
Evolution Log -- Change history for this skill

Post-Execution Reflection

After this skill completes, reflect before closing the task:

Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
What worked better than expected? — Promote it to recommended practice. Document why.
What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.