Content
75%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A strong, well-structured reference skill: the quick start handles real-world SDK quirks (typed/untyped message unions, string sample_rate, correct v2 close semantics) and the gotchas section is genuinely high-value. It uniformly sits at the 'good with minor gaps' level — the quick start isn't fully copy-paste executable, and version-sensitive deployment details and promotional sections cost tokens.
Suggestions
Replace the `mic_chunks()` placeholder with a real 80ms-frame audio source (e.g., reading a WAV file in chunks) so the quick start is copy-paste executable, and show `api_key` wiring in the `AsyncDeepgramClient` example to match the sync one.
Move version-specific deployment details (the '2026-09-15 release or later' self-hosted requirements and `[features]` flags) out of the main 'Key parameters' flow into a dedicated 'Self-hosted deployment notes' section, per the time-sensitive-information guideline.
Consolidate the skill-routing guidance duplicated in 'When to use this product' and 'Related skills' into one place, and trim the 'Central product skills' promotional section to a single line to save tokens.
Resolve the `reference.md` pointer: either place the 'Listen V2 Connect' reference in a `references/` bundle directory with a clear path, or inline the handful of details actually needed so the reference is not dangling.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and high-value — a compact 'Key parameters' table, terse gotchas ('`/v2/listen`, not `/v1/listen`', '`sample_rate` is a STRING'), and no explanation of concepts Claude already knows. Minor trimmable instances: the 'Central product skills' section with the `npx skills add deepgram/skills` promo block, routing guidance duplicated between 'When to use this product' and 'Related skills', and time-sensitive version info ('2026-09-15 release or later') embedded in the main flow rather than a deployment/deprecated section — per the guideline this last item is penalized, keeping it out of the 5 anchor ('every token earns its place'). | 4 / 5 |
Actionability | The quick start is mostly executable and unusually thorough — it registers handlers via `conn.on(EventType.MESSAGE, on_message)`, branches on typed `ListenV2TurnInfo` vs raw dict fallbacks, threads audio, and closes with `conn.send_close_stream(ListenV2CloseStream(type="CloseStream"))`, plus a concrete async equivalent. Minor gaps keep it below 5: `mic_chunks()` is an undefined placeholder, and `AsyncDeepgramClient()` is shown without the API-key wiring the sync example includes. | 4 / 5 |
Workflow Clarity | The lifecycle (connect with Flux model params → register handlers → send ~80ms chunks → `start_listening()` → `send_close_stream`) is demonstrated concretely through the quick start, with error surfacing via `EventType.ERROR` and `ListenV2FatalError` documented. Not 5: no explicit numbered sequence or error-recovery guidance beyond printing the error; not 3: this is a single-purpose API skill, not a destructive/batch operation, so the validation cap does not apply and the implicit sequence is clear. | 4 / 5 |
Progressive Disclosure | Good section structure with well-signaled, one-level-deep references: 'API reference (layered)' routes from in-repo `reference.md` to AsyncAPI/Context7/product docs, and example files are listed in a dedicated section. Minor gaps: the in-repo `reference.md` path is not part of the skill bundle (no `references/` directory exists, so the pointer can't be resolved), and the parameter/events tables plus duplicated routing content push the SKILL.md toward a length where more could be deferred. | 4 / 5 |
Total | 16 / 20 Passed |