deepgram-python-text-to-speech
Use when writing or reviewing Python code in this repo that calls Deepgram Text-to-Speech v1 (`/v1/speak`) for audio synthesis. Covers one-shot REST (`client.speak.v1.audio.generate`) and streaming WebSocket (`client.speak.v1.connect`). Also covers the in-repo `deepgram.helpers.TextBuilder` for incremental text assembly before synthesis. Use `deepgram-python-voice-agent` when you need full-duplex STT + LLM + TTS with barge-in. Triggers include "TTS", "speak", "synthesize voice", "aura", "text to speech", "speak.v1", "TextBuilder".
95
93%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that clearly defines its scope (Deepgram TTS v1), lists concrete capabilities (REST, WebSocket, TextBuilder), provides explicit trigger terms, and even disambiguates from a related skill. The 'Use when' clause is well-placed at the beginning, and the description is concise yet comprehensive.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: one-shot REST audio generation, streaming WebSocket synthesis, and TextBuilder for incremental text assembly. Also names specific API paths and method signatures. | 3 / 3 |
Completeness | Clearly answers both 'what' (Deepgram TTS v1 for audio synthesis via REST and WebSocket, plus TextBuilder) and 'when' (explicit 'Use when' clause at the start, plus explicit trigger list and a disambiguation clause pointing to another skill for full-duplex scenarios). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms including 'TTS', 'speak', 'synthesize voice', 'aura', 'text to speech', 'speak.v1', 'TextBuilder'. These cover both casual user language and technical terms users would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche (Deepgram TTS v1 specifically), and even includes an explicit disambiguation clause ('Use deepgram-python-voice-agent when you need full-duplex STT + LLM + TTS with barge-in') to reduce conflict with a related skill. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
87%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a high-quality skill that efficiently covers both REST and WebSocket TTS patterns with executable code, clear structure, and excellent progressive disclosure. The gotchas section adds significant value by documenting non-obvious pitfalls. The main weakness is the lack of explicit validation/error-handling steps in the workflows, particularly for WebSocket streaming where failures could be silent.
Suggestions
Add a brief validation step after REST audio generation (e.g., check response headers like `dg-char-count`, verify file size > 0) and after WebSocket streaming (e.g., confirm audio chunks were received before closing).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient throughout. It assumes Claude knows Python, async patterns, and SDK conventions. Every section delivers specific, non-obvious information (e.g., 'Token not Bearer', 'REST response is audio bytes not JSON', TextBuilder has no .add() method). No unnecessary explanations of basic concepts. | 3 / 3 |
Actionability | All code examples are fully executable and copy-paste ready — REST one-shot, WebSocket streaming, TextBuilder, and async equivalents. Specific model names, encoding options, and import paths are provided. The gotchas section gives concrete, actionable warnings rather than vague advice. | 3 / 3 |
Workflow Clarity | The REST and WebSocket workflows are clearly sequenced with important ordering notes (e.g., 'send all text + flush + close BEFORE calling start_listening'). However, there are no explicit validation or error-handling checkpoints — no guidance on verifying the output audio is valid, checking response headers for errors, or handling WebSocket connection failures with retry logic. | 2 / 3 |
Progressive Disclosure | Content is well-structured with a clear overview, quick starts for both modes, then progressively deeper sections (async, parameters, API reference, gotchas). References to example files, reference.md, and external docs are clearly signaled and one level deep. The layered API reference section is particularly well-organized. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- deepgram/deepgram-python-sdk
- Commit
16b9839
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.