claude-plugins/dev-tools/skills/skill-creator/SKILL.md

---
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.