agent-skill-lint

Static quality linter for AI agent skill definitions (SKILL.md files).

agent-skill-lint is the eslint of the agent skill world — pure static analysis, zero LLM calls, zero cloud dependency, pre-commit-friendly, CI-ready.

It catches bad skill definitions at development time, before they reach the agent.

Installation

pip install agent-skill-lint

Or from source:

git clone https://github.com/hananel-e/agent-skill-lint
cd agent-skill-lint
pip install -e ".[dev]"

Quick Start

# Lint all skill.md files found recursively under a path
skill-lint roo check .

# Lint a single file
skill-lint roo check .roo/skills-build/coder/skill.md

# Filter by severity
skill-lint roo check . --severity error      # errors only

# Output formats
skill-lint roo check . --format json         # machine-readable
skill-lint roo check . --format github       # GitHub Actions annotations

# Disable specific rules
skill-lint roo check . --ignore ROO012,ROO031

# List all rules
skill-lint roo rules

# Explain a specific rule
skill-lint roo explain ROO013

# Check tool dependencies
skill-lint doctor

# ── v0.2.0 commands ──────────────────────────────────────────────────────────

# Score skills (A-F quality grades)
skill-lint roo score .
skill-lint roo score . --format json
skill-lint roo score . --fail-under 80       # exit 1 if average < 80

# Simulate routing for a query (no ML required)
skill-lint roo simulate "write and fix code" --path .roo/skills/
skill-lint roo simulate "plan architecture" --path . --top 3
skill-lint roo simulate "debug errors" --path . --embeddings   # requires [embeddings] extra

# Check framework sync (.roomodes ↔ skills)
skill-lint roo sync .
skill-lint roo sync . --format json
skill-lint roo sync . --roomodes .roomodes   # use a specific .roomodes file

# Update the known mode slug cache from GitHub
skill-lint roo update-slugs

Exit Codes

Rule Catalogue

Category A — Frontmatter Rules

Category B — Description Quality Rules

Category C — Body Structure Rules

Category D — Cross-Skill Consistency Rules

Configuration

Place a .skill-lint.yaml file at your repo root (copy from .skill-lint.yaml.example):

rules:
  ROO007:
    min_length: 60          # override default (50)
  ROO008:
    max_length: 300         # override default (400)
  ROO013:
    similarity_threshold: 0.80   # override default (0.75)

ignore:
  - ".roo/skills/legacy/"        # skip entire directory
  - "ROO031"                     # globally disable a rule

# Custom vague words (appended to built-in list)
vague_words:
  - "facilitates"

# Known mode slugs (appended to built-in list)
extra_mode_slugs:
  - "my-custom-mode"

Per-rule overrides

Four rules accept numeric overrides under the rules: key:

Example — enforce 60-char minimum and flag descriptions that are 80%+ similar:

rules:
  ROO007:
    min_length: 60
  ROO013:
    similarity_threshold: 0.80

Ignoring rules and paths

ignore:
  - "ROO031"                  # disable rule globally
  - ".roo/skills/legacy/"     # skip all skill.md files under this path prefix

You can also suppress rules for a single run without touching the config:

skill-lint roo check . --ignore ROO012,ROO031

Extending the mode slug allowlist

If your Roo setup uses custom modes not in the built-in list, add them so ROO005 does not flag them as unknown:

extra_mode_slugs:
  - "my-workflow"
  - "data-analyst"

Extending the vague word list

The built-in vague words are: handles, manages, does, performs, processes. Append your own:

vague_words:
  - "facilitates"
  - "coordinates"
  - "oversees"

Example Output

.roo/skills-build/coder/skill.md
  ✗ ROO008  description is 412 chars (max 400)                    [error]
  ⚠ ROO012  description uses vague word: "owns"                   [warning]

.roo/skills/api-schema-generator/skill.md
  ✗ ROO023  broken link: .roo/skills-build/coder/ui-patterns.md   [error]
  ⚠ ROO022  no numbered sections found                            [warning]

────────────────────────────────────────────────────────────
2 errors  |  2 warnings  |  3 files scanned  |  1 clean

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/hananel-e/agent-skill-lint
    rev: v0.2.0
    hooks:
      - id: skill-lint-roo
        name: skill-lint (Roo skills)
        language: python
        entry: skill-lint roo check
        files: skill\.md$
        pass_filenames: false
        args: ["."]

Development

pip install -e ".[dev]"
pytest

Tech Stack

Zero heavy dependencies by default — no scikit-learn, no LLM calls. Use pip install 'agent-skill-lint[embeddings]' to enable the embedding-based routing simulator.

v0.2.0 Features

Quality Scorer (roo score)

Converts lint violations into a numeric score (0–100) and letter grade (A–F) per skill, plus an aggregate average. Use --fail-under N to gate CI on quality.

Scoring: base 100, -15 per ERROR, -5 per WARNING (clamped to 0)
Grades:  A ≥90  B ≥80  C ≥70  D ≥60  F <60

Routing Simulator (roo simulate)

Ranks all scanned skills by how well their description matches a natural-language query. Useful for spotting ambiguous descriptions before deploying to a live agent.

• Default: heuristic keyword scoring (no extra deps)
• --embeddings: cosine similarity via sentence-transformers (more accurate)
• --top N: show top N matches
• --fuzzy-threshold: tune fuzzy matching sensitivity

Framework Sync Checker (roo sync)

Compares .roomodes definitions against scanned skill files. Detects:

• Undocumented modes: defined in .roomodes but no skill covers them
• Orphaned slugs: a skill's modeSlugs references a mode absent from .roomodes

Slug Registry (roo update-slugs)

Fetches the latest known mode slugs from GitHub and caches them at ~/.cache/skill-lint/slugs.json. ROO005 reads from this cache so the known-slug list stays current without a code release.

New Rules

Limitations

Heuristic rules are not perfect. ROO010–ROO014 and ROO034 fire on patterns that correlate with poor skill quality — they are not proofs. A description can pass all rules and still be a bad routing signal, or fail ROO011 and still work fine in practice. Treat warnings as prompts to review, not verdicts.

Routing simulator is heuristic by default. The roo simulate command uses keyword overlap, not semantic understanding. Use --embeddings with sentence-transformers for more accurate results.

Sync checker requires .roomodes. roo sync and ROO035/ROO036 are no-ops when no .roomodes files are found in the repo. They are only meaningful for Roo-based agent setups.

License

Apache 2.0