← Voltar ao curso
Nível 2 — Ferramenta de trabalho · Módulo 2.4 — Skills de verdade

2.4.2 · Skills multi-arquivo: reference e scripts

5 min de vídeo TODOS

Objetivo: ao final, o consultor mantém o SKILL.md principal enxuto, empurrando o peso de um procedimento longo para um reference.md ao lado, e sabe que scripts na pasta da skill são executados, não descritos.

O que você precisa levar desta aula

  1. reference.md fica ao lado do SKILL.md, linkado de dentro dele — mantém o arquivo principal enxuto.
  2. O Claude só lê o reference.md quando a pergunta realmente exige aquele nível de profundidade, não toda vez que a skill dispara.
  3. Scripts na pasta da skill (como check.sh) são executados, não carregados como texto no contexto — a skill "carrega sua própria ferramenta" em vez de descrever em palavras o que fazer.

Anatomia de uma skill multi-arquivo

Arquivo Papel É lido ou executado?
SKILL.md Resumo enxuto + quando disparar (description) + link para o resto Lido, sempre que a skill dispara
reference.md Procedimento completo, longo, detalhado Lido só quando a pergunta exige esse nível de profundidade
check.sh (ou outro script) Verificação, cálculo, ação determinística Executado, não lido como texto

O que muda em cada caso

Por que isso economiza contexto

Se as 20 páginas do procedimento estivessem dentro do SKILL.md, cada disparo da skill carregaria tudo — a mesma lógica de custo do módulo 2.2. Com reference.md separado, o custo só é pago quando a profundidade é realmente necessária.

Regra Wayon Todo script dentro de uma pasta de skill passa por revisão de código antes de entrar em uso — ele executa com as mesmas permissões da sua sessão. Um script malfeito não é "só uma sugestão de texto que você pode ignorar"; ele roda.

📖 Skills — arquivos de referência e scripts

Quiz — 4 questões

1.Por que manter o procedimento completo de 20 páginas num reference.md separado, em vez de dentro do SKILL.md?
  • a)Porque o SKILL.md tem um limite rígido de linhas

    Não é uma restrição técnica de tamanho; é uma escolha para não inflar o contexto a cada disparo.

  • b)Porque o reference.md é mais fácil de editar que o SKILL.md

    Não é uma questão de facilidade de edição; é de quando o conteúdo entra no contexto.

  • c)Porque assim o conteúdo completo só é carregado quando a profundidade é realmente necessária

    Correto.

Ver resposta e por quê
❌a) Não é uma restrição técnica de tamanho; é uma escolha para não inflar o contexto a cada disparo.
❌b) Não é uma questão de facilidade de edição; é de quando o conteúdo entra no contexto.
✅c) Correto.
2.Uma pergunta simples sobre a skill de cutover ("quando começa a janela?") chega. O que acontece com o reference.md?
  • a)É sempre lido junto, para garantir que a resposta esteja completa

    Ao contrário — só é lido quando a pergunta exige aquele nível de profundidade.

  • b)Não precisa ser aberto — o resumo do SKILL.md já resolve

    Correto.

  • c)É lido parcialmente, só a primeira página

    Não existe essa leitura parcial automática; ou é aberto porque a pergunta exige, ou não é aberto.

Ver resposta e por quê
❌a) Ao contrário — só é lido quando a pergunta exige aquele nível de profundidade.
✅b) Correto.
❌c) Não existe essa leitura parcial automática; ou é aberto porque a pergunta exige, ou não é aberto.
3.O que acontece com check.sh, dentro da pasta da skill, quando a skill dispara e a verificação é necessária?
  • a)O script é executado de verdade, com saída real

    Correto.

  • b)O Claude lê o conteúdo do script e explica em texto o que ele faria

    Não é isso que acontece — o script é executado de verdade, não descrito.

  • c)O script só roda se o consultor pedir explicitamente "execute o check.sh"

    A skill já carrega e roda o script como parte do próprio procedimento, sem precisar desse pedido explícito adicional.

Ver resposta e por quê
✅a) Correto.
❌b) Não é isso que acontece — o script é executado de verdade, não descrito.
❌c) A skill já carrega e roda o script como parte do próprio procedimento, sem precisar desse pedido explícito adicional.
4.Você encontrou, dentro da pasta de uma skill compartilhada pela squad, um script que apaga arquivos de uma pasta temporária. Antes de usar essa skill num projeto de cliente: ---
  • a)Pode confiar, já que está dentro de uma skill e não é código "de verdade"

    É código de verdade — ele executa com as permissões da sessão, exatamente como qualquer outro script.

  • b)Revisar o script como revisaria qualquer código antes de rodar contra dado de cliente

    Correto. Scripts em pasta de skill são executados, não meras sugestões de texto.

  • c)Ignorar, já que scripts de skill não têm acesso ao sistema de arquivos real

    Têm acesso real — é exatamente por isso que a revisão é necessária.

Ver resposta e por quê
❌a) É código de verdade — ele executa com as permissões da sessão, exatamente como qualquer outro script.
✅b) Correto. Scripts em pasta de skill são executados, não meras sugestões de texto.
❌c) Têm acesso real — é exatamente por isso que a revisão é necessária.