dev-skills-review

RAI Skills Review

Litmus Test: Agent Usability

The ultimate quality gate. Everything below serves this — if an agent can't discover, navigate, adapt, and execute from the skill alone, the skill isn't done.

• Discovery: Given a realistic user task, does the skill's description cause it to trigger (and not trigger for unrelated tasks)?
• Navigation: Can an agent find the right section/example within the skill in 1-2 lookups (not wandering)?
• Pattern adaptation: Given a novel problem, can an agent locate a relevant example pattern and adapt it to a new domain without hallucinating API calls?
• Self-sufficiency: Can an agent go from skill content to working code without needing external docs, clarification, or guessing?
• Negative test: Does the skill clearly redirect the agent when the task is out of scope (via "When NOT to use" pointers)?

Structure

• YAML frontmatter with name and description (one line, imperative mood, trigger-ready, under 1024 characters)
• Description answers two questions: (1) WHAT the skill covers, framed from user-intent angle not implementation mechanics; (2) WHEN Claude should invoke it, including cases where the user doesn't name the domain directly ("even if they don't mention X"). One sentence, both halves present.
• SKILL.md at root, references/ for deep-dive, examples/ if applicable
• ## Summary with What, When to use, When NOT to use, Overview
• ## Quick Reference near top — tables/code blocks, not prose
• ## Common Pitfalls table (Mistake / Cause / Fix) captures counterintuitive, environment-specific facts the agent would get wrong without being told — not generic advice
• ## Examples table linking to example files
• ## Reference files with "when to use" framing
• Stability classification (v1-STABLE or v1-SENSITIVE) below title

Content Quality

• SKILL.md body under 500 lines
• One term per concept throughout (no synonym alternation)
• Examples don't contradict any documented rule/pattern
• Reference files use same API style as SKILL.md
• Progressive disclosure: metadata (L1) -> instructions (L2) -> bundled resources (L3)
• References one level deep from SKILL.md (no deep nesting)
• Degrees of freedom match task fragility (narrow bridge = specific; open field = general)
• No explaining the obvious: omit what the agent already knows (general concepts, standard libraries, common protocols) — every token should earn its place
• Concise over exhaustive: stepwise guidance with a working example beats encyclopedic coverage — if content covers every edge case, check whether most are better left to agent judgment
• Defaults over menus: when multiple tools/approaches apply, one is the default with brief escape hatch — not equal-weight lists of options
• Short, generic parentheticals: keep inline "e.g." examples short and generic. Drop overly-specific example phrases unless they disambiguate a rule — when in doubt, cut them.
• Extracted content keeps an entry point: when content moves to a reference file (line-count, depth, or scope reasons), SKILL.md retains (a) an inline summary or canonical table for the extracted topic, (b) a specific load-trigger pointer naming what's in the reference file, AND (c) a Reference Files table row. The agent must still discover the topic from SKILL.md alone.
• Grounded, not generic: guidance reflects specific APIs, conventions, and failure modes — if a paragraph could apply to any project ("follow best practices", "handle errors appropriately"), cut or replace it with the project-specific rule it's standing in for