CommunityEscrita e Ediçãogithub.com

skill-checkup

Skill-checkup diagnostica por que um SKILL.md não é acionado de forma confiável, executa uma simulação do seu fluxo de trabalho e reestrutura o pacote. 4 scripts determinísticos, sem dependências em tempo de execução.

O que é skill-checkup?

Skill-checkup é uma ferramenta de auditoria especializada para skills do Claude Code. Seu propósito principal é diagnosticar e melhorar arquivos SKILL.md que não estão sendo acionados de forma confiável pelo modelo. Ao invés de ser um manual rígido, a skill atua como uma bússola que avalia a probabilidade de cada regra ser entregue à atenção do modelo no momento correto, usando quatro lentes: harness (o que é injetado e quando), model (como o viés do modelo e a perda de contexto impactam), hard code (scripts que impõem regras que o texto não consegue) e structure (roteamento, lista de tarefas e recibos). A ferramenta suporta uma execução passo a passo que inclui leitura do SKILL.md alvo, verificação de orçamento de descrição, análise de rotas, simulação de prompts, verificação de injeção em tempo real e geração de um relatório de diagnóstico detalhado, com recomendações e uma camada de decisão para o usuário. É útil para desenvolvedores que criam e mantêm skills do Claude Code e precisam garantir que seus SKILL.md sejam eficazes, acionados corretamente e sigam as melhores práticas.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add Zane456/skill-checkup

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Skill Checkup (Skill Checkup)

Diagnostique e melhore qualquer SKILL.md. Uma bússola, não um manual — os padrões vivem em references/.

Função — auditor de entrega. Uma skill não é seu texto; é a probabilidade de que cada regra chegue à atenção do modelo no momento em que se aplica. Cada descoberta serve a essa quantidade, através de quatro lentes: harness (o que é injetado quando: descrição a cada turno, corpo no acionamento, referências apenas via Leitura), model (economizando viés, decaimento de contexto, saltos silenciosos), hard code (scripts impõem o que a prosa não pode), structure (roteamento, lista de tarefas, recibos).

Fluxo de diagnóstico (cada etapa deve imprimir)

Etapas silenciosas são puladas (Seleznov, 2026) — imprima uma linha de confirmação por etapa. Sinalizador de auto-revisão: se esta sessão já Editou/Escreveu o SKILL.md alvo, prefixe cada linha de impressão do skill-checkup com [auto-revisão], e um subagente cego de re-auditoria DEVE ser executado antes que o trabalho seja declarado concluído — inicie-o com caminhos de arquivo explícitos e NENHUMA descoberta esperada (procedimento + escalonamento multi-alvo: runtime-contract.md §4), então imprima: [skill-checkup] re-verificação de auto-revisão: <agente> → <sumário do veredito> Se não puder ser executado, diga explicitamente e marque o trabalho como não verificado — silêncio não é uma opção.

Etapa 1: Leia o alvo, execute os três verificadores

Leia o SKILL.md alvo por completo, então execute os três verificadores via python3 <this-skill-dir>/scripts/… (coloque caminhos entre aspas — espaços são comuns): check_listing_budget.py "<project_root>" --target "<skill_name>", check_routes.py "<skill_dir>", check_script_safety.py "<skill_dir>". Todos os três executam TODA auditoria; acertos de bússola/tapete/orfão = P1. Imprima cinco linhas:

[skill-checkup] Auditando: <caminho>  corpo=<N> linhas  descrição=<M> caracteres
[skill-checkup] Orçamento: <K> skills instaladas, descrições <T> caracteres vs ≈<B> → <cabe | SOBRECARGA ×N.N>
[skill-checkup] Sobreposição: <limpo | N par(es), M com alvo>
[skill-checkup] Rotas: <PASSOU | N problema(s): bússola-sobre/tapete/orfão>
[skill-checkup] Segurança: <limpo | N acerto(s): <classes>>

Saída do orçamento 2 = indisponível → linha de fallback. Categorização: sobrecarga e sobreposição não alvo = APENAS AVISO; sobreposição alvo = P2 (description-templates.md §distinção); acertos de segurança = P0 quando CRÍTICO, senão P1, pendente de legitimidade (hard-code-vs-llm-judgment.md); Segurança limpo → apenas linha de recibo, nunca uma linha de relatório. Nunca edite a skill auditada para um aviso de população; nunca exclua automaticamente um acerto de segurança (redução = passe de usuário global).

Etapa 2: Liste as dimensões, então leia UMA de cada vez

Execute python3 <this-skill-dir>/scripts/index.py "<skill_dir>" — ele mede o alvo e imprime a lista de dimensões (FORÇADO / PADRÃO / PULAR + razões) mais uma linha MODO=. O script é autoritativo para disparo; references/index.md é seu espelho legível por humanos — não re-julgue o disparo a partir da prosa. MODO=inline → percorra a lista um arquivo por iteração: Leia-o → julgue o alvo contra APENAS essa dimensão → imprima um recibo → próximo arquivo. Pulos PADRÃO devem citar a condição de pulo impressa na lista. MODO=fanout → runtime-contract.md §4.

[skill-checkup] <dimensão>: <N> descobertas

Etapa 2.5: Simulação de passos (simulação positiva quando passos-ordenados=Verdadeiro; negativa SEMPRE)

Seguindo references/effect-dry-run.md, pegue UM prompt típico POR formato de tarefa que a descrição promete (escrever / revisar / verificar, 1–3; prompt de revisão de pequeno escopo obrigatório para skills de edição). Percorra cada um através dos passos do corpo: entrada/instrução/saída se conectam, E quais portões rígidos disparam nessa granularidade. Qualquer link quebrado / ambiguidade / gatilho que nenhuma forma comum aciona → P0, na Etapa 3 da camada de Código. Imprima uma linha por prompt:

[skill-checkup] Simulação "<prompt>" (forma: <escrever|revisar|verificar>)  links quebrados=<N>  portões disparados=<M>/<total>

Nenhum processo ordenado (skill de regra / referência pura) → imprima:

[skill-checkup] Simulação: simulação positiva pulada (nenhum fluxo de trabalho)

SEMPRE (com ou sem fluxo de trabalho): julgue 1–2 prompts que NÃO-DEVERIAM-acionar contra a descrição sozinha, de acordo com effect-dry-run.md §negativo. Capturado → P2 [sobre-acionamento]. Imprima:

[skill-checkup] Simulação negativa: <K> prompts, falso-disparo=<J>

Etapa 2.6: Verificação de injeção ativa (quando o alvo está no escopo desta sessão)

O alvo aparece na lista de skills disponíveis desta sessão com sua descrição (não apenas nome)? 3 casos + regra de aviso de população → references/live-injection-check.md. Imprima uma linha:

[skill-checkup] Injeção ativa: <injetado | DESCARTADO (apenas nome) | pulado (<razão>)>

Etapa 3: Produza o relatório de diagnóstico

Apresente de acordo com references/output-format.md — um relatório em camadas no estilo lesstoken, no idioma de resposta do usuário: veredito → pontuações de qualidade → camada de Código (P0→P3, evidência arquivo:linha) → camada de Decisão dividida em ✅ Seguro corrigir agora vs 🤔 Precisa da sua decisão → pergunta de encerramento.

Substância que preenche as camadas:

  • Cada descoberta: ID estável (P0-1 …), linha/campo específico, risco 🟢/🟡/🔴, classificado P0→P3 (references/priority-tiers.md); mesma violação em N lugares = N descobertas; o mesmo defeito de duas dimensões = deduplicado para um antes da classificação.
  • Nomeie o modo de falha quando um se aplica — um rótulo de predictability-glossary.md: [sem-efeito]/[sedimento]/[conclusão-prematura]/[palavra-líder-fraca]/[duplicação]/[espalhamento]/[sobre-acionamento]/[sem-piso]/[lacuna-de-portão]/[licença-ausente]. Prefixo = que tipo, Nível-P = quão ruim.
  • Cada item 🤔 separa mecanismo (comportamento agora) de consequência (o que o próximo LLM faz de errado), então opções + recomendação.

Etapa 4: Aplique com Editar após confirmação do usuário

Nunca Edite sem confirmação — aguarde o usuário "corrigir".

Antes de agir: portão de tamanho + verificação pré-exclusão; depois feche o ciclo — procedimento em references/apply-safety.md. Após corrigir, imprima uma linha:

[skill-checkup] Aplicadas <N> correções em <caminho>  corpo: <antigo>→<novo> linhas (<+X%>)

Referência rápida de regras rígidas

Regras rígidas quantificadas (violação = erro) → references/hard-rules.md, consulte toda auditoria.

Fallback de exceção

Quando um caminho está ausente, YAML não é analisado ou qualquer script incluído em scripts/ está ausente ou sai com 2 — trate de acordo com references/exception-fallback.md (a lista de scripts autoritativa está lá); anuncie primeiro, nunca pule silenciosamente.

Idioma

Inglês padrão; sinalize não-Inglês injustificado ⚠️; política + 2 exceções → references/language-policy.md.

Fora do escopo

Correção de domínio do conteúdo (bug de lógica, não de forma — comportamento de execução está no escopo → runtime-contract.md); convenções do projeto (→ CLAUDE.md); scripts de correção pontual.

Por que existe

LLMs escrevem manuais; a divisão mecânico-vs-julgamento: references/rationale.md.

Habilidades Relacionadas