shimo4228/skill-stocktake

skill-stocktake — Auditoria de Qualidade de Skills

Avalie as habilidades instaladas de forma holística, todas em um único contexto, e atribua a cada uma um veredito: Keep (Manter) / Improve (Melhorar) / Update (Atualizar) / Retire (Aposentar) / Merge (Fundir). Este skill NÃO faz a melhoria — uma vez que tem um veredito, ele repassa para o skill-creator (o mecanismo de melhoria). Esse limite é o ponto: stocktake é o gate de qualidade, skill-creator é o responsável por corrigir.

Nota de design: a versão antiga usava scripts de varredura externos e dividia a avaliação em lotes de ~20 habilidades por subagente. Com um contexto de 1M, isso não é apenas desnecessário, mas prejudicial — o loteamento impede que cada subagente veja habilidades de outros lotes, perdendo a sobreposição entre skills. Agora enumeramos com Glob e lemos cada skill em um único contexto. A detecção de sobreposição depende dessa visão de contexto único.

Modos ($ARGUMENTS)

Argumento	Comportamento
nenhum / full	Ler e avaliar cada skill (padrão)
changed	Reavaliar apenas skills cujo SKILL.md tem mtime mais recente que evaluated_at em results.json; manter os demais vereditos do registro

changed detecta mudanças inline (sem script):

find ~/.claude/skills -name SKILL.md -newermt "$(jq -r .evaluated_at ~/.claude/skills/skill-stocktake/results.json)"

Fase 1 — Inventário

Enumere os arquivos de definição de skills com Glob (nenhum script necessário):

• ~/.claude/skills/*/SKILL.md
• ~/.claude/skills/learned/*.md
• se o diretório de trabalho atual tem .claude/skills/, também {cwd}/.claude/skills/*/SKILL.md (skills do projeto)

Como o Glob tem como alvo apenas SKILL.md / learned/*.md, markdowns de dependência sob .venv ou .pytest_cache são estruturalmente excluídos (nenhuma poda necessária). O ruído que o antigo find -name "*.md" trazia não pode ocorrer.

Contagens de uso: leia ~/.claude/metrics/skill-usage.jsonl inline (o hook PostToolUse log-skill-usage.sh adiciona a ele — uma camada de medição independente) e conte eventos por skill em 7 / 30 / 90 dias. Cada linha é JSON {ts,event,skill,path,project}; conte tanto eventos invoke quanto read. Agregue com um one-liner descartável de python3/jq em vez de contar manualmente — o log cresce com o tempo e contar manualmente desperdiça uma chamada de ferramenta por invocação.

• Se o log estiver ausente ou seu primeiro evento for mais recente que 90 dias, exiba o uso como — (não medido). Nunca o exiba como 0 — não medido e não usado são fatos diferentes.

Declare o resultado da varredura logo no início: quais caminhos foram escaneados, quantos skills encontrados e se o uso é mensurável.

Fase 2 — Avaliação (totalmente inline, holística)

Leia o corpo de cada skill alvo e avalie-os um por um enquanto vê o conjunto inteiro. Checklist:

• Sobreposição de conteúdo com outras skills (uma divisão documentada orquestrador/sub-skill NÃO é sobreposição — por exemplo, paper-ecosystem → seus revisores, citation-sync → release-doi/wikidata. Distinga camadas intencionais de duplicação genuína)
• Sobreposição com MEMORY.md / CLAUDE.md / regras
• Atualidade de referências técnicas (se flags de CLI / APIs / nomes de ferramentas parecem desatualizados, confirme com WebSearch)
• Frequência de uso (ignore como sinal quando não medido)

A avaliação é julgamento holístico, não uma rubrica numérica. Dimensões orientadoras: Acionabilidade (exemplos/passos concretos que você pode executar), Adequação de escopo (nome, trigger e corpo alinhados — nem muito amplo nem muito restrito), Unicidade (não substituível por MEMORY / outra skill), Atualidade (referências funcionam no ambiente atual).

Custo agregado (nível de conjunto, não por skill): manter uma skill não é gratuito mesmo quando a skill é individualmente boa. Os benefícios de um skill são frágeis — uma biblioteca grande e não curada degrada a capacidade do agente de selecionar o skill certo e puxa o comportamento de volta para a linha de base sem skills. Portanto, o limite para Keep aumenta com o tamanho da biblioteca: quando o conjunto é grande, um skill meramente adequado (uso raro, baixa unicidade, forte adjacência a outros) é um candidato a Retire/Merge apenas por razões de diluição agregada — independente de qualquer defeito no skill em si. Isso é uma entrada de julgamento, nunca uma cota; não aposente para atingir um número.

Veredito	Significado
Keep	Útil, atual, valor único
Improve	Vale a pena manter, mas melhorias específicas são necessárias
Update	A tecnologia referenciada está desatualizada (verifique com WebSearch)
Retire	Baixa qualidade, desatualizado ou custo-assimétrico
Merge into [X]	Sobreposição substancial com outra skill; nomeie o alvo

Regra de uso zero: quando o primeiro evento do log de uso tem pelo menos 90 dias E um skill tem use_90d == 0, ele DEVE ser apresentado como candidato a Retire (a decisão final é do usuário). Enquanto o log for mais recente que 90 dias, esta regra não é ativada, e os vereditos recaem apenas no julgamento holístico.

A avaliação é cega quanto à origem: não ramifique com base em ECC / auto-criação / extração automática. O mesmo checklist se aplica a cada skill.

Fase 3 — Resumo

Renderize uma tabela: Skill | 7d | 90d | Veredito | Motivo.

Fase 4 — Consolidação

• Retire / Merge: por arquivo, apresente (1) o defeito específico encontrado, (2) o que cobre a mesma necessidade em vez disso (Retire: qual skill/regra existente; Merge: o alvo e qual conteúdo integrar), (3) o impacto da remoção (skills dependentes, referências em MEMORY). Aja apenas após o usuário confirmar.
• Improve / Update: ofereça para repassar — "Repassar <skill> para o skill-creator para melhorar?" — e, após aprovação, invoque skill-creator com o skill alvo. Stocktake nunca faz o trabalho de melhoria em si.
• Atualize o registro: Leia results.json → mescle os vereditos desta execução → Escreva de volta (evaluated_at = UTC real de date -u +%Y-%m-%dT%H:%M:%SZ). No modo changed, preserve os vereditos anteriores dos skills que você não reavaliou.
• Se MEMORY.md exceder 100 linhas, proponha compressão.

Qualidade do motivo (obrigatório)

Cada reason (motivo) deve ser autossuficiente — que permita a tomada de decisão por si só. "inalterado" sozinho é proibido; sempre reafirme a evidência.

• Retire: declare o defeito + a substituição. Ruim: "Substituído" / Bom: "disable-model-invocation: true já definido; continuous-learning-v2 cobre os mesmos padrões mais pontuação de confiança. Nenhum conteúdo único permanece."
• Merge: nomeie o alvo + o que integrar. Ruim: "Sobreposição com X" / Bom: "Conteúdo fino de 42 linhas; o Passo 4 de chatlog-to-article já cobre este fluxo. Integre a dica de 'ângulo do artigo' lá como uma nota."
• Improve: qual seção, qual mudança (tamanho alvo se relevante). Ruim: "Muito longo" / Bom: "276 linhas; 'Comparação de Frameworks' (L80–140) duplica ai-era-architecture-principles. Delete-o para atingir ~150 linhas."
• Keep (mudança apenas de mtime no modo changed): reafirme a justificativa original. Ruim: "Inalterado" / Bom: "Conteúdo inalterado. Referência Python única importada explicitamente por rules/python/; nenhuma sobreposição."

results.json (registro enxuto)

{
  "evaluated_at": "2026-06-24T11:09:00Z",
  "skills": {
    "<nome-do-skill>": {
      "path": "~/.claude/skills/<nome>/SKILL.md",
      "verdict": "Keep",
      "reason": "...",
      "mtime": "2026-01-15T08:30:00Z"
    }
  }
}

Um registro para o histórico de vereditos e o timestamp da última auditoria apenas. Atualize-o inline com Read/Write, não com um script. Apenas skills globais (skills de projeto são lidos frescos do diretório atual, não armazenados em cache aqui).

Relacionados

• skill-creator — o mecanismo de melhoria; repasse o trabalho de Improve/Update para ele.
• config-gc — GC sobre a existência do skill e todo o ~/.claude (hooks/permissões/MCP/cache); stocktake julga a qualidade do skill.
• harness-sync — use para sincronizar este skill com seu repositório público.
• Medição de uso: ~/.claude/hooks/log-skill-usage.sh → ~/.claude/metrics/skill-usage.jsonl (uma camada de medição independente do stocktake).