convez.ai
SkillDevOps & InfraestruturaIntermediário
bitflight-devops

skilllint

bitflight-devops/skilllint

Valida estrutura e limites de tokens em skills de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Linter estático agnóstico de plataforma para validar plugins, skills e agents de IA. Detecta referências quebradas, frontmatter ausente, limites de tokens excedidos e configurações inválidas antes que causem falhas em runtime.

Instalação

$npx convez-ai bitflight-devops/skilllint

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
7
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 3 dias
Versão
v1.23.1
Issues abertas
27
Contribuidores
4

Casos de uso

  • Validar integridade de plugins e skills antes do deploy
  • Verificar conformidade com padrões de frontmatter e referências
  • Contar tokens e otimizar tamanho de arquivos de skill
  • Integrar validação contínua em pipelines CI/CD via GitHub Actions

Veredito

Ferramenta madura e bem-mantida que resolve um problema real: garantir qualidade de plugins/skills antes do deploy. Funciona com múltiplas plataformas (Claude Code, Cursor, Codex) e oferece tanto CLI quanto integração GitHub Actions, tornando-a essencial para pipelines robustos.

README

A tradução para o português deste README ainda está na fila.

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

Screenshots

Validation output with errors and warnings

skilllint check showing validation errors

All available rules

skilllint rules table

Rule detail

skilllint rule FM004 detail


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


GitHub Action

Use bitflight-devops/skilllint as a GitHub Action to validate skills, plugins, and agents in any repository:

- uses: bitflight-devops/skilllint@v1.7.0
  with:
    paths: "plugins/"          # paths to validate (default: ".")
    platform: "claude-code"   # restrict to one platform (optional)
    show-summary: "true"      # show summary panel (default: true)

Full input reference

InputDescriptionDefault
pathsSpace-separated paths to validate.
platformPlatform adapter: claude-code, cursor, codex(all)
fixAuto-fix issues where possiblefalse
check-onlyValidate only, do not auto-fixfalse
verboseShow detailed output including info messagesfalse
no-colorDisable color outputtrue
tokens-onlyOutput only the integer token countfalse
show-progressShow per-file PASSED/FAILED statusfalse
show-summaryShow summary panel at the endtrue
filterGlob pattern to restrict files within a directory(none)
filter-typeFile type filter: skills, agents, commands(all)
versionskilllint version to install (latest or 1.2.3)latest
python-versionPython version to use3.12

Outputs

OutputDescription
resultpassed when exit code is 0; failed for any non-zero exit code
exit-codeRaw exit code: 0 = pass · 1 = errors · 2 = usage error

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@v1.7.0
        with:
          paths: "plugins/ .claude/"
          platform: "claude-code"
          show-summary: "true"
          verbose: "false"

Example: report results without blocking

- name: Lint skills and plugins
  id: lint
  uses: bitflight-devops/skilllint@v1.7.0
  with:
    paths: "plugins/"
  continue-on-error: true

- name: Print result
  run: echo "skilllint result=${{ steps.lint.outputs.result }}"

Pre-commit hook

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/bitflight-devops/skilllint
    rev: v1.7.0
    hooks:
      - id: skilllint

Contributor quality checks (local)

Run this sequence before pushing:

# Auto-fix hooks first (whitespace, pypfmt, biome, 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:

PlatformAdapter IDBundled
Claude Codeclaude-code✓
Cursorcursor✓
OpenAI Codexcodex✓
OpenCode, Gemini, and others—via entry points

Restrict validation to one platform:

skilllint check --platform claude-code plugins/my-plugin

What gets validated

CodeCategoryDescription
FM001–FM010FrontmatterRequired fields, valid values, schema compliance
SK001–SK009SkillDescription quality, token limits, complexity, internal links
AS001–AS009AgentSkillsCross-platform open standard compliance
LK001–LK002LinksMarkdown link validity and broken reference detection
PD001–PD003Progressive disclosureDirectory structure for references/, examples/, scripts/
PL001–PL006PluginStructure, manifest correctness, marketplace layout, subprocess safety
HK001–HK005HookScript existence, configuration validity
NR001–NR002Namespace refsCross-plugin skill/agent/command references
SL001SymlinksSymlink hygiene within plugin directory
TC001Token countToken count reporting and threshold enforcement
PR001–PR005Plugin registrationCapability registration completeness and correctness in plugin.json
PA001Plugin agentPlugin-packaged agents: hooks / mcpServers / permissionMode unsupported per Anthropic (ignored at load; cite sub-agents doc)
CU001–CU002CursorCursor .mdc frontmatter required fields and enum values
CX001–CX002CodexCodex AGENTS.md content non-empty and header presence

CLI reference

Usage: skilllint [OPTIONS] COMMAND [ARGS]...

Commands:
  check   Validate Claude Code plugins, skills, agents, and commands.
  docs    Fetch, query, and verify cached vendor documentation.
  rule    Show documentation for a validation rule.
  rules   List all available validation rules.

Options:
  --help  Show this message and exit.

check

Usage: skilllint check [OPTIONS] [PATHS]...

Arguments:
  paths              Paths to validate

Options:
  --check            Validate only, don't auto-fix
  --fix              Auto-fix issues where possible
  --verbose, -v      Show detailed output
  --no-color         Disable color
  --tokens-only      Output token count only
  --show-progress    Show per-file status
  --show-summary     Show summary panel
  --filter TEXT          Glob pattern to match files within a directory
  --filter-type TEXT     Filter type (skills | agents | commands)
  --platform TEXT        Platform adapter
  --include-gitignore    Scan files excluded by .gitignore (default: skip them)
  --record PATH          Record terminal output to SVG or HTML file
  --help                 Show this message and exit

rules

Usage: skilllint rules [OPTIONS]

Options:
  --platform, -p TEXT  Filter rules by platform
  --category, -c TEXT  Filter rules by category
  --severity, -s TEXT  Filter rules by severity (error, warning, info)
  --record PATH        Record terminal output to SVG or HTML file
  --help               Show this message and exit

rule

Usage: skilllint rule [OPTIONS] RULE_ID

Arguments:
  rule_id  Rule identifier (e.g., "SK001", "FM002", "AS001")  [required]

Options:
  --record PATH  Record terminal output to SVG or HTML file
  --help         Show this message and exit

docs

Cache and query vendor documentation pages for offline use.

Usage: skilllint docs [OPTIONS] COMMAND [ARGS]...

Commands:
  fetch     Fetch a documentation page or return a cached copy.
  fetch-authorities  Fetch documentation for all normalized rule authority URLs.
  latest    Find the most recent cached file for a page name.
  sections  Print a table of sections in a cached markdown file.
  section   Extract the text of a named section from a cached markdown file.
  verify    Verify a cached file against its .meta.json integrity sidecar.

docs fetch

Usage: skilllint docs fetch [OPTIONS] URL

Arguments:
  url                   Documentation URL to fetch or serve from cache.

Cache Options:
  --ttl FLOAT           Cache time-to-live in hours before a refresh is attempted.  [default: 4.0]
  --force               Skip the freshness check and always attempt a network fetch.

Options:
  --help                Show this message and exit.

Prints the cached file path to stdout. Status messages go to stderr. Exits 1 when no cache exists and the network is unavailable.

docs fetch-authorities

Usage: skilllint docs fetch-authorities [OPTIONS]

Cache Options:
  --ttl FLOAT           Cache time-to-live in hours before a refresh is attempted.  [default: 4.0]
  --force               Skip the freshness check and always attempt a network fetch.

Options:
  --help                Show this message and exit.

Fetches every unique authority URL declared by the rule registry after normalizing origin-relative references against each rule authority origin. Prints one cached file path per successful fetch. Exits 1 if any URL cannot be fetched and no stale cache is available.

docs latest

Usage: skilllint docs latest [OPTIONS] PAGE_NAME

Arguments:
  page_name             Filesystem-safe page name (e.g. 'claude-code--settings').

Options:
  --help                Show this message and exit.

Prints the file path to stdout. Exits 1 when no cached file exists for that page name.

docs sections

Usage: skilllint docs sections [OPTIONS] FILE_PATH

Arguments:
  file_path             Path to the cached markdown file to index.

Options:
  --help                Show this message and exit.

Prints a table of headings with their line ranges to stdout.

docs section

Usage: skilllint docs section [OPTIONS] FILE_PATH HEADING

Arguments:
  file_path             Path to the cached markdown file.
  heading               Heading text or markdown anchor slug to locate.

Options:
  --help                Show this message and exit.

Prints the full text of the matching section to stdout. Exits 1 when the heading is not found.

Heading matching is case-insensitive and accepts two forms:

  • Heading text: "Hook input and output"
  • Markdown anchor slug: "hook-input-and-output"

Leading # characters are stripped before comparison.

docs verify

Usage: skilllint docs verify [OPTIONS] FILE_PATH

Arguments:
  file_path             Path to the cached markdown file to verify.

Options:
  --help                Show this message and exit.

Exits 0 when the file is intact. Exits 1 when the file has been modified or when no sidecar exists.

All four command names are aliases for the same tool:

skilllint   # primary
agentlint   # alias
pluginlint  # alias
skillint    # alias

Vendor documentation cache

skilllint docs provides an offline-first cache for vendor documentation pages. Pages are fetched once and stored locally; subsequent calls within the TTL window are served from disk without a network request. When the TTL has expired but the network is unavailable, the stale copy is served automatically.

Cached files are written to .claude/vendor/sources/ with filenames in the format {page-name}-{YYYY-MM-DD-HHMM}.md. Each file is accompanied by a .meta.json integrity sidecar that records the SHA-256 digest, byte count, source URL, and fetch timestamp.

# Cache a documentation page (default TTL: 4 hours)
skilllint docs fetch https://docs.anthropic.com/en/docs/claude-code/settings.md

# Pre-fetch all normalized rule authority URLs
skilllint docs fetch-authorities

# Force a network refresh regardless of TTL
skilllint docs fetch https://docs.anthropic.com/en/docs/claude-code/settings.md --force

# Find the most recently cached copy of a page
skilllint docs latest claude-code--settings

# List all sections with line ranges
skilllint docs sections .claude/vendor/sources/claude-code--settings-2025-01-01-1200.md

# Extract a section by heading text or markdown anchor slug
skilllint docs section .claude/vendor/sources/claude-code--settings-2025-01-01-1200.md "Hook input and output"
skilllint docs section .claude/vendor/sources/claude-code--settings-2025-01-01-1200.md "hook-input-and-output"

# Verify a cached file against its sidecar
skilllint docs verify .claude/vendor/sources/claude-code--settings-2025-01-01-1200.md

Section extraction uses marko for AST-based markdown parsing, so # characters inside fenced code blocks are never mistaken for headings.

If skilllint is not installed, use uvx to run it without a permanent install:

uvx skilllint docs fetch https://docs.anthropic.com/en/docs/claude-code/settings.md

scripts/fetch_doc_source.py is a PEP 723 standalone script that exposes the same commands via uv run --script. It is intended for contributors working directly on the skilllint source tree (where [tool.uv.sources] points the dependency at the local package), not for end users.


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": ["LK002", "SK006"]
  }
}

Key format:

KeyScope
"" (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.

See docs/ignore-config.md for the full reference.


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

Ver o original no GitHub

Bom para

Relacionados