Skill Linter

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...

Security Scan

The skill's declared purpose (linting SKILL.md files) matches its instructions and included code; it requests no credentials and has no install step, though it can read and (by frontmatter) be allowed to edit files you point it at.

Purpose & Capability

Name/description, the SKILL.md runtime instructions, and the provided Python linter are all aligned: they parse YAML frontmatter and check the markdown body for best practices. The skill requests no unrelated binaries, env vars, or config paths. Note: the included script accepts an arbitrary filepath argument and will read whatever file path it is given — functionally consistent with a linter but means the script can read any file you pass to it.

Instruction Scope

SKILL.md instructs the agent to load and analyze a SKILL.md file and produce a structured report — the linter code implements exactly that. The top frontmatter includes allowed-tools: Read, Edit, Write, which is reasonable if the skill will propose or apply edits, but it also expands the agent's ability to read/write files. The code itself does not access network endpoints or other system state beyond reading the supplied file path.

Install Mechanism

No install spec is present (instruction-only usage). A Python file is included but there is no automatic install/download or archive extraction. This is low risk: nothing is fetched from external URLs and no installers run.

Credentials

The skill requires no environment variables, credentials, or config paths. The absence of secrets or unrelated env requests is proportionate to a documentation/linting tool.

Persistence & Privilege

always:false and user-invocable:true (defaults) — no persistent/always-on privilege requested. The skill does not attempt to modify other skills or system-wide agent settings. The only potential privilege is file read/write if the agent is granted allowed-tools permissions.

Assessment

This skill appears coherent and focused: it lints SKILL.md files, needs no credentials, and includes a straightforward Python script that reads the file you provide and prints a report. Before installing or granting file access, consider: 1) only run it against SKILL.md files (or review the script) because it will read any path you pass it; 2) if you don't want the skill to modify files, remove or avoid granting the 'Write'/'Edit' allowed-tools or ensure it runs in read-only mode; 3) if you need higher assurance, review the included skill_linter.py locally to confirm there are no network calls or surprising behavior and run it on a sample SKILL.md first.

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)

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.