Content
37%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 body contains a genuinely good validated workflow (mandatory search → generate → validate → bounded retry loop), but it is buried in a monolithic 3,200-line TypeScript declaration dump that includes unrelated type-fest internals. The skill reads as a raw API index pasted into SKILL.md rather than a curated guide, destroying token efficiency and offering no progressive disclosure.
Suggestions
Move the entire TypeScript declaration dump out of SKILL.md into a references/ file (e.g. references/hydrogen-types.d.ts) and keep only the export surface or a few key component/type examples inline, since Claude can consult the full file on demand.
Delete the non-Hydrogen type-fest internals (UnionToIntersection, IsNever, IsAny, Simplify, OmitIndexSignature, Merge, Except, etc.) — they are generic third-party library documentation with no bearing on the skill's purpose.
Consolidate the duplicated workflow instructions (the top 'Required Tool Calls' section and the bottom 'MANDATORY: Search/Validate' sections) into one authoritative sequence, and add one complete, executable Hydrogen code example so the placeholders (YOUR_MODEL_NAME, YOUR_ARTIFACT_ID) are shown filled in.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Roughly 3,200 of the ~3,450 body lines are a verbatim inlined .d.ts dump, including long stretches of type-fest internals ("UnionToIntersection", "KeysOfIteratorOf"-style IsNever/IsAny/Simplify/OmitIndexSignature definitions) that are generic TypeScript library documentation unrelated to Hydrogen. This is the severely padded extreme — massive token cost for content Claude either knows or would never need. | 1 / 5 |
Actionability | The workflow commands are concrete ("scripts/search_docs.mjs \"<component tag name>\"", "scripts/validate.mjs --code '...' --model YOUR_MODEL_NAME --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER") and both scripts exist in the bundle, but they contain unfilled placeholders with only prose guidance on filling them. There is no complete, copy-paste-ready Hydrogen code example anywhere in the body — guidance is type reference rather than instruction. | 3 / 5 |
Workflow Clarity | The core loop is explicit and well-sequenced with a real feedback loop: search docs → write code → validate → on failure search the error type, fix, re-validate (max 3 retries) → "Return code only after validation passes". It is not a 5 because the same instructions are duplicated in two places (top "Required Tool Calls" and bottom "MANDATORY" sections with slightly different flag lists) and buried in a 3,000-line type wall, making the actual sequence hard to navigate. | 4 / 5 |
Progressive Disclosure | The entire API type dump is inlined directly in SKILL.md instead of being a references/ file — content that clearly belongs in a separate file sits inline, matching the 2 anchor. The bundled scripts are real and properly referenced (no nesting issue), and there is no references/ directory at all, which prevents a 1 but offers no progressive structure. | 2 / 5 |
Total | 10 / 20 Passed |