claude-plugins/dev-tools/skills/skill-creator/references/workflows.md

Padrões de Workflow para Skills

Sumário

1. Workflows Sequenciais
2. Workflows Condicionais
3. Workflow Completo de Criação de Skill Descomplicar
4. Checklist de Entrega Final

---

1. Workflows Sequenciais

Para tarefas complexas, dividir operações em passos claros e sequenciais. É útil dar ao agente uma visão geral do processo no início do SKILL.md:

Preencher um formulário PDF envolve estes passos:

1. Analisar o formulário (executar analyze_form.py)
2. Criar mapeamento de campos (editar fields.json)
3. Validar mapeamento (executar validate_fields.py)
4. Preencher o formulário (executar fill_form.py)
5. Verificar output (executar verify_output.py)

Características de um bom workflow sequencial

• Cada passo é concreto e verificável
• Dependências entre passos são explícitas
• Artefactos de cada passo estão identificados
• Passos opcionais estão claramente marcados

---

2. Workflows Condicionais

Para tarefas com lógica de ramificação, guiar o agente pelos pontos de decisão:

1. Determinar o tipo de modificação:
   **Criar novo conteúdo?** -> Seguir "Workflow de criação" abaixo
   **Editar conteúdo existente?** -> Seguir "Workflow de edição" abaixo

2. Workflow de criação:
   a. [passo 1]
   b. [passo 2]

3. Workflow de edição:
   a. [passo 1]
   b. [passo 2]

Árvore de decisão para tipo de skill

Ao criar uma nova skill, determinar primeiro o tipo:

Skill nova ou actualização?
├── Nova skill
│   ├── Tem scripts reutilizáveis? -> incluir scripts/
│   ├── Tem docs de referência detalhadas? -> incluir references/
│   └── Tem templates/assets de output? -> incluir assets/
└── Actualização de skill existente
    ├── SKILL.md está >500 linhas? -> mover conteúdo para references/
    ├── Description é vaga? -> melhorar com triggers explícitos
    └── Há duplicação SKILL.md / references? -> consolidar

---

3. Workflow Completo de Criação de Skill Descomplicar

Fase 1: Preparação (antes de escrever qualquer ficheiro)

1. Clarificar com o utilizador:
   - Que tarefas concretas a skill executa?
   - Que diria o utilizador para activar a skill?
   - Que conhecimento o agente não tem por defeito?

2. Identificar recursos reutilizáveis:
   - Código que é reescrito repetidamente -> scripts/
   - Docs de referência, schemas, APIs -> references/
   - Templates, assets de output -> assets/

3. Escolher o plugin de destino:
   - dev-tools: skills de desenvolvimento (PHP, JS, DB, segurança)
   - gestao: skills operacionais (worklog, desk, today)
   - crm-ops: skills comerciais (orçamento, leads)
   - core-tools: skills core do sistema

Fase 2: Estrutura

4. Criar directório da skill:
   ~/.claude/plugins/cache/descomplicar-plugins/<plugin>/1.0.0/skills/<nome>/

5. Criar SKILL.md com:
   - Frontmatter: name + description (com triggers explícitos)
   - Corpo: workflow core, <500 linhas
   - Referencias a ficheiros de references/ (quando e por quê)

6. Criar references/ se necessário:
   - Um ficheiro por domínio/tema
   - Incluir índice no topo se >100 linhas
   - Sem duplicação com SKILL.md

Fase 3: Validação

7. Verificar checklist de qualidade:
   [ ] Frontmatter: apenas name + description
   [ ] Description: triggers explícitos incluídos
   [ ] Corpo SKILL.md: <500 linhas
   [ ] Sem secção "Quando Usar" no corpo
   [ ] References documentadas com contexto sobre quando ler
   [ ] PT-PT estrito (verificar acentuação e vocabulário)
   [ ] Sem emojis nos ficheiros
   [ ] Sem ficheiros auxiliares (README, CHANGELOG, etc.)
   [ ] Graus de liberdade calibrados ao risco
   [ ] Assinatura Descomplicar® no código (se aplicável)

8. Empacotar (se scripts disponíveis):
   python scripts/package_skill.py <path/para/skill>

Fase 4: Iteração

9. Testar em uso real:
   - Activar a skill numa tarefa real
   - Notar onde o agente hesita ou erra
   - Identificar informação em falta ou excessiva

10. Actualizar baseado em feedback:
    - Se o agente pede informação -> adicionar a references/
    - Se o agente ignora informação -> remover ou mover para references/
    - Se a skill activa nos momentos errados -> refinar description

---

4. Checklist de Entrega Final

Antes de considerar uma skill completa, validar:

Frontmatter

• Apenas name e description (sem campos extra não documentados)
• description inclui o domínio e tecnologias principais
• description inclui triggers explícitos ("Usar quando...")
• description lista casos de uso concretos numerados

Corpo SKILL.md

• Abaixo de 500 linhas (contar com wc -l SKILL.md)
• Sem secção "Quando Usar" no corpo
• References documentadas: nome do ficheiro + quando ler
• Forma imperativa/infinitivo nas instruções
• Sem emojis

Língua e estilo

• PT-PT estrito (verificar: utilizador, palavra-passe, eliminar, calendarizar)
• Acentuação correcta (verificar: descrição, criação, configuração, autenticação)
• Monetário sem casas decimais desnecessárias
• Negrito para ênfase, não MAIÚSCULAS

Estrutura de ficheiros

• Apenas ficheiros que o agente precisa para o trabalho
• Sem README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
• References com índice se >100 linhas
• Scripts testados se incluídos

Padrões Descomplicar

• MCPs relevantes referenciados (se aplicável)
• Assinatura Descomplicar® no código produzido (se aplicável)
• Graus de liberdade calibrados ao risco da operação

Validação técnica (Regra #49)

• Código auditado: segurança, erros, boas práticas, performance
• Score 10/10 antes de entregar