claude-skill-lint

Structural validation and token-efficiency tooling for Claude Code skills. Catches the bugs that Claude tolerates but your users pay for.

Jump to: Installation · Quick Start · What It Checks · Repository Formats · Configuration · CI Integration · Changelog

The Problem No One Sees

Claude Code skills load into the context window on every invocation. When a skill references a context file that doesn't exist, Claude doesn't throw an error. It hallucinates the missing context and keeps going. When two skills resolve to the same install path, one silently overwrites the other. When a context file is loaded but nothing references it, you're burning tokens for nothing.

These aren't hypothetical failure modes. They're what we found running claude-skill-lint against a real 139-file production suite:

• 32 broken references. 23 skills referenced a context file that's generated at setup time — in the shareable repo, before setup runs, those skills have no context at all. 9 more referenced a file that had been renamed months earlier. Every one of those skills was silently degraded.
• 11 orphaned files. Context and agent files loaded into the window but referenced by zero skills. Dead weight on every invocation.
• 1 dependency cycle. Two context files referencing each other, pulling both into the window when only one was needed.

Caught in under two seconds. No LLM calls. Deterministic.

"Tolerate" is not "work correctly."

Companion: /sk-review

This repo also includes /sk-review, an LLM-powered deep audit skill that goes beyond structural validation — analyzing signal density, cache-stability, progressive disclosure, instruction quality, and model/effort routing. It produces a scored assessment (0-24) with a prioritized, leverage-ranked optimization plan.

claude-skill-lint catches structural bugs deterministically in CI. /sk-review is an on-demand complement for deeper optimization.

It ships as a standard Agent Skill directory (SKILL.md plus references/). Install it as a user skill:

base=https://raw.githubusercontent.com/shinytoyrobots/claude-skills-linter/main/skills/sk-review
mkdir -p ~/.claude/skills/sk-review/references
curl -fsSo ~/.claude/skills/sk-review/SKILL.md "$base/SKILL.md"
for f in suite-mode opus-5-5-checks report-template; do
  curl -fsSo ~/.claude/skills/sk-review/references/$f.md "$base/references/$f.md"
done

What It Actually Found

Against a 139-file shared skill suite

$ claude-skill-lint graph .
✖ 43 errors and 11 warnings in 54 files (139 files checked)

The headline: inv-output-conventions.md was renamed to inv-output-patterns.md at some point. Nine invention skills still referenced the old name. They silently got no output formatting guidance. A rename bug, invisible at authoring time, caught in seconds.

Against Anthropic's official skills repo (plugin format)

$ claude-skill-lint graph ~/Development/anthropic-skills/
✖ 14 errors and 24 warnings in 37 files (72 files checked)

Name collisions in the claude-api skill — five language-specific claude-api.md files (PHP, Java, Ruby, Go, C#) all resolve to the same canonical name, plus Python/TypeScript duplicates for tool-use.md, streaming.md, files-api.md, and batches.md. One genuinely broken ./README.md reference. Orphaned theme files in theme-factory (loaded dynamically, not via static references) and shared context files referenced only from other context files. All legitimate structural findings.

Against a multi-plugin production repo

$ claude-skill-lint lint ~/Development/work/ai-plugins/
✖ 3 warnings in 3 files (45 files checked)

Three unlisted plugins (valid plugin.json but not declared in the root marketplace.json). Graph validation: clean — zero errors across 45 files. The multi-plugin format's relative path resolution (../../context/foo.md) works correctly.

Frontmatter lint: honest assessment

The lint pass found 34 type errors across the same 139-file suite — argument-hint values parsed as YAML arrays instead of strings, tools fields as comma-separated strings instead of arrays.

Claude Code tolerates all of them. Skills work fine. The linter is being opinionated about structure, enforcing that frontmatter conforms to a schema. That matters when you're sharing skills, publishing to a marketplace, or building tooling that expects consistent types. For personal skills that just work, graph validation is where the real value lives.

The 4 YAML parse errors, on the other hand, are genuinely broken. The frontmatter can't be read at all.

Installation

npm install -g claude-skill-lint

Or directly:

npx claude-skill-lint lint .

Requires Node.js 20+.

Quick Start

claude-skill-lint init           # Auto-detect format, generate config
claude-skill-lint graph .        # Cross-file references — the high-value bugs
claude-skill-lint lint .         # Frontmatter structure

What It Checks

Graph Validation

Builds a dependency graph from cross-file references. Finds:

• Broken references — skill says "read context/foo.md," file doesn't exist. Claude hallucinates the gap.
• Orphaned files — context or agent files that nothing references. Tokens loaded for nothing.
• Name collisions — two files resolve to the same canonical name. One overwrites the other on install.
• Dependency cycles — circular references between files. Context pollution.

Resolves both installed paths (~/.claude/commands/context/foo.md) and relative paths (../../context/foo.md, ./reference/guide.md, agents/scanner.md), with automatic fallback between resolution strategies.

Frontmatter Validation

Validates YAML frontmatter against file-type schemas:

#### Modern Frontmatter Fields

These fields are supported across all file types (command, agent, skill):

At Level 1: model enum validation, known tool verification (including Bash(python*) pattern syntax), tool-to-body consistency, file size limits, effort value validation, skill name format and length (64 characters max).

Skills also get two warnings that explain how Claude Code will actually treat them:

• `description-budget` — description + when_to_use over 1,536 characters. Claude scans that combined text to decide when to auto-invoke; the excess is wasted or truncated.
• `name-dir-mismatch` — frontmatter name differs from the skill's directory. The message says which identifier governs invocation in the detected repo format.

#### Portable mode

Claude Code accepts more than the open Agent Skills spec does. --portable flags what won't survive an upload to claude.ai or the Skills API:

• `non-portable-field` — any frontmatter field outside name, description, license, compatibility, metadata, allowed-tools.
• `non-portable-name` — skill names containing anthropic or claude, which those upload paths reject. Claude Code itself loads them, so this is off unless you ask for portability.

Manifest Validation (plugin format)

Validates marketplace.json and plugin.json structure, source path resolution, name consistency, and missing skill files. A .claude-plugin/ directory may contain only plugin.json and marketplace.json (claude-plugin-contents): a stray skills/ or commands/ there silently breaks plugin loading.

The plugin and marketplace schema (reserved plugin names, MCP server paths, insecure URLs, dependency sources) is owned by Anthropic's official validator, claude plugin validate, and is deliberately not reimplemented here. Run it alongside the linter, or let the linter run it for you and merge the findings into one report:

claude-skill-lint lint . --run-plugin-validate   # requires the Claude Code CLI on PATH; plugin repos only

If the CLI is missing or returns something unparseable, the run fails with a claude-plugin-validate-unavailable error rather than silently skipping the check.

Progressive Quality Levels

Skills mature. The quality bar should mature with them.

Declare per file:

---
name: my-skill
description: Does something useful
quality_level: 1
---

Or set directory defaults in .skill-lint.yaml:

default_level: 0
levels:
  commands/: 1
  agents/: 1

Effective level: max(file declaration, directory default, --level flag). The highest value wins. You can raise the floor but never lower a file's declared level.

Ratchet

claude-skill-lint lint . --ratchet --base origin/main

Compares each file's quality_level against the base branch. If any level decreased, the build fails. Quality improvements become permanent. That's the point.

Repository Formats

claude-skill-lint auto-detects your repository structure. Five formats are supported:

| suite-monorepo | {suite}/commands/*.md and {suite}/skills/{name}/SKILL.md, side by side | Never detected; set format: suite-monorepo |

Detection priority: config override > multi-plugin > plugin > project-skills > legacy-commands. The first match wins.

project-skills: The .claude/skills/ Format

The project-skills format uses .claude/skills/{name}/SKILL.md — the same structure Claude Code uses for project-scoped skills. Each skill lives in its own directory under .claude/skills/.

claude-skill-lint discovers skills in nested .claude/skills/ directories automatically. In monorepo setups where multiple packages each have their own .claude/skills/ directory, point the linter at the repo root and it finds them all.

Hybrid repos work too. A repo with both .claude/skills/ and legacy commands/ directories — or a published plugin that also has project-level skills — gets everything linted in a single run. No configuration needed.

Migration Note

For repos transitioning from legacy commands to modern skills, claude-skill-lint validates both locations in a single run. Set the format explicitly in .skill-lint.yaml if auto-detection picks the wrong one, or omit it and let detection handle the transition — legacy-commands is the fallback when no modern format signals are found.

suite-monorepo: Moving a Suite Repo to SKILL.md

For a repo of suites moving from {suite}/commands/{name}.md to {suite}/skills/{name}/SKILL.md one skill at a time, where installed context and agents are also moving from ~/.claude/commands/ to ~/.claude/. Auto-detection can't identify this mid-migration, so set it explicitly. Add **/.claude/** to ignore if .claude/skills/ holds symlinks to the same skills.

• Both layouts lint together, and ~/.claude/commands/context/foo.md, ~/.claude/context/foo.md and ~/.claude/skills/{name}/SKILL.md all resolve.
• Files in skills/{name}/references/ belong to that skill. Another skill can't reference them, and same-named files in two skills don't collide. They need no frontmatter, and one with no reader in its skill is reported as orphaned.
• A SKILL.md resolves references/foo.md, ${CLAUDE_SKILL_DIR}/references/foo.md, ./foo.md and markdown links against its own directory. A path that leaves the directory is broken, because it won't resolve once installed. Commands get none of this, so their relative links behave as they do in legacy-commands.
• SKILL.md files count as referrers for orphan detection.
• Frontmatter name must equal the directory at every level (name-dir-mismatch is an error here).

Custom Structures

Not every repo follows a standard layout. claude-skill-lint provides three configuration levers for non-standard structures:

skills_root

If your skill files live in a subdirectory rather than the repo root:

skills_root: "packages/my-plugin"

All path resolution starts from this root. Useful for monorepos where skills are nested deep.

format Override

Auto-detection works for standard layouts. When it doesn't — or when your repo is mid-migration between formats — set the format explicitly:

format: plugin          # Force plugin format detection
# format: legacy-commands | plugin | multi-plugin | project-skills | suite-monorepo

ignore Patterns

Exclude paths that look like skills but aren't:

ignore:
  - "**/README.md"
  - "**/CLAUDE.md"
  - "node_modules/**"
  - "docs/**/*.md"
  - "archive/**"

Glob patterns, matched against file paths relative to skills_root. node_modules/ is always excluded.

Commands

claude-skill-lint graph [paths...]

claude-skill-lint graph .                    # Full graph analysis
claude-skill-lint graph . --format json      # JSON output
claude-skill-lint graph . --format github    # GitHub annotations
claude-skill-lint graph . --strict           # Orphan warnings become errors

claude-skill-lint lint [paths...]

claude-skill-lint lint .                                    # Lint everything
claude-skill-lint lint . --level 1                          # Enforce Level 1
claude-skill-lint lint . --strict                           # Warnings become errors
claude-skill-lint lint . --ratchet                          # Prevent quality regression
claude-skill-lint lint . --changed-only --base origin/main  # Only changed files
claude-skill-lint lint . --format json                      # JSON for tooling
claude-skill-lint lint . --format github                    # GitHub Actions annotations
claude-skill-lint lint . --portable                         # Flag Claude-Code-only fields and names that won't upload to claude.ai / Skills API
claude-skill-lint lint . --run-plugin-validate              # Also run `claude plugin validate` (plugin repos)

claude-skill-lint init

claude-skill-lint init           # Auto-detect format, generate config
claude-skill-lint init --force   # Overwrite existing

Exit codes: 0 clean, 1 errors found, 2 config error.

Options

Configuration

claude-skill-lint init generates this. Or create .skill-lint.yaml manually:

skills_root: "."
default_level: 0

levels:
  commands/: 1
  agents/: 1

# Auto-detected if omitted
# format: legacy-commands | plugin | multi-plugin | project-skills | suite-monorepo

models: [opus, sonnet, haiku]

tools:
  mcp_pattern: "mcp__*"
  custom: []

limits:
  max_file_size: 15360

ignore:
  - "**/README.md"
  - "**/CLAUDE.md"
  - "node_modules/**"

graph:
  warn_orphans: true
  detect_cycles: true
  detect_duplicates: true

CI Integration

Exit Codes

By default, warnings are informational — orphaned files and minor issues appear as annotations but don't fail the build. Add --strict to treat warnings as errors and fail on any finding.

GitHub Actions

name: Skill Lint
on:
  pull_request:
    paths: ['**/*.md', '.skill-lint.yaml']

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g claude-skill-lint

      - name: Graph validation
        run: claude-skill-lint graph . --format github

      - name: Lint changed skills
        run: claude-skill-lint lint . --format github --changed-only --base origin/${{ github.base_ref }}

      - name: Quality ratchet
        run: claude-skill-lint lint . --ratchet --base origin/${{ github.base_ref }} --format github

To fail on warnings too, add --strict to any step:

      - name: Graph validation (strict)
        run: claude-skill-lint graph . --format github --strict

--format github produces annotations that appear inline on PR diffs.

Pre-commit Hook

#!/bin/sh
STAGED=$(git diff --cached --name-only --diff-filter=ACM -- '*.md')
if [ -n "$STAGED" ]; then
  npx claude-skill-lint lint $STAGED --level 1
fi

Programmatic API

All core functions are exported for integration into custom tooling:

import { runLint, runGraph, loadConfig, validateFrontmatter, extractFile } from 'claude-skill-lint';

runPluginValidate(rootDir) wraps the official claude plugin validate and returns findings in the same shape as the rest. See the package exports for the full API surface.

Changelog

Every release is documented in CHANGELOG.md, grouped by what changed and why it matters — not by commit. For the same history with npm publish timestamps, see GitHub Releases.

License

MIT