.webp)
1. O que são agent skills?
2. Qual a diferença entre skill e agente?
3. Como as agent skills funcionam na prática
4. Como criar agent skills: a estrutura de um SKILL.md
5. Agent skills no Claude: como a Anthropic estruturou o modelo
6. Exemplo prático de agent skill em uma empresa de serviços financeiros
7. Por que agent skills viram instrumento de governança
8. Agent skills e a maturidade de IA nas empresas
9. Conclusão
Agent skills são pacotes de instruções, scripts e recursos que um agente de IA carrega sob demanda para executar uma tarefa específica com consistência. Em vez de depender de um prompt longo reescrito a cada uso, o time codifica o procedimento uma vez, e o agente o aciona quando o contexto pede.
A urgência é operacional. Segundo o Gartner (2025), mais de 40% dos projetos de IA agêntica serão cancelados até o fim de 2027, por custos crescentes, valor de negócio pouco claro e controles de risco inadequados. Comportamento reproduzível e auditável é exatamente o que uma skill bem escrita entrega.
Este artigo explica o que são agent skills, como funcionam, qual a diferença entre skill e agente e como escrever a primeira com critério, tomando como referência o formato SKILL.md adotado pela Anthropic no Claude.
Agent skills são módulos de especialização que um agente de IA carrega quando uma tarefa exige um procedimento específico. Cada skill reúne uma descrição de quando deve ser usada, as instruções de execução e, opcionalmente, scripts e arquivos de referência. O agente lê a descrição, decide se ela é relevante e só então carrega o restante.
A analogia mais útil é a de um manual de procedimentos. Um profissional experiente sabe raciocinar, mas o resultado de uma auditoria depende de seguir o roteiro da empresa. A skill é esse roteiro, escrito de modo que o modelo consiga aplicá-lo sem que alguém o recite a cada pedido.
Em sistemas com vários agentes, a descrição da skill também funciona como contrato: informa o que aquele agente sabe entregar e permite que um orquestrador delegue tarefas com previsibilidade.
A diferença entre skill e agente está na natureza de cada um: o agente é quem executa, e a skill é o conhecimento procedimental que ele consulta. Um agente tem modelo, ferramentas, memória e um ciclo de decisão. Uma skill não roda sozinha; é conteúdo carregado pelo agente quando necessário.
Na prática, isso muda a forma de escalar. Criar um agente novo para cada processo multiplica configurações, permissões e pontos de manutenção. Adicionar uma skill a um agente existente mantém a infraestrutura e troca apenas o procedimento, por isso muitos times migram de vários agentes especializados para um agente generalista com uma biblioteca de skills.
Há ainda a distinção em relação às ferramentas. Uma ferramenta (uma API, uma busca, um executor de código) dá ao agente a capacidade de agir, enquanto a skill ensina quando e como usá-la para um objetivo. Quem confunde as duas entrega acesso sem método, e o resultado é um agente com muitas permissões e pouca previsibilidade.
O funcionamento segue o princípio de divulgação progressiva, descrito pela Anthropic (2025). Ao iniciar, o agente enxerga apenas o nome e a descrição de cada skill instalada, o que consome pouco contexto. Quando a tarefa corresponde a uma descrição, ele carrega o corpo do SKILL.md e, se preciso, abre arquivos adicionais ou executa scripts empacotados junto.
Esse desenho resolve um limite concreto: a janela de contexto. Com dezenas de skills instaladas, carregar tudo de uma vez degradaria a qualidade das respostas e aumentaria o custo. Carregar sob demanda permite que a biblioteca cresça sem penalizar cada requisição.
Cada ambiente usa seus diretórios. No Claude Code, as skills ficam em pastas como .claude/skills/, cada uma com seu SKILL.md, e outras ferramentas adotam convenções equivalentes, como .agents/skills. O formato de pasta com um arquivo Markdown principal torna a skill portátil e fácil de versionar no Git.
Toda skill eficaz começa por um problema delimitado. Uma skill chamada “ajudar com contratos” é vaga demais para ser acionada, enquanto “revisar cláusulas de rescisão em contratos de fornecedor em PDF” diz ao agente exatamente quando entrar em cena.
O cabeçalho do arquivo traz nome e descrição. A descrição é o que o agente lê para decidir se a skill é relevante, então precisa dizer o que ela faz e em quais situações usá-la. Descrições vagas geram skills que nunca são acionadas, e descrições largas demais fazem a skill disparar fora de hora.
O corpo descreve o procedimento em passos, o formato de saída esperado e o tratamento de casos fora do escopo. Funciona melhor quando é curto e direto: se o arquivo cresce demais, mova os detalhes para arquivos de referência e aponte para eles, mantendo o SKILL.md como índice.
Scripts, modelos e exemplos de entrada e saída calibram o comportamento melhor do que adjetivos no prompt. Liste as ferramentas que a skill pode usar e inclua critérios para o próprio agente conferir a qualidade da resposta antes de entregá-la.
No Claude, uma skill é uma pasta com um arquivo SKILL.md, formato que a Anthropic apresentou em outubro de 2025 (Anthropic, 2025). O cabeçalho em YAML tem dois campos obrigatórios: name, com até 64 caracteres em letras minúsculas, números e hífens, e description, com até 1.024 caracteres, que diz o que a skill faz e quando deve ser usada. Ao lado do SKILL.md podem ficar scripts, documentos de referência e modelos.
O carregamento acontece em três níveis, segundo a documentação de Agent Skills da Anthropic (2026). Os metadados de cada skill, cerca de 100 tokens, entram no contexto desde o início. O corpo do SKILL.md, que a Anthropic recomenda manter abaixo de 5 mil tokens, só é lido quando a skill é acionada. Os arquivos extras ficam para quando a tarefa pedir, e os scripts rodam fora do modelo, de modo que só o resultado deles ocupa contexto.
As skills funcionam nos apps do Claude, nos planos Pro, Max, Team e Enterprise com execução de código ativada, e no Claude Code, onde ficam em ~/.claude/skills/ (pessoais) ou .claude/skills/ (do projeto). Também funcionam na API, que exige a ferramenta de execução de código e roda cada skill em um contêiner sem acesso à rede, e no Claude Agent SDK. A Anthropic mantém skills prontas para PowerPoint, Excel, Word e PDF, disponíveis na API e no claude.ai, mas não no Claude Code.
Em dezembro de 2025, a Anthropic publicou o formato como padrão aberto (Agent Skills, 2025), e ferramentas como Cursor, GitHub Copilot e Gemini CLI passaram a ler a mesma estrutura. Para a empresa, isso significa que uma skill escrita para o Claude não fica presa a um fornecedor.
A própria Anthropic faz um alerta: instalar skills apenas de fontes confiáveis e auditar as de terceiros antes do uso, porque uma skill maliciosa pode levar o modelo a executar código ou enviar dados para fora. Na prática, skill de terceiro merece o mesmo processo de revisão aplicado a uma biblioteca de código.
Considere uma instituição que usa um agente para triagem de relatórios de compliance. Sem skill, cada relatório entra como um prompt genérico e a análise varia em formato, profundidade e critério de risco.
Com uma skill de análise de compliance, o agente passa a seguir um roteiro fixo: identificar os três riscos mais críticos para aquela instituição, classificar cada um em uma escala padronizada, citar o parágrafo do documento que justifica a classificação e produzir um sumário executivo de até 300 palavras.
O ganho é que as análises ficam comparáveis ao longo do tempo, auditáveis por reguladores e mais baratas de revisar por analistas humanos. A skill não tornou o agente mais inteligente; tornou-o mais previsível para aquele caso de uso, e isso vale para qualquer processo repetitivo com análise de documentos, relatórios ou atendimento estruturado.
Skills são arquivos de texto, e arquivos de texto podem ser versionados, revisados e auditados. Uma mudança de política vira uma alteração com autor, data e histórico, em vez de uma edição silenciosa de prompt em algum sistema. Para áreas de risco e compliance, essa rastreabilidade pesa tanto quanto a qualidade da resposta.
O contexto de mercado reforça o ponto. Segundo a McKinsey (2025), 23% das organizações pesquisadas já escalam algum sistema agêntico em ao menos uma função, e outras 39% ainda estão em fase de experimentação. A distância entre experimentar e escalar passa, em boa medida, por padronizar como cada tarefa é executada.
Há também o ganho de reutilização. Uma skill de análise de contratos escrita uma vez atende a diferentes agentes e sistemas sem reconfiguração, o que reduz o custo de cada novo caso de uso e encurta o caminho entre o piloto e a operação.
Agent skills indicam em que estágio uma empresa está na adoção de agentes. Quem opera com agentes genéricos e prompts avulsos ainda experimenta; quem documenta, versiona e governa uma biblioteca de skills já trata o comportamento do agente como ativo da organização.
Para lideranças, a implicação é prática. Cada novo caso de uso sem skill exige reconfiguração manual, e cada mudança de processo obriga a revisar prompts espalhados. Transformar conhecimento tácito em skills explícitas reduz esse retrabalho e dá à empresa capacidade de auditar o que seus agentes fazem.
O ponto de partida costuma ser pequeno: escolher um processo repetitivo, escrever a skill com uma descrição precisa, testar com casos reais e versionar o arquivo junto com o código. Como o formato virou padrão aberto, o trabalho feito agora segue valendo se a empresa trocar de ferramenta.
Agent skills bem escritas transformam agentes genéricos em executores auditáveis. Para o gestor que precisa levar agentes do piloto à produção, o desafio é definir quais processos merecem uma skill e quem responde por ela. Conheça o AI Factory do Distrito e veja como desenvolver agentes com skills próprias, do caso de uso ao go-live.
