O que são Claude skills? Uma explicação sem jargão

Uma Claude skill é um módulo reutilizável (um arquivo SKILL.md mais referências e scripts opcionais) que ensina o Claude a fazer um tipo de trabalho. Ela carrega sob demanda: os metadados ficam sempre no contexto, o corpo entra quando o gatilho dispara e os arquivos de apoio só carregam quando a skill pede. Skills persistem entre sessões, são versionadas no git e seguem o padrão aberto Agent Skills.

Se você quer ir direto para a construção, o guia completo para criar Claude skills cobre a anatomia inteira.

O que uma Claude skill é de fato

Uma skill não é um prompt. É um módulo versionado, baseado em arquivos, que mora no diretório .claude/skills/ do seu projeto (ou em ~/.claude/skills/ para skills que você quer disponíveis em todo lugar). O arquivo central é o SKILL.md, um documento markdown que dá ao agente um nome, uma descrição de uma linha e instruções de como trabalhar. Referências, scripts e assets ficam ao lado dele.

A descrição é o mecanismo de gatilho. No início da sessão, o Claude lê o nome e a descrição de todas as skills no escopo. Quando a descrição bate com a sua intenção, o corpo da skill carrega. Não bateu, não carrega. Nada dispara sem a deixa.

A progressive disclosure cuida do resto.

Por que skills existem: LLMs não têm estado

Toda sessão do Claude começa em branco. Não há memória, nada é aproveitado do trabalho de ontem, nenhuma noção das decisões da semana passada. Isso é uma propriedade de design dos LLMs, não um bug do Claude especificamente.

Sem skills, essa falta de estado força um de dois resultados ruins. Ou você cola o mesmo bloco longo de contexto em toda sessão (uma dívida de prompt que cresce e se desatualiza com o tempo), ou aceita que o comportamento do agente vai variar de sessão para sessão porque as instruções nem sempre estão lá.

A skill resolve as duas coisas. Você escreve o método uma vez, num arquivo versionado, e ele carrega exatamente quando o trabalho pede. Skills servem para qualquer coisa que você faz repetidamente e não quer explicar de novo: code review, avaliação de oferta, formatação de conteúdo, workflows de git, auditorias de SEO. A única condição é que a tarefa tenha um formato consistente. Se dá para descrever em uma frase, dá para virar skill.

Como uma skill carrega: três camadas

O modelo de carregamento é o que separa uma skill de um arquivo markdown que você cola no contexto. Três camadas, cada uma condicionada à anterior.

As três camadas de carregamento

1. T1

   Metadados: sempre no contexto

   O nome e a descrição da skill carregam no início de toda sessão. É assim que o modelo sabe que a skill existe e que tipo de trabalho ela resolve. Custa quase nada, uma ou duas linhas por skill.

   +
2. T2

   Corpo do SKILL.md: carrega no gatilho

   Quando a descrição bate com a intenção do usuário, o corpo completo do SKILL.md carrega. É ali que ficam as instruções, os modos de saída e o mapa de carregamento das referências: o método que o agente vai seguir.

   +
3. T3

   Referências e scripts: carregam sob demanda

   Os arquivos de apoio (conhecimento destilado, checklists de decisão, templates, scripts) só carregam quando o mapa de carregamento do SKILL.md manda o modelo buscá-los. Nada carrega sozinho. A skill decide.

Uma skill com vinte arquivos de referência custa uma linha de metadados por sessão até disparar. Depois disso, só as referências de que a tarefa atual precisa entram no contexto. O mapa de carregamento diz ao modelo exatamente o que ler. O resto fica no disco.

O que vai dentro de uma skill

A maioria das skills tem três partes: o roteador (SKILL.md), a base de conhecimento (references/) e a automação opcional (scripts/). O roteador é obrigatório. O resto cresce conforme a skill amadurece.

Anatomia de uma skill

1

SKILL.mdo roteador: nome, descrição, instruções, mapa de carregamento

1-20

references/conhecimento destilado, dividido por domínio de decisão

0+

scripts/helpers em shell ou Python que a skill pode chamar

0+

assets/templates, schemas ou arquivos de exemplo de saída

Dentro do SKILL.md, o mapa de carregamento é a parte que a maioria pula e depois não entende por que a skill rende pouco. É uma tabela (ou uma lista curta) que liga tipos de pergunta aos arquivos de referência que as respondem. Pergunta de preço carrega a referência de preço. Code review carrega o checklist de review. Sem o mapa, o agente chuta.

A linha de descrição é a outra coisa que vale acertar com precisão. Ela é uma frase-gatilho, não documentação. Escreva do jeito que você naturalmente falaria quando precisa da skill. Descrição vaga não dispara. Descrição precisa dispara sempre.

Skills seguem um padrão aberto

As Claude skills implementam o padrão aberto Agent Skills, ou seja, a arquitetura não é proprietária do Claude Code. O mesmo módulo SKILL.md (mesmo nome, descrição, referências e mapa de carregamento) é portável para qualquer runtime de agente que suporte o padrão.

Venho construindo skills na minha própria biblioteca em ~/Work/my-second-brain/.agents/skills/. Skills de persona como alex-hormozi cuidam da avaliação de ofertas. Um sistema lifeos-* cobre tarefas de operação pessoal: revisões semanais, ritmos de planejamento, registros de decisão. Cada uma é um módulo autocontido: um roteador, um punhado de referências destiladas, um mapa de carregamento enxuto. Nenhuma é engenhosa. São só método que carrega sob demanda.

Para exemplos reais de como elas ficam, veja exemplos de Claude skills da minha biblioteca. Para a fronteira entre skills e subagents com MCP (uma dúvida que aparece rápido quando você começa a construir), veja Claude skills vs MCP e subagents.

Resumindo

Uma Claude skill é um módulo versionado, baseado em arquivos, que ensina um agente a fazer um tipo de trabalho. Metadados no contexto. Corpo no gatilho. Referências sob demanda. Sem dívida de prompt, sem deriva entre sessões, sem explicar a mesma coisa toda segunda-feira.

Skills existem porque LLMs esquecem. Uma boa skill não esquece.

Se você está pronto para construir a primeira, o guia completo para criar Claude skills passa por cada decisão: estrutura de arquivos, mapa de carregamento, referências e como testar se alguma coisa daquilo funcionou de verdade.

Perguntas frequentes

O que é uma Claude skill, em poucas palavras?+

Uma Claude skill é um módulo reutilizável (um arquivo SKILL.md mais referências e scripts opcionais) que ensina o Claude a fazer um tipo de trabalho. Ela carrega sob demanda, persiste entre sessões e é versionada no git como qualquer outro arquivo.

O método persiste num arquivo. Só entra no contexto quando o trabalho precisa dele.

Qual a diferença entre uma Claude skill e um prompt?+

Um prompt é uma instrução de sessão: você cola, usa e cola de novo na próxima vez. Uma skill é um módulo persistente, baseado em arquivo, que carrega automaticamente quando a descrição bate com a sua intenção.

O prompt se perde entre sessões. A skill fica.

Como o Claude sabe quando disparar uma skill?+

A linha de descrição no SKILL.md é o gatilho. O Claude lê os metadados de todas as skills no início da sessão. Quando a descrição bate com a intenção do usuário, o corpo completo do SKILL.md carrega. Não bateu, não carrega.

O que é 'progressive disclosure' no contexto das Claude skills?+

Progressive disclosure é o modelo de carregamento: os metadados (nome e descrição) ficam sempre no contexto; o corpo do SKILL.md carrega quando o gatilho dispara; os arquivos de referência só carregam quando o mapa de carregamento da skill manda buscá-los.

Nada carrega sozinho. Só o que a tarefa atual precisa entra no contexto.

O que vai dentro de um arquivo SKILL.md?+

No mínimo: um nome, uma descrição de uma linha (o gatilho) e instruções para o agente. Uma skill madura também inclui um mapa de carregamento, uma tabela que direciona tipos de pergunta para os arquivos de referência que as respondem. O mapa de carregamento é a parte que a maioria pula e depois se arrepende.

Dá para usar Claude skills fora do Claude Code?+

Sim. Skills seguem o padrão aberto Agent Skills, então o mesmo módulo SKILL.md é portável para qualquer runtime de agente que suporte o padrão.

O método mora no arquivo, não na ferramenta.

Onde o Claude procura skills?+

Skills de projeto ficam no diretório .claude/skills/ do projeto e valem só para ele. Skills de usuário ficam em ~/.claude/skills/ e estão disponíveis em toda sessão. Os dois são arquivos markdown simples que o agente lê no início da sessão.

Skills deixam o modelo mais lento ou consomem a context window?+

Não mais do que precisam. Os metadados são mínimos: um nome e uma descrição por skill. O corpo do SKILL.md só carrega no gatilho. Os arquivos de referência só carregam quando o mapa de carregamento pede.

Uma skill com vinte arquivos de referência custa mais ou menos uma linha de metadados por sessão até disparar. Depois, só as referências relevantes entram no contexto.

Para que tipo de tarefa vale criar uma skill?+

Qualquer coisa que você faz repetidamente com um formato consistente: code review, avaliação de oferta, formatação de conteúdo, auditorias de SEO, workflows de git, planejamento semanal. Se você consegue descrever a tarefa em uma frase e já fez mais do que umas poucas vezes, vale uma skill.

Tarefa pontual não vale. O ganho está no reuso entre sessões.