skillscan-lint

Quality linter for AI agent skill files. Catches weasel words, ambiguous instructions, missing metadata, and skill graph problems (cycles, dangling references, broken file links) before they reach production.

Works with skills from skills.sh, ClawHub, and any SKILL.md-based skill package.

Install

pip install skillscan-lint

Or run without installing:

docker run --rm -v "$PWD:/work" kurtpayne/skillscan-lint scan /work/skills/

Quick Start

# Lint a single skill file
skillscan-lint scan SKILL.md

# Lint an entire skills directory (including graph checks)
skillscan-lint scan ./skills/ --graph

# Output as JSON for CI integration
skillscan-lint scan ./skills/ --format json

# List all rules
skillscan-lint rules

Example output

SKILL.md
  QL-004  WARNING  Weasel intensifier "basically" weakens the instruction.
  QL-009  ERROR    Description too short (8 words). Minimum is 10.
  QL-015  WARNING  TODO marker found — remove before publishing.
  GR-002  ERROR    Skill "data-fetcher" references "parser" which does not exist.
  GR-006  WARNING  Broken file reference: "references/auth.md" does not exist.

2 errors, 3 warnings

Rules

skillscan-lint ships with two rule families:

Quality rules (QL-*)

Run skillscan-lint rules for the full list with descriptions.

Graph rules (GR-*, requires --graph)

Graph rules analyze the invocation graph across a skills directory — which skills call which, what files they reference, and whether the dependency structure is sound.

Graph edges are resolved from three sources, in order of reliability:

1. Front-matter keys — invoke:, calls:, depends_on:, uses:, requires: with skill names or file paths
2. Markdown links to SKILL.md files — [skill name](../other-skill/SKILL.md)
3. Path resolution — front-matter values containing / or ending in .md are resolved relative to the skill file

Reference docs, README files, and other supporting .md files within a skill package are not treated as graph nodes — they are checked by GR-006 for broken links instead.

CI Integration

GitHub Actions

- name: Lint skills
  run: |
    pip install skillscan-lint
    skillscan-lint scan ./skills/ --graph --format json > report.json

Pre-commit hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/kurtpayne/skillscan-lint
    rev: v0.3.0
    hooks:
      - id: skillscan-lint
        args: [--graph]

Docker in CI

- name: Lint skills
  run: |
    docker run --rm -v "${{ github.workspace }}:/work" \
      kurtpayne/skillscan-lint scan /work/skills/ --graph --format json \
      > skillscan-lint-report.json

Skill Graph Example

Given a skills directory:

skills/
  data-fetcher/SKILL.md   (invoke: parser)
  parser/SKILL.md         (invoke: data-fetcher)   ← cycle!
  formatter/SKILL.md      (invoke: missing-skill)  ← dangling ref

Running skillscan-lint scan ./skills/ --graph will report:

GR-001  ERROR    Cycle detected: data-fetcher → parser → data-fetcher
GR-002  ERROR    Skill "formatter" references "missing-skill" which does not exist.

Related

• skillscan-security — Security scanner for AI skills: prompt injection, IOC matching, malware detection, ML-based classifier
• skills.sh — Community registry of AI agent skills
• ClawHub — MCP skill marketplace

License

Apache-2.0. See LICENSE.