140 lines
5.1 KiB
Markdown
140 lines
5.1 KiB
Markdown
---
|
|
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 |