💡 O ponto de extensão mais importante do DeerFlow
Na Trilha 1 você aprendeu que skill é um dos pilares. Aqui você constrói uma. Skill mal-feita é invisível para o modelo (nunca é acionada) e skill bem-feita vira parte permanente do catálogo da sua organização. A diferença está quase toda na descrição.
📐 Anatomia de uma skill
Uma skill no DeerFlow é um diretório com três artefatos: SKILL.md (frontmatter YAML + corpo em Markdown), um conjunto opcional de tools/ em Python e, se necessário, references/ com arquivos de apoio. É texto puro, versionável, diff-able. Você revê skill como revê código.
🎯 Conceito Central
O frontmatter tem três campos obrigatórios: name, description e version. O resto do arquivo é a instrução que o modelo lê quando a skill é acionada. Nada mais. Se está ficando complexo, você provavelmente está tentando meter duas skills no mesmo arquivo.
- •name — kebab-case, único no registry (
brazilian-gov-research). - •description — 1-3 frases densas com gatilhos explícitos. É o que o modelo lê para decidir se aciona.
- •Corpo — instruções passo-a-passo do que fazer quando a skill é acionada. Bullet points, imperativo.
- •tools/ — funções Python com decorator
@tool. Opcional, só se a skill precisa de algo que não existe no harness.
📊 Números de uma skill saudável
- SKILL.md — 40-150 linhas. Acima disso, considere quebrar em duas.
- Descrição — 40-80 palavras. Abaixo falta sinal; acima dilui.
- Tools por skill — 0 a 5. Mais que isso é geralmente um custom agent disfarçado.
- Tempo total por turno — orçamento de 2-3s + tempo de IO das tools chamadas.
- Tokens injetados no prompt — corpo inteiro, quando acionada. Manter enxuto é economia real.
🪄 Meta-skill skill-creator
O DeerFlow já vem com uma meta-skill chamada skill-creator. Ela sabe criar skills novas — você descreve o que quer, ela gera o SKILL.md, cria o diretório e oferece 5 prompts de teste. É o caminho mais rápido para entrar no hábito certo de modelagem, e funciona exatamente como qualquer outra skill do catálogo (só tem um truque: ela sabe onde escrever arquivos).
Acionar com um pedido claro
No chat do DeerFlow: "Crie uma skill chamada brazilian-gov-research que cruza dados do IBGE com o Portal da Transparência." A skill-creator reconhece o gatilho e começa a fazer perguntas.
Responder às perguntas de escopo
Ela pergunta: qual é o gatilho típico? Quais tools usa? Qual é o formato de saída? Qual é o NOT-in-scope? Respostas curtas e concretas produzem skill melhor.
Revisar o draft gerado
A skill-creator escreve o SKILL.md e mostra o diff. Você revisa, ajusta a descrição (sempre a descrição), e aprova. Nunca aprove sem ler.
Rodar os prompts de teste
Ela gera 5 prompts: 2 que deveriam acionar a skill, 2 que não deveriam, 1 ambíguo. Se os dois positivos acionam e os dois negativos não, a descrição passou no smoke test.
Commit e revisão humana
Skill vai para o git como qualquer código. PR com diff de SKILL.md + evals. Reviewer lê a descrição primeiro, o corpo depois — a mesma ordem que o lead_agent usa.
💡 Quando não usar o skill-creator
Se você já tem uma skill parecida no catálogo, é mais rápido copiar e adaptar. O skill-creator é ótimo para primeira modelagem; não é mágico na iteração — a partir do draft inicial você edita direto.
🎯 Trigger accuracy: a arte da descrição
A pior coisa que acontece com uma skill é nunca ser acionada. A segunda pior é ser acionada quando não devia. As duas são problema de descrição, não de conteúdo. O modelo não lê o corpo da skill quando decide; ele lê a descrição. Então é nela que você investe.
✓ Fazer na descrição
- ✓Frases com gatilhos literais: "quando o usuário pedir dados de X".
- ✓Usar 3-5 sinônimos-chave para aumentar recall.
- ✓Explicitar o escopo positivo ("serve para") e negativo ("não serve para").
- ✓Exemplos concretos: "ex: IBGE, INEP, DataSUS, Portal da Transparência".
- ✓Manter sob ~80 palavras — mais que isso o modelo começa a diluir.
✗ Evitar na descrição
- ✗Vaguidades: "ajuda com dados" (que dados?).
- ✗Repetir o nome da skill no corpo — não adiciona sinal.
- ✗Frases de marketing ("a melhor forma de..."). Modelo ignora.
- ✗Cobrir dez casos de uso — vira recall baixo para todos.
- ✗Depender de contexto que o modelo não tem ("usa a base da empresa").
💡 Teste de qualidade em 30 segundos
Leia a descrição em voz alta e se pergunte: "Se eu fosse o lead_agent lendo 50 descrições, essa teria chance de vencer as outras para o meu caso?". Se a resposta for "sei lá", reescreva. Descrição campeã é a que tem gatilhos explícitos e escopo negativo.
✅ Testes e validação
Skill é código. Código tem teste. A diferença é que o "teste" aqui tem duas camadas: trigger eval (a skill é acionada quando deveria?) e output eval (quando acionada, o resultado está certo?). Ignorar qualquer uma produz skill que parece funcionar em demo e não em produção.
📊 Estrutura de um eval mínimo
- Trigger positive — 10 prompts que devem acionar. Meta: recall ≥ 90%.
- Trigger negative — 10 prompts ambíguos que não devem acionar. Meta: precision ≥ 90%.
- Output golden — 5 prompts positivos com output esperado escrito à mão. Roda em cada PR.
- Regression set — bugs já corrigidos viram tests para não voltarem.
- Latência-orçamento — máximo aceitável de tempo/tokens para skill concluir.
💡 Dica: eval não precisa ser pipeline fancy
Um script Python que roda 20 prompts contra o DeerFlow local e compara contra um JSON de expected já é 80% do valor. Ferramenta robusta vem quando a skill estiver em produção — antes é overengineering.
⚠️ Armadilha comum: "funcionou comigo"
A skill foi acionada numa demo e parece perfeita. Você não criou eval. Duas semanas depois, um colega diz que "a skill parou de funcionar" — na verdade nunca foi consistente, e sem baseline você não tem como provar nem o contrário.
Tratamento: no commit inicial da skill, um evals/<skill-name>.py com ao menos 10 casos. CI roda a cada PR. Passou a ser padrão de PR, não favor.
🧪 Lab: skill brazilian-gov-research
Construir uma skill real: cruzar dados do IBGE (indicadores socioeconômicos) com o Portal da Transparência (execução orçamentária). Quando o usuário pedir comparações do tipo "quanto o município X gastou em saúde versus sua população", a skill entra em ação.
Passos do lab
- 1.Criar diretório:
deerflow/app/skills/brazilian-gov-research/. Dentro dele, umSKILL.md, umtools/__init__.pye umreferences/endpoints.md. - 2.Escrever frontmatter + descrição:
--- name: brazilian-gov-research version: 0.1.0 description: | Cruza dados do IBGE (população, PIB, IDH, educação, saúde) com o Portal da Transparência federal (execução orçamentária, contratos, convênios). Aciona quando o usuário pedir comparações município/estado envolvendo indicadores sociais e gastos públicos brasileiros. Ex: "gasto per capita em saúde no RS", "cruzar IDH com investimento em educação em 2024". NÃO serve para dados internacionais ou privados. --- - 3.Escrever o corpo de instruções (imperativo, 1-2 parágrafos + checklist). Foco em: como consultar cada API, como normalizar códigos IBGE × códigos do Portal, como citar fonte no output.
- 4.Criar duas tools Python:
fetch_ibge(indicator, locality)efetch_transparencia(year, municipio, area). Ambas com decorator@tool, docstring clara (vira schema) e tratamento de 404. - 5.Registrar a skill: recarregar DeerFlow (
docker compose restart). No log de boot, confirme "skill loaded: brazilian-gov-research". - 6.Testar trigger: 4 prompts positivos ("gasto per capita em saúde de Florianópolis em 2024") e 4 negativos ("gasto público em Portugal"). Verifique no LangSmith qual skill foi acionada em cada um.
- 7.Iterar descrição: se algum positivo não acionou, a descrição está faltando um gatilho. Se um negativo acionou, está faltando escopo negativo. Repita.
💡 Entregável
Diretório da skill commitado + screenshots do LangSmith mostrando trigger correto em 4/4 positivos e 0/4 negativos. Bônus: um eval script em evals/brazilian-gov-research.py rodando os 8 prompts de forma automatizada.
📝 Resumo do Módulo
Próximo Módulo:
2.4 — 👥 Sub-agents e custom agents
Quando criar skill vs. custom agent. SOUL, RFC rfc-create-deerflow-agent e lab de security-auditor em canal Slack.