Skill Linter & Advisor

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

Analysis Process

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)

Content Structure

Common Issues

Output Format

# Skill Analysis Report

## File: {filepath}

### Frontmatter Analysis

| Field | Status | Value | Notes |
|-------|--------|-------|-------|
| name | ✅/⚠️/❌ | {value} | {feedback} |
| description | ✅/⚠️/❌ | {value} | {feedback} |
| ... | | | |

**Frontmatter Score:** X/10

### Content Analysis

| Check | Status | Notes |
|-------|--------|-------|
| Has clear purpose | ✅/⚠️/❌ | {feedback} |
| Actionable steps | ✅/⚠️/❌ | {feedback} |
| Output format defined | ✅/⚠️/❌ | {feedback} |
| Has examples | ✅/⚠️/❌ | {feedback} |
| Appropriate length | ✅/⚠️/❌ | {word_count} words |

**Content Score:** X/10

### Issues Found

#### 🔴 Critical (Must Fix)
1. {issue description} → {fix suggestion}

#### 🟡 Warnings (Should Fix)
1. {issue description} → {fix suggestion}

#### 🟢 Suggestions (Nice to Have)
1. {issue description} → {fix suggestion}

### Overall Assessment

**Total Score:** X/10

**Verdict:**
- ✅ Excellent - Ready to use
- 🟡 Good - Minor improvements suggested
- ⚠️ Needs Work - Address warnings before using
- ❌ Critical Issues - Must fix before using

### Recommended Actions

1. {action item}
2. {action item}
3. {action item}

### Improved Version (Optional)

If significant improvements are needed, provide a rewritten SKILL.md:

improved frontmatter

Improved content...

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:

## Output Format

Structure your review as:

**Summary**
[One-paragraph overall assessment]

**Critical Issues**
[Must fix before merging]

**Approved?**
[YES / NO / YES WITH CONDITIONS]

❌ Bad:

Just give me a review of the code.