Skip to main content

skilllint

PyPI version Python versions License CI

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.

Actual full-colour skilllint diagnostic

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.



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)

Source distribution for skilllint 1.22.0
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)

Table of built distributions (wheels) for skilllint 1.22.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.22.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page