Caminho	Score	Stages executados
Fast	<= 0	Triage → Stage C (identico ao v2)
Medium	1-2	Triage → Stage A abreviado (niveis 1-3) → Stage C
Deep	>= 3	Triage → Stage A completo → Stage B → Stage C

Principios Fundamentais

Qualidade embutida, nao parafusada — rigor em cada fase, nao so no final
Teste antes de refinar — evals empiricos antes de mudancas subjetivas
Se o Claude ja sabe fazer, nao incluir — evitar bloat de instrucoes
Explique o porque, nao so o que — LLMs respondem melhor a raciocinio do que a regras
Generalize, nao sobreajuste — skills que funcionam para muitos prompts, nao so para os testes
Rigor epistemico — distinguir fato validado de opiniao popular; classificar certeza por nivel
Extracao de metodologia — transformar conhecimento em processos replicaveis, nao em resumos

Triage Gate

Classificar a complexidade do dominio ANTES de construir. Executar o Triagista (agents/triagista.md) ou scripts/forge_triage.py.

Tabela de Sinais

Sinal	Score	Como detectar
Documentacao oficial acessivel	-1	Existe docs.X.com, man pages, spec oficial publica
Usuario diz "skill simples"	-1	Usuario explicita que e algo simples/rapido
APIs recentes/mutaveis	+1	API mudou nos ultimos 12 meses, deprecations frequentes
Contradicoes conhecidas no dominio	+2	Respostas diferentes em fontes diferentes
Claude ja errou nesse dominio	+2	Usuario reporta que IA errou 2+ vezes nesse topico
Conhecimento especializado ausente	+2	Dominio de nicho, praticas nao-documentadas
Output de alto risco	+2	Seguranca, financeiro, medico — erro tem consequencia real

Arvore de Decisao

Somar scores de todos os sinais aplicaveis
├── Score <= 0 → Fast Path (direto pro Stage C)
├── Score 1-2 → Medium Path (Stage A abreviado → Stage C)
└── Score >= 3 → Deep Path (Stage A completo → Stage B → Stage C)

Overrides:

Usuario pede "estudo profundo" → Deep Path independente do score
Usuario pede "rapido, sem estudo" → Fast Path independente do score
Na duvida entre Fast e Medium → Medium
Na duvida entre Medium e Deep → Deep

Apresentar resultado ao usuario: "Classifiquei como [path] porque [razoes]. Quer seguir assim?"

Detalhes e exemplos praticos: references/guia-triage.md

Stage A: Estudo de Dominio

Executado no Medium Path (abreviado) e Deep Path (completo).

Protocolo completo: references/protocolo-estudador.md. Agente: agents/triagista.md (triagem) seguido de estudo direto.

Resumo dos 7 Niveis

Diagnostico de Lacuna — classificar tipo de erro/incerteza
Hierarquia de Fontes — Ouro (primaria) > Prata > Bronze > Ferro > Chumbo
Triangulacao — 3+ fontes independentes; ativar Modo de Contradicao se divergencia
Escavacao Sistemica — leitura integral de docs, issues, changelogs
Busca por Ausencia — onde a evidencia DEVERIA estar e nao esta
Sintese — Mapa de Conhecimento + Manual Operacional + Pacote Especialista
Monitoramento — fontes a vigiar, gatilhos de reabertura

Modo Abreviado (Medium): Executar apenas niveis 1-3. Pular niveis 4-7.

Output: Study Bundle em workspace/stage-a-study/<data>/<tema>/ com index.json e 9 arquivos. Schemas: references/formatos-intermediarios.md

Stage B: Dissecacao de Processo

Executado apenas no Deep Path. Requer Study Bundle do Stage A como input.

Protocolo completo: references/protocolo-dissector.md. Agente: agents/dissector.md.

Resumo das 8 Fases

Recepcao — ler index.json, validar completude do Study Bundle
Mapeamento Estrutural — claims por nivel de certeza, marcos de desenvolvimento
Conhecimento Tacito — padroes implicitos, regras invisiveis para iniciantes
Arquitetura Conceitual — hierarquias de ideias e dependencias
Contexto e Continuidade — fio condutor, evolucao gradual vs saltos
Formalizacao de Tecnica — praticas validadas em metodos step-by-step
Modelo Replicavel — process map, principios operacionais, ferramentas
Padroes Metalinguisticos — terminologia essencial e antipadroes

Output: Dissection Package em workspace/stage-b-dissection/ com 5 arquivos + dissection-manifest.json. Schemas: references/formatos-intermediarios.md

Stage C: Construcao da Skill (Forge)

Identico ao v2 no Fast Path. Enriquecido pelos Stages A/B no Medium e Deep Path.

Fase 1: Descoberta Profunda

Coletar exemplos concretos antes de construir:

Minimo 3 casos de uso reais e validados
Triggers de ativacao: quando exatamente essa skill deve ativar?
Outputs esperados: formato, estrutura e conteudo
Ferramentas necessarias: quais tools do Claude
Templates: formatos fixos de output
Erros comuns: armadilhas que o Claude deve evitar
Conhecimento de dominio: o que um especialista saberia que o Claude nao sabe
Edge cases: inputs invalidos, vazios, ambiguos

Enriquecimento Deep: O dissection-manifest.json pre-popula a descoberta. A entrevista com o usuario vira CONFIRMACAO dos dados extraidos, nao coleta do zero. Usar --from-dissection no forge_init.py.

Fase 2: Analise de Recursos

Se o Claude ja sabe fazer algo naturalmente, NAO incluir na skill. So incluir o que e especifico, nao-obvio ou facil de errar.

O que e?	Onde vai?	Quando incluir?
Codigo executavel	`scripts/`	Validacao, automacao, calculos
Documentacao tecnica	`references/`	Dominio especializado, padroes
Templates de output	`assets/`	Formatos fixos, boilerplates
Instrucoes de processo	`SKILL.md` corpo	Sempre — e o core
Avisos e armadilhas	`SKILL.md` corpo	Erros que o Claude comete sem orientacao

Enriquecimento Deep: Os niveis de certeza do Study Bundle informam a Regra de Ouro. Claims Strong Probable ou acima = SEMPRE incluir na skill. Claims Popular sem Validacao = incluir como WARNING explicito. Claims Indeterminado = excluir ou marcar como julgamento do usuario.

Fase 3: Arquitetura

Selecionar padrao arquitetural. Consultar references/arquiteturas.md.

As etapas sao sequenciais e obrigatorias?
├── Sim → Fluxo de Trabalho
└── Nao → As operacoes sao independentes?
    ├── Sim → Baseado em Tarefas
    └── Nao → E sobre padroes/regras?
        ├── Sim → Referencia e Diretrizes
        └── Nao → Baseado em Capacidades

Enriquecimento Deep: O skill_recommendations.architecture_pattern do manifest pre-seleciona a arquitetura. Validar pela arvore de decisao acima. Se divergir, justificar e escolher o mais adequado.

Fase 4: Implementacao

Inicializar com forge_init.py:

python3 scripts/forge_init.py nome-da-skill                              # instala global (~/.claude/skills/)
python3 scripts/forge_init.py nome --local                               # instala no projeto atual (.claude/skills/)
python3 scripts/forge_init.py nome --path /caminho/custom                # caminho customizado
python3 scripts/forge_init.py nome --pipeline-mode deep                  # com workspace de pipeline
python3 scripts/forge_init.py nome --from-dissection manifest.json       # pre-populado via dissecacao

Default: Sem --path ou --local, instala em ~/.claude/skills/ (global). Skills globais sao auto-descobertas pelo Claude Code em qualquer projeto, sem necessidade de referencia em CLAUDE.md. Usar --local apenas quando a skill for especifica de um unico projeto.

Caminhos por OS: macOS/Linux: ~/.claude/skills/. Windows: %USERPROFILE%\.claude\skills\.

Escrever SKILL.md: frontmatter (name + description ate 1024 chars) + corpo (max 500 linhas). Usar voz imperativa. Consultar references/frontmatter-exemplos.md.

Enriquecimento Deep: O corpo da skill e escrito a partir de: 01-process-map.md (esqueleto do workflow), 02-operational-principles.md (principios), antipadroes do manifest (secao "Nao Faca"). Claims com claude_knows: false do manifest DEVEM estar no SKILL.md.

Fase 5: Avaliacao & Benchmark

Criar 2-3 prompts realistas em evals/evals.json
Rodar evals A/B: forge_eval.py --skill-path X --evals Y
Avaliar com agentes: Avaliador, Comparador, Analisador
Agregar benchmark: forge_benchmark.py --workspace X --iteration N
Gerar visualizador: forge_report.py --workspace X --iteration N
Otimizar description (opcional): forge_optimize.py --skill-path X --iterations 5

Enriquecimento Deep: Assertions do evals.json sao semeadas por 05-validation-tests.md do Dissection Package. Adicionar metrica knowledge_accuracy (ver secao abaixo). Rodar: forge_knowledge_accuracy.py --skill-path X --study-bundle Y

Fase 6: Iteracao

Melhorar com base em padroes, nao em exemplos individuais
Se um problema aparece em 1 eval, pode ser edge case
Se aparece em 2+ evals, e padrao que precisa de correcao
Parar quando: usuario satisfeito, feedbacks vazios, ou pass rate estabilizado
Empacotar: forge_package.py caminho/skill --output dist/

Enriquecimento Deep: Na iteracao, e possivel voltar ao Stage A para re-estudar um sub-topico especifico que falhou nos evals. Isso gera um Study Bundle parcial que alimenta uma nova rodada do Forge sem refazer o pipeline inteiro.

Deploy em Projetos

Apos criar/atualizar o Skill Forge, propagar para projetos que o usam:

# Deploy em um projeto especifico
python3 scripts/forge_deploy.py --project /caminho/projeto --git-push

# Re-deploy em todos os projetos registrados
python3 scripts/forge_deploy.py --all --git-push

# Simular antes de executar
python3 scripts/forge_deploy.py --project /caminho/projeto --dry-run

# Listar projetos registrados
python3 scripts/forge_deploy.py --list

# Instalar triggers no CLAUDE.md global (pos-instalacao)
python3 scripts/forge_deploy.py --setup

O deploy automatiza: (1) injecao da secao SKILL FORGE no CLAUDE.md do projeto, (2) adicao de skills: [skill-forge] nos agentes construtores, (3) git commit + push. Registro em workspace/deploy-registry.json.

O --setup injeta os triggers de ativacao (frases como "crie uma skill", "extraia metodo", "transforme em processo") no ~/.claude/CLAUDE.md global, garantindo ativacao automatica com 100% de certeza. Deve ser rodado uma vez apos instalar o Skill Forge.

Fast Path (Score <= 0)

Quando o dominio e simples e bem documentado, pular Stages A e B. Executar diretamente:

Fase 1 (Descoberta) → 2. Fase 2 (Analise) → 3. Fase 3 (Arquitetura) → 4. Fase 4 (Implementacao) → 5. Fase 5 (Avaliacao) → 6. Fase 6 (Iteracao)

Identico ao Skill Forge v2. Sem estudo de dominio, sem dissecacao.

Metrica: knowledge_accuracy

Compara o output da skill contra claims validados do Study Bundle (Stage A).

Calculo:

knowledge_accuracy = claims_corretos_no_output / claims_validados_no_bundle

Niveis:

= 0.90: Excelente — skill reproduz conhecimento validado com fidelidade
0.70-0.89: Aceitavel — revisar claims nao cobertos
< 0.70: Insuficiente — requer re-estudo ou reescrita

Executar: forge_knowledge_accuracy.py --skill-path X --study-bundle Y

Aplicavel apenas em Medium e Deep paths (Fast Path nao tem Study Bundle).

Adaptacao por Ambiente

Ambiente	Subagentes	Evals A/B	Visualizador	Otimizacao
Claude Code (CLI)	Paralelos	Completo	HTML no browser	Via `claude -p`
Claude.ai (Web)	Nao	Sequencial, sem baseline	Inline no chat	Manual
Cowork (Headless)	Sim	Completo	`--static` HTML	Via subprocess

Antipadroes

Antipadrao	Por que e ruim	Fazer em vez disso
Descriptions vagas	Claude nao sabe quando ativar	Incluir cenarios concretos e formatos de arquivo
Explicar conceitos basicos	Desperdica tokens de contexto	So incluir conhecimento especifico do dominio
Instrucoes com "pode" ou "talvez"	Cria ambiguidade	Usar imperativo: "Fazer X"
Duplicar info entre arquivos	Inconsistencia e bloat	Uma fonte de verdade por conceito
Scripts nao testados	Falhas em producao	Testar com inputs variados antes de incluir
Sobreajustar para testes	Skill falha com prompts reais	Generalizar a partir de padroes
SKILL.md > 500 linhas	Consome contexto excessivo	Mover detalhes para references/
Pular a Fase 5	"Funciona" nao e evidencia	Rodar evals A/B para validar
Tratar opiniao como fato	Skill propaga erros	Classificar certeza por nivel (Ouro/Prata/Bronze)
Resumir em vez de extrair	Conhecimento nao-acionavel	Extrair metodologia replicavel com steps concretos

Referencia de Scripts

Script	Proposito	Uso
`forge_init.py`	Scaffolding de nova skill	`forge_init.py nome [--path destino] [--local] [--pipeline-mode X] [--from-dissection Y]`
`forge_validate.py`	Validacao estrutural + pipeline	`forge_validate.py caminho --verbose`
`forge_analyze.py`	Analise de skill existente	`forge_analyze.py caminho`
`forge_eval.py`	Executar evals A/B	`forge_eval.py --skill-path X --evals Y`
`forge_benchmark.py`	Agregar benchmarks + pipeline metadata	`forge_benchmark.py --workspace X --iteration N`
`forge_optimize.py`	Otimizar description	`forge_optimize.py --skill-path X --iterations 5`
`forge_report.py`	Gerar visualizador HTML	`forge_report.py --workspace X --iteration N`
`forge_package.py`	Empacotar .skill	`forge_package.py caminho --output dist/`
`forge_deploy.py`	Deploy em projetos	`forge_deploy.py --project X [--git-push] [--dry-run] [--all] [--list]`
`forge_triage.py`	Triage Gate scorer	`forge_triage.py --topic X --signals Y --output Z`
`forge_pipeline.py`	Orquestrador do pipeline completo	`forge_pipeline.py --topic X --path fast\|medium\|deep`
`forge_knowledge_accuracy.py`	Comparar output vs claims validados	`forge_knowledge_accuracy.py --skill-path X --study-bundle Y`
`estudador_save_bundle.py`	Salvar Study Bundle no workspace	`estudador_save_bundle.py --tema X --output Y`
`estudador_normalize_sources.py`	Normalizar fontes para formato padrao	`estudador_normalize_sources.py --input X --output Y`
`dissector_extract.py`	Extracao auxiliar de dissecacao	`dissector_extract.py --bundle X --output Y`
`dissector_validate.py`	Validar Dissection Package	`dissector_validate.py --manifest X --verbose`

Referencia de Agentes

Agente	Proposito	Input	Output
`triagista.md`	Classificar complexidade do dominio	Descricao + contexto	`triage.json`
`dissector.md`	Extrair metodologia replicavel	Study Bundle	Dissection Package + `dissection-manifest.json`
`avaliador.md`	Grading de assertions	Output + assertions	`grading.json`
`comparador.md`	Comparacao cega A/B	Dois outputs anonimos	`comparison.json`
`analisador.md`	Analise pos-comparacao	Winner/loser + transcricoes	`analysis.json`

Referencia de Documentos

Documento	Conteudo
`references/arquiteturas.md`	4 padroes arquiteturais com arvore de decisao
`references/checklist-qualidade.md`	Checklist de validacao em 8 categorias
`references/frontmatter-exemplos.md`	3 formulas comprovadas de description
`references/padroes-codigo.md`	8 padroes para documentar codigo
`references/schemas.md`	Schemas JSON para todos os dados
`references/protocolo-estudador.md`	Protocolo completo do Stage A (7 niveis)
`references/protocolo-dissector.md`	Protocolo completo do Stage B (8 fases)
`references/guia-triage.md`	Guia de triagem com exemplos praticos
`references/formatos-intermediarios.md`	Schemas de handoff entre stages

skill-forge

Skill Forge v3

Pipeline