diff --git a/README.md b/README.md
index 9c29878..2597985 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,8 @@ It explains how to combine a strong planning/review model with faster workers,
reusable skills, subagent handoffs, Git worktrees, and explicit verification.
An interactive field kit compares common behavior skills such as
`ponytail-lite`, `caveman`, `unlazy`, research, debugging, and review.
+The skill-forge workflow covers discovery, triggers, package anatomy,
+progressive instructions, structural validation, and behavioral iteration.
## Run locally
diff --git a/app.js b/app.js
index 71880b6..b17f13a 100644
--- a/app.js
+++ b/app.js
@@ -28,6 +28,13 @@ const interactiveCopy = {
scripts: { icon: '›_', title: 'scripts/', en: 'Deterministic checks and repeated operations. Prefer executable proof over prose.', pt: 'Verificações determinísticas e operações repetidas. Prefira prova executável a prosa.' },
assets: { icon: '▧', title: 'assets/', en: 'Templates and examples the agent can copy without reinventing the expected shape.', pt: 'Templates e exemplos que o agente pode copiar sem reinventar o formato esperado.' }
},
+ skillWorkflow: {
+ observe: { number: '01', title: { en: 'Start from repeated friction', pt: 'Comece pelo atrito repetido' }, question: { en: 'Which non-obvious decision keeps being rediscovered?', pt: 'Qual decisão não óbvia continua sendo redescoberta?' }, action: { en: 'Collect two or three realistic requests. Separate durable judgment from one project’s temporary details.', pt: 'Colete dois ou três pedidos realistas. Separe julgamento durável dos detalhes temporários de um projeto.' }, output: { en: 'A narrow capability and concrete examples.', pt: 'Uma capacidade estreita e exemplos concretos.' }, proof: { en: 'Without the skill, agents repeatedly make the same avoidable mistake.', pt: 'Sem a skill, agentes repetem o mesmo erro evitável.' } },
+ trigger: { number: '02', title: { en: 'Make discovery precise', pt: 'Torne a descoberta precisa' }, question: { en: 'When should this load—and when should it stay out?', pt: 'Quando isto deve carregar — e quando deve ficar de fora?' }, action: { en: 'Choose a short action-oriented name. Write a discriminating description that names the task and meaningful boundary.', pt: 'Escolha um nome curto orientado à ação. Escreva uma descrição discriminante que nomeie a tarefa e seu limite.' }, output: { en: 'YAML name + description in SKILL.md.', pt: 'Nome + descrição YAML em SKILL.md.' }, proof: { en: 'Relevant prompts select it; nearby unrelated prompts do not.', pt: 'Prompts relevantes selecionam; prompts próximos mas não relacionados, não.' } },
+ scaffold: { number: '03', title: { en: 'Choose only useful anatomy', pt: 'Escolha apenas a anatomia útil' }, question: { en: 'What must be instructions, executable, consulted, or copied?', pt: 'O que deve ser instrução, executável, consultado ou copiado?' }, action: { en: 'Keep shared guidance in SKILL.md. Add scripts for repeated deterministic work, references for conditional facts, and assets for generated output.', pt: 'Mantenha orientação comum em SKILL.md. Adicione scripts para trabalho determinístico, referências para fatos condicionais e assets para saída.' }, output: { en: 'Smallest folder structure that supports the workflow.', pt: 'A menor estrutura de pastas que sustenta o fluxo.' }, proof: { en: 'Every file has a real caller; no placeholder directories.', pt: 'Cada arquivo tem um consumidor real; nenhuma pasta placeholder.' } },
+ write: { number: '04', title: { en: 'Write what changes decisions', pt: 'Escreva o que muda decisões' }, question: { en: 'What would a capable agent still get wrong?', pt: 'O que um agente capaz ainda erraria?' }, action: { en: 'State outcome, non-obvious constraints, routing, and stopping conditions. Remove generic advice, duplicate facts, and speculative rules.', pt: 'Declare resultado, restrições não óbvias, roteamento e condições de parada. Remova conselhos genéricos, fatos duplicados e regras especulativas.' }, output: { en: 'Lean SKILL.md with progressive links.', pt: 'SKILL.md enxuto com links progressivos.' }, proof: { en: 'Another agent can act correctly without loading irrelevant detail.', pt: 'Outro agente consegue agir corretamente sem carregar detalhes irrelevantes.' } },
+ validate: { number: '05', title: { en: 'Test behavior, then sharpen', pt: 'Teste comportamento, depois refine' }, question: { en: 'Did the skill improve a realistic outcome?', pt: 'A skill melhorou um resultado realista?' }, action: { en: 'Run structural validation, execute every new script, and forward-test realistic requests. Fix observed failures with the narrowest rule.', pt: 'Execute validação estrutural, rode cada script novo e teste pedidos realistas. Corrija falhas observadas com a regra mais estreita.' }, output: { en: 'Validated package plus evidence from real use.', pt: 'Pacote validado mais evidência de uso real.' }, proof: { en: 'quick_validate passes and behavior improves without unrelated side effects.', pt: 'quick_validate passa e o comportamento melhora sem efeitos colaterais.' } }
+ },
commonSkills: {
ponytail: { number: '01', kind: { en: 'SIMPLIFICATION INSTINCT', pt: 'INSTINTO DE SIMPLIFICAÇÃO' }, title: 'ponytail-lite', rule: { en: 'Stop at the first rung that holds.', pt: 'Pare no primeiro degrau que sustenta.' }, use: { en: 'Use when a request invites frameworks, dependencies, abstractions, or speculative scaffolding. It checks reuse, standard library, and native platform features before adding code.', pt: 'Use quando um pedido convida frameworks, dependências, abstrações ou scaffolding especulativo. Verifica reúso, biblioteca padrão e recursos nativos antes de adicionar código.' }, example: { en: 'Date picker? Start with <input type="date">.', pt: 'Seletor de data? Comece com <input type="date">.' }, caution: { en: 'Never simplify away security, accessibility, validation, or real edge cases.', pt: 'Nunca simplifique segurança, acessibilidade, validação ou casos extremos reais.' } },
caveman: { number: '02', kind: { en: 'COMMUNICATION STYLE', pt: 'ESTILO DE COMUNICAÇÃO' }, title: 'caveman', rule: { en: 'Signal first. Drop filler.', pt: 'Sinal primeiro. Corte o excesso.' }, use: { en: 'Use for routine status, handoffs, and technical summaries where speed matters. Short fragments make actions and evidence easy to scan.', pt: 'Use em status, handoffs e resumos técnicos rotineiros onde velocidade importa. Fragmentos curtos facilitam localizar ações e evidências.' }, example: { en: 'Built. Tests pass. Published.', pt: 'Feito. Testes passaram. Publicado.' }, caution: { en: 'Drop the style for security warnings, irreversible actions, and sequences where terse wording can be misread.', pt: 'Abandone o estilo em alertas de segurança, ações irreversíveis e sequências onde concisão pode causar erro.' } },
@@ -41,7 +48,7 @@ const interactiveCopy = {
const translations = {
pt: {
- '.chapter-links a:nth-child(1)': '01 frota', '.chapter-links a:nth-child(2)': '02 worktrees', '.chapter-links a:nth-child(3)': '03 skills', '.chapter-links a:nth-child(4)': '04 kit de campo', '.edition': 'ENGENHARIA DE IA 01 / 2026',
+ '.chapter-links a:nth-child(1)': '01 frota', '.chapter-links a:nth-child(2)': '02 worktrees', '.chapter-links a:nth-child(3)': '03 skills', '.chapter-links a:nth-child(4)': '04 criar', '.chapter-links a:nth-child(5)': '05 kit de campo', '.edition': 'ENGENHARIA DE IA 01 / 2026',
'.hero .eyebrow': 'Uma apresentação para quem entrega software', '.lede': 'Você não precisa de um exército de modelos. Precisa de um sistema: uma mente para enquadrar o trabalho, várias mãos para executá-lo e uma fronteira clara entre cada tarefa.', '.hero-index span': 'NOTA DE CAMPO / 001', '.hero-index strong': 'Entregue o sistema.', '.hero-index small': 'Skills · agentes · worktrees · evidências',
'.hero-stats div:nth-child(1) span': 'modelo forte para ambiguidade', '.hero-stats div:nth-child(2) span': 'workers delimitados em paralelo', '.hero-stats div:nth-child(3) span': 'iterações com evidências', '.hero-stats p': 'Leia isto como um mapa de rota, não como uma receita de prompt.',
'.thesis span': 'REGRA ZERO', '.thesis strong': 'Modelo forte para ambiguidade. Modelo leve para trabalho delimitado.', '.fleet .section-label span:nth-child(1)': 'Uma pequena frota', '.fleet .section-label span:nth-child(2)': 'coordenação antes do paralelismo', '.captain span': 'ORQUESTRADOR', '.captain h2': 'Decide o que precisa acontecer.', '.worker-card[data-worker="ui"] strong': 'Componentes e estados visuais', '.worker-card[data-worker="tests"] strong': 'Casos de aceitação', '.worker-card[data-worker="docs"] strong': 'Guia e exemplos', '.caption': 'O orquestrador preserva a intenção, escreve pequenos contratos e reúne resultados verificáveis. Ele não precisa digitar cada linha.',
@@ -52,6 +59,22 @@ const translations = {
}
};
+Object.assign(translations.pt, {
+ '.skill-builder .section-label span:nth-child(1)': 'Criar uma skill',
+ '.skill-builder .section-label span:nth-child(2)': 'atrito repetido → julgamento reutilizável',
+ '.builder-intro .eyebrow': 'A forja de skills',
+ '.builder-intro h2': 'Ensine a decisão. Mantenha o contexto leve.',
+ '.builder-intro > p': 'Não empacote tudo o que você sabe. Capture as escolhas não óbvias que melhoram resultados repetidamente e prove que a skill muda o comportamento.',
+ '[data-skill-step="observe"] span': 'Observar', '[data-skill-step="observe"] small': 'encontre atrito repetido',
+ '[data-skill-step="trigger"] span': 'Definir gatilho', '[data-skill-step="trigger"] small': 'roteie com precisão',
+ '[data-skill-step="scaffold"] span': 'Escolher anatomia', '[data-skill-step="scaffold"] small': 'apenas arquivos necessários',
+ '[data-skill-step="write"] span': 'Escrever orientação', '[data-skill-step="write"] small': 'decisões, não trivialidades',
+ '[data-skill-step="validate"] span': 'Validar', '[data-skill-step="validate"] small': 'teste comportamento real',
+ '.artifact-head span': 'SAÍDA / PACOTE DE SKILL', '.artifact-command span': 'VALIDAR',
+ '.builder-loop > span': 'APÓS USO REAL',
+ '.builder-loop > div': 'observar falha→refinar uma regra→retestar comportamento→manter estreita'
+});
+
const panel = document.querySelector('#phase-panel');
const buttons = document.querySelectorAll('[data-phase]');
const originals = new Map();
@@ -104,6 +127,16 @@ function renderSkillFile(id) {
selectButtons('[data-skill-file]', id, 'skillFile');
}
+function renderSkillWorkflow(id) {
+ const item = interactiveCopy.skillWorkflow[id];
+ const language = currentLanguage;
+ const labels = language === 'pt'
+ ? ['PERGUNTA', 'AÇÃO', 'ARTEFATO', 'PROVA']
+ : ['QUESTION', 'ACTION', 'ARTIFACT', 'PROOF'];
+ document.querySelector('#builder-detail').innerHTML = `${item.number}${labels[0]}
You do not need an army of models. You need a system: one mind to frame the work, several hands to execute it, and a clean boundary between every task.
01strong model for ambiguity
03bounded workers in parallel
∞iterations with evidence
Read this as a route map, not a prompt recipe.
RULE ZEROStrong model for ambiguity. Light model for bounded work.
THINKMAKE
@@ -22,6 +22,7 @@
Git worktrees
One branch per hand.
A worktree is another directory linked to the same repository. Each agent gets its own checkout and index; history remains shared.
Select a node to inspect its checkout, owner, and next action.
repository topology 4 checkouts
Model routing
Do not pay for reasoning where you need rhythm.
Choose a job to see why the model profile changes.
WorkProfilePrompt shape
Skills
Write the right way once.
A skill is a reusable procedure. It can carry instructions, references, scripts, and assets. It is not magical memory, and it does not replace acceptance criteria.
Do not package everything you know. Capture the non-obvious choices that repeatedly improve an outcome, then prove the skill changes behavior.
AFTER REAL USE
observe failure→sharpen one rule→retest behavior→keep it narrow
Common skillschoose behavior before model
The field kit
Different jobs. Different instincts.
A skill changes how an agent approaches work. Some shape communication. Others enforce research, debugging, review, or completion discipline. Select one to inspect its operating rule.
ONE PRACTICAL LOADOUT
PLAN unlazy →BUILD ponytail-lite →DEBUG diagnosing-bugs →REPORT caveman