Skill Review

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

• 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

Step 2: Analyze ⚠️ REQUIRED

2.1 Structure Compliance

• 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

• 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

• 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

• 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

• 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

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

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)