skilllint
Static analysis linter for AI agent plugins, skills, and agents — for Claude Code, Cursor, Codex, and any agentskills.io-compatible platform.
See the failing line and how to fix it:
skilllint check --output-format full path/to/SKILL.md
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.
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 to compare the available formats.
Output formats
Use full to investigate issues locally, concise for pre-commit checks,
or a structured format to integrate with automation.
| Format | Use it to | Example | Output file |
|---|---|---|---|
full |
Find the source of an issue and how to fix it | Terminal output | ANSI |
concise |
Run pre-commit checks with one finding per line | Plain-text findings | Text |
json-lines |
Process findings in scripts or agents | JSON Lines | JSONL |
github |
Show annotations in GitHub Actions | Annotation commands | Workflow commands |
gitlab |
Report Code Quality findings in GitLab | Code Quality report | JSON |
junit |
Send findings to tools that read JUnit test reports | JUnit report | XML |
Select a format with skilllint check --output-format FORMAT path/to/SKILL.md.
For full output, colour is detected automatically. Use --color always to
force it or --color never (also --no-color) to turn it off.
See output examples for commands and reports in each format.
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 example annotation commands
and GitHub annotations reference.
For GitLab CI, skilllint check --output-format gitlab emits a Code Quality
JSON report. See the example Code Quality report
and CI configuration.
For tools that accept test reports, skilllint check --output-format junit emits
JUnit-style XML. See the example JUnit report
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 example pre-commit output.
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.2
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.2.tar.gz | 1.4 MB | Without provenance | Details for skilllint-1.22.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| skilllint-1.22.2-py3-none-any.whl | Python 3 | none | any | Details for skilllint-1.22.2-py3-none-any.whl |
Total release size: 2.4 MB
Release files / skilllint-1.22.2.tar.gz
| Download URL | skilllint-1.22.2.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e0962cf54c5a7e5ffe9e2a1fbb23f6a82f4c0cc44c7a222bb579c6814cccc085
|
|
BLAKE2b-256 checksum How to use checksums |
d855421798bddd966545824d2b6394f22e98fb678bd235d0a54d356802de7456
|
| 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.2-py3-none-any.whl
| Download URL | skilllint-1.22.2-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
844ee8f45b154a8f3561f6aa008b2b0463a26769dd63149ee1e30a134ecdae6e
|
|
BLAKE2b-256 checksum How to use checksums |
27e9502c941312e3832358cfe46e536e97e740bd149482f35c9b45b998e778a4
|
| 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.2
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.