# Standards Descomplicar para Skills Standards adicionais aplicados sobre os padrões Anthropic base. ## Sumário 1. Frontmatter Descomplicar 2. Língua e Estilo PT-PT 3. Integração com MCPs 4. Assinatura de Código 5. Localização no Sistema de Plugins 6. Campos Opcionais do Frontmatter 7. Exemplos de Skills Bem e Mal Estruturadas --- ## 1. Frontmatter Descomplicar O padrão mínimo segue o Anthropic (apenas `name` + `description`): ```yaml --- name: nome-da-skill description: > Descrição completa do que a skill faz. Incluir domínio, tecnologias chave e triggers explícitos. Usar quando: (1) caso de uso A, (2) caso de uso B, (3) caso de uso C. --- ``` **Campo opcional `allowed-tools`** (quando a skill usa ferramentas específicas): ```yaml --- name: nome-da-skill description: > Descrição da skill. Usar quando [contexto]. allowed-tools: Read, Write, Edit, Bash, mcp__memory-supabase__search_memories --- ``` Incluir `allowed-tools` apenas quando a skill tem dependências de ferramentas não óbvias ou quando restringir o acesso é importante para segurança. --- ## 2. Língua e Estilo PT-PT **Regra absoluta:** Português europeu estrito em tudo — código, comentários, documentação, output. ### Acentuação obrigatória | Errado (BR) | Correcto (PT) | |-------------|---------------| | descrição | descrição | | criacao | criação | | informacao | informação | | configuracao | configuração | | autenticacao | autenticação | ### Vocabulário técnico | Errado | Correcto | |--------|----------| | você | tu / o utilizador | | usuário | utilizador | | senha | palavra-passe | | agendar | calendarizar | | deletar | eliminar | | implementar (como "deploy") | publicar / implementar | ### Monetário ``` 95EUR — correcto 95,00EUR — evitar casas decimais desnecessárias R$95 — nunca ``` ### Estilo - Usar **negrito** para ênfase (não MAIÚSCULAS) - Excepção: siglas (API, MCP, CRM, JWT) - Sem emojis nos ficheiros de skill - Datas em DD-MM-YYYY nos ficheiros e notas --- ## 3. Integração com MCPs Skills que necessitam de contexto especializado devem referenciar MCPs relevantes: ### Padrão de consulta NotebookLM ```markdown ## Contexto NotebookLM Consultar notebooks relevantes antes de executar: | Notebook | ID | Consultar quando | |----------|-----|-----------------| | Nome | id-do-notebook | situação específica | ``` ### Notebooks principais por domínio | Domínio | Notebook ID | |---------|-------------| | Programação geral | `24947ffa-0019-448a-a340-2f4a275d2eb1` | | Arquitectura / Delivery | `24947ffa-0019-448a-a340-2f4a275d2eb1` | | Roadmap / Prioridades | `79d43410-0e29-4be1-881d-84db6bdc239a` | | Gestão de Projectos / Agile | `0c9c079c-a426-486c-99eb-1564d42d37ad` | | Claude Code / IA | `2876d1fe-5cea-4d98-8140-b0e1a81c6bc4` | | MCPs / Desenvolvimento | `73102308-70ef-403e-9be9-eae0cfc62d55` | ### Padrão de memória Para skills que aprendem com execuções anteriores: ```markdown ## Memória Pesquisar experiência anterior antes de começar: `mcp__memory-supabase__search_memories "[keywords relevantes]"` Guardar aprendizagens ao concluir: `mcp__memory-supabase__save_memory { content: "...", tags: ["domínio", "skill"] }` ``` --- ## 4. Assinatura de Código Código produzido por skills deve incluir a assinatura Descomplicar: ### PHP ```php //skills// ``` **Plugins disponíveis e as suas skills:** | Plugin | Path | Skills típicas | |--------|------|----------------| | dev-tools | `dev-tools/1.0.0/skills/` | php-dev, db-design, react-patterns, nextjs, security-check | | gestao | `gestao/*/skills/` | worklog, desk, today | | crm-ops | `crm-ops/*/skills/` | orcamento, lead-approach | | core-tools | `core-tools/*/skills/` | _core, reflect | **Skill nova para plugin existente:** 1. Identificar o plugin mais adequado pelo domínio 2. Criar pasta em `skills//` 3. Verificar se o `plugin.json` precisa de ser actualizado **Skill nova para novo plugin:** Coordenar com o processo de criação de plugin (fora do âmbito desta skill). --- ## 6. Campos Opcionais do Frontmatter O Anthropic define apenas `name` e `description` como obrigatórios. O sistema Descomplicar aceita `allowed-tools` como campo adicional documentado: ```yaml --- name: nome-da-skill description: > Descrição completa com triggers. allowed-tools: Read, Write, Edit, Bash, mcp__memory-supabase__search_memories, mcp__notebooklm__notebook_query --- ``` **Não adicionar** outros campos não documentados — quebra a compatibilidade com o packaging script. --- ## 7. Exemplos de Skills Bem e Mal Estruturadas ### Má: Description vaga sem triggers ```yaml --- name: php-helper description: Ajuda com PHP. --- ``` **Problema:** O agente não sabe quando activar esta skill. ### Má: Corpo do SKILL.md com "Quando Usar" ```markdown # PHP Helper ## Quando Usar Esta Skill - Quando precisar de criar APIs - Quando precisar de autenticação ``` **Problema:** A secção "Quando Usar" no corpo nunca é lida pelo sistema de triggering (que usa apenas a `description`). Esta informação pertence à `description`. ### Má: Conteúdo duplicado ```yaml description: Usar quando criar APIs RESTful com Laravel. ``` ```markdown # PHP Dev ## Quando usar - Criar APIs RESTful com Laravel ← duplicado da description ``` ### Má: Ficheiros auxiliares desnecessários ``` php-dev/ ├── SKILL.md ├── README.md ← não deve existir ├── CHANGELOG.md ← não deve existir └── references/ ``` ### Boa: Description completa com triggers explícitos ```yaml --- name: php-dev description: > Desenvolvimento PHP moderno com Laravel, Symfony e APIs RESTful — autenticação (JWT, OAuth, Sanctum), service classes e refactorização de código legacy seguindo padrões PSR. Usar quando: (1) criar APIs RESTful, (2) implementar autenticação, (3) desenvolver service classes, (4) refactorizar código PHP, (5) integrar com APIs externas. --- ``` ### Boa: Progressive disclosure correcta ```markdown # PHP Dev ## Protocolo obrigatório 1. Pesquisar memória: `mcp__memory-supabase__search_memories "[keywords]"` 2. Consultar NotebookLM: ver tabela em references/notebooklm-context.md 3. Implementar com padrões Laravel: ver references/laravel-patterns.md ## Checklist de entrega - [ ] Assinatura Descomplicar® em todos os ficheiros - [ ] Type hints completos - [ ] PSR-12 compliant ``` O corpo do SKILL.md é conciso e delega detalhes para references. ### Boa: Estrutura de directório mínima e limpa ``` php-dev/ ├── SKILL.md └── references/ ├── laravel-patterns.md └── security-checklist.md ``` Apenas o necessário, sem ficheiros auxiliares.