Content
88%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 tight, highly actionable SDK skill with copy-paste code, a useful parameters table, and genuinely non-obvious gotchas. The main weakness is the triple repetition of the `summarize` boolean-only caveat plus a promotional 'central skills' block that inflate tokens, and the absence of any bundled reference file despite naming `reference.md`.
Suggestions
State the `summarize` boolean-only caveat once in the Gotchas section and reference it from the quick-start comment and the parameters table instead of repeating the full SDK type-alias/docstring explanation three times.
Remove or shrink the promotional 'Central product skills' / `npx skills add deepgram/skills` block, which does not advance the skill's task.
Either bundle a `reference.md` with the full Read V1 Text response shape and link to it, or relabel the `reference.md` mention as an external repo file so the progressive-disclosure layer is honest about what is in-skill vs. in-repo.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly lean and high-signal (tight quick-start, abridged response shape, focused gotchas), but the `summarize` boolean-only gotcha is repeated three times (quick-start comment, the long parameters-table cell quoting the SDK type alias and docstring, and Gotcha #3 verbatim), and the 'Central product skills' block is promotional padding — clear trim opportunities that keep it just below the top anchor. | 4 / 5 |
Actionability | Provides copy-paste-ready executable code for the common case (text input with all analytics on), an async equivalent, the text-vs-url body variants, and a concrete parameters table with types — fully executable guidance covering the common cases. | 5 / 5 |
Workflow Clarity | This is a single-shot REST call skill with no fragile multi-step pipeline, so the simple-skill exception applies; the single action is unambiguous and the gotchas act as explicit pre-flight guardrails (Token auth, English-only, required language, summarize boolean-only), with no destructive/batch operation triggering the validation cap. | 5 / 5 |
Progressive Disclosure | Well-organized sections and the API reference is properly layered (in-repo reference -> OpenAPI -> Context7 -> product docs) rather than inlined, but the skill bundle contains no actual reference files (no references/scripts/assets dirs), so the named `reference.md` is an external repo path, not a resolvable one-level-deep bundled reference the top anchor requires. | 4 / 5 |
Total | 18 / 20 Passed |