Planejamento de Arquitetura de Skills

Planejamento de Arquitetura & Design de Skills

Processo

Passo 1: Descoberta de Domínio

Faça ao usuário estas perguntas (adaptando conforme o contexto):

1. Qual o domínio deste skill? (ex.: SEO, publicidade, DevOps, análise de dados)
2. Quais são os 2-3 principais casos de uso? O que os usuários devem poder realizar?
3. Que frases de gatilho os usuários diriam? Liste de 5 a 10 gatilhos em linguagem natural.
4. Ele precisa de ferramentas externas? Servidores MCP, APIs, ferramentas CLI?
5. Quem é o usuário-alvo? Desenvolvedor, profissional de marketing, analista, usuário geral?

Passo 2: Decomposição de Casos de Uso

Para cada caso de uso, defina:

Caso de Uso: [Nome]
Gatilho: Usuário diz "[frases]"
Passos:
1. [Primeira ação]
2. [Ponto de decisão ou validação]
3. [Próxima ação]
Resultado: [Qual a aparência do sucesso]
Ferramentas Necessárias: [embutidas, MCP, scripts]

Passo 3: Avaliação do Nível de Complexidade

Avalie com base nas respostas:

Sinal	Nível 1	Nível 2	Nível 3	Nível 4
Casos de uso	1-2	2-3	4-8	8+
Precisa de scripts?	Não	Sim	Talvez	Sim
Precisa de sub-skills?	Não	Não	Sim	Sim
Execução paralela?	Não	Não	Não	Sim
Documentos de referência?	Não	Talvez	Sim	Sim
Modelos do setor?	Não	Não	Talvez	Sim

Matriz de decisão:

• Fluxo único, sem scripts -> Nível 1 (mínimo)
• Precisa de validação determinística -> Nível 2 (fluxo de trabalho)
• Múltiplos fluxos de trabalho distintos -> Nível 3 (multi-skill)
• Domínio complexo com delegação paralela -> Nível 4 (ecossistema)

Passo 4: Design da Arquitetura

Com base no nível, gere a arquitetura:

Saída do Nível 1:

nome-do-skill/
  SKILL.md

Saída do Nível 2:

nome-do-skill/
  SKILL.md
  scripts/
    validar.py
    processar.py
  references/
    conhecimento-dominio.md

Saída do Nível 3:

nome-do-skill/              # Orquestrador principal
  SKILL.md
  references/
    referencia-compartilhada.md
skills/
  nome-do-skill-sub1/
    SKILL.md
  nome-do-skill-sub2/
    SKILL.md

Saída do Nível 4:

nome-do-skill/              # Orquestrador principal
  SKILL.md
  references/
    ref1.md
    ref2.md
  scripts/
    script1.py
    script2.py
  assets/
    template1.md
    template2.md
skills/
  nome-do-skill-sub1/
    SKILL.md
  nome-do-skill-sub2/
    SKILL.md
  ...
agents/
  nome-do-skill-papel1.md
  nome-do-skill-papel2.md

Passo 5: Decomposição de Sub-Skills (apenas Nível 3-4)

Para cada sub-skill, defina:

• Nome: {pai}-{função} (kebab-case)
• Responsabilidade: Propósito único e claro
• Entradas: O que precisa do orquestrador
• Saídas: O que retorna
• Referências cruzadas: Outros sub-skills ou referências necessárias
• Autossuficiente?: Pode ser executado independentemente ou precisa de orquestração?

Passo 6: Tabela de Roteamento

Projete o roteamento de comandos:

| Comando | Roteia para | Propósito |
|---------|-------------|-----------|
| /nome-do-skill | SKILL.md principal | Modo interativo |
| /nome-do-skill sub1 | skills/nome-do-skill-sub1/ | Subfluxo 1 |
| /nome-do-skill sub2 | skills/nome-do-skill-sub2/ | Subfluxo 2 |

Passo 7: Planejamento de Arquivos de Referência

Identifique o conhecimento que deve ser extraído para arquivos de referência:

• Regras e limites específicos do domínio
• Modelos do setor
• Documentação de API
• Gates de qualidade e critérios de validação

Regra prática: se a informação tiver mais de 50 linhas e for necessária apenas para subfluxos específicos, extraia-a para references/.

Passo 8: Gerar Documento de Plano

Crie um documento de plano estruturado:

# Plano de Skill: [nome]

## Visão Geral
- Domínio: [domínio]
- Nível: [1-4]
- Sub-skills: [contagem]
- Scripts: [contagem]

## Casos de Uso
[lista do Passo 2]

## Arquitetura
[diagrama do Passo 4]

## Sub-Skills
[detalhes do Passo 5]

## Roteamento
[tabela do Passo 6]

## Arquivos de Referência
[lista do Passo 7]

## Próximos Passos
Execute `/skill-forge build [nome]` para criar o scaffolding do skill.

Exemplos

Exemplo: Planejando um Skill de DevOps

Usuário: "Quero criar um skill para gerenciar contêineres Docker e implantações Kubernetes"

A descoberta revela:

• 6 casos de uso (gerenciamento de contêineres, implantação K8s, monitoramento, logs, escalonamento, solução de problemas)
• Precisa de scripts para comandos kubectl e docker
• Múltiplos fluxos de trabalho distintos
• Referências cruzadas entre monitoramento e solução de problemas

Avaliação: Nível 3 (orquestrador multi-skill)

Arquitetura:

devops/                     # Orquestrador principal
  SKILL.md
  scripts/
    health_check.py         # Verificação de saúde do cluster
    log_parser.py           # Análise de logs
  references/
    k8s-patterns.md         # Padrões de implantação
    docker-best-practices.md
skills/
  devops-docker/SKILL.md    # Gerenciamento de contêineres
  devops-k8s/SKILL.md       # Implantações Kubernetes
  devops-monitor/SKILL.md   # Monitoramento e alertas
  devops-logs/SKILL.md      # Análise de logs
  devops-scale/SKILL.md     # Estratégias de escalonamento
  devops-fix/SKILL.md       # Solução de problemas