| name | skill-lint |
| description | Checks Claude Code skills against official best practices and reports violations. Triggers on "skill-lint", "スキルチェック", "lint skill", "ベストプラクティスチェック", or requests to validate skill structure, naming, or quality.
|
Skill Lint
Validate skills against The Complete Guide to Building Skills for Claude.
Usage
Run the lint script with the path to a skill directory or parent directory. Use absolute path.
python3 /path/to/skills/skill-lint/scripts/skill-lint.py <target> [OPTIONS]
Build the absolute path from the skill's Base directory.
| Flag | Description | Default |
|---|
<target> | Skill directory or parent containing multiple skills | (required) |
--format | table or json | table |
Single skill
python3 /path/to/scripts/skill-lint.py skills/suggest-permissions/
All skills
python3 /path/to/scripts/skill-lint.py skills/
Checks
Frontmatter
| Check | Severity | Description |
|---|
frontmatter-xml | ERROR | XML angle brackets (< >) in frontmatter (injection risk) |
name-missing | ERROR | name field is missing |
name-length | ERROR | name exceeds 64 chars |
name-format | WARN | name is not lowercase/digits/hyphens |
name-reserved | ERROR | name contains "claude" or "anthropic" |
name-mismatch | WARN | name doesn't match directory name |
description-missing | ERROR | description field is missing |
description-length | ERROR | description exceeds 1024 chars |
description-xml | ERROR | XML angle brackets in description |
description-vague | WARN | description too generic (e.g. "Helps with projects") |
description-short | WARN | description under 30 chars |
description-no-triggers | WARN | description lacks trigger conditions |
compatibility-length | WARN | compatibility exceeds 500 chars |
Body Content
| Check | Severity | Description |
|---|
body-length | ERROR/INFO | Body exceeds 500 lines (ERROR) or 300 lines (INFO) |
body-word-count | WARN | Body exceeds 5,000 words |
broken-reference | ERROR | Referenced file does not exist |
stale-date | WARN | Body contains date patterns that may become stale |
nested-reference | WARN | Reference file links to other references |
no-examples | INFO | No examples section found |
no-troubleshooting | INFO | No troubleshooting/error handling section |
Structure
| Check | Severity | Description |
|---|
readme-in-skill | WARN | README.md found inside skill folder |
no-checklist | WARN | Multi-step workflow without progress checklist |
no-toc | INFO | Long reference file (100+ lines) without TOC |
windows-path | WARN | Windows-style paths detected |
ambiguous-filename | INFO | Generic filename (helper, utils, misc, etc.) |
Scripts
| Check | Severity | Description |
|---|
magic-number | INFO | Argparse default without named constant |
silent-exception | WARN | Exception swallowed with pass/continue |
no-error-handling | INFO | No try/except in 50+ line script |
no-set-e | INFO | Shell script without set -e |
Examples
User: 「スキルチェックして」
→ カレントディレクトリの skills/ を対象にスクリプトを実行し、結果を報告。
User: "lint skill suggest-permissions"
→ skills/suggest-permissions/ を対象にスクリプトを実行し、指摘ごとに修正案を提示。
Troubleshooting
スクリプトが見つからない
Base directory からの絶対パスが間違っている。スキルの展開先を確認する。
全チェック通過しているのに品質が低い
Lint は構造とメタデータのみをチェックする。指示の具体性や workflow の妥当性は手動レビューが必要。
Severity Levels
| Level | Meaning |
|---|
| ERROR | Clear best practices violation (missing frontmatter, security issue) |
| WARN | Non-compliance with recommendations (vague description, README in skill) |
| INFO | Improvement suggestion (add examples, add TOC) |
Interpreting Results
Present findings grouped by skill. For each finding, explain the issue and suggest a fix.
If no issues found, confirm the skill passes all checks.
