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:
188
dev-tools/skills/skill-creator/SKILL.md
Normal file
188
dev-tools/skills/skill-creator/SKILL.md
Normal file
@@ -0,0 +1,188 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Criar, melhorar e empacotar skills para o sistema de plugins Descomplicar. Usar quando o utilizador pede para criar uma nova skill, actualizar uma skill existente, ou quando é necessário estruturar conhecimento especializado em formato skill. Inclui padrões Anthropic oficiais (progressive disclosure, graus de liberdade) adaptados ao ecossistema Descomplicar com PT-PT estrito.
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
Guia para criar skills eficazes no ecossistema Descomplicar, seguindo padrões Anthropic com adaptações Descomplicar.
|
||||
|
||||
## O Que é uma Skill
|
||||
|
||||
Skills são pacotes modulares e auto-suficientes que estendem as capacidades do agente com conhecimento especializado, workflows e integrações de ferramentas. Funcionam como "guias de integração" para domínios específicos — transformam um agente geral num especialista equipado com conhecimento processual.
|
||||
|
||||
## Processo de Criação (6 Passos)
|
||||
|
||||
**Visão geral:**
|
||||
1. Compreender o contexto com exemplos concretos
|
||||
2. Planear recursos reutilizáveis (scripts, references, assets)
|
||||
3. Inicializar a estrutura de directórios
|
||||
4. Implementar conteúdo e escrever SKILL.md
|
||||
5. Validar com checklist de qualidade
|
||||
6. Iterar com base em uso real
|
||||
|
||||
---
|
||||
|
||||
### Passo 1: Compreender com Exemplos Concretos
|
||||
|
||||
Antes de escrever qualquer conteúdo, clarificar:
|
||||
- Que tarefas concretas a skill vai executar?
|
||||
- Que diria o utilizador para activar esta skill?
|
||||
- Que informação o agente não tem por defeito?
|
||||
|
||||
Exemplo de perguntas úteis: "Podes dar exemplos de como usarias esta skill?" ou "O que é que o agente deve fazer que hoje não faz?"
|
||||
|
||||
Concluir este passo quando os padrões de uso estiverem claros.
|
||||
|
||||
---
|
||||
|
||||
### Passo 2: Planear Recursos Reutilizáveis
|
||||
|
||||
Para cada exemplo concreto, identificar:
|
||||
- Código que seria reescrito repetidamente -> `scripts/`
|
||||
- Documentação de referência, schemas, APIs -> `references/`
|
||||
- Templates, assets, ficheiros de output -> `assets/`
|
||||
|
||||
---
|
||||
|
||||
### Passo 3: Inicializar Estrutura
|
||||
|
||||
Estrutura de directório padrão Descomplicar:
|
||||
|
||||
```
|
||||
nome-da-skill/
|
||||
├── SKILL.md (obrigatório)
|
||||
├── references/ (quando há docs detalhadas)
|
||||
│ ├── anthropic-patterns.md
|
||||
│ ├── descomplicar-standards.md
|
||||
│ ├── output-patterns.md
|
||||
│ └── workflows.md
|
||||
├── scripts/ (quando há código reutilizável)
|
||||
│ └── script.py
|
||||
└── assets/ (quando há templates/ficheiros de output)
|
||||
└── template.ext
|
||||
```
|
||||
|
||||
**Script de inicialização Anthropic** (quando disponível):
|
||||
```bash
|
||||
python scripts/init_skill.py <nome-skill> --path <directório-destino>
|
||||
```
|
||||
|
||||
O script gera SKILL.md com frontmatter e placeholders, mais directórios de exemplo.
|
||||
|
||||
---
|
||||
|
||||
### Passo 4: Implementar Conteúdo
|
||||
|
||||
#### Frontmatter (obrigatório, mínimo)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: nome-da-skill
|
||||
description: >
|
||||
Descrição clara do que a skill faz e quando usar.
|
||||
Incluir triggers explícitos: "Usar quando [contexto específico]".
|
||||
Listar casos de uso principais: (1) caso A, (2) caso B, (3) caso C.
|
||||
---
|
||||
```
|
||||
|
||||
**Regras do frontmatter:**
|
||||
- Apenas `name` e `description` (padrão Anthropic)
|
||||
- A `description` é o mecanismo de activação — deve ser completa e incluir triggers explícitos
|
||||
- Nunca incluir "Quando Usar" no corpo — só é lido após activação
|
||||
|
||||
#### Corpo do SKILL.md
|
||||
|
||||
- Manter abaixo de 500 linhas
|
||||
- Usar forma imperativa/infinitivo nas instruções
|
||||
- Conteúdo detalhado vai para `references/`
|
||||
- Referenciar ficheiros de references com contexto sobre quando ler
|
||||
|
||||
**Para conteúdo detalhado, ver:**
|
||||
- `references/anthropic-patterns.md` — padrões Anthropic (graus de liberdade, progressive disclosure)
|
||||
- `references/descomplicar-standards.md` — standards Descomplicar adicionais (PT-PT, MCPs, assinatura)
|
||||
- `references/output-patterns.md` — templates de output e padrões de exemplos
|
||||
- `references/workflows.md` — padrões de workflows sequenciais e condicionais
|
||||
|
||||
#### Graus de Liberdade
|
||||
|
||||
Calibrar o nível de especificidade ao risco da tarefa:
|
||||
|
||||
| Grau | Quando usar | Forma |
|
||||
|------|-------------|-------|
|
||||
| **Alta** | Múltiplas abordagens válidas, decisão contextual | Instruções textuais, heurísticas |
|
||||
| **Média** | Padrão preferido, alguma variação aceitável | Pseudocódigo, scripts com parâmetros |
|
||||
| **Baixa** | Operação frágil, consistência crítica, sequência obrigatória | Scripts específicos, poucos parâmetros |
|
||||
|
||||
---
|
||||
|
||||
### Passo 5: Checklist de Qualidade
|
||||
|
||||
**Frontmatter:**
|
||||
- [ ] Apenas `name` e `description` (sem campos extra)
|
||||
- [ ] `description` inclui triggers explícitos de quando usar
|
||||
- [ ] `description` lista casos de uso concretos
|
||||
|
||||
**SKILL.md corpo:**
|
||||
- [ ] Abaixo de 500 linhas
|
||||
- [ ] Sem secção "Quando Usar" no corpo
|
||||
- [ ] References documentadas com contexto sobre quando ler
|
||||
- [ ] Forma imperativa/infinitivo nas instruções
|
||||
- [ ] PT-PT estrito (sem brasileirismos, sem emojis nos ficheiros)
|
||||
|
||||
**Conteúdo:**
|
||||
- [ ] Graus de liberdade calibrados ao risco
|
||||
- [ ] Exemplos concretos de uso (bom vs mau)
|
||||
- [ ] Scripts testados (se incluídos)
|
||||
- [ ] Sem ficheiros auxiliares (README.md, CHANGELOG.md, etc.)
|
||||
|
||||
**Padrões Descomplicar:**
|
||||
- [ ] Assinatura Descomplicar® no código (quando aplicável)
|
||||
- [ ] MCPs relevantes referenciados
|
||||
- [ ] Monetário em EUR sem casas decimais desnecessárias
|
||||
|
||||
---
|
||||
|
||||
### Passo 6: Empacotar
|
||||
|
||||
**Script de packaging Anthropic** (quando disponível):
|
||||
```bash
|
||||
python scripts/package_skill.py <path/para/pasta-skill>
|
||||
# ou com output directory:
|
||||
python scripts/package_skill.py <path/para/pasta-skill> ./dist
|
||||
```
|
||||
|
||||
O script valida frontmatter, naming conventions, estrutura de directórios, e gera ficheiro `.skill` (zip com extensão .skill).
|
||||
|
||||
Se não estiver disponível, verificar manualmente com o checklist do Passo 5.
|
||||
|
||||
---
|
||||
|
||||
## Anti-Padrões a Evitar
|
||||
|
||||
**Má skill (demasiado vaga):**
|
||||
```yaml
|
||||
description: Ajuda com PHP.
|
||||
```
|
||||
|
||||
**Má skill (conteúdo duplicado em references e SKILL.md):**
|
||||
Documentar a mesma informação em dois locais — viola o princípio progressive disclosure.
|
||||
|
||||
**Má skill (ficheiros auxiliares):**
|
||||
Criar README.md, CHANGELOG.md, INSTALLATION_GUIDE.md — não devem existir numa skill.
|
||||
|
||||
**Boa skill:**
|
||||
```yaml
|
||||
description: >
|
||||
Desenvolvimento PHP moderno com Laravel e Symfony — autenticação JWT/OAuth,
|
||||
service classes, refactorização legacy. Usar quando: (1) criar APIs RESTful,
|
||||
(2) implementar autenticação, (3) desenvolver service classes, (4) refactorizar
|
||||
código PHP existente.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exemplos Concretos: Bom vs Mau
|
||||
|
||||
Ver `references/anthropic-patterns.md` para exemplos detalhados de progressive disclosure.
|
||||
Ver `references/descomplicar-standards.md` para exemplos de skills Descomplicar bem estruturadas.
|
||||
Reference in New Issue
Block a user