Forja de Habilidades (SkillForge)

SkillForge

Crie habilidades bem formadas e compatíveis com as especificações a partir de padrões observados.

Quando Forjar

✅ Forje quando:

• Você repetiu a mesma sequência 2 a 3 vezes em uma sessão
• Uma convenção do projeto não está documentada em lugar nenhum
• Você resolveu um problema difícil com uma solução reutilizável
• Alguém pedir para você criar uma habilidade

❌ Não forje quando:

• É uma tarefa única
• Uma habilidade existente já cobre o caso (atualize-a, em vez disso)
• A "habilidade" é apenas um comando único (use um alias de script)

Passos

1. Dê nome ao padrão

• Que problema esta habilidade resolve?
• O que a desencadeia? (seja específico — o campo description é a superfície de descoberta)
• Quais são as entradas e saídas?

2. Escolha um nome

• kebab-case, de 1 a 64 caracteres
• Comece com um verbo quando possível: deploy-preview, scaffold-component, triage-bug
• Uma responsabilidade por habilidade

3. Crie o diretório da habilidade

mkdir -p skills/<nome-da-habilidade>

4. Escreva SKILL.md

Use este esqueleto:

---
name: <nome-da-habilidade>
description: <o que faz>. Use quando <gatilhos>.
metadata:
  forged-by: <id-do-agente>
  forged-from: <sessão-ou-contexto>
  forged-reason: "<por que foi criada>"
---

# <Nome da Habilidade>

## Entradas
- ...

## Passos
1. ...
2. ...

## Convenções
- Padrões específicos do projeto que se aplicam

## Casos Extremos
- Pegadinhas conhecidas ou tratamentos especiais

5. Adicione scripts (opcional)

Se a habilidade envolver geração de arquivos ou automação:

skills/<nome-da-habilidade>/
├── SKILL.md
├── scripts/
│   └── run.sh         # Automação executável
└── references/
    └── conventions.md # Referência detalhada (mantém SKILL.md enxuto)

6. Registre a habilidade

Atualize o arquivo .skills-registry.md na raiz do projeto (mesmo nível que skills/). Crie-o se não existir:

| <nome-da-habilidade> | local | <hoje> | 1 | <descrição> |

Se o projeto usar o registro legível por máquina (.skills-registry.json), atualize-o também — o comando skdd forge lida com ambos os formatos automaticamente.

Atualizando uma Habilidade Existente

Quando você usar uma habilidade e encontrar algo que ela não cobre:

1. Adicione o novo caso extremo ou passo ao SKILL.md existente
2. Se a habilidade estiver ficando muito longa (>200 linhas), divida-a
3. Atualize last-used e incremente usage-count no registro

Checklist de Qualidade

Antes de confirmar uma nova habilidade:

• name está em kebab-case, ≤64 caracteres
• description inclui o que faz E quando usar
• Passos são numerados e acionáveis
• Nenhum caminho fixo, segredo ou valor específico de ambiente
• SKILL.md tem menos de 200 linhas (mova detalhes para references/)
• Registrada em .skills-registry.md