helix4u/kokoro-tts
skills/integrations/kokoro-tts/SKILL.md
Use a local Kokoro FastAPI server for text-to-speech, voice discovery, and mixed-voice synthesis. Trigger when working with the user's Kokoro FastAPI Docker service, validating health, listing voices, generating speech with a specific Kokoro voice or voice mix, or using the Kokoro API independently of Hermes' built-in text_to_speech provider.
$ install --global
skillsauthnpx skillsauth add helix4u/hermes-agent kokoro-ttsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 16, 2026, 7:47 AM318.0s2 files scanned
SKILL.md
- name:
- kokoro-tts
- description:
- Use a local Kokoro FastAPI server for text-to-speech, voice discovery, and mixed-voice synthesis. Trigger when working with the user's Kokoro FastAPI Docker service, validating health, listing voices, generating speech with a specific Kokoro voice or voice mix, or using the Kokoro API independently of Hermes' built-in text_to_speech provider.
- tags:
- [TTS, Kokoro, Voice Mixing, FastAPI, Audio]
kokoro-tts
Use this skill when the task is specifically about the user's local Kokoro FastAPI server or when you need to choose voices or mixed voice strings directly instead of relying on Hermes' default text_to_speech configuration.
Core workflow
- Check the service first with
GET /health. - Read the base URL from
tts.kokoro.base_urlin~/.hermes/config.yamlwhen available. Default tohttp://localhost:8880. - List voices with
GET /v1/audio/voicesinstead of guessing. - Generate audio with
POST /v1/audio/speech. - Use the configured default voice from
tts.kokoro.voicewhen the user does not specify one. - Use the configured default speed from
tts.kokoro.speedwhen the user does not specify one. Hermes defaults this to1.75. - Save the returned audio bytes to disk and return the file path or
MEDIA:tag as needed.
Preferred behavior
- Prefer the built-in Hermes
text_to_speechtool when the user simply wants speech output and the configured Kokoro default voice is fine. - Prefer direct Kokoro API use when the user wants to inspect available voices, choose a custom mix, debug the local server, or bypass Hermes' default provider selection.
- Preserve the user's text exactly unless they asked for rewriting.
- Treat the
voicefield as a raw Kokoro voice selector. Mixed voices likeaf_sky+af_v0+af_nicoleare valid. - Weighted voice mixes are also valid, such as
af_bella(2)+af_sky(1).
Voice mixing
- Simple mixes use
+, for exampleaf_sky+af_v0+af_nicole. - Weighted mixes add ratios in parentheses, for example
af_bella(2)+af_sky(1). - Kokoro normalizes the ratios automatically.
- If the user wants to reuse a blended voice repeatedly, the server also supports voice-combine flows described in
references/api.md.
Failure handling
- If
/healthfails, report that the local Kokoro container is unavailable before trying anything else. - If
GET /v1/audio/voicesfails, report that voice discovery is unavailable and do not guess a replacement voice. - If synthesis fails, surface the server error and include the requested voice string and response format in the diagnosis.
- If the user requests a format that the target platform does not like, prefer
opusfor Telegram or Discord voice-style playback andmp3otherwise.
Reference file
- Load
references/api.mdwhen you need exact endpoint shapes or request examples.
Related Skills
helix4u/writing-plans
development
VerifiedTrustedCommunity
Use when you have a spec or requirements for a multi-step task. Creates comprehensive implementation plans with bite-sized tasks, exact file paths, and complete code examples.
4SKILL.mdUpdated Apr 18, 2026
helix4u/test-driven-development
development
VerifiedTrustedCommunity
Use when implementing any feature or bugfix, before writing implementation code. Enforces RED-GREEN-REFACTOR cycle with test-first approach.
4SKILL.mdUpdated Apr 18, 2026
helix4u/systematic-debugging
development
VerifiedTrustedCommunity
Use when encountering any bug, test failure, or unexpected behavior. 4-phase root cause investigation — NO fixes without understanding the problem first.
4SKILL.mdUpdated Apr 18, 2026
helix4u/subagent-driven-development
development
VerifiedTrustedCommunity
Use when executing implementation plans with independent tasks. Dispatches fresh delegate_task per task with two-stage review (spec compliance then code quality).
4SKILL.mdUpdated Apr 18, 2026