Skill Review

Skill Review

IRON LAW: Be specific and actionable. Never say "could be improved" without stating exactly what to change and why it matters for model output quality.

Workflow

Skill Review Progress:

- [ ] Step 1: Load Target ⚠️ REQUIRED
  - [ ] 1.1 Identify skill path
  - [ ] 1.2 Read SKILL.md and inventory all files
- [ ] Step 2: Analyze ⚠️ REQUIRED
  - [ ] 2.1 Structure compliance
  - [ ] 2.2 Description quality
  - [ ] 2.3 Workflow design
  - [ ] 2.4 Token efficiency
  - [ ] 2.5 Anti-pattern detection
- [ ] Step 3: Report ⚠️ REQUIRED
  - [ ] 3.1 Strengths (what's done well)
  - [ ] 3.2 Suggestions (prioritized improvements)

Step 1: Load Target ⚠️ REQUIRED

Identify the skill to review. Accept:

• Explicit path: /skill-review path/to/skill
• Current directory context: if user is already in a skill folder
• Skill name: search within the workspace for matching skill directory

Read the full SKILL.md and list all files in the skill directory. Count SKILL.md line count — this is a key metric.

Step 2: Analyze ⚠️ REQUIRED

Load references/review-criteria.md for detailed criteria. Evaluate the skill across five dimensions:

2.1 Structure Compliance

Questions to answer:

• Does the directory follow the standard layout (SKILL.md, scripts/, references/, assets/)?
• Is SKILL.md under 500 lines?
• Does frontmatter contain only name and description (plus optional allowed-tools, license, metadata)?
• Are there unnecessary files (README.md, CHANGELOG.md, LICENSE duplicates)?
• Are references organized by domain with one level of nesting?

2.2 Description Quality

Questions to answer:

• Does the description include concrete trigger keywords and phrases?
• Does it use keyword bombing (multiple phrasings of the same intent)?
• Is it self-contained — can a router understand what this skill does without reading the body?
• Does it avoid putting "When to Use" info in the body instead of the description?
• Would a user's natural language query match this description?

2.3 Workflow Design

Questions to answer:

• Is there a trackable checklist with copy-paste-friendly format?
• Are critical steps marked with ⚠️ REQUIRED or ⛔ BLOCKING?
• Are there confirmation gates before destructive/generative operations?
• Is the workflow linear and progressive, or does it jump around?
• Are sub-steps used where complexity demands it?

2.4 Token Efficiency

Questions to answer:

• Is there an Iron Law or core constraint at the top?
• Does SKILL.md only contain what Claude doesn't already know?
• Are references loaded progressively (on-demand) rather than all upfront?
• Are instructions in imperative form (not "You should...")?
• Are scripts executed rather than loaded into context?
• Is there redundancy between SKILL.md and reference files?

2.5 Anti-Pattern Detection

Check for these known bad patterns:

• Vague directives ("ensure good quality", "make it better")
• Placeholder residue (TODO, FIXME, xxx, TBD)
• Over-specification of things Claude already knows
• No anti-patterns section (model has no guardrails against lazy defaults)
• Missing pre-delivery checklist (no concrete verification criteria)
• Giant monolithic SKILL.md with no reference extraction
• Instructions that describe WHAT rather than constrain HOW

Step 3: Report ⚠️ REQUIRED

Output Format

Present the review in this order:

1. Strengths — What this skill does well. Be specific: quote the actual lines or patterns that work. Minimum 2 strengths, even for weak skills (find what's salvageable).

2. Suggestions — Improvements sorted by impact (highest first). Each suggestion must include:

• What: the specific issue found
• Where: file and location
• Fix: concrete actionable change (show before/after when helpful)

Group suggestions by dimension only if there are many (5+). Otherwise present as a flat prioritized list.

Tone

• Direct, constructive, collegial
• Lead with genuine strengths — not filler praise
• Suggestions are opportunities, not failures
• If the skill is already solid, say so briefly and move on

Anti-Patterns for This Skill

• Giving vague praise ("nice structure!") without quoting what specifically works
• Listing problems without actionable fixes
• Reviewing against personal taste rather than the documented principles
• Suggesting over-engineering for simple skills
• Flagging missing features that the skill intentionally omits (check if simplicity is the point)

Review Criteria Reference

Detailed criteria for each review dimension. Load this file during Step 2 analysis.

Structure Compliance — Detailed Checks

Required

• SKILL.md exists at root
• Frontmatter has name field (matches directory name)
• Frontmatter has description field (non-empty, >50 chars)

Expected

• SKILL.md ≤ 500 lines (hard limit; flag if >400 as approaching)
• No files that serve no purpose: README.md (unless skill IS about READMEs), CHANGELOG.md, CONTRIBUTING.md
• scripts/ — if present, all files are executable and tested
• references/ — if present, each file is referenced from SKILL.md with load instructions
• assets/ — if present, files are used in output, not loaded into context

Red Flags

• SKILL.md > 500 lines → must extract to references
• Deeply nested references (2+ levels) → flatten
• Orphaned files (not referenced from SKILL.md)
• Scripts without clear invocation instructions in SKILL.md

Description Quality — Detailed Checks

Keyword Bombing Indicators (Good)

• 3+ verb variations for the same action (create/build/write/make)
• Noun variations (skill/agent/tool/plugin)
• Natural phrases a user would type
• Both imperative ("create a skill") and question form ("how do I build a skill")

Description Anti-Patterns (Bad)

• Single-sentence description under 100 characters
• Only technical terms, no natural language triggers
• Describes implementation ("Uses markdown frontmatter...") instead of user intent
• Contains instructions meant for the model body

Scoring Heuristic

• Count unique trigger phrases → <3 is weak, 5-8 is good, >10 is excellent
• Check if casual user language would match → try 3 hypothetical queries mentally

Workflow Design — Detailed Checks

Checklist Quality

• Uses - [ ] format (copy-paste friendly)
• Steps are numbered and sequential
• Sub-steps use indentation
• ⚠️ marks appear on steps that must not be skipped
• ⛔ marks appear on prerequisites/blockers

Confirmation Gates

Must exist before:

• File creation/deletion/overwrite
• External API calls with side effects
• Long-running generative operations
• Applying analysis results to code

Flow Quality

• Can a reader understand the full process from the checklist alone?
• Are conditional branches clearly marked?
• Is there a clear start and end state?

Token Efficiency — Detailed Checks

Iron Law

• Present: yes/no
• Placed at top (before workflow): yes/no
• Specific and falsifiable: yes/no (bad: "write good code"; good: "never use placeholder text")
• Addresses the #1 likely failure mode: yes/no

Progressive Loading Signals (Good)

• "Load references/X.md for..." with clear trigger conditions
• References loaded at specific workflow steps, not all in Step 1
• Large context only loaded when that branch is taken

Bloat Signals (Bad)

• Explaining things Claude knows (how to write markdown, what JSON is)
• "You should" / "You will" / "Remember to" (wasted tokens on filler)
• Duplicated instructions (same thing said in workflow AND in later section)
• Comments/explanations aimed at human readers, not model behavior

Anti-Pattern Detection — Detailed Examples

Vague Directives (rewrite as questions)

• ❌ "Ensure the output is high quality"
• ✅ "Does every heading have ≥2 sentences of content beneath it?"

Over-Specification

• ❌ "Use markdown headers with # for h1, ## for h2..." (Claude knows this)
• ✅ "Use exactly 2 levels of headers: # for sections, ## for subsections" (this constrains)

Missing Guardrails

• No anti-patterns section = model will take lazy defaults
• No pre-delivery checklist = no verification step
• No Iron Law = no north star for quality decisions

Monolithic SKILL.md

• If SKILL.md > 300 lines, check: could any section be a reference loaded on-demand?
• Domain knowledge that applies to only one step → extract to reference
• Examples longer than 10 lines → extract to reference