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

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

description: Ajuda com WordPress

✅ Bom:

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):

---
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):

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

# 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:

# 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

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

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

---
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
• anthropics/skills
• VoltAgent/awesome-agent-skills