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 well-crafted API skill body: copy-paste executable examples, an explicit staleness-rejection checkpoint, prompt-injection content-safety guidance, and clear disambiguation from sibling endpoints. The main improvement space is tightening the coverage/staleness prose and moving the response-field semantics into a reference file.
Suggestions
Compress the 'coverage' bullet's staleness policy into a compact decision rule (e.g. a two-line table of staleReason values and the 21600s bound) to cut tokens without losing the validation guidance.
Add a short numbered sequence at the top (authenticate → call with jmespath → check coverage → project) so the workflow is explicit rather than implied by section order.
Move the field-by-field response semantics (threat, location, feedStatuses vocabulary, coverage fields) into a references/response-fields.md and link to it from the Response shape section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and nearly every section earns its tokens — auth matrix, parameter table, response shape, worked curl examples — with no tutorial-style explanation of concepts Claude already knows. The one spot that could tighten is the 'coverage' bullet, whose staleness policy ('staleAgeSeconds is bounded at 21600 (6 hours) — past that window...') is explained more discursively than needed, which keeps it below the lean 'every token earns its place' anchor. | 4 / 5 |
Actionability | Fully executable: a copy-paste-ready curl command with header auth and URL-encoded params, a concrete JMESPath projection example ('categories.geopolitics.items[:10].{t: title, s: source}'), a second variant/lang example, an exact endpoint, and enumerated error codes with handling guidance (401, 429 retry with backoff). | 5 / 5 |
Workflow Clarity | The flow is unambiguous and includes a real validation checkpoint — 'reject a response when coverage.servedStale is true or coverage.state is stale' — plus error-recovery guidance, and the single call is demonstrated end-to-end in the worked example. It stops short of a 5 because the steps (authenticate → call → check coverage → project) are implied by section order rather than stated as an explicit sequence; this is not a destructive or batch operation, so the validation cap does not apply. | 4 / 5 |
Progressive Disclosure | Sections are well-organized with a clear References section linking one-level-deep external material (OpenAPI spec, auth matrix, docs), and the 'When NOT to use' section cleanly routes to sibling capabilities. It falls just short of the top anchor because the field-by-field response documentation (notably the multi-paragraph coverage/staleness semantics) is inlined in SKILL.md where a local reference file could carry it, and there are no local bundle files to offload it to. | 4 / 5 |
Total | 17 / 20 Passed |