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 purpose (linting SKILL.md) matches what the code does, but there are multiple small inconsistencies (instruction-only claim vs. included Python script, missing dependency declarations, and an overly-broad allowed-tools hint) that merit caution before installing.

Purpose & Capability

Name/description match the observed behavior: the code and SKILL.md both implement a SKILL.md linter. However the registry metadata claims 'instruction-only' while a Python implementation (skill_linter.py) is present — that mismatch and the lack of declared runtime dependencies (Python module 'yaml'/PyYAML) are unexpected.

Instruction Scope

Runtime instructions and the Python code operate only on the SKILL.md file provided as input (parse frontmatter, analyze body, print a report). There are no network calls, credential access, or references to unrelated system paths. Note: the frontmatter includes allowed-tools: Read, Edit, Write which suggests write capability, but neither the instructions nor the visible code require network/credential access or sweep other files.

Install Mechanism

There is no install spec, but a Python script is included. The package does not declare runtime requirements (python3, PyYAML). That omission can cause runtime failures or hidden implicit requirements; the skill will need a Python runtime and the 'yaml' package even though the registry lists no dependencies.

Credentials

The skill requests no environment variables, no credentials, and the code does not read env vars or secrets. Its file access is limited to the SKILL.md path supplied by the user, which is proportionate to its purpose.

Persistence & Privilege

Flags are normal (always: false, user-invocable true). The skill does not request permanent presence or modify agent-wide settings in the visible code. No evidence it writes to other skills or global config.

What to consider before installing

This skill appears to implement a legitimate SKILL.md linter, but review these before installing: - The registry claims 'instruction-only' yet includes a Python script (skill_linter.py). Inspect the full script yourself (it appears to only parse and print reports) and confirm you trust the author. - The package does not declare runtime dependencies. Ensure your environment has Python 3 and the PyYAML package (the code imports 'yaml') before running. - The SKILL.md frontmatter lists allowed-tools: Read, Edit, Write. The linter reads the SKILL.md you point it at — avoid passing paths to sensitive files. Confirm whether the skill will ever be allowed to perform writes on your system; if you do not want it to modify files, restrict its permissions or run it in a sandbox. - Because this is an included script (not a vetted install), prefer running it in an isolated environment (container or temporary VM) if you are unsure. If you plan to install for regular use, ask the owner to: 1) Update registry metadata to declare this is a code-backed skill (not instruction-only); 2) Add explicit dependency declarations (python, PyYAML) or provide an install spec; 3) Clarify whether the skill will write changes and whether allowed-tools: Write is required. These changes will remove the remaining incoherence and raise confidence.

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.