Mapa da trilha
Conteúdo detalhado
🧱 Skills e subagentes: o que são
As duas peças que transformam o Claude Code numa fábrica: skill (capacidade reutilizável sob demanda) e subagente (trabalho isolado, contexto próprio). Quando usar cada um e por que isso vira ativo.
Uma capacidade que o Claude Code carrega quando precisa: um arquivo SKILL.md com instruções e referências. Ensina uma vez, usa sempre que o gatilho disparar.
Cada tarefa repetida da Fábrica (diagnosticar, gerar doc) vira skill. Você para de re-explicar e ganha consistência.
Sob demanda · SKILL.md · reutilização · gatilho por description.
Uma instância separada do Claude com janela de contexto própria, prompt de sistema e ferramentas. Recebe uma tarefa, trabalha sozinho e devolve só o resultado.
Pesquisar uma empresa enche o contexto. Um subagente isola essa bagunça e te entrega só o essencial — o pai não suja.
Contexto isolado · system prompt · ferramentas próprias · retorna resumo.
Skill = uma habilidade que o agente principal ganha (gerar PPTX). Subagente = um trabalhador separado para uma missão que consome muito contexto (varrer a web).
Escolher errado custa contexto e tempo. A regra simples evita sobre-engenharia.
Habilidade vs delegação · custo de contexto · "no mesmo fio" vs "fio separado".
Um arquivo SKILL.md com frontmatter (name + description) no topo e o corpo em Markdown com os passos. A description é o que faz a skill disparar.
Escrever a description certa decide se a skill é usada. É a peça mais importante e a mais ignorada.
Frontmatter · name · description-gatilho · corpo com passos.
Skills ficam em .claude/skills/ (do projeto) ou ~/.claude/skills/ (pessoais). Subagentes ficam em .claude/agents/. Cada um numa pasta com seu arquivo.
Saber o lugar é o que faz o Claude Code achar o recurso. Pessoal = vale em todo projeto; do projeto = vai junto no repo.
.claude/skills · .claude/agents · escopo projeto vs pessoal.
Cada skill e agente é uma peça que você constrói uma vez e reusa sempre. Juntas, formam a engrenagem da Fábrica — seu arsenal.
É a tese "entrada mínima, saída máxima" virando código. O esforço fica na construção, não na entrega.
Ativo reutilizável · composição · arsenal · custo marginal quase zero.
🎯 Construa sua primeira skill (diagnostico-ia)
Do gatilho ao empacotamento: definir a description que dispara, escrever o corpo determinístico, anexar os cheat sheets da T2, testar, iterar e versionar. No fim, uma skill cuspindo um mini-diagnóstico.
A description do frontmatter descreve quando usar a skill. "Use ao diagnosticar a maturidade de IA de uma empresa descrita em texto."
Se a description for vaga, a skill nunca dispara. Boa description = bons verbos + gatilhos concretos.
Gatilho · verbos de ação · "use quando" · especificidade.
O corpo em Markdown lista os passos: ler a empresa, pontuar maturidade 1-5, listar 3 quick wins, sugerir roadmap 30/60/90.
Passos numerados e específicos dão saída repetível. Vago gera resultado diferente toda vez.
Passos numerados · determinismo · formato de saída fixo.
A skill aponta para arquivos de apoio (os cheat sheets de maturidade e quick wins que você destilou na T2), carregados só quando precisa.
Referências dão o rigor de consultoria à skill sem inchar o SKILL.md. RAG preguiçoso aplicado.
Arquivos de apoio · carregamento sob demanda · contexto enxuto.
Rodar a skill com uma empresa de verdade e checar: ela disparou sozinha? A saída tem maturidade, quick wins e roadmap?
Teste com caso real revela se a description dispara e se a saída serve. Sem isso é só teoria.
Caso de teste · disparo · checagem de saída.
Ajustar a description e os passos com base no teste, fechar a pasta da skill (SKILL.md + referências) e deixá-la pronta para uso.
A primeira versão raramente acerta. Iterar é o trabalho real; empacotar é o que a torna ativo.
Iteração · pasta da skill · pronto para reuso.
Versionar a skill no Git (junto ao projeto) e, se quiser, compartilhar com o time ou na comunidade. Histórico = evolução rastreável.
Versionar protege seu ativo e deixa melhorar sem medo. Compartilhar gera autoridade.
Git · versão · compartilhar · ativo durável.
📄 A skill de documentos (DocX/PPTX/Excel/PDF)
Os entregáveis chiques não saem de Markdown: saem de Python. python-docx, python-pptx, openpyxl (com convenção de cores) e reportlab — embrulhados na skill gerar-entregavel. Markdown entra, .docx e .pptx saem.
O cliente abre .docx, .pptx, .xlsx e .pdf — não Markdown cru. Gerar via código deixa tudo formatado, repetível e com a sua marca.
É o que faz o pacote parecer consultoria de elite. Sem isso, o entregável morre no editor de texto.
Entregável final · formatação · repetível · marca.
A biblioteca que cria .docx: Document(), add_heading, add_paragraph, add_table e runs com cor/negrito. Gera o relatório e o SOW.
Relatório final e SOW são entregáveis Word. Dominar docx é gerar os dois sem trabalho manual.
Document · headings · tabelas · runs formatados.
Presentation(), slides por layout (0 título, 6 branco), textboxes, bullets e RGBColor para cores. Gera o deck executivo.
O deck é o que fecha a venda (T5). Cuidado com a pegadinha: é RGBColor, não RgbColor.
Layouts · textboxes · RGBColor · deck executivo.
Cria .xlsx com fórmulas reais (nunca valores fixos) e a convenção de cores: azul = input, preto = fórmula, verde = link, vermelho = externo, amarelo = premissa.
A calculadora de ROI vive em Excel. Fórmulas + cores certas deixam o cliente confiar e editar premissas.
Fórmulas vs valores · indexação 1-based · convenção de cores · ROI.
O método Platypus monta um story de elementos (Paragraph, Spacer, Table) e fecha com doc.build(story). Gera PDFs prontos para enviar.
PDF é o formato universal de entrega. Platypus dá controle de estilo sem mexer em coordenadas.
Platypus · story · build no fim · estilos.
Embrulhar as quatro bibliotecas numa skill: "dado um Markdown, gere o .docx/.pptx/.xlsx/.pdf correspondente". Uma referência única para todo o pacote.
Vira o motor de saída da Fábrica. Markdown entra de qualquer prompt; arquivo profissional sai.
gerar-entregavel · wrapper · Markdown → arquivo · motor de saída.
🕵️ Construa seu subagente (pesquisador & redator)
Dois trabalhadores isolados: o pesquisador-empresa coleta contexto estruturado, o redator-estrategia rascunha o entregável. Saída em schema confiável, orquestrados com a skill — e quando vale paralelizar.
Um arquivo de agente: frontmatter (name/description), prompt de sistema (quem ele é), ferramentas liberadas e o formato de saída que deve devolver.
Definir bem essas quatro partes é o que separa um agente útil de um que devolve texto solto.
System prompt · ferramentas · saída esperada · escopo.
Um subagente que recebe nome + descrição da empresa, pesquisa e devolve um CompanyContext: setor, stack, dores, concorrentes e iniciativas de IA.
É a Fase 1 da Fábrica virando trabalhador. Isola a pesquisa pesada e devolve só o contexto limpo.
CompanyContext · pesquisa isolada · saída estruturada.
Recebe o CompanyContext + um framework (ex.: quick wins) e escreve o entregável em Markdown, pronto para a skill gerar-entregavel formatar.
Separa pesquisa de escrita. Cada agente faz uma coisa bem — fica fácil de testar e melhorar.
Contexto + framework → rascunho · separação de papéis.
Pedir ao agente que devolva JSON num formato fixo (um schema). Como o CompanyInput/ResearchOutput da arquitetura: campos previsíveis.
Saída estruturada é o que permite encadear agentes. Texto solto quebra o pipeline; schema, não.
Schema · JSON previsível · encadeável · contrato.
O agente principal chama o pesquisador-empresa, passa o contexto ao redator-estrategia e usa a skill gerar-entregavel para fechar o arquivo.
É a Fábrica em miniatura: pesquisa → redação → documento. Orquestrar é o trabalho do construtor.
Orquestração · encadeamento · pipeline pesquisa→redação→doc.
Disparar vários subagentes ao mesmo tempo quando as tarefas são independentes — ex.: pesquisar 3 empresas em paralelo, sem estado compartilhado.
Paralelizar tarefas independentes economiza tempo. Mas se uma depende da outra, é sequencial — saber a diferença evita bug.
Paralelo vs sequencial · independência · sem estado compartilhado.