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)
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
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:
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
Verify the edited value is within the valid range (see Config Reference)
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
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:
Verify all config groups in SKILL.md match current mise.toml
Update config-reference.md if new env vars were added
Test that changed settings take effect after bot restart
Update references/evolution-log.md with change description
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
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.
1---
2name: settings-and-tuning
3description: Configure TTS voices, speed, timeouts, queue depth, and bot settings. TRIGGERS - configure tts, change voice, tts speed
4allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
5metadata:
6 source: https://skillmd.com/skills/terrylica/settings-and-tuning
7---
89# Settings and Tuning
1011Configure all adjustable parameters for the TTS engine, Telegram bot, and supporting infrastructure. All settings are centralized in the mise.toml SSoT.
1213> **Platform**: macOS (Apple Silicon)
1415> **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.
1617## When to Use This Skill
1819- Changing TTS voice (English, Chinese, or macOS `say` voices)
20- Adjusting speech speed
21- Tuning TTS timeouts or queue depth
22- Configuring notification rate limiting or circuit breakers
23- Adjusting prompt executor throttling
24- Modifying session picker limits
25- Changing audit log retention
2627---
2829## Requirements
3031| Component | Required | Installation |
32| ----------- | ----------- | ------------------------------------------------- |
33| mise | Yes | `brew install mise` (for env loading) |
34| Bot running | Recommended | Changes to TTS/queue settings require bot restart |
3536---
3738## Workflow Phases
3940### Phase 0: Read Current Configuration
4142Read the current mise.toml to see all active settings:
4344```bash
45cat ~/.claude/automation/claude-telegram-sync/mise.toml
46```
4748All configurable values live in the `[env]` section. The file is the single source of truth for the entire stack.
4950### Phase 1: Identify What to Change
5152Present the config groups to the user via AskUserQuestion. Config groups:
5354| Group | Settings | Description |
55| --------------- | ---------------------------------------------------------------------- | ----------------------------------------------- |
56| TTS Voice | `TTS_VOICE_EN`, `TTS_VOICE_ZH`, `TTS_VOICE_SAY_EN`, `TTS_VOICE_SAY_ZH` | Voice selection per language |
57| TTS Speed | `TTS_SPEED` | Speech rate multiplier |
58| TTS Timeouts | `TTS_GENERATE_TIMEOUT_MS`, `TTS_SAY_TIMEOUT_MS` | Generation and playback timeouts |
59| TTS Queue | `TTS_MAX_QUEUE_DEPTH`, `TTS_STALE_TTL_MS`, `TTS_MAX_TEXT_LEN` | Queue limits and staleness |
60| TTS Signal | `TTS_SIGNAL_SOUND` | Signal sound path (empty to disable) |
61| Rate Limiting | `NOTIFICATION_MIN_INTERVAL_MS`, `SUMMARIZER_*` | Notification and summarizer throttling |
62| Prompt Executor | `PROMPT_*` | Prompt execution throttling and circuit breaker |
63| Session Picker | `SESSION_*` | Session scanning and display limits |
64| Audit | `AUDIT_RETENTION_DAYS` | Log retention period |
65| Model | `HAIKU_MODEL` | Claude model for Agent SDK calls |
6667### Phase 2: Edit Configuration
6869Edit the appropriate line(s) in `~/.claude/automation/claude-telegram-sync/mise.toml`. Use the Edit tool to make precise changes to specific values.
7071### Phase 3: Validate and Apply
72731. Verify the edited value is within the valid range (see [Config Reference](./references/config-reference.md))
742. If TTS, queue, or rate limiting settings changed, restart the bot:
7576```bash
77# Option A: If using mise tasks
78cd ~/.claude/automation/claude-telegram-sync && mise run bot:restart
7980# Option B: Manual restart
81pkill -f "bun.*main.ts" && cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts
82```
83841. Confirm new settings are active by checking bot logs or testing the affected feature
8586---
8788## TodoWrite Task Templates
8990### Template: Settings Adjustment
9192```
931. [Read] Read current mise.toml configuration
942. [Identify] Present config groups to user via AskUserQuestion
953. [Select] User selects setting category to modify
964. [Edit] Update mise.toml with new values
975. [Validate] Verify values are in valid range
986. [Apply] Restart bot to apply changes (if TTS or queue settings changed)
997. [Verify] Confirm new settings are active
100```
101102---
103104## Post-Change Checklist
105106After modifying this skill:
1071081. [ ] Verify all config groups in SKILL.md match current mise.toml
1092. [ ] Update config-reference.md if new env vars were added
1103. [ ] Test that changed settings take effect after bot restart
1114. [ ] Update `references/evolution-log.md` with change description
112113## Troubleshooting
114115| Issue | Cause | Solution |
116| -------------------------- | -------------------------------- | ------------------------------------------------------ |
117| Settings not taking effect | Bot not restarted | Restart bot after changing mise.toml |
118| mise.toml parse error | Invalid TOML syntax | Check for missing quotes or unescaped chars |
119| Voice not found | Invalid voice name | Check voice catalog (Kokoro voices are case-sensitive) |
120| Speed too fast/slow | Value out of range | Use 0.5 to 2.0 range for TTS_SPEED |
121| Circuit breaker stuck open | Too many failures | Wait for breaker timeout or restart bot |
122| Timeout too short | TTS generation slow on first run | Model warmup takes longer; increase timeout |
123124---
125126## Reference Documentation
127128- [Config Reference](./references/config-reference.md) - Full reference table with all env vars, defaults, valid ranges, and component ownership
129- [mise.toml Reference](./references/mise-toml-reference.md) - Hub/spoke mise architecture, secret loading, and task file structure
130- [Evolution Log](./references/evolution-log.md) - Change history for this skill
131132## Post-Execution Reflection
133134After this skill completes, reflect before closing the task:
1351360. **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.
1371. **What failed?** — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
1382. **What worked better than expected?** — Promote it to recommended practice. Document why.
1393. **What drifted?** — Any script, reference, or external dependency that no longer matches reality gets fixed now.
1404. **Log it.** — Every change gets an evolution-log entry with trigger, fix, and evidence.
141142Do NOT defer. The next invocation inherits whatever you leave behind.
143144---
145146---
Run npx get-skill add terrylica/settings-and-tuning in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Configure TTS voices, speed, timeouts, queue depth, and bot settings. TRIGGERS - configure tts, change voice, tts speed It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
terrylica (@terrylica) published this skill. Their other Agent Skills are listed on their SkillMD profile.