Skills do Claude Code: manter recursos sem inflar o contexto
Auditoria prática de skills do Claude Code: separe regras persistentes de recursos sob demanda e verifique a descoberta correta.
Conteúdo
Scripts, regras e modelos se acumulam rapidamente. Transformar cada ajuda em instrução permanente consome contexto antes da primeira tarefa. Faça o inventário dos skills e separe regras persistentes de fluxos sob demanda.
O que entra no contexto
Com on, Claude Code recebe nome e description; name-only mantém somente o nome. user-invocable-only e disable-model-invocation: true ocultam a descrição do modelo, enquanto off oculta o skill. O corpo de SKILL.md carrega na invocação e fica na sessão; referências são lidas quando necessárias e scripts rodam como ferramentas. Veja a documentação oficial.
Separe anúncio da lista, corpo carregado e recursos sob demanda. Não coloque manuais longos em description ou CLAUDE.md. O Dashboard BetterToken permite comparar testes de API por modelo, hora, status, input, output e cache tokens, mas não mede contexto local nem substitui /context; consulte os BetterToken Docs.
Inventário e /skill-doctor
Rode /skill-doctor localmente quando a lista ficar difícil de avaliar. Stats em /plugin mostram custo de contexto e frequência de chamada, incluindo skills carregados sem uso, mas excluem skills integrados e corporativos; veja a documentação do relatório. Compare a lista com tarefas reais: não ter chamadas não significa que um skill seja inútil; uma recuperação pode ser necessária apenas a cada alguns meses. Para um skill pessoal ou de projeto pouco frequente, selecione user-invocable-only em /skills (exibido como user-only). Use off apenas se ele não for mais necessário nesse ambiente. Gerencie skills de plugins em /plugin. Em uma sessão nova, compare /context, uma tarefa comum e uma chamada explícita ao skill mantido. As notas de v2.1.261 mencionam o comando; a documentação atual indica v2.1.252 como mínimo. Confira claude --version e feature flags. Remote Control não oferece o relatório: use o terminal da máquina em que a sessão está rodando. Se o comando não estiver disponível, continue o inventário manual.
Compare .claude/skills/ e ~/.claude/skills/ com /skills em cada ambiente. Um skill aninhado pode aparecer depois de seu diretório ser lido ou alterado; plugins usam namespace, não skillOverrides; skills sincronizados podem diferir entre local, Cowork e cloud. Deixe regras frequentes curtas em CLAUDE.md, procedimentos em skills de description específica e rotinas raras de segurança, recuperação ou release disponíveis por chamada explícita.
Escolher o mecanismo que aplica a regra
| Necessidade | Local |
|---|---|
| Lembrete recorrente | Regra curta em CLAUDE.md |
| Regeneração de documentação | Skill dedicado |
| Recusar antes de escrever | Hook PreToolUse |
| Checagem independente | Subagent com permissões mínimas |
| Leitura externa permitida | MCP |
Instruções não bloqueiam escrita: teste evento, matcher e recusa real. Write não bloqueia escrita por Bash, e subagent separado não é automaticamente read-only. Consulte mecanismos, Hooks, regras CLAUDE.md, Stop Hook e MCP ou comando.
Stop Hook verifica o término do trabalho; não substitui PreToolUse antes de uma escrita. Mantenha uma regra curta e um link para o skill em CLAUDE.md, sem copiar o procedimento inteiro para todos os mecanismos.
Frontmatter compacto e scripts
---
name: db-migrator
description: >-
Use para validar e aplicar migrações Prisma após uma alteração de schema.
---Coloque lógica repetível em scripts/:
<!-- Dentro de SKILL.md -->
```bash
python3 "${CLAUDE_SKILL_DIR}/scripts/validate_schema.py" --strict
```Não desative verificações de segurança, linters ou tipos para economizar tokens.
Quatro verificações
SKILL.mdexiste.- O frontmatter é YAML e tem
descriptionnão vazia. references/,examples/escripts/resolvem a partir do diretório do skill.- O script roda com entrada segura e retorna o código esperado.
Python chamado por python3 não precisa de bit executável; test -f não valida YAML. Em sessões novas, confira /skills, uma chamada explícita e uma solicitação correspondente sem citar o skill. Compare /skill-doctor, /doctor e /context antes e depois de uma mudança, considerando tokens e trigger correto.
