// resumo em 30 segundos

• →Missão é um objetivo que vira PRD, plano em fases e contrato de validação, escrito antes de qualquer código.
• →Quem implementa não aprova, e cada agente começa com contexto limpo: sessão curta erra menos e ninguém defende o próprio código.
• →Custa mais token e mais tempo. Em 2026 o formato ainda vale, com escrita em série e paralelo só pra leitura.

Escrito e revisado por Jefferson Oliveira. Os exemplos vêm da missão que construiu este site e das skills que eu uso no dia a dia.

Pedir pro agente “faz a Home inteira” funciona no começo. Depois ele esquece o que combinou, mede uma coisa e implementa outra, e no fim diz que está tudo pronto. Não está.

O modelo dá conta de cada parte. O que dá errado é juntar tudo numa conversa só: ele planeja, escreve e confere o próprio trabalho com o mesmo contexto, que só cresce. Missão é o fluxo que eu uso pra separar esses trabalhos. Este site foi feito assim, e eu uso o mesmo formato em outros projetos, de WordPress a Laravel.

Vi o formato numa palestra do Luke Alvoeiro, da Factory, no canal AI Engineer [1]. A Factory chama de Missions um modo do agente deles em que um orquestrador planeja junto com você, workers implementam features organizadas em milestones e validadores conferem cada milestone no fim.

Duas ideias da palestra me pegaram. Teste escrito depois da implementação não pega bug, só confirma as decisões que já foram tomadas. E quem implementou avalia pior o próprio trabalho do que um revisor que chega sem contexto. A Factory ainda diz que a maior parte do valor está no planejamento [2].

Eu não uso o produto da Factory. Montei a mesma ideia no Claude Code, com uma skill de orquestração e quatro agentes. A versão enxuta deles está no fim do post, pra copiar.

O /mission é o único comando. Ele lê o estado em docs/mission/plan.md e faz um passo só: planeja, executa a próxima fase ou valida o milestone que fechou. Um passo por chamada é de propósito, pra eu revisar entre as fases.

O planner lê a spec e o Figma e escreve três arquivos: o PRD, o plano em milestones e fases, e o contrato de validação. Se algo estiver ambíguo, ele para e devolve perguntas antes de escrever qualquer coisa.

O worker implementa uma fase, em contexto limpo. Lê o PRD, o plano, o contrato e os handoffs anteriores, faz o trabalho e escreve o próprio handoff. Não commita.

No fim de cada milestone entram dois validadores que não implementaram nada. O scrutiny roda lint, build e code review e não tem ferramenta pra editar arquivo. O user-testing é o QA: navega o site como visitante e como editor, mede cada seção contra o Figma e não lê o código-fonte.

Jefferson Oliveira // o detalhe que eu gosto

O orquestrador não lê código. Só despacha, lê o retorno e marca o plano. Numa missão longa ele é quem mais acumula contexto, então quanto menos carrega, mais tempo aguenta sem se perder.

O contrato de validação é uma lista de asserções verificáveis, escrita a partir do PRD antes da primeira linha de código. Ele define quando a missão terminou.

Aqui no site, cada seção tem uma asserção de fidelidade com os nodes do Figma e os ids que o validador mede em 1366, 768 e 390. Tem outra dizendo onde o editor troca cada texto pelo painel, e uma de performance: nenhum get_field em Blade, nenhuma query repetida. O worker grava exatamente esses ids, e o validador confere contra o contrato, não contra o que o worker disse que fez.

É o que mais muda o resultado. Sem contrato, o validador lê o código e acha razoável. Com contrato, ele tem uma régua que ninguém ajustou depois.

Cada fase termina num arquivo: o que foi feito, onde o editor mexe, o que ficou de fora e por quê, os comandos com exit code, os problemas encontrados e os arquivos tocados. A próxima fase lê os handoffs que tocam nela. Ninguém depende de lembrar da conversa.

1## Ficou de fora2- ... (e por quê)34## Comandos executados5| Comando | Exit code |6| --- | --- |7| `...` | 0 |89## Procedimentos10- [ ] Lint/build rodados11- [ ] Script de conteúdo rodado 2x (idempotente)12- [ ] (UI) Inventário escrito antes do build13- [ ] Conferido em 1366 e 390 contra o Figma14      (`measure.py` + `--overflow`)15- [ ] Ficou dentro do escopo da fase

O “Procedimentos” é o que o orquestrador olha primeiro. Caixa desmarcada ou bloqueio, ele para e me chama em vez de seguir pra próxima fase.

Jefferson Oliveira // na prática

O handoff vale pelo que ele admite. Na fase do blog da Home, a conexão com o Figma caiu logo depois da leitura dos nodes, e o worker escreveu que dois scripts de conferência não rodaram e o que faltava checar. Num agente só, isso vira “pronto” e some.

Dividir em agentes tem outro efeito, fora o validador: cada sessão fica pequena. O worker começa do zero, lê o PRD, o plano, o contrato e os handoffs que tocam nele, faz uma fase e acaba. Ninguém carrega a conversa das 40 fases anteriores.

Tem gente que fala que até uns 200 mil tokens de contexto o modelo é inteligente, e depois disso começa a ficar burro. Não sei se o corte é esse número, mas a direção bate com o que eu vi. Com as fases separadas, o agente ficou mais certeiro: menos “esqueci o que combinamos”, menos medida trocada. É mais um ponto a favor.

Jefferson Oliveira // o número que eu medi

Nos registros da missão deste site, o pico de contexto dos 64 agentes teve mediana de 158 mil tokens. A sessão do orquestrador, que só despachava, chegou a 366 mil, mesmo compactada cinco vezes. Numa conversa só, tudo isso estaria junto. Ainda tem o que cortar: 15 agentes passaram de 200 mil.

O que me ajudou a enxergar isso foi o TokenLens, um painel open source que eu fiz pra ver os tokens das sessões do Claude Code, do Codex e do pi (github.com/jeffersonrucu/token-lens). Ele roda só na máquina e lê os registros que os agentes já gravam. Mostra o gasto de cada subagente e quem iniciou cada um, o contexto enviado a cada resposta, onde o cache se perdeu e onde um /compact cortou. A sessão ao vivo fica vermelha quando passa de 100 mil tokens.

Foi nesses gráficos que eu debuguei o fluxo, otimizei e entendi quanto custava cada parte.

A missão deste site teve 7 milestones, 43 handoffs e 101 asserções no contrato. Os validadores reprovaram 4 rodadas e aprovaram 13.

Nenhuma reprovação era erro de compilar. No primeiro milestone, o foco do teclado sumia abaixo de 1024 px porque o contorno laranja ficava em cima do botão laranja. Na Home, durante a animação de digitação do terminal, o Tab parava num link invisível. Os dois passam no lint, no build e no olho de quem escreveu.

Jefferson Oliveira // quase foi pro ar

Na passada final, com tudo aprovado, o QA abriu o sitemap e achou /author/jefferson/ indexável, sem layout, com a lista crua de posts. Nenhuma fase tinha tocado nessa página, então nenhuma asserção cobria. Ele achou porque navega o site em vez de ler o código.

Validador também erra. Um apontou que faltava o link “ver certificado”, que estava lá. Outro rodou uma exclusão com o ID errado, e por sorte nada se perdeu. Validador é mais um agente: o veredito dele também passa pelo meu olho antes de virar fase de correção.

O custo é alto, em token e em tempo. Cada fase é um agente novo que relê PRD, plano, contrato e Figma antes de escrever uma linha. Cada milestone chama mais dois agentes. Fase reprovada volta pro começo.

A Anthropic mediu algo parecido: o mesmo app saiu em 20 minutos e US$ 9 com um agente sozinho, e em 6 horas e US$ 200 com planner, gerador e avaliador separados, com qualidade bem maior [3].

O tempo pesa mais que o token. A missão deste site levou umas 48 horas corridas, do pedido ao “terminamos”. Pra quem está acostumado a pedir e receber em minutos, é lento mesmo. A troca que eu faço é essa: demora mais, acerta mais e me sobra menos pra revisar.

E boa parte desse tempo vai pra validação. O QA não lê código: ele roda scripts que sobem um navegador, abrem o site, navegam, preenchem formulário, editam pelo painel e medem cada seção em várias larguras. Cada passo espera a página carregar. É lento por natureza, e pular essa etapa é perder justamente o que pega o bug.

Jefferson Oliveira // onde vai o tempo

Somando o tempo ativo dos agentes da missão deste site, os validadores ficaram com cerca de 30% e os workers com o resto. Dentro do QA, mais de um terço do tempo foi esperando script de navegador. E o worker também roda o medidor contra o Figma antes de entregar a fase, então a conferência aparece dos dois lados.

Pra não depender de mim a cada fase, existe o modo autônomo. A dúvida que surge vira uma linha num arquivo de pendências, com o padrão mais conservador aplicado, e o trabalho segue. Nesta missão foram 45 dúvidas registradas assim, pra eu revisar de uma vez depois.

Jefferson Oliveira // onde eu errei

Fui dormir às duas da manhã pedindo pra ele rodar em loop e não pausar por dúvida. Meia hora depois ele parou: a conexão com o Figma tinha caído, e sem Figma o worker não mede nada. Voltei ao meio-dia e a missão estava no mesmo lugar. Modo autônomo resolve dúvida. Ferramenta fora do ar, não.

A primeira vontade é rodar vários workers juntos. A Factory diz que execução em série, com paralelismo pontual, funcionou melhor que paralelismo amplo [2]. Eu tentei e vi por quê.

Num projeto em Laravel, deixei workers em paralelo na mesma árvore quando as fases não tocavam os mesmos arquivos. Mesmo assim, um handoff registrou a fonte computada mudando entre uma medição e outra, 4 a 7 px abaixo do Figma, provavelmente porque outro worker mexia no CSS. Daí veio a regra: cada fase lista os arquivos que vai tocar, e só roda junto com outra se as listas não se cruzam. Se houver dúvida, uma depois da outra.

Aqui no WordPress, até os validadores rodam em sequência: juntos, um suja o debug.log do outro. Onde o paralelo funcionou foi com milestones independentes. No fim deste site eu pedi pra acelerar, e quatro agentes, um por milestone que faltava, fecharam Projetos, Blog, Post e o resto em menos de uma hora.

Eu me perguntei isso antes de escrever. Sai modelo novo todo mês, e andaime de agente envelhece rápido. A própria Anthropic tirou peças do harness dela quando os modelos melhoraram: resets de contexto e sprints deixaram de ser necessários [3].

O miolo da ideia continua de pé. Factory, Anthropic, Cognition e Cursor publicaram sobre isso este ano e chegaram perto do mesmo formato: um agente escreve por vez, paralelo só pra ler e revisar, revisor separado com contexto limpo e um plano definido antes do código. O que caiu foi o enxame de agentes escrevendo juntos.

Pra tarefa de minutos, missão é exagero. Um ajuste de CSS, um bug com causa conhecida, uma tela pequena: eu peço direto, com um plano rápido e no máximo um subagente revisando no fim. Missão eu uso quando o trabalho dura horas, quando dá pra escrever o critério de pronto antes e quando um bug que passa custa mais caro que o token gasto.

Abaixo vai uma versão enxuta do que eu uso, sem nada de WordPress ou Figma. São cinco arquivos: a skill de orquestração em .claude/skills/mission/ e os quatro agentes em .claude/agents/. Cole no seu projeto, ajuste os comandos de lint, build e teste, e rode.

1---2name: mission3description: Planeja, executa a próxima fase ou valida o4  milestone conforme o estado de docs/mission/. Use quando5  o usuário pedir /mission.6---78Você é o orchestrator. Não explore código nem implemente:9só despache agentes, leia os retornos e atualize o plano.1011Argumento: $ARGUMENTS1213Leia docs/mission/plan.md e siga **um** caso:14151. Sem plano: chame o `planner` com o objetivo. Se ele16   devolver perguntas, faça-as ao usuário e retome o mesmo17   planner com as respostas. Mostre o plano e pare.182. Plano em `Status: rascunho`: peça aprovação. Aprovado,19   troque para `Status: aprovado` e pare.203. Fase pendente: chame o `worker` com "Leia21   docs/mission/prd.md, plan.md e validation-contract.md.22   Faça a Fase <N>." Leia o handoff. Procedimento23   incompleto ou bloqueio: pare e reporte. Senão, marque24   `- [x]`. Se o milestone fechou, chame25   `scrutiny-validator` e depois `user-testing-validator`.26   Reprovado: crie fases de correção e pare. Se o27   milestone já reprovou duas vezes: pare e reporte.284. Tudo feito: troque para `Status: concluído` e resuma.

1---2name: planner3description: Transforma um objetivo em PRD, plano de fases e4  contrato de validação. Devolve perguntas quando o escopo5  estiver ambíguo. Use via /mission.6model: opus7---89Você planeja uma missão. Não implemente nada.10111. Leia docs/escopo.md, se existir, e só o necessário12   do código.132. Se algo for ambíguo, pare e devolva só as perguntas14   (máx. 5, com a opção recomendada).153. Com o escopo fechado, escreva:16   - docs/mission/prd.md: objetivo, regras, fora do17     escopo, fluxos e critérios de aceite.18   - docs/mission/plan.md: `Status: rascunho`, milestones19     e fases `- [ ]`, cada fase pequena o bastante pra20     um agente só.21   - docs/mission/validation-contract.md: asserções22     verificáveis por milestone, escritas antes do código.23     É contra elas que os validadores conferem.244. Devolva um resumo do plano.

1---2name: worker3description: Implementa uma única fase de docs/mission/plan.md4  em contexto limpo e devolve um handoff. Use via /mission.5model: opus6---78Implemente **só** a fase indicada no pedido.9101. Leia prd.md, plan.md, validation-contract.md e os11   handoffs anteriores que tocam na sua fase.122. Implemente. Rode lint, build e testes.133. Salve docs/mission/handoffs/phase-<N>.md e devolva o14   mesmo conteúdo: Implementado, Ficou de fora (e por15   quê), Comandos executados (com exit code), Problemas16   descobertos, Arquivos alterados e Procedimentos17   (checklist do que rodou).184. Não commite. Problema fora da fase vai em "Problemas",19   não no código.

1---2name: scrutiny-validator3description: Valida um milestone com lint, build, testes e4  code review contra o contrato. Use via /mission.5tools: Read, Grep, Glob, Bash6model: sonnet7---89Você valida um milestone que **não** foi você quem10implementou. Não edite código.11121. Leia o prd.md, o milestone no plan.md e os itens dele13   no validation-contract.md.142. Rode lint, build e testes. Anote o exit code de cada.153. Revise os arquivos listados nos handoffs do milestone.164. Confira cada item do contrato. Vale o contrato, não o17   que o código faz.1819Devolva: **Veredito:** APROVADO | REPROVADO, os checks20com exit code, o contrato marcado e os problemas, do mais21grave pro menos grave, com arquivo:linha.

1---2name: user-testing-validator3description: QA de um milestone: usa o produto ponta a ponta4  sem olhar o código. Use via /mission.5model: sonnet6---78Você é QA. **Não leia o código-fonte.**9101. Leia o prd.md, o milestone no plan.md e os itens dele11   no validation-contract.md.122. Suba o app e use como o usuário usaria: navegador,13   CLI ou API, o que o projeto tiver.143. Teste cada item do contrato e guarde a evidência15   (screenshot, saída do comando) em16   docs/mission/evidence/M<n>/.1718Devolva: **Veredito:** APROVADO | REPROVADO, item por item19do contrato com a evidência, e os problemas com o passo a20passo pra reproduzir.

Jefferson Oliveira // a dica

Antes do /mission, eu rodo o /grill-me, uma skill do Matt Pocock (github.com/mattpocock/skills). Ela me entrevista em rodadas, cada pergunta com a resposta que ela recomenda, até não sobrar decisão no ar. No fim eu peço pra salvar as decisões em docs/escopo.md, e o planner começa com bem menos perguntas.

Com o escopo fechado e o plano aprovado, daí pra frente é automático. O /loop do Claude Code repete um comando, e sem intervalo o próprio agente decide quando rodar de novo. Com /loop /mission ele vai executando fase por fase e validando cada milestone, e eu só volto pra ler os vereditos. O fluxo inteiro cabe em três comandos, e entre o segundo e o terceiro você lê o plano e aprova.

1/grill-me painel de pedidos com filtro e export CSV2/mission painel de pedidos, decisões em docs/escopo.md3/loop /mission

1. [1] Palestra · The Multi-Agent Architecture That Actually Ships, Luke Alvoeiro (AI Engineer) (abre em nova aba) youtube.com/watch?v=ow1we5PzK-o copiar link da referência 1copiado
2. [2] Factory · Missions (abre em nova aba) factory.com/news/missions copiar link da referência 2copiado
3. [3] Anthropic Engineering · Harness design for long-running apps (abre em nova aba) anthropic.com/engineering/harness-design-long-running-apps copiar link da referência 3copiado
4. [4] Pesquisa · Chroma: Context Rot (abre em nova aba) trychroma.com/research/context-rot copiar link da referência 4copiado

Fontes conferidas em nov 2026.

The post Missões: o fluxo que eu uso pra IA entregar projeto inteiro appeared first on Jefferson Oliveira.

// resumo em 30 segundos

• →Senha colada no chat vai pro modelo, fica salva no histórico e pode parar num commit. Trate como vazada.
• →O agente não precisa ver a senha, só usar. O KeePassXC guarda, um script busca e conecta, e o Claude recebe só a saída.
• →Não é blindagem. Se a senha escapar, a ordem é trocar primeiro e procurar as cópias depois.

Escrito e revisado por Jefferson Oliveira. Os scripts são versões enxutas: adapte nomes e caminhos ao seu ambiente.

Uma hora o agente precisa entrar num servidor. Ver o disco, rodar um wp plugin list, ler um log. O caminho mais curto é colar a senha no chat, e ele funciona. Esse é o problema.

Eu queria pedir “entra no servidor-x e vê o disco” e o Claude Code resolver sozinho, sem a senha passar pela conversa. Deu pra montar com um app no meu computador e um script de vinte linhas.

Tudo o que aparece na conversa vai pro modelo: o que você cola e o que um comando imprime. Um cat .env rodado pelo agente põe o segredo no contexto do mesmo jeito.

Daí ela fica em texto puro em ~/.claude/projects, pode parar num commit, sair por injeção de prompt e volta inteira com claude –resume.

O ssh-agent faz isso há décadas: a chave fica carregada nele e nunca passa por quem roda o comando. A ideia é a mesma pra qualquer credencial: o segredo fica num cofre, um script entrega direto pro processo e o Claude recebe só a saída.

Escolhi o KeePassXC: gratuito, open source (GPL) e o cofre é um arquivo .kdbx no meu disco, sem servidor de terceiro. Ele já traz um SSH agent e o Secret Service, que deixa o secret-tool buscar uma senha sem pedir a senha mestra de novo.

Jefferson Oliveira // o detalhe que eu gosto

Travar o KeePassXC vira um interruptor. Cofre travado, o agente perde acesso a tudo na hora, sem mexer em configuração nenhuma.

No Pop!_OS (base Ubuntu), são quatro ajustes depois de instalar:

1$ sudo apt install keepassxc libsecret-tools sshpass

1. Crie o cofre e um grupo só pro agente. Cada servidor vira uma entrada: o título é o nome que você usa na conversa, o host vai no campo URL.

2. Ative o Secret Service em Tools › Settings e exponha só esse grupo.

3. Tire o gnome-keyring da frente: só um programa responde pelo Secret Service, e no Pop!_OS é ele. Um override no systemd desliga a parte de segredos dele e o D-Bus passa a abrir o KeePassXC. Ele guarda a chave das senhas salvas do Chrome, então sincronize a Conta Google antes.

4. Se usa chave, ative o SSH Agent e anexe a chave na entrada, com a senha em branco.

O cofre-ssh, em ~/.local/bin, busca a entrada e conecta:

1#!/usr/bin/env bash2# cofre-ssh <entrada> "<comando>"3set -euo pipefail4entrada="$1"; shift56attr() {7  # atributos saem no stderr; o stdout traz o segredo8  secret-tool search Title "$entrada" 2>&1 >/dev/null \9    | sed -n "s/^attribute\.$1 = //p" | head -n110}11host=$(attr URL)12user=$(attr UserName)13senha=$(secret-tool lookup Title "$entrada" || true)14opts=(-o StrictHostKeyChecking=accept-new)1516# sem senha: chave SSH, o agent do KeePassXC assina17if [[ -z "$senha" ]]; then18  exec ssh "${opts[@]}" "$user@$host" "$@"19fi2021# com senha: vai pelo ambiente, nunca no argumento22export SSHPASS="$senha"23exec sshpass -e ssh "${opts[@]}" "$user@$host" "$@"

A senha vai pela variável SSHPASS e não aparece nos argumentos do processo. Um irmão dele, o cofre-lista, imprime só os títulos das entradas: é assim que o Claude sabe o que existe.

Jefferson Oliveira // onde eu errei

Na primeira versão eu lia os atributos do stdout, e o script dizia que a entrada não existia. O secret-tool manda os atributos pro stderr e o segredo pro stdout. Trocar pra 2>&1 >/dev/null resolveu e ainda deixou melhor: a senha nem passa pelo sed.

Falta fechar o acesso direto. O Claude não lê o cofre nem chama o secret-tool; o script continua chamando por dentro:

1{2  "permissions": {3    "deny": [4      "Read(**/*.kdbx)",5      "Read(~/.ssh/**)",6      "Read(**/.env*)",7      "Bash(secret-tool:*)",8      "Bash(keepassxc-cli:*)",9      "Bash(printenv:*)"10    ]11  }12}

E contar pro Claude que o cofre existe. Sem isso, ele acaba pedindo a senha no chat:

1## Servidores2- Acesso a servidor só pelo cofre.3- `cofre-lista` mostra os nomes disponíveis.4- `cofre-ssh <nome> "<comando>"` roda o comando no servidor.5- Nunca peça senha nem chave no chat.

Pronto. Eu peço “entra no servidor-x e vê o disco”, e o Claude roda:

1$ cofre-lista2servidor-x3servidor-y4site-cliente56$ cofre-ssh servidor-x "df -h"7Filesystem      Size  Used Avail Use% Mounted on8/dev/sda1        80G   41G   36G  54% /

Com o WP-CLI, cofre-ssh servidor-x “wp plugin list” resolve o WordPress sem senha de admin. Painel web é o único caso em que o login fica comigo: eu entro pelo navegador e o Claude in Chrome usa a sessão aberta.

Isso é boa prática, não blindagem. Regra de deny bloqueia o comando que ela nomeia, e o mesmo arquivo pode ser lido de outro jeito. E um cat wp-config.php no servidor põe a senha do banco na conversa, com cofre ou sem cofre.

Então eu reduzo o estrago: cofre só com o que o agente pode usar, usuário próprio pra ele, sem admin onde não precisa. Garantia de verdade, só com o agente isolado em container ou sandbox.

Senha que apareceu na conversa está vazada. Primeiro ela para de funcionar: troque a senha, tire a chave antiga do authorized_keys, revogue o token e derrube as sessões. Depois procure as cópias, num terminal fora do Claude:

1# digita a senha antiga sem aparecer na tela2$ read -rs S34# arquivos que contêm o valor, só os nomes5$ grep -rlF -- "$S" ~/.claude/projects .67# commits que adicionaram ou removeram o valor8$ git log --all -S "$S" --oneline910$ unset S

Achou, apague a sessão e tire o valor dos arquivos. Commit já enviado o git filter-repo limpa, mas quem clonou antes continua com a cópia. Por isso a troca vem primeiro.

1. [1] Claude Code Docs: Settings e permissões (abre em nova aba) code.claude.com/docs/en/settings copiar link da referência 1copiado
2. [2] KeePassXC (abre em nova aba) keepassxc.org copiar link da referência 2copiado
3. [3] keepassxc-mcp (abre em nova aba) glama.ai/mcp/servers/preginald/keepassxc-mcp copiar link da referência 3copiado
4. [4] GitHub Docs: Removing sensitive data from a repository (abre em nova aba) docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository copiar link da referência 4copiado

Fontes conferidas em nov 2026.

The post Como eu passo senha e chave SSH pro Claude Code sem colar no chat appeared first on Jefferson Oliveira.

// resumo em 30 segundos

• →Skill é uma pasta com um SKILL.md: name e description obrigatórios, instruções no corpo.
• →Só a descrição fica no contexto o tempo todo. O resto carrega quando o pedido combina com ela.
• →Seja curto, diga o que a skill faz e quando usar, e teste com casos reais antes de crescer.

Escrito e revisado por Jefferson Oliveira. As regras vêm da documentação da Anthropic, conferida em out 2026.

Skill é o jeito mais simples de ensinar um fluxo seu pro agente. Uma pasta, um arquivo SKILL.md com nome, descrição e instruções. O agente lê a descrição de todas e só abre a que serve pro pedido do momento. Este post resume a documentação da Anthropic e as boas práticas que eles publicaram.

Uma pasta com um SKILL.md dentro e, se precisar, scripts e arquivos de referência ao lado. No Claude Code, por exemplo, ela fica em ~/.claude/skills/ quando é sua, pra todos os projetos, ou em .claude/skills/ quando é do projeto. No segundo caso vai pro git, e o time inteiro ganha a skill junto.

1---2name: pr-description3description: Escreve a descrição de um pull request a4  partir do diff. Use ao abrir um PR ou quando pedirem5  pra descrever as mudanças da branch.6---78# pr-description9101. Leia o diff da branch contra a principal.112. Escreva o título como `tipo: o que muda`.123. Explique o porquê em até 15 linhas.

Só name e description são obrigatórios. O name aceita letras minúsculas, números e hífen, até 64 caracteres. A description vai até 1.024 caracteres e diz o que a skill faz e quando usar.

Prompt resolve uma vez. Você escreve, o agente executa, e na próxima sessão começa do zero: ou você cola de novo, ou escreve de outro jeito e recebe outro resultado. A skill é esse prompt guardado num lugar que o agente conhece, e isso muda quatro coisas.

Ela se repete igual. O mesmo SKILL.md roda hoje e daqui a um mês, com os mesmos passos, sem você lembrar de colar nada.

Ela é chamada sozinha. O agente lê a descrição e decide quando usar. Você pede “descreve esse PR” e a skill certa entra.

Ela é do time. Commitada no projeto, vale pra todo mundo, e uma correção de uma linha chega pra todos no próximo pull.

Ela carrega só o necessário. A pasta pode ter script e arquivo de referência, e o agente só abre o que a tarefa pede. Um prompt colado ocupa o contexto inteiro desde a primeira mensagem.

Uma regra que eu uso: colou o mesmo prompt duas vezes, ele virou skill.

A skill carrega em etapas. Na abertura da sessão entram só o nome e a descrição de cada uma. O corpo do SKILL.md entra quando o pedido combina com a descrição. Arquivos extras, como uma referência ou um script, só quando o próprio SKILL.md manda abrir.

Por isso a descrição é a parte que mais importa. Se ela não diz quando usar, a skill nunca é chamada.

Seja curto. A premissa do guia é que o modelo já é muito inteligente, então escreva só o que ele não sabe sobre o seu caso.

Descrição em terceira pessoa, com o que faz e quando usar. “Processa planilhas e gera relatório”, e não “Eu posso te ajudar com planilhas”. A descrição entra no prompt de sistema, e misturar pontos de vista atrapalha a descoberta.

Corpo do SKILL.md abaixo de 500 linhas. Passou disso, divida em arquivos e aponte pra eles a partir do SKILL.md, com um nível de profundidade só.

Um termo por conceito, do começo ao fim, e nada com data de validade. E teste antes de escrever muito: o guia pede pelo menos três avaliações com cenários reais, rodadas em todos os modelos que vão usar a skill.

Jefferson Oliveira // o detalhe que eu gosto

Skill melhora com o uso. A que monta estes posts ganhou uma regra nova esta semana, depois que eu cortei um fechamento que soava grosso. Uma linha no SKILL.md, e o próximo post já sai sem ele.

O agente decide sozinho quando usar uma skill, mas dá pra chamar na mão. No Claude Code é /nome-da-skill. Pra fluxo que só deve rodar quando você pede, como um deploy, coloque disable-model-invocation: true no frontmatter.

1. [1] Documentação oficial · Claude Code Docs: Skills (abre em nova aba) code.claude.com/docs/en/skills copiar link da referência 1copiado
2. [2] Documentação oficial · Agent Skills overview (abre em nova aba) platform.claude.com/docs/en/agents-and-tools/agent-skills/overview copiar link da referência 2copiado
3. [3] Documentação oficial · Skill authoring best practices (abre em nova aba) platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices copiar link da referência 3copiado
4. [4] Padrão aberto · Agent Skills (abre em nova aba) agentskills.io copiar link da referência 4copiado

Fontes conferidas em out 2026.

The post Skills para agentes, direto ao ponto appeared first on Jefferson Oliveira.