A Claude Code plugin for validating, linting, and scoring Agent Skill (SKILL.md) files.

The plugin's main feature is an auto-lint hook that runs after every SKILL.md edit, feeding results back to Claude as context so it can self-correct quality issues in the same turn.

Inside Claude Code:

/install-plugin https://github.com/skill-tools/skill-tools-plugin

For local development:

claude --plugin-dir /path/to/skill-tools-plugin

• Node.js 18+ and npx
• macOS or Linux (shell-based hooks; Windows is not currently supported)

After installing, run the dependency checker to verify and pre-warm the cache:

bash /path/to/skill-tools-plugin/scripts/setup.sh

If <path> is omitted, the command finds all SKILL.md files in the project.

A PostToolUse hook watches for Write and Edit tool calls. When the target file is a SKILL.md, the hook:

1. Runs skill-tools lint --format json (no ANSI, machine-readable)
2. Builds a plain-text summary from the JSON
3. Returns it as additionalContext so Claude sees the results immediately

The hook is pinned to skill-tools@0.2.2 to avoid supply chain risk. It silently skips if dependencies are missing — it never blocks edits.

The skill-quality skill activates when working on SKILL.md files. It teaches the thinking behind good skills rather than restating the linter's rules:

• Why descriptions matter for agent selection
• How to write instructions that guide well (examples, error handling, structure)
• When to split large skills using progressive disclosure
• Common lint failures and the reasoning behind each fix

Run the test suite:

bash tests/test-hook.sh

This tests hook input validation, JSON output structure, graceful degradation, and plugin manifest correctness.

skill-tools-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── check.md
│   └── lint.md
├── hooks/
│   ├── hooks.json
│   └── post-write-lint.sh
├── skills/
│   └── skill-quality/
│       └── SKILL.md
├── scripts/
│   └── setup.sh
├── tests/
│   └── test-hook.sh
├── CHANGELOG.md
├── LICENSE
├── .gitignore
└── README.md

The skill-tools npm package version is pinned in four places:

• hooks/post-write-lint.sh — SKILL_TOOLS_VERSION variable
• scripts/setup.sh — SKILL_TOOLS_VERSION variable
• commands/check.md — version in the npx command
• commands/lint.md — version in the npx command

All four must be updated together. Search for the old version string to find them.

MIT — see LICENSE.