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".
76
93%
Does it follow best practices?
Impact
—
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 hits all the marks. It provides specific capabilities (REST and WebSocket TTS, TextBuilder), explicit trigger guidance with natural keywords, clear 'Use when' framing, and even proactively disambiguates from a related skill. 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 specifies exact API paths and method names. | 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). Also includes a helpful disambiguation clause pointing to a different 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 natural language and technical terms users would actually use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with specific API paths (/v1/speak), method names, and explicit disambiguation from the related 'deepgram-python-voice-agent' skill. The niche is clearly Deepgram TTS v1, unlikely to conflict with other skills. | 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 workflows 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/verification steps (e.g., checking response status, verifying audio output integrity), which would strengthen the workflow clarity for production use.
Suggestions
Add a brief validation step after audio generation (e.g., check response headers for dg-char-count > 0, verify file size is non-zero, or handle HTTP error status codes) to strengthen workflow reliability.
| 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 | Provides fully executable, copy-paste-ready code for REST, WebSocket (sync and async), TextBuilder, and authentication. Specific model names, encoding options, and import paths are given. The gotchas section provides concrete, actionable warnings rather than vague advice. | 3 / 3 |
Workflow Clarity | The two main workflows (REST and WSS) are clearly presented with correct sequencing, and the critical ordering constraint for sync WSS (send all text + flush + close BEFORE start_listening) is explicitly called out. However, there are no explicit validation/verification steps — no guidance on checking if audio was generated correctly, verifying file output, or handling error responses from the API. | 2 / 3 |
Progressive Disclosure | Content is well-structured with a clear overview, quick starts for both modes, then progressively deeper sections (async equivalents, parameters, API reference, gotchas). References to example files, reference.md, external docs, and the central skills bundle 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
e169f63
- 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.