convez.ai
SkillDevOps & InfraestruturaIntermediário
gesh75

Claude Skill Lint

gesh75/claude-skill-lint

Validador estrutural para skills Claude com regras de custo e confiabilidade

Ver no GitHub
InicialPluginScore · de 0 a 100

Linter 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-lint

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
2
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
v0.5.0
Issues abertas
0
Contribuidores
2

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

ci license: MIT python: 3.8+

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 description is 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]
FlagDefaultMeaning
PATH~/.claude/skillsdirectory to scan
--jsonoffmachine-readable output
--max-desc350max description length (chars) before a warning
--max-body400max body length (lines) before a warning
--quietoffhide 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

CodeLevelWhat it catches
no-frontmatterERRORno --- frontmatter block
no-nameERRORmissing name: (skill won't register)
no-descriptionERRORmissing description:
dead-referenceERRORa Markdown link to a local .md that doesn't exist
name-mismatchWARNname: doesn't match the file/dir name
long-descriptionWARNdescription over --max-desc chars
bloated-bodyWARNbody over --max-body lines (use progressive disclosure)
stale-model-idWARNan outdated Claude model id (e.g. claude-3-*, claude-opus-4-1)
short-descriptionINFOdescription 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.

Ver o original no GitHub

Bom para

Relacionados