Use when writing or reviewing Python code in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live audio transcription. Covers `client.listen.v1.media.transcribe_url` / `transcribe_file` (REST) and `client.listen.v1.connect` (WebSocket). Use this skill for basic ASR; use `deepgram-python-audio-intelligence` for summarize/sentiment/topics/diarize overlays, `deepgram-python-conversational-stt` for turn-taking v2/Flux, and `deepgram-python-voice-agent` for full-duplex assistants. Triggers include "transcribe", "live transcription", "speech to text", "STT", "listen endpoint", "nova-3", "listen.v1".
71
86%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
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 specifies concrete API methods and endpoints, provides a clear 'Use when' clause, lists natural trigger terms, and explicitly differentiates itself from sibling skills. The boundary-drawing with related skills is particularly strong and reduces conflict risk significantly.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions and API methods: 'transcribe_url', 'transcribe_file' (REST), 'client.listen.v1.connect' (WebSocket), prerecorded and live audio transcription. Also explicitly names the endpoint '/v1/listen'. | 3 / 3 |
Completeness | Clearly answers both 'what' (Python code calling Deepgram STT v1 for prerecorded/live transcription via REST and WebSocket) and 'when' (explicit 'Use when' clause at the start, plus explicit trigger terms listed at the end). Also clarifies when NOT to use it by pointing to sibling skills. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: 'transcribe', 'live transcription', 'speech to text', 'STT', 'listen endpoint', 'nova-3', 'listen.v1'. These cover both casual and technical variations. | 3 / 3 |
Distinctiveness Conflict Risk | Exceptionally distinctive — explicitly delineates boundaries with related skills ('deepgram-python-audio-intelligence', 'deepgram-python-conversational-stt', 'deepgram-python-voice-agent'), making it very unlikely to conflict with similar skills in the same repo. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill with excellent code examples covering all major Deepgram STT use cases. Its main weaknesses are moderate verbosity (some sections explain concepts Claude already knows, and the interim results semantics section is quite detailed) and missing error handling/validation workflows. The progressive disclosure and cross-referencing to related skills is exemplary.
Suggestions
Trim explanatory comments in code that Claude would already understand (e.g., 'Mutable container so the on_message closure can update state without global') and reduce prose around the async/deferred patterns comparison to save tokens.
Add explicit error handling/validation steps — e.g., checking response status, handling common API errors (401, 400 encoding mismatch), and retry logic for transient failures.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is generally well-structured but includes some unnecessary verbosity — the interim vs. final flag semantics section is quite detailed, the async/deferred patterns section is lengthy with a comparison table, and some explanatory prose (e.g., 'Mutable container so the on_message closure can update state without `global`') explains things Claude already knows. The gotchas section is valuable but could be tighter. | 2 / 3 |
Actionability | Excellent actionability throughout — every major use case (REST URL, REST file, WebSocket, async, callback) has fully executable, copy-paste-ready Python code with correct imports and realistic examples. The code is complete and specific, not pseudocode. | 3 / 3 |
Workflow Clarity | The skill covers multiple patterns clearly but lacks explicit validation checkpoints. For example, there's no guidance on verifying transcription quality, handling API errors/retries, or checking response status codes. The WebSocket workflow is well-sequenced (connect → register handlers → start listening → send audio → finalize) but error recovery is not addressed beyond printing errors. | 2 / 3 |
Progressive Disclosure | Content is well-organized with clear sections progressing from simple (REST) to complex (WebSocket, async patterns). References to other skills, example files, and external API docs are clearly signaled and one level deep. The 'Use a different skill when' section and 'API reference (layered)' section provide excellent navigation. | 3 / 3 |
Total | 10 / 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.
e169f63
Table of Contents
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.