Anatomia de uma Skill: instruções, contexto, ferramentas e limites

Uma Skill bem escrita não é um bloco único de texto. É a combinação de pelo menos quatro componentes que fazem trabalhos diferentes: o que o agente deve fazer naquele domínio, o que ele precisa saber para fazer bem, o que ele pode acionar para agir, e onde para. Confundir esses papéis é o que costuma produzir Skills que funcionam bem em teste isolado e falham de forma estranha em uso real.

Definição de papel: o que essa Skill representa

A primeira camada é a definição de escopo e papel, geralmente expressa logo no início do corpo do SKILL.md: qual domínio essa Skill cobre, sob que perspectiva. Isso normalmente já está implícito na description do frontmatter, mas o corpo do arquivo pode aprofundar: como o agente deve se posicionar diante de ambiguidade, que tom de resposta é esperado, o que está dentro do escopo da Skill e o que deveria ser tratado por outra parte do sistema.

Sem essa definição, o restante da Skill fica sem referência: instruções técnicas soltas sem indicação clara de quando e como aplicá-las.

Contexto: informação que o modelo não teria por conta própria

Contexto é o conhecimento específico daquele domínio que o modelo não carrega por padrão: convenção interna, terminologia própria, estrutura de dado particular daquele sistema. É aqui que entra a divulgação progressiva como princípio de design, não só como detalhe técnico de implementação.

No nível mais leve, só nome e descrição da Skill ficam sempre carregados, o suficiente para o agente saber que aquela Skill existe e quando ela pode se aplicar. O corpo do SKILL.md só entra em jogo quando a Skill é de fato acionada. Arquivos de referência mais extensos, terceiro nível, só são lidos quando a instrução principal aponta explicitamente para eles. Contexto bem organizado nessa hierarquia evita que informação raramente necessária ocupe espaço o tempo inteiro, e evita, ao mesmo tempo, que informação necessária fique de fora por medo de sobrecarregar o início.

Ferramentas: o que a Skill autoriza o agente a fazer

Uma Skill pode instruir o uso de ferramentas específicas, seja invocando função definida externamente, seja executando script incluído junto dela. O ponto central aqui é que a Skill não cria capacidade nova por conta própria: ela orienta como e quando usar capacidades que já existem no ambiente onde o agente está rodando.

O princípio do menor privilégio se aplica diretamente nesse componente. Uma Skill que instrui o uso de uma ferramenta ampla demais para uma tarefa estreita cria superfície de erro desnecessária. Instruções claras sobre exatamente qual ferramenta, com quais parâmetros, para qual situação, reduzem a chance de o agente inventar um uso de ferramenta que a instrução nunca pretendeu autorizar, o tipo de alucinação de ferramenta que costuma aparecer quando a orientação é vaga demais sobre o que realmente está disponível.

Limites: onde a Skill explicitamente para

O quarto componente, com frequência o mais negligenciado, é a fronteira: o que a Skill não deve fazer, mesmo que tecnicamente fosse possível dentro do que as ferramentas disponíveis permitem. Isso inclui casos de borda que deveriam ser escalados em vez de resolvidos automaticamente, tipos de dado sensível que não deveriam ser expostos sem confirmação, e situações em que a resposta correta é reconhecer incerteza em vez de seguir adiante com uma suposição.

## Quando não prosseguir

Se o valor solicitado ultrapassar o limite configurado, não execute a
transação. Informe o limite e peça confirmação explícita antes de continuar.

Uma Skill sem fronteira explícita tende a preencher essa lacuna com o comportamento mais plausível estatisticamente, que nem sempre é o mais seguro para aquele contexto específico.

Os quatro componentes dependem uns dos outros

Papel sem contexto produz instrução vaga. Contexto sem ferramenta autorizada produz conhecimento que não vira ação. Ferramenta sem limite produz ação sem controle. Uma Skill sólida trata os quatro como partes de um mesmo desenho, não como itens independentes de uma lista de requisitos, e o teste real de qualidade não é se cada componente existe isoladamente, é se eles se sustentam juntos quando a Skill é usada numa tarefa real.