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

name, description

name	description
skill-creator	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):

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)

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

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

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:

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.