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.
This is a strong, near-copy-paste-ready SDK skill: complete executable REST/async examples, honest gotchas with real sequencing guidance, and clearly layered external references. The main gaps are the placeholder audio-send in the WebSocket quick start, a repetitive null-guard example, and a moderate amount of API-surface enumeration inlined where a separate reference file would improve token efficiency.
Suggestions
Replace the commented placeholder in the WebSocket quick start with a minimal executable send loop (e.g., read a file in chunks and call `wsClient.sendMedia(okio.ByteString.of(chunk))`) so the live-streaming path is copy-paste ready like the REST examples.
Trim the visitor example's repeated `.getChannels().get(0).getAlternatives().orElse(Collections.emptyList())` chain by extracting it once into a local variable — the duplication costs tokens without teaching anything new.
Move the 'Key parameters / API surface' enumeration into a bundled reference file (e.g., references/api-surface.md) and keep only the most common parameters inline, keeping SKILL.md a lean overview with well-signaled one-level-deep references.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and SDK-specific (builder chains, visitor pattern, handler names) with essentially no explanation of concepts Claude already knows, matching 'Efficient; minor instances of over-explanation that could be trimmed'. It is not anchor 5 because the visitor example repeats the long `.getChannels().get(0).getAlternatives().orElse(...)` chain twice, and the pinned version `0.2.1` appears in two build snippets — time-sensitive detail that the guidelines penalize outside a deprecated/old-patterns section. | 4 / 5 |
Actionability | The REST URL, file-bytes, async, and client-builder examples are copy-paste ready with real imports and a working sample URL, and the parameter lists are concrete. It falls short of anchor 5's 'specific examples cover the common cases' because the WebSocket quick start leaves the core streaming action as a placeholder — "// send raw audio chunks here // wsClient.sendMedia(okio.ByteString.of(audioChunk));" — so the most common live use case is not fully executable as written. | 4 / 5 |
Workflow Clarity | The Gotchas section supplies effective sequencing and checkpoints for the risky parts — "handlers should be registered before `connect(...)`", "Wait on `connect(...).get(...)` before sending audio", "Live sessions should end explicitly" — giving a clear sequence with most checkpoints present. It is not anchor 5 because there is no single consolidated step order (connect → send → finalize/close) with explicit verification of a connected/healthy session, and not anchor 3 since the checkpoints are stated explicitly rather than merely implied. | 4 / 5 |
Progressive Disclosure | The skill ships no bundle files (no references/, scripts/, or assets/ directories), yet the body is well sectioned and its 'API reference (layered)' section signals one-level-deep sources — the in-repo `src/main/java/com/deepgram/resources/listen/v1/` checkout, canonical OpenAPI/AsyncAPI URLs, and product docs — matching 'Good structure; most content is appropriately placed; references mostly clear'. It falls short of anchor 5 because ~30 lines of parameter/API-surface enumeration are inlined in 'Key parameters / API surface' where a reference file would keep SKILL.md a leaner overview, and there are no bundled reference files despite the breadth of the surface. | 4 / 5 |
Total | 16 / 20 Passed |