skilllint
Static analysis linter for AI agent plugins, skills, and agents — for Claude Code, Cursor, Codex, and any agentskills.io-compatible platform.
What it does
skilllint validates the structure and content of AI agent files: plugins, skills, agents, and commands. It catches broken references, missing frontmatter, oversized skills, invalid hook configurations, and more — before they cause silent failures at runtime.
$ skilllint check plugins/my-plugin
plugins/my-plugin/skills/my-skill/SKILL.md
SK006 Token count 14823 exceeds recommended limit of 8192
plugins/my-plugin/agents/my-agent.md
NR001 Namespace reference 'other-plugin:some-skill' — plugin directory not found
2 errors in 2 files
Installation
pip install skilllint
Or with uv:
uv add skilllint # add to a project
uv tool install skilllint # install as a global tool
Requires Python 3.11–3.14.
Quick start
# Validate a plugin directory
skilllint check plugins/my-plugin
# Validate a single skill file
skilllint check plugins/my-plugin/skills/my-skill/SKILL.md
# Validate everything and show a summary
skilllint check --show-summary plugins/
# Auto-fix issues where possible
skilllint check --fix plugins/my-plugin
# Count tokens in any markdown file
skilllint check --tokens-only .claude/CLAUDE.md
Exit codes: 0 = all checks passed · 1 = validation errors · 2 = usage error
See output examples for captured reports and colour SVG previews.
Output formats
Choose a format for the reader or CI consumer. Every example below is captured
from the same deliberately invalid skill; the command exits 1.
| Format | Use | Preview | Raw output |
|---|---|---|---|
full |
Human-readable source excerpts, highlights, and help | Actual terminal colours | ANSI |
concise |
One monochrome finding per line for pre-commit | Monochrome findings | Text |
json-lines |
One parseable finding per line for agents | JSONL preview | JSONL |
github |
Native GitHub Actions annotations | Command preview | Workflow commands |
gitlab |
GitLab Code Quality artifacts | Report preview | JSON |
junit |
JUnit-style test-report consumers | Report preview | XML |
For source-aware human diagnostics, use skilllint check --output-format full.
Colour defaults to terminal detection; choose --color always or --color never
independently of the format. Existing defaults and --no-color are preserved.
See the complete six-format output gallery for reproducible captures, raw reports, commands, and consumer-specific examples. The machine-format SVGs are labelled report previews, not CI interface screenshots.
GitHub Action
Use bitflight-devops/skilllint as a GitHub Action to validate skills, plugins, and agents in any repository.
For direct CLI use in Actions, skilllint check --output-format github emits
native workflow annotations. See the captured commands and colour SVG preview
and format contract.
For GitLab CI, skilllint check --output-format gitlab emits a Code Quality
JSON report. See the raw report and colour SVG preview
and CI configuration.
For test-report consumers, skilllint check --output-format junit emits
JUnit-style XML. See the raw XML and colour SVG preview
and result semantics and CI configuration.
Replace X.Y.Z in the examples with the release you intend to pin. The Action
ref and the version input pin the Action and the installed package
independently. Packages containing the structured Action runner produce annotations
and outputs from one scan, including fix: true, while keeping the requested
human log styling. Older pinned packages use an explicitly announced legacy
compatibility path: their historical output parsing may repeat a scan and does
not provide the new native annotations. This keeps existing package pins working.
version: source builds from a local Git checkout of this repository (including
its Git metadata) and tests unreleased changes with uses: ./. It is not intended
for GitHub's downloaded remote Action archive, which lacks version metadata.
- uses: bitflight-devops/skilllint@vX.Y.Z
with:
paths: "plugins/"
platform: "claude-code"
version: "X.Y.Z"
show-summary: "true"
Full input reference
| Input | Description | Default |
|---|---|---|
paths |
Space-separated paths to validate | . |
platform |
Platform adapter: claude-code, cursor, codex; omit to validate each selected file with every matching adapter |
(matching adapters) |
fix |
Auto-fix issues where possible | false |
check-only |
Validate only, do not auto-fix | false |
verbose |
Show detailed output including info messages | false |
no-color |
Disable color output | true |
tokens-only |
Output only the integer token count | false |
show-progress |
Show per-file PASSED/FAILED status | false |
show-summary |
Show summary panel at the end | true |
filter |
Glob pattern to restrict files within a directory | (none) |
filter-type |
File type filter: skills, agents, commands |
(all) |
version |
skilllint version to install (latest, 1.2.3, or source for local Git checkout tests) |
latest |
python-version |
Python version to use | 3.12 |
Outputs
| Output | Description |
|---|---|
result |
passed when exit code is 0; failed for any non-zero exit code |
exit-code |
Raw exit code: 0 = pass · 1 = errors · 2 = usage error |
inspected-count |
Number of files inspected by skilllint |
findings |
Distinct finding codes emitted by skilllint |
tool-python |
Python runtime used by the installed skilllint tool |
tool-version |
Version reported by the installed skilllint tool |
Example: fail the CI on validation errors
name: Validate skills
on: [push, pull_request]
jobs:
skilllint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Lint skills and plugins
uses: bitflight-devops/skilllint@vX.Y.Z
with:
paths: "plugins/ .claude/"
platform: "claude-code"
version: "X.Y.Z"
show-summary: "true"
verbose: "false"
Example: report results without blocking
- name: Lint skills and plugins
id: lint
uses: bitflight-devops/skilllint@vX.Y.Z
with:
paths: "plugins/"
version: "X.Y.Z"
continue-on-error: true
- name: Print result
run: echo "skilllint result=${{ steps.lint.outputs.result }}"
Pre-commit hook
Install pre-commit, using Python 3.11–3.14 for the skilllint hook:
python -m pip install pre-commit
Add to .pre-commit-config.yaml. Replace X.Y.Z with a release version that
includes the hooks and output format you need, or replace the entire vX.Y.Z
with a commit SHA. vX.Y.Z is a placeholder, not a published tag.
repos:
- repo: https://github.com/bitflight-devops/skilllint
rev: vX.Y.Z
hooks:
- id: skilllint
Install the Git hook, then check all matching tracked files once:
pre-commit install
pre-commit run skilllint --all-files
Later commits check matching staged files automatically. Pre-commit installs skilllint in its own hook environment; a separate skilllint installation is not needed for this configuration.
Both skilllint and skilllint-fix use --output-format concise --no-color:
one plain line per finding, with no progress or summary. To opt into fixes,
replace id: skilllint with id: skilllint-fix, then run
pre-commit run skilllint-fix --all-files. Review and re-stage changed files.
The fix hook keeps the same file selection and applies supported fixes in place.
See pre-commit usage for selected-file checks,
custom arguments, exclusions, and prek commands.
See the captured concise output and SVG preview.
Contributor quality checks (local)
Run this sequence before pushing:
# Auto-fix hooks first (whitespace, pypfmt, oxlint/oxfmt, ruff --fix, etc.)
uv run prek run --all-files
uv run pytest
Platform support
skilllint ships with adapters for three platforms and supports third-party adapters via Python entry points:
| Platform | Adapter ID | Bundled |
|---|---|---|
| Claude Code | claude-code |
✓ |
| Cursor | cursor |
✓ |
| OpenAI Codex | codex |
✓ |
| OpenCode, Gemini, and others | — | via entry points |
Restrict validation to one platform:
skilllint check --platform claude-code plugins/my-plugin
Runtime rule reference
The installed runtime owns the active rule catalog, severity, platform scope, fixability, and rule documentation. Query it directly instead of relying on a copied table in this README:
skilllint rules
skilllint rule SK006
This keeps rule additions, retirements, and metadata changes synchronized with the executable that will perform the scan.
CLI reference
Use the executable's help for the current command and option inventory:
skilllint --help
skilllint check --help
skilllint rules --help
skilllint rule --help
skilllint docs --help
See Usage and integrations for maintained workflows and configuration examples.
Vendor documentation cache
skilllint docs provides the project's offline-first authority cache. Query
the current command surface with skilllint docs --help; see
Vendor documentation cache for cache ownership,
lifecycle, integrity, and contributor guidance.
Suppressing warnings
Use a .skilllint.json file to suppress specific rule codes for a directory tree. Place the file at any level — skilllint walks up from each scanned file and uses the nearest config it finds.
{
"ignore": {
"": ["AS008"],
"skills/legacy": ["FM007", "SK006"]
}
}
Key format:
| Key | Scope |
|---|---|
"" (empty string) |
All files under this .skilllint.json |
"skills/legacy" |
Files whose path (relative to the config file) starts with that prefix |
Plugin-level suppression (inside a .claude-plugin/ plugin):
Place validator.json inside .claude-plugin/:
{
"ignore": {
"": ["PA001"],
"agents/generated": ["FM004", "FM007"]
}
}
The same key format applies. Plugin-level config takes priority over a .skilllint.json in a parent directory.
Third-party adapters
Register a custom platform adapter via Python entry points in your pyproject.toml:
[project.entry-points."skilllint.adapters"]
my-platform = "my_package.adapter:MyPlatformAdapter"
Your adapter must implement the AdapterProtocol interface from skilllint.adapters.protocol.
Links
License
MIT
Metadata
Release files for skilllint 1.22.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| skilllint-1.22.0.tar.gz | 1.3 MB | Without provenance | Details for skilllint-1.22.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| skilllint-1.22.0-py3-none-any.whl | Python 3 | none | any | Details for skilllint-1.22.0-py3-none-any.whl |
Total release size: 2.4 MB
Release files / skilllint-1.22.0.tar.gz
| Download URL | skilllint-1.22.0.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
096fe5fa582d17ec2b7d96c350438ea1759197ee307507f194912d74c6be17b5
|
|
BLAKE2b-256 checksum How to use checksums |
22835fe197d0316937064dcf37bf4f79d0cd1ff20c3b84196a71c9bd2145bb36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / skilllint-1.22.0-py3-none-any.whl
| Download URL | skilllint-1.22.0-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d4fa2726e74a333785e728ae5e24653441b976c806b1407c3641ad2bacdfb1d5
|
|
BLAKE2b-256 checksum How to use checksums |
a1f498ce7e1b1cbfc216ea43532b223ccff27485510927ccbae7ae0d3b1bea05
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for skilllint 1.22.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.