descomplicar-meta-plugin/docs/01-GUIA-SKILLS.md

# Guia Definitivo: Skills Claude Code

**Versão:** 2.0 | **Data:** 2026-02-04 | **Autor:** Descomplicar®

---

## 1. Conceitos Fundamentais

### O que são Skills?

Skills são **meta-tools que injectam instruções especializadas** no contexto do Claude. Transformam o Claude generalista em especialista equipado com conhecimento procedimental.

### Arquitectura de Carregamento

```
┌─────────────────────────────────────────────────────────────┐
│ Nível 1: METADATA (~100 tokens)                             │
│ → name + description carregados SEMPRE                      │
│ → Claude usa para decidir quando activar                    │
├─────────────────────────────────────────────────────────────┤
│ Nível 2: BODY (<5k tokens)                                  │
│ → SKILL.md completo carregado quando activado               │
│ → Instruções injectadas no contexto                         │
├─────────────────────────────────────────────────────────────┤
│ Nível 3: RESOURCES (on-demand)                              │
│ → Ficheiros em references/ carregados via Read tool         │
│ → Scripts executados quando necessário                      │
└─────────────────────────────────────────────────────────────┘
```

### Mecanismo de Selecção

**Não há routing algorítmico** - Claude usa raciocínio semântico:
1. Lê descrições de todas as skills disponíveis
2. Compara com o intent do utilizador
3. Selecciona baseado em compreensão de linguagem natural

**Implicação Crítica:** A `description` determina se a skill é activada.

---

## 2. Estrutura de Ficheiros

### Estrutura Mínima

```
skill-name/
└── SKILL.md          # OBRIGATÓRIO
```

### Estrutura Completa

```
skill-name/
├── SKILL.md              # OBRIGATÓRIO (<500 linhas)
├── scripts/              # Código executável
│   └── helper.py
├── references/           # Documentação detalhada
│   ├── api-docs.md
│   └── examples.md
└── assets/               # Ficheiros de output
    └── template.html
```

### Regras de Profundidade

```
✅ SKILL.md → references/api.md (1 nível)
❌ SKILL.md → docs/api.md → docs/endpoints.md (2 níveis)
```

---

## 3. SKILL.md - Estrutura

### Formato Obrigatório

```yaml
---
name: nome-da-skill
description: >
  [Capacidade principal]. [Capacidades secundárias].
  Use when [trigger1], [trigger2], or when user mentions
  "[keyword1]", "[keyword2]", "[keyword3]".
---

# Título da Skill

[Instruções que Claude segue quando skill activa]
```

### Frontmatter - Campos

| Campo | Obrigatório | Descrição |
|-------|-------------|-----------|
| `name` | Sim | Identificador único, kebab-case, <64 chars |
| `description` | **Sim** | O que faz + quando usar, <1024 chars |
| `argument-hint` | Não | Hint para argumentos: `[issue-number]` |
| `disable-model-invocation` | Não | `true` = só invocação manual via `/skill` |
| `user-invocable` | Não | `false` = esconde do menu `/` |
| `allowed-tools` | Não | Tools permitidos sem confirmação |
| `model` | Não | Modelo específico para esta skill |
| `context` | Não | `fork` para executar em subagent |

### Campos Custom Descomplicar

| Campo | Uso |
|-------|-----|
| `author` | `Descomplicar®` |
| `version` | Versão semântica (1.0.0) |
| `desk_task` | ID da tarefa no Desk CRM |
| `sdk` | SDK a que pertence |

### Controlo de Invocação

| Configuração | Utilizador Invoca | Claude Invoca |
|--------------|-------------------|---------------|
| (default) | ✅ | ✅ |
| `disable-model-invocation: true` | ✅ | ❌ |
| `user-invocable: false` | ❌ | ✅ |

---

## 4. Descrições Eficazes

### Taxa de Sucesso por Optimização

| Abordagem | Taxa Activação |
|-----------|----------------|
| Sem optimização | ~20% |
| Descrição optimizada | 50% |
| + Keywords específicas | 72% |
| + Hooks de avaliação | 84-90% |

### Fórmula de Descrição

```
[Capacidade principal]. [Capacidades secundárias].
Use when [trigger 1], [trigger 2], or when user mentions
"[keyword1]", "[keyword2]", "[keyword3]".
```

### Exemplos

**❌ Mau:**
```yaml
description: Ajuda com WordPress
```

**✅ Bom:**
```yaml
description: >
  Desenvolvimento WordPress especializado - plugins, temas, WooCommerce.
  Use when user asks to "criar plugin", "desenvolver tema", "woocommerce",
  "wordpress", "wp", "gutenberg", "elementor", "child theme".
```

### Regras de Descrição

1. **Duas partes obrigatórias:** Capacidade + Triggers
2. **5+ keywords específicas** do workflow real
3. **Mencionar tipos de ficheiros** relevantes (.php, functions.php)
4. **Terceira pessoa** (This skill... não Use this...)
5. **Evitar linguagem vaga** (helps with, works with)
6. **Declarar limites** - o que NÃO faz

---

## 5. Conteúdo do SKILL.md

### Dois Tipos de Skills

**Reference Skills (Conhecimento):**
```yaml
---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
```

**Task Skills (Acções):**
```yaml
---
name: deploy
description: Deploy the application to production
---

Deploy the application:
1. Run test suite
2. Build application
3. Push to deployment target
```

### Limites de Tamanho

| Componente | Limite |
|------------|--------|
| SKILL.md total | < 500 linhas |
| description | < 1024 caracteres |
| name | < 64 caracteres |
| Conteúdo principal | < 5000 tokens |

### Progressive Disclosure

```markdown
# SKILL.md

## Instruções Principais
[Conteúdo essencial - carregado sempre]

## Recursos Adicionais
- Para API completa: [docs/reference.md](references/reference.md)
- Para exemplos: [docs/examples.md](references/examples.md)

[Claude carrega via Read tool apenas quando necessário]
```

---

## 6. Scripts, References e Assets

### Scripts (`scripts/`)

**Quando incluir:**
- Código reescrito repetidamente
- Tarefas que precisam de reliability determinística
- Operações complexas que beneficiam de código testado

**Exemplo:**
```python
# scripts/validate.py
import sys
import json

def validate_config(path):
    with open(path) as f:
        config = json.load(f)
    # validation logic
    return True
```

### References (`references/`)

**Quando incluir:**
- Documentação de APIs
- Schemas de base de dados
- Políticas e guidelines
- Conhecimento de domínio específico

**Best Practice:** Se > 10k palavras, incluir grep patterns no SKILL.md.

### Assets (`assets/`)

**Quando incluir:**
- Templates (HTML, PPTX, etc.)
- Logos e imagens
- Boilerplate code

**Diferença de References:** Assets são usados no OUTPUT, não carregados em contexto.

---

## 7. Anti-Patterns

| Anti-Pattern | Problema | Solução |
|--------------|----------|---------|
| Context Bloat | 5000 linhas inline | Usar references/ |
| Paths Absolutos | Quebra em outros sistemas | Paths relativos |
| Descrição Vaga | Não activa | Keywords específicas |
| Over-Specification Tools | Risco segurança | Apenas necessários |
| Info Time-Sensitive | Desactualiza | Linguagem atemporal |
| Múltiplas Opções Sem Preferência | Ambiguidade | Preferência clara |

---

## 8. Métricas de Qualidade

### Score (0-100)

| Critério | Peso |
|----------|------|
| Descrição optimizada | 25 |
| Estrutura correcta | 20 |
| Tamanho adequado (<500 linhas) | 15 |
| Exemplos práticos | 15 |
| Limites definidos | 10 |
| Tools mínimos | 10 |
| Testada 3+ cenários | 5 |

### Níveis

| Nível | Score | Requisitos |
|-------|-------|------------|
| **Production** | 90+ | Todos os critérios |
| **Beta** | 70-89 | Descrição + estrutura + exemplos |
| **Draft** | <70 | Em desenvolvimento |

---

## 9. Integração Descomplicar

### Registo no Component Registry

```sql
INSERT INTO cr_skills (name, slug, description, path, sdk_id, status)
VALUES ('Nome Skill', 'skill-slug', 'Descrição...', '~/.claude/skills/skill-slug', 1, 'active');
```

### Relações

```sql
-- Skill → SDK
INSERT INTO cr_sdk_skills (sdk_id, skill_id) VALUES (1, 100);

-- Skill → Agent (se usado por agent)
INSERT INTO cr_agent_skills (agent_id, skill_id) VALUES (1, 100);
```

### Tarefa Desk CRM

Toda skill deve ter tarefa associada no projecto #65 com:
- Milestone: 294 (Skills Claude Code)
- Tags: skill (79), stackworkflow (75), claude-code (81)
- Responsáveis: Emanuel (1) + AikTop (25)

---

## 10. Checklist de Validação

```
□ FRONTMATTER
  □ name: kebab-case, <64 chars
  □ description: <1024 chars, "Use when..." com 5+ keywords
  □ version: semver
  □ desk_task: ID válido

□ ESTRUTURA
  □ SKILL.md <500 linhas
  □ Título corresponde ao name
  □ Secções: Quando Usar, Protocolo, Exemplos
  □ references/ linkados como markdown [](./references/file.md)

□ CONTEÚDO
  □ Limites definidos (quando NÃO usar)
  □ Exemplos input/output concretos
  □ Sem paths absolutos
  □ Sem informação time-sensitive

□ QUALIDADE
  □ Testada com 3+ cenários reais
  □ Score >= 70
  □ allowed-tools mínimos

□ INTEGRAÇÃO
  □ Registada em cr_skills
  □ SDK associado
  □ Tarefa Desk criada/actualizada
```

---

## 11. Template Padrão Descomplicar

```yaml
---
name: skill-name
description: >
  [Capacidade principal]. [Capacidades secundárias].
  Use when [trigger1], [trigger2], or when user mentions
  "[keyword1]", "[keyword2]", "[keyword3]".
author: Descomplicar®
version: 1.0.0
desk_task: XXXX
sdk: sdk-slug
allowed-tools: Read, Grep
---

# [Nome da Skill]

Skill para [objectivo principal] seguindo padrões Descomplicar®.

## Quando Usar

- [Cenário 1]
- [Cenário 2]
- [Cenário 3]

## Quando NÃO Usar

- [Limite 1] → usar /skill-x em vez
- [Limite 2] → fora do escopo

## Protocolo

### 1. Verificação Inicial
[Passos de verificação antes de agir]

### 2. Execução
[Passos principais]

### 3. Validação
[Como verificar que funcionou]

## Exemplos

### Exemplo 1: [Cenário Normal]

**Input:**
```
[Exemplo de input]
```

**Output:**
```
[Exemplo de output]
```

### Exemplo 2: [Edge Case]

**Input:**
```
[Edge case]
```

**Output:**
```
[Como é tratado]
```

## Recursos Adicionais

- [API Reference](./references/api.md)
- [Template Output](./assets/template.md)

## Integração

- **MCPs:** [lista]
- **Skills Relacionadas:** [lista]
- **Agents:** [lista]

---
*Skill v1.0.0 | Descomplicar® | desk.descomplicar.pt/tasks/view/XXXX*
```

---

**Referências:**
- [Documentação Oficial Skills](https://code.claude.com/docs/en/skills)
- [anthropics/skills](https://github.com/anthropics/skills)
- [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)