Este post pressupõe que você já tem familiaridade com agents de programação com IA (Cursor, Claude Code, Windsurf etc.), conceitos básicos de prompt engineering e rules files (o .cursor/rules/ do Cursor ou o CLAUDE.md do Claude Code).
Se você está começando agora no desenvolvimento assistido por agents, comece pela documentação inicial da sua ferramenta. Se nunca usou rules, leia a documentação de rules do Cursor ou a documentação de memory do Claude Code antes de continuar. Entender rules é o contexto essencial para saber por que as skills existem.
O problema: rules que viram manuais de operação
O rules file de todo time segue a mesma trajetória. Começa com alguns guardrails sensatos:
- “Pergunte antes de ações destrutivas”
- “Não adicione novas dependências sem aprovação”
Aí alguém adiciona um checklist para o código de cobrança. Outra pessoa inclui procedimentos de migração. Uma terceira contribui com templates de design de API. Seis meses depois, a sua seção de “rules” virou um manual de operação de 5.000 tokens que carrega em toda interação com o agent.
O que dá errado:
- O prompt base incha. Toda conversa paga o custo em tokens de todos os workflows, inclusive os que nunca são acionados.
- Políticas importantes se perdem no meio. “Nunca apague bancos de dados de produção” fica ao lado de “No código de cobrança, verifique as chaves de idempotência”, e o agent trata as duas com o mesmo peso.
- Workflows especializados não podem ser reaproveitados. Aquele checklist caprichado de revisão de migração fica preso no rules file de um único projeto.
- A manutenção é sofrida. Mudar um único procedimento significa editar um bloco gigante de texto e torcer para nada mais quebrar.
- O debug fica mais difícil. Quando o agent se comporta mal, rastrear a causa em um paredão de assuntos misturados é tedioso.
Rules deveriam ser guardrails: políticas curtas, sempre ativas, que moldam o comportamento em qualquer tarefa. Quando você as sobrecarrega com procedimentos específicos de uma tarefa, está usando a ferramenta errada para o trabalho.
Leia também: Boas práticas em React: separação de responsabilidades e otimização de código
O que são agent skills?
Uma skill é uma pasta autocontida que empacota um workflow específico ou uma área de expertise:
my-skill/
├── SKILL.md # Obrigatório: instruções + metadados
├── scripts/ # Opcional: código executável
├── references/ # Opcional: documentação
└── assets/ # Opcional: templates, recursosCode language: PHP (php)O arquivo SKILL.md é o ponto de entrada. O frontmatter dele traz um nome e uma descrição, e o corpo traz as instruções propriamente ditas.
Veja um exemplo real de skill que aplica Inversão de Dependência a um módulo:
---
name: dependency-inversion
description:
Refactor a module to follow the Dependency Inversion Principle by extracting
interfaces, inverting concrete dependencies, and wiring via injection. Use
when the user asks to decouple modules, invert dependencies, extract an
interface, apply SOLID principles, or improve testability of tightly coupled
code.
---
Decouples modules by replacing direct imports of concrete implementations with
injected abstractions, improving testability and swappability.
## Dependency Inversion Progress:
- [ ] Step 1: Identify concrete dependencies in the target module
- [ ] Step 2: Extract an interface (port) for each dependency
- [ ] Step 3: Update the module to depend on the interface, not the concrete
- [ ] Step 4: Create an adapter implementing the interface for the original concrete
- [ ] Step 5: Wire the adapter via constructor or factory injectionCode language: CSS (css)As skills usam progressive disclosure para gerenciar o contexto em três estágios:
- Descoberta. Na inicialização, os agents carregam apenas o nome e a descrição de cada skill disponível. São poucos tokens por skill, o suficiente para saber quando cada uma se aplica.
- Ativação. Quando uma tarefa combina com a descrição de uma skill, o agent carrega o SKILL.md completo no contexto.
- Execução. O agent segue as instruções, carregando arquivos referenciados ou rodando os scripts empacotados conforme a necessidade.
Um projeto pode ter dezenas de skills instaladas. O agent só paga o custo em tokens das que realmente usa em cada conversa.
Antes e depois
Um padrão que aparece o tempo todo. Veja:
Antes, tudo mora nas rules:
- “Sempre pergunte antes de ações arriscadas”
- “Não adicione novas dependências sem aprovação”
- “No código de cobrança, verifique a idempotência”
- “Em migrações, confira os caminhos de rollback”
As quatro instruções carregam em todo prompt, sempre. As duas últimas são irrelevantes, a menos que a pessoa esteja mexendo justamente em cobrança ou em migrações.
Depois: rules curtas, com a expertise movida para skills
Rules (sempre carregadas):
- Pergunte antes de ações arriscadas
- Não adicione novas dependências sem aprovação
Skills (carregadas sob demanda):
- billing-review: verificações de idempotência, casos extremos de pagamento
- migration-review: caminhos de rollback, verificação de integridade dos dados
As rules seguem focadas em políticas universais. O conhecimento especializado só entra em cena quando é preciso.
Números reais
Um projeto React real migrou de uma configuração só com rules para rules mais skills, e o impacto em tokens na inicialização do prompt foi medido:
| Configuração | Componente | Tokens |
| Antes | overview.md (rule sempre ativa) | 1.636 |
| patterns.md (rule sempre ativa) | 3.137 | |
| structure.md (rule sempre ativa) | 2.348 | |
| Total | 7.121 | |
| Depois | project.md (rule sempre ativa) | 1.911 |
| feature-flags (frontmatter da skill) | 71 | |
| feature-screen-creator (frontmatter da skill) | 61 | |
| react-component (frontmatter da skill) | 59 | |
| redux-state-management (frontmatter da skill) | 67 | |
| unit-tests (frontmatter da skill) | 44 | |
| Total | 2.213 |
Isso dá uma redução de 4.908 tokens na inicialização, 69% menos contexto consumido antes mesmo de o agent começar a trabalhar. As instruções completas das skills continuam existindo e continuam sendo usadas. Elas só não carregam antes de o agent precisar delas.
Skills x rules: quando usar cada uma
Skills e rules resolvem problemas diferentes:
| Dimensão | Rules | Skills |
| Objetivo principal | Moldar o comportamento | Ensinar um workflow |
| Escopo | Amplo, vale para todas as tarefas | Mais restrito, focado em uma tarefa |
| Quando fica ativa | Sempre | Só quando é relevante |
| Conteúdo típico | Políticas, prioridades, tom, segurança | Procedimentos, exemplos, referências, templates |
| Melhor uso | Guardrails e consistência | Know-how especializado e reutilizável |
Use rules para políticas universais, que devem valer em toda interação.
- “Pergunte antes de ações destrutivas.”
- “Use conventional commits.”
- “Prefira composição a herança.”
Use skills para workflows específicos, que só importam em determinados contextos.
- “Como escrever um teste e2e com Playwright.”
- “Como criar a estrutura de um novo endpoint de API.”
- “Como revisar código de cobrança em busca de casos extremos de pagamento.”
Leia também: Machine Learning explicado: o que é, como funciona e por que importa para o negócio
Onde as agent skills se encaixam ao lado de MCPs e subagents
Skills não são a única forma de ampliar as capacidades de um agent. Outros dois padrões, servidores MCP e subagents, resolvem problemas diferentes.
MCP (Model Context Protocol)
O MCP dá aos agents uma forma padronizada de se conectar a ferramentas externas, fontes de dados e aplicações. É como uma porta USB para o agent acessar sistemas em execução.
| Dimensão | Skills | MCPs |
| Papel principal | Ensinar ao agent como trabalhar | Permitir que o agent acesse sistemas |
| O que contém | Instruções, workflows, expertise | Conectividade reutilizável |
| Uso de contexto | Só quando a skill é carregada | Só quando a ferramenta é usada |
| Exemplo | “Como revisar um PR” | “Servidor MCP do GitHub com as APIs de PR” |
Skills e MCPs se complementam. Uma skill ensina ao agent como usar as ferramentas que um MCP oferece. A skill diz “este é o workflow para revisar um PR”. O MCP dá o acesso à API do GitHub para buscar diffs e publicar comentários.
Vale registrar: as respostas das ferramentas MCP também consomem os limites de tokens. Payloads grandes vindos de chamadas MCP enchem a context window rápido, o que deixa o argumento do contexto enxuto a favor das skills ainda mais forte.
Subagents
Subagents são instâncias de trabalho especializadas, que cuidam de subtarefas de forma independente e muitas vezes em paralelo.
| Dimensão | Skills | Subagents |
| Papel principal | Fornecer expertise ou workflow | Fornecer delegação e paralelismo |
| Formato | Pacote de conhecimento e instruções | Instância de trabalho adicional |
| O que resolve | “Como esta tarefa deve ser feita?” | “Quem deve fazer esta subtarefa?” |
| Exemplo | “Checklist de revisão de segurança” | “Suba um worker de revisão de segurança e outro para corrigir testes” |
Skills dizem ao agent o que fazer. Subagents cuidam de quem faz. Um subagent pode até carregar uma skill para aprender a executar a tarefa que recebeu.
Escolhendo a ferramenta certa
| Mecanismo | Quando usar | Exemplo |
| Rules | Guardrails universais, que precisam estar sempre ativos | “Nunca apague bancos de dados de produção.” |
| Skills | Workflows de tarefas reutilizáveis, padrões de código, convenções do projeto | “Como escrever um teste e2e com Playwright.” |
| MCPs | Conexões ao vivo com APIs externas, bancos de dados ou sistemas fechados | “Consulte o JIRA para pegar os últimos relatórios de bug.” |
| Subagents | Trabalho pesado e tarefas paralelas, para poupar a context window do agent principal | “Vasculhe 100 arquivos de log em busca de um memory leak específico.” |
Esses mecanismos se somam em camadas: rules para os guardrails de segurança, skills para os workflows do time, MCPs para o acesso a ferramentas e subagents para o trabalho que dá para paralelizar.
Por que isso importa para os times
Economizar tokens importa. O ganho organizacional importa ainda mais. As skills transformam o conhecimento do time em artefatos portáteis e versionados, que qualquer agent consegue pegar e executar.
Quando uma pessoa sênior escreve uma skill de security-review, todo mundo do time passa a ter o mesmo checklist de revisão, do recém-chegado ao veterano. O conhecimento deixa de morar na cabeça de alguém ou em uma página do Confluence que ninguém lê. Ele passa a morar onde o agent usa.
Como compartilhar skills entre times
Skills são pastas. Distribua com as ferramentas que os devs já usam. Os runtimes de agent que suportam skills reconhecem vários escopos de instalação:
| Escopo | Local | Quem se beneficia | Exemplo |
| Projeto | .cursor/skills/ ou .claude/skills/ no repo | Todo mundo no projeto | migration-review para um schema de banco específico |
| Usuário | ~/.cursor/skills/ ou ~/.claude/skills/ | Você, em todos os projetos | technical-blog-writing para o seu workflow pessoal |
| Time / organização | Compartilhado via Git ou um registry | Todo mundo na organização | api-design com os padrões de API da sua empresa |
Skills com escopo de projeto entram no commit do repo e viajam junto com ele. Skills com escopo de usuário são pessoais: seu estilo de código preferido, seu workflow de escrita.
Para distribuir no time, o caminho mais simples é um repo Git compartilhado. Aponte um diretório do seu projeto para ele via submodule e as atualizações chegam a cada pull:
git submodule add https://github.com/your-org/shared-skills .claude/skills/shared
Um ponto de partida prático
Por onde começar:
- Audite o seu rules file. Tudo que for específico de uma tarefa é candidato a virar skill.
- Comece por uma skill de alto valor. Escolha o workflow que o seu time mais repete: escrita de testes, revisão de PR, criação da estrutura de um serviço.
- Coloque no repo. Skills com escopo de projeto não exigem infraestrutura nenhuma. Faça o commit da pasta e o agent de cada pessoa do time passa a reconhecê-la automaticamente.
- Itere com base no uso. Observe como o agent ativa a skill. Ajuste a descrição se ela dispara demais ou de menos. Aperte as instruções quando o agent pular etapas.
- Promova para compartilhar. Quando uma skill provar seu valor em um projeto, mova para um repositório compartilhado ou um registry e amplie o alcance.
Trade-offs e limitações
As agent skills também têm suas limitações:
- A descoberta depende da qualidade da descrição. Se a descrição da skill não bate com a forma como as pessoas escrevem os pedidos, o agent não vai ativá-la. Escrever boas descrições de gatilho exige iteração.
- Skills são mais uma coisa para manter. Elas ficam desatualizadas do mesmo jeito que a documentação. Uma skill velha, que ensina o workflow errado, é pior do que nenhuma skill.
- Nem todo runtime de agent suporta skills ainda. O padrão vem ganhando tração, mas não está universalmente padronizado. Confira na documentação da sua ferramenta o suporte atual.
- Overhead em projetos pequenos. Se o seu rules file tem 500 tokens e cobre tudo o que você precisa, extrair skills só adiciona complexidade organizacional, sem economia real de tokens.
Conclusão
Se o seu rules file já está parecendo bagunçado, você sabe. Faz tempo que você passa direto por certas seções pensando “isso não deveria estar aqui”. Confie nesse instinto. Tire aquele trecho e coloque em uma pasta de skill. Dê um nome e uma descrição. Veja no que dá.
Leituras recomendadas
- Agent Skills Specs: a especificação em si
- The Complete Guide to Building Skills for Claude (PDF): o guia completo da Anthropic
- Documentação de skills do Claude Code: detalhes de implementação específicos do Claude Code
- Documentação de skills do Cursor: detalhes de implementação específicos da IDE
- Skills.sh: navegue e descubra skills da comunidade
