Claude Skill Lint
gesh75/claude-skill-lint
Validador estrutural para skills Claude com regras de custo e confiabilidade
Ver no GitHubLinter de zero dependências para skills do Claude Code que valida frontmatter, comprimento de descrições, disclosure progressivo, links mortos e IDs de modelos desatualizados. Garante que sua biblioteca de skills mantenha qualidade e performance, evitando descrições bloated que consumem contexto em toda execução.
Instalação
npx convez-ai gesh75/claude-skill-lint1 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
Casos de uso
- Auditar e manter biblioteca de skills Claude Code
- Detectar descrições e bodies bloated que degradam performance
- Validar integridade de frontmatter e referências em lote
- Integrar verificações em CI/CD com exit codes informativos
Veredito

Ferramenta essencial e pragmática para quem mantém múltiplas skills no Claude Code. Zero dependências e design minimalista a tornam confiável; regras codificadas (tamanho desc, progressive disclosure, links mortos) endereçam problemas reais de custo e confiabilidade que escalas maiores revelam.
README
A tradução para o português deste README ainda está na fila.
claude-skill-lint
A tiny, zero-dependency linter for Claude Code skills.
Point it at your ~/.claude/skills directory and it flags the things that quietly
degrade a skills library: broken frontmatter, descriptions that are too long
(they're loaded into context on every turn), bloated skill bodies that should
use progressive disclosure, dead reference/ links, and outdated model IDs.
$ skill_lint.py ~/.claude/skills
! [WARN ] api-design: body is 417 lines (> 400); move detail to reference/*.md (bloated-body)
✗ [ERROR] token-budget-advisor: link points to a missing file: ../context-budget/SKILL.md (dead-reference)
Scanned 124 skills in /Users/me/.claude/skills
122 clean · 1 errors · 1 warnings · 0 info
Why
A Claude Code skill has two cost surfaces:
- its
descriptionis loaded into context on every turn — so a bloated or vague description is a permanent tax and a trigger-reliability problem; - its body is loaded only when the skill fires — so large bodies should push
detail into
reference/*.md(progressive disclosure) instead of sitting inline.
This linter encodes those rules, plus the structural checks (valid frontmatter, names that match, no dead links) that keep a library trustworthy.
Install
No dependencies beyond Python 3.8+.
Option 1 — install script
Installs a skill-lint command to ~/.local/bin (review the script first, as you should with any installer):
curl -fsSL https://raw.githubusercontent.com/gesh75/claude-skill-lint/main/install.sh -o install.sh
bash install.sh # then run: skill-lint ~/.claude/skills
Customize with env vars — VERSION=v0.1.0 pins a release, BIN_DIR=/usr/local/bin changes the location:
VERSION=v0.1.0 BIN_DIR=/usr/local/bin bash install.sh
Option 2 — single file
curl -O https://raw.githubusercontent.com/gesh75/claude-skill-lint/main/skill_lint.py
chmod +x skill_lint.py
Usage
skill_lint.py [PATH] [--json] [--max-desc N] [--max-body N] [--quiet]
| Flag | Default | Meaning |
|---|---|---|
PATH | ~/.claude/skills | directory to scan |
--json | off | machine-readable output |
--max-desc | 350 | max description length (chars) before a warning |
--max-body | 400 | max body length (lines) before a warning |
--quiet | off | hide INFO findings |
Exit code is non-zero when any ERROR-level finding exists, so it drops straight into CI or a pre-commit hook.
Examples
Audit your whole skills library (the default path):
$ skill_lint.py
! [WARN ] api-design: body is 417 lines (> 400); move detail to reference/*.md (progressive disclosure) (bloated-body)
! [WARN ] blueprint: description is 364 chars (> 350); it's loaded every turn — tighten it (long-description)
✗ [ERROR] token-budget-advisor: link points to a missing file: ../context-budget/SKILL.md (dead-reference)
Scanned 124 skills in /Users/me/.claude/skills
121 clean · 1 errors · 2 warnings · 0 info
$ echo $?
1
Scan a specific directory, errors/warnings only:
skill_lint.py ./my-plugin/skills --quiet
Machine-readable output (pipe to jq, a dashboard, or a bot):
$ skill_lint.py --json | jq '.summary'
{
"errors": 1,
"warnings": 2,
"info": 0
}
Tighten the budgets — fail on descriptions over 250 chars or bodies over 300 lines:
skill_lint.py --max-desc 250 --max-body 300
As a pre-commit hook (.git/hooks/pre-commit):
#!/usr/bin/env bash
python3 skill_lint.py "$HOME/.claude/skills" --quiet || {
echo "skill-lint found errors — commit aborted."; exit 1;
}
What counts as a skill
Exactly two shapes — nothing else:
- a top-level
<name>.md, or - a
<dir>/SKILL.md.
reference/, rules/, agents/, and sibling content files are supporting
material and are deliberately not linted as skills (so counts stay accurate).
Checks
| Code | Level | What it catches |
|---|---|---|
no-frontmatter | ERROR | no --- frontmatter block |
no-name | ERROR | missing name: (skill won't register) |
no-description | ERROR | missing description: |
dead-reference | ERROR | a Markdown link to a local .md that doesn't exist |
name-mismatch | WARN | name: doesn't match the file/dir name |
long-description | WARN | description over --max-desc chars |
bloated-body | WARN | body over --max-body lines (use progressive disclosure) |
stale-model-id | WARN | an outdated Claude model id (e.g. claude-3-*, claude-opus-4-1) |
short-description | INFO | description under 30 chars (may not trigger) |
Current model ids — Opus 4.8 (claude-opus-4-8), Sonnet 4.6 (claude-sonnet-4-6),
Haiku 4.5 (claude-haiku-4-5) — are not flagged.
CI
# .github/workflows/lint.yml
name: skill-lint
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: "3.x" }
- run: python3 skill_lint.py . --quiet
License
MIT — see LICENSE.