Como escrever uma Cursor Skill: anatomia do SKILL.md, descrições de ativação e o que vai em uma skill vs uma regra

O Cursor agora tem duas formas de ensinar algo ao seu agente: regras e skills. As regras levaram toda a atenção inicial, então a maioria dos guias que você encontra é sobre arquivos .mdc. Mas desde que o Cursor lançou as Agent Skills, o lugar certo para boa parte desse conteúdo mudou, e surpreendentemente pouco foi escrito sobre como construir uma bem feita. Este é esse guia: a mecânica real de arquivos segundo as docs do Cursor, mais o que aprendemos gerando e analisando milhares de arquivos de contexto para agentes.

O que é uma Cursor Skill (e quando uma regra é a ferramenta errada)

Uma regra do Cursor é contexto passivo. Ela vive em .cursor/rules/*.mdc e, dependendo do frontmatter, é injetada em cada requisição (alwaysApply: true) ou anexada quando um arquivo que bate com seus globs entra na conversa. O agente nunca escolhe usar uma regra. A regra simplesmente está lá, gastando tokens seja ou não relevante para a tarefa atual.

Uma skill é uma capacidade sob demanda. Ela vive na própria pasta (.cursor/skills/<name>/SKILL.md) e, por padrão, o agente só vê o name e a description. Quando o agente decide que a skill é relevante para o que você pediu, ele carrega o SKILL.md completo, e só então. Você também pode invocá-la explicitamente digitando /skill-name no chat do Agent. Além disso, a pasta de uma skill pode carregar scripts/ que o agente pode executar, docs em references/ que ele carrega só quando precisa e assets/ como templates. Regras não fazem nada disso.

Essa diferença dita a escolha:

• Regra: uma restrição permanente que deve moldar tudo o que o agente faz em alguma fatia do código. "Usamos named exports." "Nunca edite arquivos gerados, regenere-os."
• Skill: um procedimento que o agente executa quando solicitado. "Crie uma migração de banco de dados." "Escreva uma entrada de changelog." "Publique uma release."

Se você está descrevendo como o código deve sempre parecer, você quer uma regra (também temos um gerador gratuito para isso). Se está descrevendo como fazer uma tarefa, você quer uma skill.

Anatomia de uma skill

A skill mínima viável é uma pasta com um arquivo. Skills de projeto vão em .cursor/skills/ (ou .agents/skills/), são commitadas no git e chegam ao time inteiro. As pessoais vão em ~/.cursor/skills/ e acompanham você em todos os projetos. O Cursor descobre arquivos SKILL.md de forma recursiva e também lê caminhos legados como .claude/skills/, então skills escritas para outros agentes costumam funcionar como estão.

Aqui vai uma skill completa e realista para um projeto que gerencia o banco de dados com migrações SQL numeradas:

---
name: db-migration
description: Create a new numbered SQL migration for the Supabase database.
  Use when the user asks to add a migration, change the schema, create a
  table, add a column, or write RLS policies.
paths:
  - "supabase/migrations/**"
---

# db-migration

Create exactly one migration file per schema change in supabase/migrations/.

## Workflow

1. Find the next number: run `scripts/next-number.sh` from the skill root.
2. Name the file `NNN_short_description.sql` (three digits, snake_case).
3. Write the forward migration only. This project does not use down
   migrations; reverting means writing a new forward migration.
4. Enable RLS on every new table and add an owner-only policy, because
   every user-data table in this repo is RLS-guarded.
5. Run `supabase db push` against the local instance and paste the output.

## Restrictions

- Never edit an already-committed migration, because it may have run in
  production. Create a new migration instead.

Os campos do frontmatter, segundo as docs do Cursor:

• name (obrigatório): letras minúsculas, números e hífens, e precisa coincidir com o nome da pasta. É também o que você digita depois de / para invocá-la manualmente.
• description (obrigatório): o que a skill faz e quando usá-la. É a única parte do corpo que o agente vê antes de decidir carregar a skill, o que a torna a linha de maior alavancagem do arquivo inteiro.
• paths (opcional): padrões glob que restringem a skill aos arquivos correspondentes. A chave legada globs ainda funciona, mas paths é a forma atual.
• disable-model-invocation (opcional): defina como true e a skill só roda quando um humano digita /skill-name, como um slash command tradicional. Use para procedimentos destrutivos ou caros (deploys, backfills de dados) que você nunca quer disparados por um palpite.

Tudo abaixo do frontmatter são instruções em markdown puro, escritas para o agente, não para humanos.

Escrevendo a descrição para o agente realmente ativá-la

É aqui que a maioria das skills morre. A descoberta funciona como uma tabela de roteamento: o agente compara seu pedido com a descrição de cada skill e carrega o corpo apenas da que julga relevante. Uma descrição vaga significa uma skill que nunca dispara, e você vai concluir que skills "não funcionam" quando na verdade seu resumo de uma linha perdeu a decisão de roteamento.

Três regras que resolvem:

1. Diga o que ela faz e quando usá-la, na terceira pessoa. Não "Ajuda com migrações", e sim "Cria uma migração SQL numerada. Use quando o usuário pedir para mudar o esquema, adicionar uma tabela ou adicionar uma coluna."
2. Inclua as palavras que as pessoas realmente digitam. Se o seu time diz "adicionar uma coluna" e "escrever uma política RLS", essas frases entram na descrição literalmente. O roteamento casa com o seu vocabulário, não com a sua intenção.
3. Diga quando não usá-la se houver uma vizinha próxima. Duas skills com descrições sobrepostas (digamos, db-migration e db-seed) vão roubar invocações uma da outra, a menos que cada uma nomeie sua fronteira.

Se a skill continuar sem disparar, teste-a direto com /skill-name. Se funciona invocada manualmente mas nunca automaticamente, o corpo está bom e o problema é a descrição. Reescreva a descrição, não as instruções.

Escopo: o que vai na skill vs em uma regra

Um teste útil para cada linha que você está prestes a escrever: "isto se aplica sempre, ou só durante esta tarefa?"

• "Todo SQL em minúsculas com vírgulas no início" se aplica sempre. Regra.
• "Rode scripts/next-number.sh para escolher o número da migração" se aplica só durante a tarefa. Skill.
• Fatos do repositório ("fazemos deploy no Cloudflare Workers") não vão em nenhuma das duas. Vão no seu arquivo de contexto sempre ativo, e tanto regras quanto skills podem assumi-los.

Manter essa fronteira limpa paga em dobro: as regras ficam pequenas (são pagas em cada requisição) e as skills ficam autocontidas, em vez de se comportar diferente conforme quais regras estejam carregadas.

Erros comuns

Analisamos muitos arquivos de configuração de agentes, e nas skills aparecem as mesmas falhas:

Descrições de ativação vagas. "Ajuda com coisas de banco de dados." O roteamento não tem com o que casar, e nosso linter marcaria o corpo equivalente como vague/low-signal: sem conteúdo verificável, nada sobre o que o agente possa agir.

Skills que deveriam ser regras. Uma "skill" cujo corpo é uma lista de convenções de formatação não tem procedimento a executar. Vai disparar rara e aleatoriamente, e as convenções não valerão nos outros 95% do tempo. Converta-a em uma regra auto-anexada com globs e ela funciona toda vez que os arquivos relevantes estiverem abertos.

Inchaço. Skills são carregadas sob demanda, o que tenta as pessoas a despejar guias de estilo inteiros e referências de API no SKILL.md. Mas, uma vez ativada, o arquivo inteiro cai no contexto. Mantenha o SKILL.md no procedimento e empurre o detalhe para references/, que o agente carrega progressivamente, só quando um passo realmente precisa. Isso espelha os orçamentos de tamanho que existem para cada formato de arquivo de contexto.

Gritaria e proibições sem fundamento. Instruções escritas para modelos da era 2024, "CRITICAL: you MUST ALWAYS...", degradam os atuais, que se sobre-ativam com a agressividade (antipattern/emphasis-inflation). E um "NEVER do X" sem razão generaliza pior do que um com a justificativa anexada (antipattern/bare-prohibition). Repare como o exemplo acima diz por que migrações já commitadas não podem ser editadas.

Você pode passar o corpo de uma skill pelo linter de graça para pegar isso antes que custe uma execução ruim do agente.

Validar e iterar

1. Teste de fumaça manual. Invoque-a com /skill-name e observe o procedimento sendo executado de ponta a ponta. Isso isola o corpo de instruções do problema de roteamento.
2. Teste de descoberta. Abra um chat novo do Agent e formule o pedido como um colega de time faria, sem nomear a skill. Se ela não carregar, itere apenas na descrição.
3. Passe no linter. Rode o corpo pelo linter gratuito para pegar diretivas vagas, inflação de ênfase e proibições sem explicação.
4. Observe o uso real. Quando o agente usar mal a skill, o conserto costuma ser um destes: uma frase de "quando usar" faltando na descrição, um passo que assumia conhecimento que o agente não tinha, ou um excesso de escopo que pertence a uma regra.

Pule a página em branco

Você pode escrever seu primeiro SKILL.md à mão com o template acima, ou usar nosso gerador gratuito de Cursor skills: descreva a tarefa, as condições de ativação, os globs e as permissões de ferramentas, e ele produz um SKILL.md completo e limpo para o linter, com o frontmatter e a estrutura cobertos aqui. É grátis, roda no navegador e não exige cadastro. Gere uma, coloque em .cursor/skills/ e teste com /skill-name.