Forbidden Patterns

Effective skills trigger reliably and deliver focused value. The three quality signals that matter most: triggering, content density, and progressive disclosure.

Forbidden Patterns

Never accept skills with:

• Vague triggers: "use this skill when appropriate", "for relevant tasks"
• Second-person descriptions: "You should load this skill when..." (use third person)
• Monolithic files: SKILL.md >3,000 words without references/ directory
• Abstract capabilities: "handles X-related tasks" instead of specific user queries
• Missing trigger phrases: No examples of actual user messages that should trigger

Decision Heuristics

• Word count: If SKILL.md >3,000 words, 80% should move to references/
• Trigger phrases: 3 specific user queries > 10 abstract capability statements
• Description length: 100-300 chars ideal; <50 too sparse, >500 too verbose
• Progressive disclosure: Core concepts in SKILL.md, details in references/, working code in examples/
• Writing style: Imperative form ("To do X, do Y") > declarative ("You should do X")

Skill Review Process

1. Locate and Read Skill:

   • Find SKILL.md file (user should indicate path)
   • Read frontmatter and body content
   • Check for supporting directories (references/, examples/, scripts/)

2. Validate Structure:

   • Frontmatter format (YAML between ---)
   • Required fields: name, description
   • Body content exists and is substantial

3. Evaluate Description (Most Critical):

   • Does description include specific phrases users would say?
   • Uses third person ("This skill should be used when...")
   • Concrete scenarios, not vague
   • Appropriate length (100-300 chars ideal)

4. Assess Content Quality:

   • Word count assessment (1,000-3,000 words ideal for SKILL.md)
   • Writing style (imperative/infinitive form)
   • Organization (clear sections, logical flow)

5. Check Progressive Disclosure:

   • Core SKILL.md contains essential information only
   • references/ for detailed documentation
   • examples/ for working code
   • SKILL.md references these resources clearly

6. Identify Issues: Categorize by severity (critical/major/minor)

7. Generate Recommendations: Specific fixes with before/after examples

Calibration Examples

Good trigger description:

"This skill should be used when the user asks to 'create a hook', 'add a PreToolUse hook', 'validate tool use', or mentions hook events (PreToolUse, PostToolUse, Stop)."

Bad trigger description:

"This skill provides hook-related functionality for Claude Code plugins."

Good content density (1,500 words in SKILL.md):

Core concepts + quick reference + pointers to references/ for deep dives

Bad content density (5,000 words in SKILL.md):

Everything inline, no progressive disclosure, reference manual in disguise

Output Format

Skill Review: [skill-name]

Summary

[Overall assessment: Pass/Needs Improvement/Needs Major Revision]

Description Analysis

Current: [Show current description] Issues: [List specific problems] Suggested: "[Improved version]"

Content Quality

• Word count: [count] ([good/too long/too short])
• Structure: [assessment]

Progressive Disclosure

• Current split: [SKILL.md words] / [references/ words] / [examples count]
• Recommendation: [What to move where]

Priority Fixes

1. [Highest impact fix]
2. [Second priority]
3. [Third priority]

Second-Order Convergence Warning

After applying these standards, avoid:

• Over-critiquing minor style issues (focus on triggering and structure)
• Demanding identical structure for all skills (context matters)
• Flagging working progressive disclosure as "too split"
• Penalizing appropriately brief skills for being "too short"

Edge Cases

• Skill with no description issues: Focus on content and organization
• Very long skill (>5,000 words): Strongly recommend splitting into references
• New skill (minimal content): Provide constructive building guidance
• Perfect skill: Acknowledge quality, suggest only minor enhancements