📦 Anatomia de uma Skill
Skill é uma pasta com convenção: SKILL.md como manual, references/ com profundidade, scripts/ com utilitários executáveis. Estrutura previsível faz outra IA carregar e usar sem você precisar explicar.
📁 Estrutura de pastas
novo-vertical/
├── SKILL.md ← manual + frontmatter (curto)
├── references/
│ ├── verticals.md ← detalhe por nicho (lazy load)
│ ├── prompts-base.md ← biblioteca de prompts
│ └── checklist.md ← validação pós-clone
├── scripts/
│ ├── clone-inboxai.sh ← clona repo base
│ ├── apply-vertical.js ← aplica config do nicho
│ └── smoke-test.sh ← valida SaaS clonado
└── examples/
├── clinica.json ← input exemplo
└── imobiliaria.json
📌 Por que essa convenção
Quando outro agente (ou outra IA) encontra uma pasta com SKILL.md, ele sabe imediatamente como navegar: lê o manual, segue links para references quando precisar de detalhe, executa scripts quando precisa de ação. Sair do padrão sem motivo quebra essa interoperabilidade — e seu trabalho não compõe com o ecossistema.
📜 Frontmatter: name, description, when_to_use
O frontmatter YAML no topo do SKILL.md é o gatilho de carregamento. Description vaga = skill nunca invocada. Description precisa = skill resolve sozinha.
📄 SKILL.md — exemplo bom
---
name: novo-vertical
description: |
Clona o InboxAI base e customiza para um nicho específico
(clínica, imobiliária, advocacia, e-commerce). Use quando o
usuário pedir "criar SaaS para clínica", "fazer InboxAI da
imobiliária X", ou similar — qualquer pedido que combine
"novo cliente" + "vertical" + "white-label".
when_to_use: |
- Usuário menciona criar SaaS para nicho específico
- Pedido envolve white-label do InboxAI
- Briefing inclui nome de cliente + setor (clínica, etc.)
when_NOT_to_use: |
- Apenas customizar features de um cliente existente
- Criar produto do zero sem base InboxAI
allowed-tools: Bash, Read, Write, Edit
---
# Skill: novo-vertical
Esta skill executa o fluxo de white-label em 4 passos:
1. Clonar repo base (`scripts/clone-inboxai.sh`)
2. Aplicar config do vertical (`scripts/apply-vertical.js`)
3. Smoke test (`scripts/smoke-test.sh`)
4. Abrir PR no novo repo do cliente
Para detalhes por vertical, ver `references/verticals.md`.
✅ Description boa
"Clona InboxAI e customiza para nicho. Use quando usuário pedir 'criar SaaS para clínica'..."
Tem exemplos de gatilhos verbais.
❌ Description ruim
"Skill para criar SaaS rapidamente."
Vago demais — IA não sabe quando invocar.
🪜 Progressive Disclosure (Não Inflar Contexto)
SKILL.md curto com a essência. References/ com profundidade que só carrega quando necessário. Skill grande inflada queima tokens à toa em toda invocação.
📊 Token Budget — comparação
✂️ O que vai onde
- SKILL.md — visão geral em 1–2 páginas, frontmatter, links para references.
- references/ — detalhes por caso, tabelas longas, listas extensas, troubleshooting.
- scripts/ — código executável; ações concretas em vez de descrição.
- examples/ — inputs/outputs reais; valem mais que mil palavras de explicação.
🎯 Skill Autoral: novo-vertical (construída ao vivo)
A skill que multiplica a fábrica: recebe nome do nicho, clona o InboxAI base, customiza textos, prompts e branding, valida com smoke test e abre PR no repo do cliente.
🔧 scripts/clone-inboxai.sh
#!/usr/bin/env bash
set -euo pipefail
VERTICAL="${1:?vertical e obrigatorio (clinica|imobiliaria|advocacia|ecommerce)}"
CLIENT_NAME="${2:?nome do cliente e obrigatorio}"
SLUG=$(echo "$CLIENT_NAME" | tr '[:upper:] ' '[:lower:]-')
echo "→ Clonando InboxAI base para inboxai-${SLUG}..."
gh repo create "inema/inboxai-${SLUG}" --private --template inema/inboxai-base --clone
cd "inboxai-${SLUG}"
echo "→ Aplicando vertical: ${VERTICAL}"
node ../scripts/apply-vertical.js --vertical "${VERTICAL}" --slug "${SLUG}"
echo "→ Smoke test..."
bash ../scripts/smoke-test.sh
echo "✅ Pronto. Repo: inema/inboxai-${SLUG}"
🔧 scripts/apply-vertical.js
const fs = require('fs');
const path = require('path');
const verticals = {
clinica: {
title: 'InboxAI Clínica',
primaryColor: '#0f766e',
prompts: 'agendamento de consulta, lembrete, confirmação',
integrations: ['google-calendar', 'whatsapp']
},
imobiliaria: {
title: 'InboxAI Imóveis',
primaryColor: '#7c2d12',
prompts: 'qualificação de lead, agendamento de visita',
integrations: ['hubspot', 'whatsapp']
},
advocacia: {
title: 'InboxAI Jurídico',
primaryColor: '#1e3a8a',
prompts: 'triagem de caso, follow-up de cliente',
integrations: ['email', 'whatsapp']
},
ecommerce: {
title: 'InboxAI Pós-Venda',
primaryColor: '#9f1239',
prompts: 'confirmação de pedido, rastreamento, NPS',
integrations: ['shopify', 'whatsapp']
}
};
const args = require('minimist')(process.argv.slice(2));
const config = verticals[args.vertical];
if (!config) throw new Error(`Vertical desconhecido: ${args.vertical}`);
fs.writeFileSync('vertical.config.json', JSON.stringify({ ...config, slug: args.slug }, null, 2));
console.log(`✓ vertical.config.json gerado para ${args.vertical}`);
🚀 O efeito na fábrica
Sem essa skill: cada novo cliente exige 2 dias de trabalho manual de clonagem e customização. Com ela: 2 horas e o resto vira atendimento ao cliente. Multiplicador direto: 10x em throughput de novos clientes por semana.
🌍 Compartilhando Skills
Skills úteis viram lead inbound de clientes que descobriram seu trabalho. Há três caminhos para distribuir, cada um com trade-off de alcance vs controle.
| Canal | Alcance | Controle | Quando usar |
|---|---|---|---|
| Plugin privado | Sua org / clientes | Total | IP sensível, lógica de negócio |
| Repo público GitHub | Médio (quem buscar) | Alto (você decide) | Marketing inbound |
| Loja oficial OpenAI | Alto (curado) | Médio (revisão) | Skill polida, genérica |
📋 Checklist antes de publicar
✨ Boas Práticas de Design de Skill
Skill que tenta fazer "tudo" não faz nada bem. Aderir aos padrões aumenta a probabilidade de o agente invocá-la corretamente e da skill envelhecer bem.
🎯 Foco único
Uma responsabilidade clara. "novo-vertical" clona+customiza; não treina equipe nem gera contrato.
📛 Naming verbo+objeto
novo-vertical, scan-vulnerabilidade, relatorio-vendas — não vertical-helper.
📚 Examples na descrição
Frases-gatilho concretas. Ajudam outras IAs a decidir invocar.
🔁 Scripts idempotentes
Rodar 2x não causa estrago. Cheque "já existe?" antes de criar.
🪶 Deps mínimas
Bash, Node, gh CLI — sem framework exótico que falha em ambiente novo.
🧪 Smoke test pós-uso
A skill termina validando que o output funciona. Sem isso, errors silenciam.
💡 Skill é patrimônio
Cada skill bem desenhada é tempo recuperado para sempre. Em 6 meses, você terá 5–8 skills cobrindo seus processos repetidos. Outro agente novo entra na sua "fábrica" e produz ao seu nível em 1 dia — porque o conhecimento está nas skills, não na sua cabeça. Esse é o ativo de longo prazo do diretor de agentes.
✅ O que Aprendemos
Próximo Módulo:
6.4 — O Método: 1 Micro-SaaS por Semana. Pesquisa de nicho, white-label, precificação por valor e a aritmética que leva 10 clientes a R$ 15k/mês.