CtrlK
BlogDocsLog inGet started
Tessl Logo

deepgram-python-speech-to-text

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

Quality

86%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Advisory

Suggest reviewing before use

SKILL.md
Quality
Evals
Security

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.

DimensionReasoningScore

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.

DimensionReasoningScore

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.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
deepgram/deepgram-python-sdk
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.