Skill Linter & Advisor

Analyze SKILL.md files against Claude Code Skills best practices and provide actionable feedback.

Analysis Process

1. 1. Read the SKILL.md file - Load the complete content
2. Parse frontmatter - Validate YAML structure and required fields
3. Check content structure - Verify best practices for the markdown body
4. Compare against patterns - Match against known good Skill patterns
5. Generate report - Provide structured feedback with severity levels

Validation Checklist

Frontmatter (YAML Header)

Check	Severity	Description
Has --- delimiters	🔴 Critical	Must have opening and closing INLINECODE1
Valid YAML syntax

🔴 Critical | YAML must parse without errors | | Has name field | 🟡 Warning | Defaults to directory name, but explicit is better | | Has description | 🔴 Critical | Required for auto-trigger to work | | Description quality | 🟡 Warning | Should be specific, mention when to use | | disable-model-invocation | 🟢 Info | Only set if you want manual-only | | user-invocable | 🟢 Info | Set to false to hide from / menu | | allowed-tools | 🟡 Warning | Specify if Skill needs specific tools | | model override | 🟢 Info | Only if you need specific model | | context: fork | 🟢 Info | Use for long-running or isolated tasks | | agent with context | 🟢 Info | Required when context: fork |

Content Structure

Check	Severity	Description
Has clear title/heading	🟡 Warning	First line should indicate purpose
Has process/steps

🟡 Warning | Skills should have actionable steps | | Has output format | 🟡 Warning | Define expected output structure | | Uses specific language | 🟡 Warning | Avoid vague terms like "etc", "etc." | | Has examples | 🟢 Info | Concrete examples improve reliability | | Has constraints/guardrails | 🟢 Info | Define what NOT to do | | Appropriate length | 🟡 Warning | Too short (<100 words) or too long (>2000) |

Common Issues

Issue	Severity	Fix
Missing description	🔴 Critical	Add description explaining when to trigger
Description too vague

🟡 Warning | Be specific about use cases | | No clear output format | 🟡 Warning | Add expected output structure | | Missing tool declarations | 🟡 Warning | Add allowed-tools if using tools | | Too many responsibilities | 🟡 Warning | Split into multiple focused Skills | | Hardcoded paths | 🟡 Warning | Use variables or relative paths | | No error handling guidance | 🟢 Info | Add what to do when things go wrong |

Output Format

CODEBLOCK0yaml

---

improved frontmatter

---

Improved content...

CODEBLOCK1

Skill Patterns Reference

Pattern 1: Checklist/Task Skill

For: Code review, testing, validation tasks

Structure:

• - Clear trigger description
• Step-by-step process
• Checklist categories
• Severity ratings
• Structured output format

Pattern 2: Generator Skill

For: Documentation, commit messages, reports

Structure:

• - Input requirements
• Analysis steps
• Template/format specification
• Examples
• Constraints

Pattern 3: Explorer/Research Skill

For: Code exploration, debugging, analysis

Structure:

• - Context gathering (!commands)
• Investigation steps
• What to look for
• How to present findings

Pattern 4: Workflow Skill

For: Multi-step processes, releases, deployments

Structure:

• - Prerequisites check
• Sequential steps
• Validation points
• Rollback guidance

Examples of Good Descriptions

✅ Good:

• - "Perform a thorough code review following the team checklist. Use when reviewing code changes, pull requests, or when the user asks for a code review."
• "Generate API documentation from source code. Use when the user asks to document an API endpoint, route handler, or controller."
• "Create a standardized git commit message following Conventional Commits format. Use when the user asks to commit or create a commit message."

❌ Bad:

• - "Does code review" (too vague)
• "Helps with documentation" (when?)
• "A skill for git" (too broad)

Examples of Good Output Formats

✅ Good:
CODEBLOCK2

❌ Bad:
CODEBLOCK3