Skills e Rules para agentes de IA: como padronizar o comportamento do time

Sem instruções persistentes, cada sessão de agente é um júnior novo: esquece o linter, inventa pasta, commit afoito, ignora o design system. Rules e skills são o jeito de transformar “o que a gente sempre faz” em contexto carregável — versionado no git, revisável no PR, igual para Cursor, Claude Code, OpenCode e o que mais o time usar.


Rules vs skills (definição prática)

RulesSkills
PapelPolíticas sempre (ou quase sempre) ativasProcedimentos sob demanda
Tom“Nunca faça X / sempre faça Y”“Quando o usuário pedir Z, siga este playbook”
Onde costuma viver.cursor/rules, CLAUDE.md, AGENTS.mdSKILL.md / pastas de skills do produto
TamanhoCurto, scorávelPode ser longo: passos, checklists, exemplos

Regra de ouro: rule é lei do repo; skill é manual de operação. Se tudo for rule, o contexto explode e o modelo dilui o que importa. Se tudo for skill, o agente só se comporta bem quando alguém lembra de invocar.


O padrão AGENTS.md / CLAUDE.md

Vários harnesses convergem para um arquivo na raiz (ou por pacote):

# AGENTS.md

## Stack
- Next.js App Router, TypeScript strict, Yarn

## Não fazer
- Não adicionar dependência sem pedir
- Não commitar sem o usuário pedir

## Como verificar
- yarn lint && yarn test

Claude Code prioriza CLAUDE.md; Cursor lê rules em .cursor/rules e também entende AGENTS.md em muitos setups. OpenCode documenta AGENTS.md. Em times multi-tool, mantenha uma fonte canônica e, se preciso, um ponteiro curto nos outros arquivos (“ver AGENTS.md”).

Detalhe de produto varia — trate paths como convencões do seu harness atual.


Rules que valem ouro (e as que não)

Valem:

  • Fronteiras de confiança (secrets, produção, force push).
  • Comandos de verificação reais do repo.
  • Convenções de pasta e naming que o lint não pega.
  • “Commit só quando pedido” / política de PR.

Não valem como rule global:

  • Tutorial de 400 linhas sobre um framework.
  • Preferências pessoais de um dev.
  • Texto que contradiz o CI.

Se a rule não cabe em uma tela, provavelmente é skill ou doc humana.


Anatomy de uma skill útil

Uma skill boa responde três perguntas em segundos: quando usar, o que fazer, o que nunca fazer.

---
name: create-pr
description: Use when opening a pull request for the current branch.
---

# Create PR

1. git status + git diff + git log vs main
2. Push com -u se necessário
3. gh pr create com summary e test plan
4. Devolver a URL

Never force-push to main.

Dicas:

  • description rica: é o que o roteador do agente usa para decidir se a skill aplica.
  • Passos numerados com comandos literais.
  • Zero placeholders do tipo “adicione tratamento de erro adequado”.
  • Uma skill = um job (abrir PR ≠ deploy ≠ inventar feature).

Isso combina com orquestração: workers recebem skills diferentes (implementar vs só revisar). Ver orquestração de agentes.


Padronizar o time sem burocracia

  1. Comece com 5 rules que o CI não cobre.
  2. Extraia skills só depois da terceira vez que alguém repetir o mesmo prompt.
  3. Revise skills no PR como código: diff de procedimento.
  4. Delete skill que ninguém invocou em 60 dias.
  5. Separe skill de produto (MCP, browser) de skill de git.

Ferramentas diferentes? O conteúdo importa mais que o formato. Um AGENTS.md bem escrito já reduz 80% da deriva; rules/skills específicas refinam o resto. Mapa das tools: OpenCode vs Cursor vs Claude Code vs Orca.


Ligação com MCP

Rules dizem política; MCP expõe capacidade (Jira, DB read-only, docs). Sem rules, o agente chama tools demais; sem MCP, ele alucina integrações. Os dois se complementam — MCP para agentes de código.

Exemplo de rule curta:

Use o MCP de docs só para APIs externas.
Nunca use tools de deploy em branches que não sejam main.

Exemplo de pacote mínimo para um repo Next.js

AGENTS.md                 # canônico
.cursor/rules/
  git-safety.mdc          # commits, push, amend
  frontend.mdc            # padrões do design system
skills/
  pr/SKILL.md
  verify/SKILL.md         # lint + test + o que olhar no diff

No verify skill, fixe os comandos do projeto (yarn lint, yarn test) — agentes adoram inventar npm no repo Yarn.


Checklist

  • Existe um arquivo canônico de instruções no git?
  • Rules cabem em “sempre / nunca”?
  • Skills têm description acionável e passos verificáveis?
  • Segredos e produção estão explicitamente fora de escopo?
  • Alguém revisa mudanças nesses arquivos como código?

Conclusão

Agentes sem rules são dados; com rules ruins são lentos; com skills demais são confusos. O sweet spot é poucas leis claras + playbooks curtos para tarefas repetidas. Versionar isso no repo é o que faz o “comportamento do time” sobreviver à troca de modelo ou de IDE.

Mais sobre meu trabalho e projetos: portfolio.