Content
82%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, code-first reference skill: executable quick starts for REST, WSS, TextBuilder, and async variants, with terse high-value gotchas and explicit ordering constraints. Deductions are for the promotional 'Central product skills' section and layered link list (verbosity), the absence of an explicit verify/test step in the workflows, and an unverifiable `reference.md` pointer with no bundle files present.
Suggestions
Trim the 'Central product skills' cross-promotion section and collapse the five-layer API reference to the one or two authoritative sources (e.g., the in-repo reference plus the OpenAPI/AsyncAPI links) to cut tokens without losing guidance.
Add an explicit validation checkpoint to each quick start, e.g. 'after wiring, run `python tests/wire/test_speak_v1_audio.py` (or the manual WSS test under tests/manual/speak/v1/connect/) to verify' — the test files are already listed but never wired into the workflow.
Give `reference.md` a resolvable path (e.g., `references/reference.md`) and actually include it in the bundle, or drop the pointer; also consider moving the 'Key parameters' listing into that reference file to keep SKILL.md a pure overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and code-first with no explanation of concepts Claude already knows — gotchas like 'REST response is audio bytes, not JSON' and 'Token auth, not Bearer' are non-obvious SDK/API facts that earn their tokens. It falls short of anchor 5 because of the 'Central product skills' cross-promotion section ('npx skills add deepgram/skills') and the five-layer API-reference enumeration (Context7, two product-doc URLs), which are trimmable relative to the skill's core task. | 4 / 5 |
Actionability | Every workflow ships complete, executable code: the REST quick start writes chunks to 'output.raw', the WSS quick start registers all four event handlers and sends SpeakV1Text/flush/close in order, and TextBuilder and async equivalents are copy-paste ready. This matches the anchor-5 pattern of fully executable examples covering the common cases, with specifics like encoding='linear16', sample_rate=24000. | 5 / 5 |
Workflow Clarity | Sequencing is clear: REST vs WSS selection criteria up front, per-path quick starts, and ordering constraints called out ('send all text + flush + close BEFORE calling it' for sync start_listening). It sits at anchor 4 rather than 5 because there is no explicit validation checkpoint after writing code — e.g., no 'run tests/wire/test_speak_v1_audio.py' step — leaving verification implicit; not 3, since no destructive/batch operation is involved and the sequences present are complete. | 4 / 5 |
Progressive Disclosure | Good structure with clear sections and one-level-deep, clearly signaled references (numbered 'API reference (layered)' list, 'Example files in this repo' section, 'See `docs/FluxTtsControls.md`, `examples/22-text-builder-demo.py`'). It does not reach anchor 5 because the top-priority reference '`reference.md`' is not present in the skill bundle (no references/ directory exists) and is given without a path, so navigation to the primary in-repo reference cannot be verified, and the inline 'Key parameters' section is a compressed API reference that could live in a separate file. | 4 / 5 |
Total | 17 / 20 Passed |