Content
78%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-structured, interview-driven instruction skill: the five-step workflow is explicit and easy to follow, guidance is concrete (specific files to scan, exact questions to ask, named design options), and detail is appropriately pushed into two real, clearly-signaled reference files. Remaining gaps are minor — a small amount of motivational padding, a few mechanics fully deferred to references with no inline fallback, and no post-generation validation step for the README's links/badges.
Suggestions
Trim the 'Why the interview matters' section to one or two directive sentences (e.g., 'Never generate a README without the interview — it is what separates a tailored README from a template'), cutting the 8-seconds/2-minutes narrative Claude doesn't need.
Add a lightweight validation step after drafting: re-check that every TOC anchor link resolves under GitHub's slug rules (per references/seo-and-structure.md) and that no badge or star count was fabricated, before presenting the file.
Include one inline fallback example (e.g., a single shields.io badge URL pattern or one anchor-slug transformation) so the skill still yields correct mechanics if a reference file cannot be read.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is largely tight, actionable instruction ('Before asking the user anything, check what's already available', 'Get the *exact* commands — never invent install commands'), with only minor over-explanation such as the 'A README has about 8 seconds to convince a visitor' rationale paragraph and a few padded asides ('the kind that make a project look alive, trustworthy, and easy to try in under 60 seconds'). It is more than anchor 3 because the padding is incidental rather than systematic explanation of things Claude already knows. | 4 / 5 |
Actionability | Guidance is mostly executable: a concrete scan list ('package.json, pyproject.toml, Cargo.toml, go.mod, setup.py, composer.json'), numbered interview questions, four named design options, and per-step deliverable rules ('always create it, don't just paste it in chat'). It falls short of anchor 5 because a few directives remain high-level (e.g., badge syntax and anchor slug rules are deferred to references rather than given any inline example), leaving minor gaps if the reference files were unavailable. | 4 / 5 |
Workflow Clarity | The five steps (silent scan → batched interview → research → draft → deliver) are clearly sequenced, with most checkpoints present: mandatory pre-write reading of both reference files, 'never fabricate' rules for badges/stars/install commands, a placeholder summary on delivery, and an iterate-directly loop. It is not anchor 5 because there is no explicit validation of the produced README (e.g., verifying generated anchor links resolve) — checks are preventive rather than a validate-fix-retry loop. | 4 / 5 |
Progressive Disclosure | The SKILL.md is a clear overview with both detail files split out one level deep and well signaled: 'Read `references/design-styles.md` for the full template' and 'Read `references/seo-and-structure.md` … both are required reading before writing', plus a closing 'Reference files' section describing each file's purpose and when to read it. Both referenced files exist in the bundle, and no content that belongs in references is bulk-inlined. | 5 / 5 |
Total | 17 / 20 Passed |