feat(dev-tools): adiciona plugin dev-tools (agents, skills, knowledge e metadados do projeto)

2026-10-28 16:08:45 +00:00
parent ce6030ee00
commit 7b2162ff29
180 changed files with 52164 additions and 0 deletions
@@ -0,0 +1,140 @@
+---
+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.
+layer: wiki
+---
+
+# 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 <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)
+
+```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 Descompl