Content
50%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.
The skill has a solid executable core — verified script functions, copy-pasteable examples, and useful API details — but it is wrapped in generic templated boilerplate that dilutes the token budget, and it contains dangling references (missing requirements.txt, wrong-direction cross-reference, machine-specific cd path). Trimming the filler and fixing the broken references would move this to a good example.
Suggestions
Cut the generic template sections (When to Use, Key Features, Implementation Details, Output Contract, Validation and Safety Rules, Failure Handling) or fold their one useful line each into the Usage section — they are boilerplate that adds no ENCODE-specific knowledge.
Fix the dangling references: replace 'pip install -r requirements.txt' with 'pip install requests' (no requirements.txt exists in the bundle), correct 'See ## Usage above' to point forward, and remove the machine-specific 'cd "20260316/..."' path.
Make the workflow concrete: replace abstract steps like 'Run a final validation pass' with a checkpoint tied to the script, e.g. 'run python scripts/encode_client.py --help to confirm arguments, verify the JSON result is non-empty, and check the HTTP status on errors'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Roughly half the body is generic template boilerplate that assumes Claude's competence is low: 'Use this skill when the request matches its documented task boundary', 'Structured execution path designed to keep outputs consistent and reviewable', plus padded sections (Key Features, Implementation Details, Output Contract, Validation and Safety Rules, Failure Handling) that teach nothing ENCODE-specific. Not a 1 because the Usage and API Reference sections are lean and earn their tokens. | 2 / 5 |
Actionability | The Usage section gives complete, executable examples ('from scripts.encode_client import search_encode', 'search_encode(term="bone chip", limit=10)', 'get_object(accession="ENCBS000AAA")') and both functions exist in the script. Not a 5 because of concrete gaps: the dependency instruction references a non-existent 'requirements.txt', the bash example cds into a machine-specific path ('20260316/scientific-skills/Evidence Insight/encode-api'), and 'See ## Usage above' points the wrong direction (Usage appears later in the file). | 4 / 5 |
Workflow Clarity | A sequence exists ('Recommended Workflow' and the numbered 'Example run plan'), but the steps are abstract ('Select the documented execution path', 'Run a final validation pass') with no concrete checkpoints tied to the script. It fits the score-3 anchor — sequence present but checkpoints implicit — rather than 4, because validation is described only generically and the only concrete check ('python scripts/encode_client.py --help') is isolated in a separate section. | 3 / 5 |
Progressive Disclosure | Section headers give real structure and the single bundle file (scripts/encode_client.py) is correctly referenced, but the body inlines ~70 lines of generic template content that serves no navigational purpose, cites a missing 'requirements.txt', and the broken cross-reference ('See ## Usage above') hampers navigation. This matches the score-3 anchor of some structure with organization gaps; not a 2 because the core content is genuinely sectioned and the primary script path is clear. | 3 / 5 |
Total | 12 / 20 Passed |