Skill Lint

Author: jovd83 | Version: 3.0.0 | License: MIT

Lint AgentSkill folders and report what would stop a harness from loading a skill, or from picking it by its description, plus the house rules of this library. Linting is read-only. Fixes happen only after the user approves them.

Run it as /skill-lint <path>. With no path, lint the current repository.

Run The Linter

python "<skill folder>/scripts/skill_lint.py" <path> [<path> ...]

<skill folder> is the folder that holds this SKILL.md (${CLAUDE_SKILL_DIR} in Claude Code). A path can be a skill folder, a SKILL.md, or a tree such as a whole skills directory. The script needs PyYAML: pip install pyyaml, or uv run --with pyyaml python ....

Exit codes: 0 nothing fails, 1 findings fail the run, 2 bad invocation.

Checks

A .skill-lint.json next to SKILL.md or at the repository root switches checks off for that skill: {"skip": ["telemetry"], "expect_name": "my-skill"}. Every skip needs a reason in the repository, such as a line in the README or CHANGELOG.

Report

1. Lead with the totals: skills checked, errors, warnings.
2. List the errors grouped by skill, each with file:line, the check id and one line on the fix.
3. Summarise warnings by check, unless the user asks for all of them.
4. Mark third-party skills (no source in the user's own repositories) as report-only.
5. Propose fixes and stop. Change nothing until the user approves.

Fixing Findings

After fixing, run the linter again on the changed skills only and report the new totals.

Oversized Frontmatter

When frontmatter is too long for a platform's budget, use the trim tools. Every tool supports --dry-run, so preview first.

1. python scripts/audit.py --dir <skills directory> [--limit 1000] reports blocks over the limit by severity.
2. python scripts/analyze.py --file <SKILL.md> proposes deduplication, list flattening, noise removal, field migration and description trimming, with estimated savings.
3. Show the before/after proposal and ask for approval. This is a hard stop: nothing is written without a yes.
4. Apply in order: deduplicate.py --backup, flatten.py, remove_noise.py, migrate_to_body.py, then any approved description edit.
5. Re-run audit.py and skill_lint.py on the changed files.

migrate_to_body.py moves license, compatibility, homepage, platforms and metadata.maturity into the body line. author and version stay in metadata. scripts/cleanup.py runs the same pipeline in one command and still needs the approval gate before --apply.

Continuous Integration

The repository is also a GitHub Action:

- uses: actions/checkout@v7
- uses: jovd83/skill-lint@v3
  with:
    path: .
    readme: "true"

Inputs: path (default .), readme, strict, and args for extra flags. In Actions the checkout folder is named after the repository, so name-folder compares the skill name with the repository name.

Guardrails

• Linting never writes files. Fixes wait for explicit approval, and the first write to a file uses --backup.
• Never run the scripts of the skill under review; read its files only.
• Do not bypass a failing check with --skip or .skill-lint.json unless the user agrees, and record the reason.
• In the two-tree layout, fix the development source and let the sync update the installed copy. Never edit the installed copy.

Scripts Reference