deepgram-python-voice-agent
Use when writing or reviewing Python code in this repo that builds an interactive voice agent via `agent.deepgram.com/v1/agent/converse`. Covers `client.agent.v1.connect()`, `AgentV1Settings`, `send_settings`, `send_media`, event handling, and function/tool calling. Full-duplex STT + LLM + TTS with barge-in. Use `deepgram-python-text-to-speech` for one-way synthesis, `deepgram-python-speech-to-text` / `deepgram-python-conversational-stt` for transcription only. Triggers include "voice agent", "agent converse", "full duplex", "interactive assistant", "barge-in", "agent.v1", "function calling", "AgentV1Settings".
90
88%
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 is highly specific, complete, and distinctive. It names concrete API methods and endpoints, provides explicit 'Use when' guidance, lists natural trigger terms, and clearly differentiates itself from related skills by specifying boundary conditions. The third-person voice is maintained throughout.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions and API elements: `client.agent.v1.connect()`, `AgentV1Settings`, `send_settings`, `send_media`, event handling, function/tool calling, and references the specific endpoint `agent.deepgram.com/v1/agent/converse`. Also distinguishes from related skills for one-way synthesis and transcription. | 3 / 3 |
Completeness | Clearly answers both 'what' (building an interactive voice agent with specific API methods, full-duplex STT+LLM+TTS) and 'when' (explicit 'Use when writing or reviewing Python code in this repo...' clause plus explicit trigger list). Also clarifies when NOT to use it by pointing to alternative skills. | 3 / 3 |
Trigger Term Quality | Includes a rich set of natural trigger terms users would say: 'voice agent', 'agent converse', 'full duplex', 'interactive assistant', 'barge-in', 'agent.v1', 'function calling', 'AgentV1Settings'. These cover both natural language and technical terms a developer would use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive by specifying the exact API endpoint, SDK methods, and use case (interactive voice agent). Explicitly delineates boundaries with related skills (`deepgram-python-text-to-speech` for one-way synthesis, `deepgram-python-speech-to-text` for transcription only), minimizing conflict risk. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
77%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 workflow clarity covering the full agent lifecycle including edge cases like reconnection and mid-session updates. Its main weakness is length — at ~250 lines with extensive inline examples, it could benefit from splitting the mid-session adjustment and stream lifecycle sections into separate reference files to improve progressive disclosure and conciseness. The content is well-organized with clear sections and practical gotchas.
Suggestions
Move the 'Dynamic mid-session adjustment' section (6 examples) to a separate MIDSTREAM.md file, keeping only a brief summary and link in SKILL.md
Move the 'Stream lifecycle & recovery' section to a separate LIFECYCLE.md file, retaining a 2-3 line summary with link in the main skill
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is generally efficient and avoids explaining basic concepts, but it's quite long (~250 lines). Some sections like the full type import lists, the detailed reconnect example, and the mid-session adjustment section with 6 sub-examples could be trimmed or moved to reference files. The 'Reusable agent configurations' paragraph and some inline comments add moderate verbosity. | 2 / 3 |
Actionability | Excellent actionability throughout — the quick start is fully executable with real SDK types, the mid-session adjustment section provides 6 concrete copy-paste examples, the keepalive loop and reconnect-with-context examples are complete and executable. Import paths are specific and real. | 3 / 3 |
Workflow Clarity | The lifecycle is clearly sequenced: connect → send_settings (MUST be first) → register handlers → send audio → listen. The 'Stream lifecycle & recovery' section explicitly covers pause/idle, resume, reconnect with context preservation, and disconnect detection. Validation checkpoints are present (e.g., 'Server replies with SettingsApplied', 'retry after AgentAudioDone', check ERROR payloads for cause). | 3 / 3 |
Progressive Disclosure | The skill references external files (reference.md, example files, external docs) and cross-links to other skills appropriately. However, the mid-session adjustment section and stream lifecycle/recovery section are quite lengthy and could be split into separate files. The inline content is heavy for a SKILL.md overview, though the layered API reference section is well-structured. | 2 / 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.
- 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.