A instrução que você escreve uma vez, não a cada sessão

Existe um momento, a cada poucos dias, em que você digita a mesma correção de novo. Use o nosso componente de botão. Não adicione uma dependência para isso. As datas neste projeto são sempre ISO. Você disse isso na terça, a sessão terminou e o conhecimento terminou com ela.

Uma skill é aquela instrução, escrita uma vez só, num arquivo que o agente pega sozinho quando ela passa a ser relevante.

Esse é o conceito inteiro, e o resto desta página é a mecânica, o julgamento sobre o que cabe dentro de uma e a depuração — porque a falha típica não é escrever uma skill ruim, é escrever uma skill boa que nunca carrega.

O que é uma skill no disco

Uma pasta com um arquivo markdown dentro:

.claude/skills/
  cc-brand/
    SKILL.md
    references/
      token-reference.md
      motion-and-craft.md
    assets/
      AppShell.vue
      cc-tokens.css

O SKILL.md abre com um frontmatter que carrega duas coisas que importam:

---
name: cc-brand
description: Implements UI in the CC design system for Vue. Use this WHENEVER
  building, styling, theming or reviewing any Vue interface, component, page,
  dashboard or form for CommitCycle — and whenever the user mentions CC UI, the
  brand blue (#693DFF), Plus Jakarta Sans, shadcn-vue, or "make this on-brand".
---

# CC Design System Implementor

Everything the agent should know, in ordinary markdown.

Nada além disso é necessário. Sem etapa de build, sem registro, sem arquivo de configuração. A pasta existe, logo a skill existe.

Por que não colocar isso no prompt?

Porque você precisa lembrar, toda vez, e você não vai. Mais precisamente: as vezes em que você esquece não são aleatórias. São as vezes em que você estava indo rápido, que são as vezes em que o agente tinha menos contexto, que é exatamente quando a convenção mais importava.

Por que não colocar isso no AGENTS.md?

Esta é a pergunta de verdade, e a resposta é o projeto inteiro do recurso.

O AGENTS.md (ou CLAUDE.md) é sempre carregado. Todo turno, toda sessão, toda task, seja relevante ou não. Isso o torna perfeito para fatos que são sempre verdadeiros — a stack, os comandos, o layout de pastas, as coisas que nunca se deve fazer — e significa que cada linha que você acrescenta custa contexto em trabalhos que não têm nada a ver com ela. Um AGENTS.md de 900 linhas é um imposto sobre cada pedido.

Uma skill é carregada só quando casa. O que está sempre em contexto é o nome e a description dela: umas duas linhas. O corpo é lido só quando o agente decide que o trabalho pede aquilo.

Isso se chama progressive disclosure, e funciona em três níveis:

É por isso que uma skill pode ser enorme — um design system completo, um checklist de conformidade, a superfície inteira de uma API — sem deixar mais lento um pedido sobre outra coisa. Você está carregando uma biblioteca, não um bilhete.

O que vai onde

O julgamento que faz tudo isso funcionar:

O erro comum é colocar conteúdo do tamanho de um design system no AGENTS.md, onde ele é carregado a cada pedido, inclusive nos que são sobre um script de build. O outro erro comum é colocar a stack do projeto numa skill, onde ela pode não carregar no momento em que é necessária.

A description é o gatilho inteiro

Se você levar uma coisa só desta página: a description não é documentação, é a regra de casamento. Ela é a única parte da sua skill que o agente vê antes de decidir se lê o resto.

Então escreva com as palavras que uma pessoa digita de verdade. Não:

Diretrizes de implementação de marca e padrões de componentes.

Isso não casa com nada. Quem pede “faz isso parecer o nosso app” não usou nenhuma dessas palavras. Em vez disso:

Use isto sempre que estiver construindo, estilizando, tematizando ou revisando qualquer interface, página, dashboard, formulário ou componente de [produto] — e sempre que o usuário mencionar [a cor da marca], [a fonte], [a biblioteca de componentes] ou “deixa on-brand”. Recorra a isto mesmo quando o pedido for só “faz uma página de configurações” ou “estiliza este card”.

Concretamente, uma description que dispara de forma confiável nomeia:

• Os verbos — construir, estilizar, revisar, migrar, redigir
• Os substantivos — os artefatos aos quais ela se aplica
• As strings literais — nomes de produto, códigos hex, nomes de fonte, nomes de biblioteca
• As formulações informais — “deixa on-brand”, “do jeito de sempre”, “igual às outras páginas”
• Quando usar mesmo quando não parece que se aplica — esta linha faz um trabalho surpreendente

Ser inclusivo demais custa um pouco de contexto quando dispara sem necessidade. Ser inclusivo de menos custa a skill inteira, em silêncio, para sempre. Incline-se para disparar.

Onde as skills ficam

Dois lugares, e a escolha importa mais do que parece.

.claude/skills/ dentro do projeto. É commitado junto com o repositório, então está na sua outra máquina, em toda sessão futura e para qualquer pessoa que clone. Tudo que descreve este produto pertence aqui.

~/.claude/skills/ na sua pasta pessoal. Disponível em todo projeto que você toca, invisível para todo mundo. Isso é para o seu jeito de trabalhar: como você gosta que os commits sejam escritos, como você quer os documentos estruturados.

O padrão deve ser o projeto. Uma skill que vive só no seu notebook está a uma máquina de distância de não existir, e é a razão pela qual um projeto “só funciona direito quando é você que roda”.

Como sei que ela disparou?

Pergunte. Quais skills você usou para isso? é uma pergunta razoável e recebe uma resposta direta. Quais skills você tem disponíveis? lista todas, que é a primeira verificação depois de instalar uma.

A verificação forte é comportamental: abra uma sessão nova, formule um pedido do jeito que um usuário real formularia — não do jeito que a documentação da própria skill formula — e veja se a saída segue as regras sem você mencioná-las. Esse é o único teste que importa, porque essa é a condição real de uso.

Por que minha skill não dispara?

Repare que quatro dos cinco são problemas de description ou de localização. O conteúdo raramente é o que está errado.

Mantendo o SKILL.md curto

Uma vez carregado, o corpo é lido inteiro — então o tamanho custa alguma coisa, e a boa estrutura é um arquivo de instruções curto que aponta para o detalhe.

SKILL.md               as regras, a ordem de decisão, o que vence num conflito
references/             o material longo: tabelas de tokens, superfícies de API, exemplos
assets/                 coisas para copiar: componentes, folhas de estilo, modelos
scripts/                coisas para rodar

A skill cc-brand do exemplo acima tem exatamente esse formato: o SKILL.md declara a prioridade de camadas e a regra de conflito em algumas centenas de palavras, e a referência de tokens, a orientação de movimento e os componentes de shell prontos ficam em arquivos para os quais ele aponta. O agente abre a referência da barra lateral quando está construindo uma barra lateral, e nunca em outra hora.

Duas coisas pertencem ao SKILL.md e não a um arquivo de referência: a ordem de precedência (quando duas regras colidem, qual vence) e o que não fazer. As duas são curtas e as duas são o que o agente erra quando elas faltam.

Skills, MCP, subagents, slash commands

Quatro coisas que se confundem, em eixos genuinamente diferentes:

Skills e MCP são complementos, não alternativas. O servidor MCP dá ao agente uma conexão com o seu banco de dados; a skill conta a ele as suas convenções de schema e quais tabelas nunca são escritas diretamente. Ferramentas sem instruções é a configuração que a maior parte das pessoas tem, e é por isso que o agente consegue alcançar tudo e ainda assim fazer a coisa errada com aquilo.

Instalando uma que alguém te deu

1. Coloque a pasta em .claude/skills/ (projeto) ou ~/.claude/skills/ (pessoal).
2. Abra uma sessão nova — uma já aberta já montou a lista dela.
3. Pergunte quais skills você tem disponíveis e confira se a sua aparece pelo nome.
4. Dê a ela um pedido realista e veja se as regras se aplicam sem serem mencionadas.

Se o passo 3 falhar, a pasta está no lugar errado ou o SKILL.md está com o nome errado. Se o passo 4 falhar, é a description.

A que vale instalar no primeiro dia é uma skill de design. Se você tem uma ideia mas ainda nenhuma marca e nenhuma opinião visual, o startpow.com deixa você escolher o que gosta, exportar e baixar o resultado como skill. Você solta a pasta lá dentro e, daí em diante, cada tela que o agente construir chega nas suas cores, na sua tipografia e no seu espaçamento sem você descrever tudo de novo — que é, mais ou menos, a diferença entre um produto e uma demo, por uns dez minutos de trabalho.

Quantas skills são demais?

Existe um orçamento real, e não é o que as pessoas temem. Os corpos são de graça até carregarem, então uma pasta com quarenta skills não deixa nada mais lento. O que não é de graça são as descriptions, que estão todas em contexto, o tempo todo.

Quarenta descriptions vagas são piores que cinco afiadas por uma segunda razão também: quanto mais elas se sobrepõem, menos confiável é que a certa vença. Duas skills que cobrem “estilo” de forma igualmente plausível significam um cara ou coroa a cada pedido de UI.

O formato prático é um punhado de skills com fronteiras limpas, cada uma das quais você conseguiria descrever numa frase sem usar a palavra “e”. Quando você não consegue, aquilo são duas skills.

Uma skill é instrução que você concorda em executar

Vale dizer com todas as letras, porque skills circulam como se fossem modelos de estilo, e não são.

Uma skill é um conjunto de instruções que um agente vai seguir, com as suas permissões, no seu repositório. Uma skill baixada pode dizer a um agente para instalar um pacote, para mandar um arquivo para algum lugar, para tratar uma regra como mais importante que as que você escreveu. É a mesma decisão de confiança de rodar um script que alguém te mandou, e o fato de ser markdown em vez de código faz aquilo parecer menor do que é.

Então: leia o SKILL.md antes de instalar, olhe o que mais tem na pasta e tenha mais cuidado com skills que trazem scripts do que com skills que trazem documentação. Um design system de uma ferramenta que você escolheu é uma proposta muito diferente de uma skill colada num fio de fórum.

O mesmo vale ao contrário quando você publica uma: quem instala a sua está te estendendo essa confiança.

Levando isso para um time

Três caminhos, em ordem crescente de cerimônia:

• Faça o commit delas no repositório. .claude/skills/ está no repo, então clonar traz tudo. Isso cobre a maior parte dos casos e não precisa de infraestrutura nenhuma.
• Distribua num plugin. Um plugin pode carregar skills junto com comandos e servidores MCP, instalado pelo nome e atualizado de forma central. É o certo quando vários repositórios precisam das mesmas convenções.
• Mande a pasta. Serve uma vez, é ingerenciável na quarta pessoa, porque agora não há resposta para “qual versão você tem?”.

A falha a evitar é aquela em que a skill existe só na pasta pessoal de uma pessoa. O projeto passa a se comportar de forma diferente dependendo de quem está no volante, e ninguém consegue ver por quê.

O jeito mais rápido de escrever sua primeira skill

Não comece de uma página em branco. Páginas em branco produzem regras genéricas, e regras genéricas são as que o modelo já segue.

Em vez disso: trabalhe normalmente e preste atenção no que você corrige. Na terceira vez que você disser a mesma coisa — a terceira vez que apontar o formato de data, ou o componente, ou que aqui a gente não usa aquela biblioteca — diga:

Transforme o que você acabou de aprender numa skill. Escreva a description para que ela dispare sempre que alguém pedir qualquer coisa nesta área, inclusive nas formulações informais. Mantenha o SKILL.md curto e coloque o detalhe longo num arquivo de referência.

Suas correções já são exatamente o conteúdo de que uma skill precisa. São específicas, são reais e são as que de fato estavam sendo erradas — o que é um ponto de partida muito melhor do que qualquer coisa que você pensaria em escrever de antemão.

Truques que fazem diferença de verdade

• Mostre, não só conte. Um exemplo trabalhado da sua convenção rende mais que três parágrafos descrevendo-a. Modelos são extremamente bons em reconhecer padrões a partir de um exemplo, e meramente obedientes ao seguir uma regra.
• Uma skill por assunto. Uma única skill de “nossos padrões” cobrindo design, testes e deploy dispara em tudo e não se aplica bem a nada. Divida.
• Diga qual vence. Toda skill que contém mais de uma fonte de orientação precisa de uma frase dizendo qual tem precedência num conflito. Sem ela, o modelo escolhe, e escolhe diferente a cada vez.
• Escreva as regras negativas. Não introduza uma segunda biblioteca de componentes. Não adicione dependências para algo que a biblioteca padrão já faz. Restrições negativas são seguidas de forma mais confiável que as positivas e quase sempre são o que você de fato queria.
• Versione junto com o código que ela descreve. Uma skill de design no repositório muda no mesmo commit que os tokens que ela documenta. Uma skill de design no seu notebook desvia em quinze dias e depois ensina, com toda a confiança, as cores do mês passado.
• Teste com uma sessão fria e uma formulação preguiçosa. “faz a página de configurações” é como o pedido vai chegar de verdade. Se a skill precisa da versão bem formulada para disparar, ela não funciona.
• Deixe as skills velhas morrerem. Uma skill que descreve uma convenção que você abandonou é pior que nenhuma skill: é uma instrução confiante e sempre disponível para fazer a coisa errada.

Se você não está no Claude Code

Skills como pastas são um recurso do Claude Code. Outras ferramentas agênticas leem um único arquivo de instruções sempre carregado, e a convenção quase universal é AGENTS.md na raiz do repositório.

O conteúdo se transfere direto. O que não se transfere é o carregamento seletivo — tudo naquele arquivo é pago a cada pedido — então a disciplina é outra: limite ao que é sempre verdadeiro, coloque o material longo em documentação comum e aponte para ela a partir do arquivo em vez de colar tudo dentro.

De um jeito ou de outro, o movimento de fundo é o mesmo, e é o hábito de maior alavancagem no desenvolvimento com agentes: na segunda vez que você explicar alguma coisa, escreva isso onde o agente vai encontrar. O resto da configuração em volta disso — o repositório, o modelo, o host, a stack, as salvaguardas — são seis decisões.