Skill Builder — Scaffold & Generate

Skill Builder — Scaffold & Generate (Estrutura & Geração)

Processo

Etapa 1: Coletar Entradas

Determine a partir do que estamos construindo:

• Documento de plano: Saída de /skill-forge plan (preferencial)
• Descrição: Descrição em linguagem natural da skill
• Skill existente: Caminho para uma skill a ser usada como base

Se não houver plano, execute uma passagem rápida de planejamento (faça 3 perguntas-chave):

1. O que a skill faz? (1-2 frases)
2. Quais comandos ela deve ter? (lista)
3. Ela precisa de scripts ou ferramentas externas? (sim/não)

Etapa 2: Gerar Frontmatter

A etapa mais crítica. O campo de descrição determina a ativação.

Estrutura para escrever descrições:

[Declaração de capacidade] + [Capacidades detalhadas] + [Frases de gatilho]

Regras:

• Menos de 1024 caracteres no total
• Sem colchetes angulares XML (< >)
• Incluir 5 a 10 frases de gatilho que os usuários diriam
• Mencionar tipos de arquivo, se relevante
• Adicionar gatilhos negativos se houver risco de ativação excessiva

Use references/description-guide.md para a estrutura completa.

Etapa 3: Escrever o SKILL.md Principal

Estruture o corpo seguindo este modelo:

# [Nome da Skill] -- [Slogan]

[Visão geral de 1 a 2 frases]

## Referência Rápida

| Comando | O que faz |
|---------|-----------|
| /nome cmd1 | Descrição |
| /nome cmd2 | Descrição |

## Lógica de Orquestração

[Como os comandos roteiam para sub-skills]
[Árvores de decisão para roteamento condicional]

## [Seção Específica do Domínio]

[Regras principais, limites, portões de qualidade]

## Arquivos de Referência

[Lista de arquivos de referência sob demanda]

## Sub-Skills

[Lista de sub-skills com descrições de uma linha]

Regras críticas do SKILL.md:

• Menos de 500 linhas
• Menos de 5000 tokens
• Instruções acionáveis (não vagas)
• Incluir tratamento de erros
• Vincular referências, não as incorporar

Etapa 4: Gerar Sub-Skills (Nível 3 a 4)

Para cada sub-skill, gere um SKILL.md com:

---
name: pai-filho
description: >
  [O que faz]. Use quando o usuário disser "[gatilho 1]", "[gatilho 2]",
  "[gatilho 3]" ou "[gatilho 4]".
---

Diretrizes para o corpo da sub-skill:

• Instruções autocontidas para UM fluxo de trabalho
• Referenciar outras sub-skills pelo nome (não incorporar o conteúdo delas)
• Referenciar arquivos compartilhados no diretório references/ da skill pai
• Incluir definições explícitas de entrada/saída

Etapa 5: Gerar Scripts (Nível 2 a 4)

Para cada script:

#!/usr/bin/env python3
"""
Propósito: [O que este script faz]
Entrada: [Formato de entrada esperado]
Saída: [Formato de saída esperado]
Uso: python scripts/nome_do_script.py [argumentos]
"""

import argparse
import json
import sys
from typing import Any


def main(args: argparse.Namespace) -> dict[str, Any]:
    """Função principal de execução."""
    # Validar entradas
    # Realizar o trabalho
    # Retornar saída estruturada
    pass


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="[Descrição do script]")
    parser.add_argument("input", help="[Descrição da entrada]")
    parser.add_argument("--output", "-o", help="Caminho do arquivo de saída")
    args = parser.parse_args()

    try:
        result = main(args)
        print(json.dumps(result, indent=2))
    except Exception as e:
        print(json.dumps({"error": str(e)}), file=sys.stderr)
        sys.exit(1)

Regras do script:

• Um script, uma responsabilidade
• Interface CLI com argparse
• Saída JSON estruturada
• Mensagens de erro claras
• Sem dependências além da stdlib quando possível

Etapa 6: Gerar Arquivos de Referência

Para cada arquivo de referência:

• Foco em UM tópico
• Menos de 200 linhas
• Incluir exemplos concretos
• Usar tabelas para limites e especificações
• Marcar com "Carregar sob demanda" no SKILL.md pai

Etapa 7: Gerar Definições de Agente (Nível 4)

Arquivos de agente usam frontmatter YAML (diferente das skills):

---
name: [nome-da-skill]-[função]
description: >
  [O que este agente analisa].
  <example>Usuário diz: "[gatilho]"</example>
model: inherit
color: blue
tools:
  - Read
  - Grep
  - Glob
---

Você é um especialista em [função].

## Seu Papel
[O que este agente faz]

## Processo
1. [Passos...]

## Formato de Saída
Retorne markdown estruturado com descobertas e recomendações.

Principais diferenças das skills: O name do agente tem de 3 a 50 caracteres, descrições PODEM usar blocos <example>, campos exclusivos de agente incluem tools, color, permissionMode, maxTurns, memory. O corpo se torna o prompt do sistema (segunda pessoa).

Etapa 8: Gerar Script de Instalação

Crie install.sh que copia arquivos para ~/.claude/skills/ e ~/.claude/agents/.

Etapa 9: Validar

Execute python scripts/validate_skill.py <caminho> na skill gerada. Verifique todos os portões de qualidade do SKILL.md principal.

Etapa 10: Resumo da Saída

Apresente ao usuário:

1. Árvore de arquivos gerada
2. Arquivos principais e seus propósitos
3. Instruções de instalação
4. Consultas de teste sugeridas (3 que devem disparar, 3 que NÃO devem)
5. Próximos passos (testar, iterar, publicar)

Comando de Scaffolding

Para scaffolding rápido, use:

python scripts/init_skill.py <nome-da-skill> --tier <1-4> --path <caminho-de-saída>

Isso cria a estrutura completa do diretório com conteúdo de espaço reservado.