Agent-Skills.md

Agent Skills: Settings and Tuning

Configure TTS voices, speed, timeouts, queue depth, and bot settings. TRIGGERS - configure tts, change voice, tts speed, queue depth, tts timeout, bot config, tune settings, adjust parameters.

UncategorizedID: terrylica/cc-skills/settings-and-tuning

Repository

terrylica/cc-skills
terrylicaLicense: MIT
264

Install this agent skill to your local

pnpm dlx add-skill https://github.com/terrylica/cc-skills/tree/HEAD/plugins/tts-tg-sync/skills/settings-and-tuning

Skill Files

Browse the full folder contents for settings-and-tuning.

Download Skill

Loading file tree…

plugins/tts-tg-sync/skills/settings-and-tuning/SKILL.md

Skill Metadata

Name
settings-and-tuning
Description
Configure TTS voices, speed, timeouts, queue depth, and bot settings. TRIGGERS - configure tts, change voice, tts speed, queue depth, tts timeout, bot config, tune settings, adjust parameters.

Settings and Tuning

Configure all adjustable parameters for the TTS engine, Telegram bot, and supporting infrastructure. All settings are centralized in the mise.toml SSoT.

Platform: macOS (Apple Silicon)

When to Use This Skill

  • Changing TTS voice (English, Chinese, or macOS say voices)
  • Adjusting speech speed
  • Tuning TTS timeouts or queue depth
  • Configuring notification rate limiting or circuit breakers
  • Adjusting prompt executor throttling
  • Modifying session picker limits
  • Changing audit log retention

Requirements

| Component | Required | Installation | | ----------- | ----------- | ------------------------------------------------- | | mise | Yes | brew install mise (for env loading) | | Bot running | Recommended | Changes to TTS/queue settings require bot restart |

Workflow Phases

Phase 0: Read Current Configuration

Read the current mise.toml to see all active settings:

cat ~/.claude/automation/claude-telegram-sync/mise.toml

All configurable values live in the [env] section. The file is the single source of truth for the entire stack.

Phase 1: Identify What to Change

Present the config groups to the user via AskUserQuestion. Config groups:

| Group | Settings | Description | | --------------- | ---------------------------------------------------------------------- | ----------------------------------------------- | | TTS Voice | TTS_VOICE_EN, TTS_VOICE_ZH, TTS_VOICE_SAY_EN, TTS_VOICE_SAY_ZH | Voice selection per language | | TTS Speed | TTS_SPEED | Speech rate multiplier | | TTS Timeouts | TTS_GENERATE_TIMEOUT_MS, TTS_SAY_TIMEOUT_MS | Generation and playback timeouts | | TTS Queue | TTS_MAX_QUEUE_DEPTH, TTS_STALE_TTL_MS, TTS_MAX_TEXT_LEN | Queue limits and staleness | | TTS Signal | TTS_SIGNAL_SOUND | Signal sound path (empty to disable) | | Rate Limiting | NOTIFICATION_MIN_INTERVAL_MS, SUMMARIZER_* | Notification and summarizer throttling | | Prompt Executor | PROMPT_* | Prompt execution throttling and circuit breaker | | Session Picker | SESSION_* | Session scanning and display limits | | Audit | AUDIT_RETENTION_DAYS | Log retention period | | Model | HAIKU_MODEL | Claude model for Agent SDK calls |

Phase 2: Edit Configuration

Edit the appropriate line(s) in ~/.claude/automation/claude-telegram-sync/mise.toml. Use the Edit tool to make precise changes to specific values.

Phase 3: Validate and Apply

  1. Verify the edited value is within the valid range (see Config Reference)
  2. If TTS, queue, or rate limiting settings changed, restart the bot:
# Option A: If using mise tasks
cd ~/.claude/automation/claude-telegram-sync && mise run bot:restart

# Option B: Manual restart
pkill -f "bun.*main.ts" && cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts
  1. Confirm new settings are active by checking bot logs or testing the affected feature

TodoWrite Task Templates

Template: Settings Adjustment

1. [Read] Read current mise.toml configuration
2. [Identify] Present config groups to user via AskUserQuestion
3. [Select] User selects setting category to modify
4. [Edit] Update mise.toml with new values
5. [Validate] Verify values are in valid range
6. [Apply] Restart bot to apply changes (if TTS or queue settings changed)
7. [Verify] Confirm new settings are active

Post-Change Checklist

After modifying this skill:

  1. [ ] Verify all config groups in SKILL.md match current mise.toml
  2. [ ] Update config-reference.md if new env vars were added
  3. [ ] Test that changed settings take effect after bot restart
  4. [ ] Update references/evolution-log.md with change description

Post-Execution Reflection

After this skill completes, reflect before closing the task:

  1. 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.
  2. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
  3. What worked better than expected? — Promote it to recommended practice. Document why.
  4. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
  5. 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.

Troubleshooting

| Issue | Cause | Solution | | -------------------------- | -------------------------------- | ------------------------------------------------------ | | Settings not taking effect | Bot not restarted | Restart bot after changing mise.toml | | mise.toml parse error | Invalid TOML syntax | Check for missing quotes or unescaped chars | | Voice not found | Invalid voice name | Check voice catalog (Kokoro voices are case-sensitive) | | Speed too fast/slow | Value out of range | Use 0.5 to 2.0 range for TTS_SPEED | | Circuit breaker stuck open | Too many failures | Wait for breaker timeout or restart bot | | Timeout too short | TTS generation slow on first run | Model warmup takes longer; increase timeout |

Reference Documentation

  • Config Reference - Full reference table with all env vars, defaults, valid ranges, and component ownership
  • mise.toml Reference - Hub/spoke mise architecture, secret loading, and task file structure
  • Evolution Log - Change history for this skill