--- 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 --path ``` 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 # ou com output directory: python scripts/package_skill.py ./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.