feat: refactor 30+ skills to Anthropic progressive disclosure pattern
- All SKILL.md files now <500 lines (avg reduction 69%) - Detailed content extracted to references/ subdirectories - Frontmatter standardised: only name + description (Anthropic standard) - New skills: brand-guidelines, spec-coauthor, report-templates, skill-creator - Design skills: anti-slop guidelines, premium-proposals reference - Removed non-standard frontmatter fields (triggers, version, author, category) Plugins affected: infraestrutura, marketing, dev-tools, crm-ops, gestao, core-tools, negocio, perfex-dev, wordpress, design-media Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
181
dev-tools/skills/skill-creator/references/workflows.md
Normal file
181
dev-tools/skills/skill-creator/references/workflows.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# 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:
|
||||
|
||||
```markdown
|
||||
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:
|
||||
|
||||
```markdown
|
||||
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
|
||||
Reference in New Issue
Block a user