Skills

First Pass: Structure and Security

Focus Areas:

• Not done: YAML frontmatter present and valid
• Not done: Skill file size ≤ 500 lines (progressive disclosure requirement)
• Not done: No hardcoded secrets or credentials
• Not done: File references point to existing files
• Not done: Supporting files are properly organized

Critical Issues to Flag Immediately:

• Missing YAML frontmatter (skill won’t be recognized)
• File > 500 lines without progressive disclosure
• Hardcoded API keys, tokens, or passwords
• Broken file references
• Committed settings.local.json

Second Pass: YAML Frontmatter Validation

Required Fields:

Optional Fields:

Check For:

• Not done: name field exists and is kebab-case
• Not done: description field exists and is clear
• Not done: Description includes activation triggers (when to use)
• Not done: YAML syntax is valid (proper indentation, no tabs)
• Not done: If versioned, follows semver (MAJOR.MINOR.PATCH)

Common Issues:

• Missing name or description
• Name not in kebab-case (use-dashes-not-underscores)
• Description too vague (“does stuff” → specify what and when)
• Malformed YAML (tabs instead of spaces, missing colons)

Third Pass: Progressive Disclosure

Main skill.md Requirements:

• Not done: File size ≤ 500 lines
• Not done: Clear routing logic (when to load which files)
• Not done: Structured thinking blocks guide decision-making
• Not done: References supporting files explicitly

Supporting Files Requirements:

• Not done: Each file is self-contained (understandable in isolation)
• Not done: Clear purpose stated at top of file
• Not done: No circular dependencies between files
• Not done: Loaded on-demand, not all at once

File Organization Patterns:

Red Flags:

• Main skill.md > 500 lines (should be split into supporting files)
• Supporting files reference each other in circles
• All context loaded upfront instead of on-demand
• Supporting files not self-contained (require reading multiple files)

Fourth Pass: Prompt Engineering Quality

Clarity:

• Not done: Instructions are specific, not vague
• Not done: Technical terms are defined or demonstrated
• Not done: Expected behavior is clearly stated
• Not done: Step-by-step procedures where appropriate

Examples:

• Not done: Code examples for patterns to follow
• Not done: Sample outputs showing expected format
• Not done: Anti-patterns demonstrated (what NOT to do)
• Not done: File structure examples where relevant

Emphasis:

• Not done: Bold for critical requirements
• Not done: Code blocks for technical terms and examples
• Not done: Headers organize content logically
• Not done: Lists break down complex information

Structured Thinking:

• Not done: <thinking> blocks guide systematic analysis
• Not done: Key questions posed before each major step
• Not done: Decision criteria made explicit
• Not done: Reasoning process modeled for complex decisions

Constructive Tone:

• Not done: Focus on “do this” not just “don’t do that”
• Not done: Explain rationale (why things matter)
• Not done: Provide actionable fixes, not just problem identification
• Not done: Avoid blame or judgment language

Fifth Pass: Token Efficiency

Efficient Organization:

• Not done: Progressive disclosure implemented (load only what’s needed)
• Not done: No duplicate information across files
• Not done: Reference other docs instead of copying content
• Not done: Clear routing to minimize unnecessary context loading

Concise Language:

• Not done: Direct statements preferred over verbose explanations
• Not done: Technical precision without fluff
• Not done: Examples are minimal but sufficient
• Not done: Headers and structure reduce need for transitional text

Avoid:

• Repeating same information in multiple places
• Loading all context upfront “just in case”
• Verbose explanations when examples suffice
• Including information not directly relevant to task

Priority Classification

Classify findings using reference/priority-framework.md:

• CRITICAL - Prevents functionality or exposes security vulnerabilities
• IMPORTANT - Significantly impacts quality or maintainability
• SUGGESTED - Improvements that aren’t essential
• OPTIONAL - Personal preferences

Common Skill Anti-Patterns

Monolithic Skills:

• Single file > 500 lines
• All context loaded upfront
• No progressive disclosure strategy
• Fix: Split into main orchestration + supporting files

Vague Activation:

• Description: “Helps with code stuff”
• Better: “Reviews Kotlin code for MVVM violations. Use when checking ViewModels, state management, or UI layer architecture.”

Missing Structured Thinking:

• Instructions without guidance on reasoning process
• No decision criteria for complex choices
• Fix: Add <thinking> blocks with key questions

Broken Progressive Disclosure:

• Supporting files reference each other circularly
• Files not self-contained
• Unclear when to load what
• Fix: Clear routing logic, self-contained files

Token Waste:

• Duplicate information across files
• Loading all context upfront
• Verbose explanations without adding value
• Fix: Reference instead of duplicate, load on-demand

Final Checklist Summary

Before completing review, verify:

• Not done: YAML frontmatter present and valid
• Not done: Main skill.md ≤ 500 lines
• Not done: No security issues (secrets, credentials)
• Not done: All file references valid
• Not done: Progressive disclosure properly implemented
• Not done: Structured thinking blocks present
• Not done: Clear activation triggers in description
• Not done: Examples provided for complex concepts
• Not done: Token-efficient organization
• Not done: Constructive, actionable feedback tone