📖 技能介绍

name: skill-linter description: Analyze and validate SKILL.md files for best practices, common issues, and improvement suggestions. Use when reviewing a Skill, creating a new Skill, or when asked to check/audit/improve a SKILL.md file. allowed-tools: Read, Edit, Write

Skill Linter & Advisor

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

Analysis Process

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

Validation Checklist

Frontmatter (YAML Header)

Check	Severity	Description
Has `---` delimiters	🔴 Critical	Must have opening and closing `---`
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

# 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:

```yaml
---
# 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:**
```markdown
## 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.

🤖 AI 评测

这是一份质量较高的 Skill 工具文档，结构完整、条理清晰，提供的内容检查清单详细实用，评分机制设计合理。优点是规范到位、示例丰富、容易上手；不足是描述较为技术化，对普通用户理解有一定门槛，且在深度评估方面还有提升空间。整体而言，这是一个可靠的参考模板，适合需要创建或审核 Skill 的用户使用。