PACKAGE EXPLORERView in registry

agent-skill-lint

PyPI

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

Versions collected1

Direct dependencies11From release 0.2.0

Last observed20 Oct, 23:24 UTC

README

Version 0.2.0 documentation

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

Code	Meaning
`0`	Clean — no violations
`1`	One or more violations found
`2`	Tool error (file not found, parse failure, etc.)

Rule Catalogue

Category A — Frontmatter Rules

Rule ID	Severity	Description
`ROO001`	error	`name` field missing from frontmatter
`ROO002`	error	`description` field missing from frontmatter
`ROO003`	error	`modeSlugs` field missing from frontmatter
`ROO004`	error	`modeSlugs` is an empty list
`ROO005`	warning	`modeSlugs` contains an unrecognised mode slug
`ROO006`	warning	`name` value does not match the parent directory name
`ROO007`	error	`description` is too short (< 50 characters)
`ROO008`	warning	`description` is too long (> 400 characters)

Category B — Description Quality Rules

Rule ID	Severity	Description
`ROO010`	warning	Description missing a trigger condition keyword
`ROO011`	warning	Description does not start with an action verb or `Use`
`ROO012`	warning	Description contains vague words
`ROO013`	warning	Description has >75% token overlap with another skill
`ROO014`	warning	Skill `name` mentioned in description is inconsistent with frontmatter

Category C — Body Structure Rules

Rule ID	Severity	Description
`ROO020`	error	No H1 heading found after frontmatter
`ROO021`	warning	H1 heading text does not match frontmatter `name`
`ROO022`	warning	Body has no numbered sections — likely a stub
`ROO023`	error	Markdown link target does not exist relative to repo root
`ROO024`	warning	Body references a mode slug not present in `.roomodes`
`ROO025`	warning	Body after frontmatter is < 100 characters — stub skill

Category D — Cross-Skill Consistency Rules

Rule ID	Severity	Description
`ROO030`	warning	Body references a skill name with no corresponding `skill.md`
`ROO031`	warning	Handoff file path uses a non-standard pattern
`ROO032`	error	Two or more skills claim the same `modeSlugs` entry
`ROO034`	warning	Two skills have descriptions with high token overlap — ambiguous routing
`ROO035`	warning	Skill's `modeSlugs` references a mode not defined in any `.roomodes` file
`ROO036`	warning	A mode defined in `.roomodes` has no skill covering it

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:

Rule	Config key	Default	Effect
`ROO007`	`rules.ROO007.min_length`	`50`	Minimum description length in characters. Raise it if your team requires more detail.
`ROO008`	`rules.ROO008.max_length`	`400`	Maximum description length in characters. Lower it to enforce tighter descriptions.
`ROO013`	`rules.ROO013.similarity_threshold`	`0.75`	Token-overlap ratio (0–1) above which two skill descriptions are flagged as too similar. Raise it to allow more overlap; lower it to enforce stricter uniqueness.
`ROO034`	`rules.ROO034.overlap_threshold`	`0.60`	SequenceMatcher ratio (0–1) above which two skill descriptions are flagged as routing-ambiguous.

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

Concern	Library
CLI	`typer`
Terminal output	`rich`
Frontmatter parsing	`python-frontmatter`
Markdown parsing	`markdown-it-py`
Token overlap (ROO013, ROO034)	`difflib.SequenceMatcher` (stdlib)
Config file	`pyyaml`
Slug registry	stdlib `urllib`, `json`
Routing simulator	stdlib `difflib`, `re`
Embedding backend (opt-in)	`sentence-transformers` + `numpy`
Build backend	`hatchling`
Test framework	`pytest`

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

Rule	Description
`ROO034`	Two skills have descriptions with high token overlap — ambiguous routing
`ROO035`	Skill's `modeSlugs` references a mode not defined in any `.roomodes` file
`ROO036`	A mode defined in `.roomodes` has no skill covering it

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

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Versions 1

Collected releases

Version	Published	Direct dependencies	Open version
0.2.0	26 Jun 2026	11

Package advisories

No matching advisories collected

This describes our collected data; it is not a security assessment.

Repository

PENDING

hananel-e/agent-skill-lint

Shared repository data · GitHub

License detected in repository: Not collected

Metadata history

Meaningful changes

Current collected state Current

Observed since 20 Oct, 23:24 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package:c7998d9b7814286b4b009900359927279a02b36e579e8c01a10c4a30b3afdf0e

Package details

Ecosystem: PyPI
Registry license: Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean, as submitted to the Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of developing and improving the Work, but excluding communication that is conspicuously marked or designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any Legal Entity on behalf of whom a Contribution has been received by the Licensor and included within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by the combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or any Contribution embodied within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, You must include a readable copy of the attribution notices contained within such NOTICE file, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or in addition to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own license statement for Your modifications and may provide additional grant of rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Derivative Works, as set forth in this Section, without any of the additional conditions stated in Sections 4(a), 4(b), and 4(c) above. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or reproducing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or exemplary damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may offer only conditions consistent with this License. END OF TERMS AND CONDITIONS
Collected versions: 1
Source: PyPI

PACKAGE URL

pkg:pypi/agent-skill-lint

Project links

Registry Bug Tracker Changelog Homepage

Source & dates

Source modified: Unknown
First observed: 20 Oct 2026
Last observed: 20 Oct, 23:24 UTC

Publication, source changes and collection are separate events.

agent-skill-lint

README

agent-skill-lint

Installation

Quick Start

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

Per-rule overrides

Ignoring rules and paths

Extending the mode slug allowlist

Extending the vague word list

Example Output

Pre-commit Hook

Development

Tech Stack

v0.2.0 Features

Quality Scorer (roo score)

Routing Simulator (roo simulate)

Framework Sync Checker (roo sync)

Slug Registry (roo update-slugs)

New Rules

Limitations

License

Downloads & popularity

No metric observations yet

Versions 1

Package advisories

Repository

Metadata history

Record identity

Quality Scorer (`roo score`)

Routing Simulator (`roo simulate`)

Framework Sync Checker (`roo sync`)

Slug Registry (`roo update-slugs`)