agent-skill-linter

Lint agent skills for spec compliance and publishing readiness. Checks what a GitHub release needs: SKILL.md frontmatter, LICENSE, badges, CI, and README sections, with auto-fix for the common ones.

Installation

Recommended: npx skills

npx skills add William-Yeh/agent-skill-linter

Manual installation

Copy the skill/ directory to your agent's skill folder as agent-skill-linter:

Agent	Directory
Claude Code	~/.claude/skills/
Codex	.agents/skills/
Pi	.pi/skills/
oh-my-pi	.omp/skills/

Usage

After installing, try these prompts with your agent:

• Lint the skill in this directory for publishing readiness
• Check ~/projects/my-skill for spec compliance and fix any issues
• Triage this skill and tell me what's blocking a GitHub release

CLI

Run the script directly from the installed skill directory:

./scripts/skill-lint.py check ./my-skill          # Lint a skill directory
./scripts/skill-lint.py check .                    # Lint repo-root skill
./scripts/skill-lint.py check ./my-skill --fix    # Auto-fix fixable issues
./scripts/skill-lint.py check ./my-skill --format json  # JSON output for CI

Requires uv. Exit code: 1 if errors, 0 otherwise.

What Gets Checked

The linter checks ~20 rules across seven categories:

• Spec compliance — SKILL.md frontmatter, required fields, version (Rule 1, Error; Claude Code-only fields warn)
• Repo hygiene — LICENSE, CI workflow, README sections, badges (Rules 2–7)
• Routing signal quality — description prefix, gerund names (Rule 11, plus semantic Steps 5/6)
• Progressive disclosure — body size, reference-tier headings moved to references/ (Rules 9, 14, 15, plus semantic Step 8)
• Multi-step workflow quality — exit conditions, retry caps, observable triggers (semantic Steps 8 and 9)
• Plugin mode — manifest validity, script dep declarations (Rules 24, 25, Error)
• Plain prose — README and user guide say what the skill does, in short sentences, without marketing fluff (Rule 28, plus semantic Step 10)

For the full rule list with severities and auto-fix status, see skill/SKILL.md. Semantic rules are the checks regex can't make. They live in skill/references/semantic-rules.md, and the agent applies them in Steps 5–10 of the triage workflow.

Plugin layout

When the lint target contains .claude-plugin/plugin.json, the linter switches to plugin mode: validates the manifest, checks each skill's script dependencies, and runs the per-skill rule pack across all skills/<name>/ directories. Single-skill repos lint as before.

Repo root as target

skill-lint check . from a repo that keeps its skill in skill/ lints that subdirectory and says so on stderr. A SKILL.md at the root still wins, so legacy layouts are unchanged.