Conteúdo detalhado
🧩 Três camadas, uma ordem
Este módulo cobre de uma vez as três camadas de capacidade: Habilidades (camada 4), Ferramentas (camada 5) e Agentes (camada 6). O next te leva por elas nessa sequência, e a sequência não é por acaso: um agente só faz sentido quando há skills pra ele orquestrar, e skills só fazem sentido quando há substrato pra elas lerem.
🌱 Novo aqui?
Skill (em PT: habilidade) é um trabalho repetível escrito como receita, pra rodar igual toda vez. Ferramenta é um fio que liga o OS a uma fonte de dados real (um banco, um calendário, uma planilha). Agente é um "trabalhador" com um papel, que decide quais skills usar e em que ordem — e revisa antes de algo sair.
Como ler: a capacidade cresce da esquerda pra direita. O agente (caixa âmbar) contém as skills que orquestra e um portão de revisão. Por isso ele vem por último: sem skills dentro, ele não tem o que coordenar.
Por que aprender
Porque o erro nº1 de quem está animado é pular direto pros agentes — a parte "legal" — e montar um agente que não tem nenhuma skill pra usar. Saber a ordem te poupa de construir o telhado antes da parede. Você ganha capacidade real, camada por camada, em vez de uma casca vazia.
Conceitos-chave
🛠️ Skill = verbo conquistado (a mais repetida primeiro)
A analogia do coach: uma skill é uma ficha de receita. As primeiras vezes você cozinha "no olho"; depois anota a receita pra qualquer um repetir igual. Por isso você conquista uma skill — faz o trabalho à mão umas vezes e só então captura os passos. O coach começa por UMA skill: a sua tarefa mais repetida.
As perguntas que ele faz
Que tarefa você repete?
"...e gostaria que rodasse igual toda vez?" Essa é a candidata a primeira skill.
Como você faz à mão?
"Me mostre o passo a passo." É daqui que saem os passos da receita.
Como sabe que ficou bom?
Vira a linha "o que é um bom resultado" — o critério de qualidade da skill.
⚠️ O erro comum
Tentar escrever dez skills de uma vez, ou escrever uma skill para algo que você nunca fez à mão. Conquiste primeiro: faça o trabalho de verdade umas vezes, aí capture. Uma skill é a foto de um processo que já funciona, não um chute.
Por que aprender
Porque começar pela mais repetida dá o maior retorno com o menor risco. É a tarefa que você conhece de cor, então a receita sai precisa, e é a que mais economiza seu tempo depois. E o coach lembra: uma skill nunca está "pronta" — você vai melhorando a receita a cada uso.
Conceitos-chave
📂 Anatomia de skills/<nome>/SKILL.md
Quando você responde, o coach cria a pasta skills/ e, dentro dela, uma subpasta por skill com um SKILL.md simples. Ele captura três coisas: quando usar, os passos e o que é um bom resultado. Nada de jargão — é a sua receita, escrita pra você repetir.
Recriação ilustrativa — skills/checar-prazos/SKILL.md
# Checar prazos ## Quando usar Toda manhã, ou quando eu perguntar "o que vence?". ## Passos 1. Ler o tracker em substrate/compendium.md. 2. Calcular os prazos a partir de cada data. 3. Listar o que vence em 10 dias e o que já está atrasado. ## O que é um bom resultado Uma lista curta, com data e dias restantes, sem nenhum prazo esquecido.
🌱 Novo aqui?
No Claude Code, uma skill costuma virar um slash command — um atalho que você chama digitando /algo. O SKILL.md é o arquivo de texto que descreve essa skill: o harness o lê e passa a saber executar aquela receita quando você a invoca.
Por que aprender
Porque o done-check da camada é exatamente isto: um trabalho real e repetido, escrito como skill, com passos claros e uma linha de "bom resultado". Ver a anatomia te deixa reconhecer quando uma skill está completa — e quando ainda é só uma ideia solta.
Conceitos-chave
🔌 Ferramentas: o fio só-leitura
A camada 5 conecta o OS a fontes de dados reais. A analogia do coach é forte: uma ferramenta é uma janela pela qual o OS olha, não uma chave da casa inteira. Por padrão é só-leitura (read-only): pode ler, mas não pode mexer. E nenhum segredo (senha, chave) entra na pasta.
🌱 Novo aqui?
Read-only (só-leitura) significa que a conexão consegue ver os dados mas não consegue alterar nada. API é a "tomada" oficial de um serviço pra programas conversarem com ele; CLI é um comando de terminal que você roda; MCP é um conector pronto entre a IA e uma ferramenta. O coach te ajuda a escolher o caminho mais simples pra cada fonte.
Recriação ilustrativa — tools.md
# Tools # Cada fonte: pra quê, e nível de acesso. - Calendário — ler datas de entrega — só-leitura - Planilha — ler bookings — só-leitura - E-mail — rascunhar (não enviar) — só-leitura # Segredos (senhas/chaves) ficam FORA desta pasta.
✓ Padrão seguro
- ✓Só-leitura por padrão.
- ✓Segredos fora da pasta.
- ✓Escrita só onde for mesmo necessária.
✗ O erro comum
- ✗Dar escrita em tudo "por garantia".
- ✗Guardar senha dentro da pasta do OS.
- ✗Conectar fontes que o objetivo não pede.
Por que aprender
Porque escrita em tudo é o caminho mais curto pra um estrago irreversível. Só-leitura é a versão "olhar pela janela": o OS te dá respostas com dados reais sem o risco de bagunçar a fonte. O done-check é direto — toda fonte que o objetivo precisa está listada com seu nível de acesso, e nenhum segredo mora na pasta.
Conceitos-chave
🤖 Agente: papel com julgamento + portão de revisão
A analogia que fecha tudo: skills são as ferramentas da cozinha; o agente é o chef que sabe qual pegar e prova o prato antes de ele sair. Um agente é um papel com julgamento: decide quais skills usar e em que ordem, e roda uma checagem obrigatória antes de qualquer coisa ir pra fora. O coach só constrói um agente para uma rotina que você já faz à mão hoje.
Como ler: a tarefa entra, o chef encadeia skills, mas nada sai sem passar pelo portão de revisão. Esse portão é o que torna seguro delegar — não é o agente que decide sozinho o que publica.
Recriação ilustrativa — agents/<nome>/AGENT.md
# Gerente de entregas ## Papel Cuidar pra nenhuma entrega de cliente atrasar. ## Skills que orquestra - checar-prazos - rascunhar-aviso ## Portão de revisão (obrigatório) Nada vai a um cliente sem você ler e aprovar primeiro.
✓ Um agente
- ✓Tem UM papel claro.
- ✓Orquestra skills que já existem.
- ✓Tem um portão de revisão obrigatório.
✗ Agente "faz-tudo"
- ✗Quer resolver dez papéis de uma vez.
- ✗É construído antes de existir skill.
- ✗Deixa trabalho sair sem revisão.
Por que aprender
Porque o portão de revisão é o que separa "automação que ajuda" de "automação que assusta". Sem ele, um agente pode mandar algo errado pra um cliente. Com ele, você delega a coordenação mas mantém a palavra final. O done-check: uma rotina real, orquestrada, com um portão de revisão claro.
Conceitos-chave
🚦 Não pule etapas (e o "not started" honesto)
Duas travas de segurança guiam este módulo. Primeira: nunca um agente antes das skills que ele orquestraria existirem — você não é empurrado a construir o chef antes de ter as panelas. Segunda: se uma camada não se aplica ao seu objetivo ainda, o coach a marca como not started com uma linha de motivo, em vez de inventar trabalho inútil.
🧭 Quando marcar "not started"
- Tools — seu objetivo ainda só lê arquivos locais? Sem fonte externa, marque not started: "nenhuma fonte externa necessária ainda".
- Agents — você só tem uma skill? Não há o que orquestrar. Not started: "volte quando houver 2-3 skills encadeáveis".
- O sinal de honestidade: uma linha de motivo > uma pasta vazia fingindo trabalho.
💡 Dica prática
"Camada vazia" não é fracasso. Um OS honesto com 3 camadas sólidas e 3 marcadas not started vale mais que um OS com 6 camadas meia-boca. O coach prefere a verdade — e a auditoria do 4.6 também.
Por que aprender
Porque a tentação de pular pro agente é o erro nº1 — e o "not started" honesto é o antídoto contra o oposto: encher o OS de camadas falsas pra parecer completo. As duas travas juntas mantêm seu sistema real: só tem o que serve ao objetivo, e na ordem que aguenta o próximo passo.
Conceitos-chave
✅ Done-checks + copy-run
Cada uma das três camadas tem seu done-check. Você roda /os-coach next uma vez por camada, e o coach constrói o artefato e marca o status no memory.md.
Os três done-checks
- ✓Skills: um trabalho real e repetido virou skill com passos claros e uma linha de "bom resultado".
- ✓Tools: toda fonte que o objetivo precisa está listada com seu nível de acesso, e nenhum segredo na pasta.
- ✓Agents: uma rotina real, orquestrada, com um portão de revisão claro.
Objetivo: percorrer as três camadas de capacidade, uma de cada vez, deixando o coach construir cada artefato.
1) Abra a camada de Skills:
/os-coach next
Responda (troque pelos seus):
Tarefa que repito: <ex.: checar quais entregas vencem> À mão eu faço assim: <passo 1; passo 2; passo 3> Fica bom quando: <ex.: nenhuma data passa batida>
2) Rode de novo pra Tools; responda quais fontes e o acesso:
/os-coach next
Fontes: <ex.: calendário e planilha de bookings> → só-leitura
3) Rode de novo pra Agents (só se já tiver skills encadeáveis):
/os-coach next Rotina que encadeio à mão: <ex.: checar prazos e rascunhar o aviso> Revisão antes de sair: <ex.: eu aprovo todo aviso a cliente>
Como verificar: confira que existem skills/<nome>/SKILL.md e tools.md, e que o tools.md diz "só-leitura". Rode /os-coach status: camadas sem uso aparecem como not started com motivo, não como erro.
Por que aprender
Porque ao fim deste módulo seu OS tem capacidade real: pelo menos uma skill que roda igual, fios só-leitura para os dados de que precisa e, se fizer sentido, um agente com portão de revisão. É a hora certa de parar e pontuar tudo contra o objetivo — o que você faz no Módulo 4.6 com o audit.
Conceitos-chave
✅ Resumo do módulo
Próximo módulo:
4.6 — audit: pontuar contra o objetivo 📊