feat: refactor 30+ skills to Anthropic progressive disclosure pattern
- All SKILL.md files now <500 lines (avg reduction 69%) - Detailed content extracted to references/ subdirectories - Frontmatter standardised: only name + description (Anthropic standard) - New skills: brand-guidelines, spec-coauthor, report-templates, skill-creator - Design skills: anti-slop guidelines, premium-proposals reference - Removed non-standard frontmatter fields (triggers, version, author, category) Plugins affected: infraestrutura, marketing, dev-tools, crm-ops, gestao, core-tools, negocio, perfex-dev, wordpress, design-media Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
188
dev-tools/skills/skill-creator/SKILL.md
Normal file
188
dev-tools/skills/skill-creator/SKILL.md
Normal file
@@ -0,0 +1,188 @@
|
||||
---
|
||||
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 <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 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 <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):**
|
||||
```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.
|
||||
258
dev-tools/skills/skill-creator/references/anthropic-patterns.md
Normal file
258
dev-tools/skills/skill-creator/references/anthropic-patterns.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Padrões Oficiais Anthropic para Skills
|
||||
|
||||
Referência baseada na documentação oficial do marketplace `anthropic-agent-skills`.
|
||||
|
||||
## Sumário
|
||||
|
||||
1. Progressive Disclosure (3 níveis de carregamento)
|
||||
2. Graus de Liberdade (alta/média/baixa)
|
||||
3. Anatomia de uma Skill
|
||||
4. Padrões de Progressive Disclosure
|
||||
5. O Que Não Incluir
|
||||
6. Scripts init_skill.py e package_skill.py
|
||||
|
||||
---
|
||||
|
||||
## 1. Progressive Disclosure
|
||||
|
||||
Skills usam um sistema de carregamento em 3 níveis para gerir o contexto de forma eficiente:
|
||||
|
||||
| Nível | O que carrega | Quando | Tamanho |
|
||||
|-------|--------------|--------|---------|
|
||||
| **Metadata** | `name` + `description` | Sempre em contexto | ~100 palavras |
|
||||
| **SKILL.md corpo** | Instruções e workflow | Quando a skill é activada | <500 linhas |
|
||||
| **Bundled resources** | Scripts, references, assets | Conforme necessário | Ilimitado |
|
||||
|
||||
**Princípio fundamental:** O contexto é um bem público. Skills partilham o contexto com o system prompt, histórico de conversa, metadata de outras skills e o pedido actual do utilizador.
|
||||
|
||||
**Assunção base:** O agente já é inteligente. Incluir apenas contexto que o agente não possui. Questionar cada parágrafo: "O agente realmente precisa desta explicação?" e "Este parágrafo justifica o custo em tokens?"
|
||||
|
||||
---
|
||||
|
||||
## 2. Graus de Liberdade
|
||||
|
||||
Calibrar o nível de especificidade ao risco e variabilidade da tarefa:
|
||||
|
||||
### Alta Liberdade — Instruções Textuais
|
||||
|
||||
Usar quando múltiplas abordagens são válidas, as decisões dependem do contexto, ou heurísticas guiam a abordagem.
|
||||
|
||||
```markdown
|
||||
## Análise de logs
|
||||
|
||||
Examinar os logs do servidor para identificar padrões de erro.
|
||||
Priorizar erros críticos e repetidos. Correlacionar timestamps com eventos
|
||||
conhecidos. Sugerir acções correctivas com base nos padrões encontrados.
|
||||
```
|
||||
|
||||
### Média Liberdade — Pseudocódigo ou Scripts com Parâmetros
|
||||
|
||||
Usar quando existe um padrão preferido, alguma variação é aceitável, ou a configuração afecta o comportamento.
|
||||
|
||||
```markdown
|
||||
## Criar endpoint API
|
||||
|
||||
1. Definir rota em `routes/api.php`
|
||||
2. Criar FormRequest para validação
|
||||
3. Implementar Controller com Service injectado
|
||||
4. Retornar Resource para transformação
|
||||
5. Documentar com PHPDoc
|
||||
|
||||
Adaptar ao contexto: GET sem body, POST/PUT com FormRequest.
|
||||
```
|
||||
|
||||
### Baixa Liberdade — Scripts Específicos, Poucos Parâmetros
|
||||
|
||||
Usar quando as operações são frágeis e propensas a erro, a consistência é crítica, ou uma sequência específica deve ser seguida.
|
||||
|
||||
```bash
|
||||
# SEMPRE usar exactamente esta sequência para deploy:
|
||||
git pull origin main
|
||||
composer install --no-dev --optimize-autoloader
|
||||
php artisan config:cache
|
||||
php artisan route:cache
|
||||
php artisan migrate --force
|
||||
sudo systemctl reload php-fpm
|
||||
```
|
||||
|
||||
**Analogia:** O agente é como um explorador num caminho — uma ponte estreita com precipícios precisa de guardas específicos (baixa liberdade), enquanto um campo aberto permite muitas rotas (alta liberdade).
|
||||
|
||||
---
|
||||
|
||||
## 3. Anatomia de uma Skill
|
||||
|
||||
```
|
||||
nome-da-skill/
|
||||
├── SKILL.md (obrigatório)
|
||||
│ ├── Frontmatter YAML (obrigatório: name + description)
|
||||
│ └── Corpo Markdown (obrigatório: instruções)
|
||||
└── Recursos Bundled (opcional)
|
||||
├── scripts/ Código executável (Python/Bash/etc.)
|
||||
├── references/ Documentação carregada conforme necessário
|
||||
└── assets/ Ficheiros usados no output (templates, ícones, fonts)
|
||||
```
|
||||
|
||||
### SKILL.md
|
||||
|
||||
**Frontmatter:** Contém apenas `name` e `description`. Estes são os únicos campos que o sistema lê para determinar quando a skill é activada. A `description` deve ser clara e abrangente — é o mecanismo primário de triggering.
|
||||
|
||||
**Corpo:** Instruções e orientações para usar a skill. Só é carregado DEPOIS de a skill ser activada.
|
||||
|
||||
### scripts/
|
||||
|
||||
Código executável para tarefas que requerem fiabilidade determinística ou são reescritas repetidamente.
|
||||
|
||||
- Quando incluir: quando o mesmo código é reescrito repetidamente ou fiabilidade determinística é necessária
|
||||
- Exemplo: `scripts/rotate_pdf.py` para rotação de PDFs
|
||||
- Vantagem: eficiente em tokens, determinístico, pode ser executado sem carregar para contexto
|
||||
|
||||
### references/
|
||||
|
||||
Documentação e material de referência para ser carregado conforme necessário.
|
||||
|
||||
- Quando incluir: para documentação que o agente deve consultar durante o trabalho
|
||||
- Exemplos: schemas de BD, documentação de API, políticas da empresa, guias detalhados de workflow
|
||||
- Se ficheiros grandes (>10k palavras): incluir padrões de pesquisa grep em SKILL.md
|
||||
- Evitar duplicação: informação deve existir em SKILL.md OU em references, nunca em ambos
|
||||
|
||||
### assets/
|
||||
|
||||
Ficheiros não destinados a ser carregados em contexto, mas usados no output produzido.
|
||||
|
||||
- Quando incluir: quando a skill precisa de ficheiros que serão usados no output final
|
||||
- Exemplos: `assets/logo.png`, `assets/slides.pptx`, `assets/frontend-template/`
|
||||
|
||||
---
|
||||
|
||||
## 4. Padrões de Progressive Disclosure
|
||||
|
||||
### Padrão 1: Guia de Alto Nível com References
|
||||
|
||||
```markdown
|
||||
# Processamento de PDF
|
||||
|
||||
## Início rápido
|
||||
|
||||
Extrair texto com pdfplumber:
|
||||
[exemplo de código]
|
||||
|
||||
## Funcionalidades avançadas
|
||||
|
||||
- **Preenchimento de formulários**: Ver references/forms.md para guia completo
|
||||
- **Referência da API**: Ver references/reference.md para todos os métodos
|
||||
- **Exemplos**: Ver references/examples.md para padrões comuns
|
||||
```
|
||||
|
||||
Claude carrega `forms.md`, `reference.md`, ou `examples.md` apenas quando necessário.
|
||||
|
||||
### Padrão 2: Organização por Domínio
|
||||
|
||||
Para skills com múltiplos domínios, organizar por domínio para evitar carregar contexto irrelevante:
|
||||
|
||||
```
|
||||
bigquery-skill/
|
||||
├── SKILL.md (visão geral e navegação)
|
||||
└── references/
|
||||
├── finance.md (métricas de receita, facturação)
|
||||
├── sales.md (oportunidades, pipeline)
|
||||
├── product.md (uso da API, funcionalidades)
|
||||
└── marketing.md (campanhas, atribuição)
|
||||
```
|
||||
|
||||
Quando o utilizador pergunta sobre métricas de vendas, Claude lê apenas `sales.md`.
|
||||
|
||||
### Padrão 3: Detalhes Condicionais
|
||||
|
||||
Mostrar conteúdo básico, ligar a conteúdo avançado:
|
||||
|
||||
```markdown
|
||||
# Processamento DOCX
|
||||
|
||||
## Criar documentos
|
||||
|
||||
Usar docx-js para novos documentos. Ver references/docx-js.md.
|
||||
|
||||
## Editar documentos
|
||||
|
||||
Para edições simples, modificar o XML directamente.
|
||||
|
||||
**Para tracked changes**: Ver references/redlining.md
|
||||
**Para detalhes OOXML**: Ver references/ooxml.md
|
||||
```
|
||||
|
||||
**Directrizes importantes:**
|
||||
- Evitar references aninhadas — manter um nível de profundidade a partir de SKILL.md
|
||||
- Para ficheiros de reference com mais de 100 linhas: incluir índice no topo
|
||||
|
||||
---
|
||||
|
||||
## 5. O Que Não Incluir
|
||||
|
||||
Uma skill deve conter apenas ficheiros essenciais que suportam directamente a sua funcionalidade. **Não criar:**
|
||||
|
||||
- README.md
|
||||
- INSTALLATION_GUIDE.md
|
||||
- QUICK_REFERENCE.md
|
||||
- CHANGELOG.md
|
||||
- Qualquer outro ficheiro auxiliar de documentação
|
||||
|
||||
A skill deve conter apenas a informação que um agente precisa para executar o trabalho. Não deve conter contexto sobre o processo de criação, procedimentos de setup/teste, ou documentação orientada ao utilizador.
|
||||
|
||||
---
|
||||
|
||||
## 6. Scripts init_skill.py e package_skill.py
|
||||
|
||||
### init_skill.py
|
||||
|
||||
Gera um directório de skill template com tudo o que é necessário:
|
||||
|
||||
```bash
|
||||
python scripts/init_skill.py <nome-skill> --path <directório-output>
|
||||
```
|
||||
|
||||
O script:
|
||||
- Cria o directório da skill no path especificado
|
||||
- Gera SKILL.md template com frontmatter correcto e placeholders TODO
|
||||
- Cria directórios de exemplo: `scripts/`, `references/`, `assets/`
|
||||
- Adiciona ficheiros de exemplo em cada directório
|
||||
|
||||
Após inicialização, personalizar ou remover os ficheiros gerados conforme necessário.
|
||||
|
||||
### package_skill.py
|
||||
|
||||
Empacota a skill num ficheiro `.skill` distribuível:
|
||||
|
||||
```bash
|
||||
python scripts/package_skill.py <path/para/pasta-skill>
|
||||
# Com directório de output opcional:
|
||||
python scripts/package_skill.py <path/para/pasta-skill> ./dist
|
||||
```
|
||||
|
||||
O script de packaging:
|
||||
|
||||
1. **Valida** automaticamente:
|
||||
- Formato do frontmatter YAML e campos obrigatórios
|
||||
- Convenções de naming e estrutura de directórios
|
||||
- Completude e qualidade da description
|
||||
- Organização de ficheiros e referências a recursos
|
||||
|
||||
2. **Empacota** se a validação passar, criando um ficheiro `.skill` (zip com extensão .skill)
|
||||
|
||||
Se a validação falhar, o script reporta os erros e sai sem criar o pacote.
|
||||
|
||||
---
|
||||
|
||||
## Processo Completo de Criação
|
||||
|
||||
1. **Compreender** a skill com exemplos concretos
|
||||
2. **Planear** conteúdos reutilizáveis (scripts, references, assets)
|
||||
3. **Inicializar** a skill (executar init_skill.py)
|
||||
4. **Implementar** recursos e escrever SKILL.md
|
||||
5. **Empacotar** a skill (executar package_skill.py)
|
||||
6. **Iterar** com base em uso real
|
||||
|
||||
**Workflow de iteração:**
|
||||
1. Usar a skill em tarefas reais
|
||||
2. Notar dificuldades ou ineficiências
|
||||
3. Identificar como SKILL.md ou recursos devem ser actualizados
|
||||
4. Implementar alterações e testar novamente
|
||||
@@ -0,0 +1,318 @@
|
||||
# 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
|
||||
<?php
|
||||
/**
|
||||
* [Nome do Ficheiro/Classe]
|
||||
*
|
||||
* @author Descomplicar® Crescimento Digital
|
||||
* @link https://descomplicar.pt
|
||||
* @copyright 2026 Descomplicar®
|
||||
*/
|
||||
```
|
||||
|
||||
### JavaScript / TypeScript
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* @author Descomplicar® | @link descomplicar.pt | @copyright 2026
|
||||
*/
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
Nome do módulo.
|
||||
|
||||
@author: Descomplicar® Crescimento Digital
|
||||
@link: https://descomplicar.pt
|
||||
@copyright: 2026 Descomplicar®
|
||||
"""
|
||||
```
|
||||
|
||||
### CSS
|
||||
|
||||
```css
|
||||
/**
|
||||
* Nome do ficheiro
|
||||
* @author Descomplicar® | descomplicar.pt | © 2026
|
||||
*/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Localização no Sistema de Plugins
|
||||
|
||||
Skills do ecossistema Descomplicar residem em:
|
||||
|
||||
```
|
||||
~/.claude/plugins/cache/descomplicar-plugins/<plugin-name>/<versão>/skills/<skill-name>/
|
||||
```
|
||||
|
||||
**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/<nome-da-skill>/`
|
||||
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.
|
||||
184
dev-tools/skills/skill-creator/references/output-patterns.md
Normal file
184
dev-tools/skills/skill-creator/references/output-patterns.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# Padrões de Output para Skills
|
||||
|
||||
Usar estes padrões quando skills precisam de produzir output consistente e de qualidade.
|
||||
|
||||
## Sumário
|
||||
|
||||
1. Padrão de Template
|
||||
2. Padrão de Exemplos
|
||||
3. Templates de Output Específicos Descomplicar
|
||||
|
||||
---
|
||||
|
||||
## 1. Padrão de Template
|
||||
|
||||
Fornecer templates para o formato de output. Calibrar o nível de rigor às necessidades.
|
||||
|
||||
### Para requisitos estritos (respostas de API, formatos de dados)
|
||||
|
||||
```markdown
|
||||
## Estrutura do relatório
|
||||
|
||||
SEMPRE usar exactamente esta estrutura:
|
||||
|
||||
# [Título da Análise]
|
||||
|
||||
## Sumário executivo
|
||||
[Parágrafo único com as principais conclusões]
|
||||
|
||||
## Principais conclusões
|
||||
- Conclusão 1 com dados de suporte
|
||||
- Conclusão 2 com dados de suporte
|
||||
|
||||
## Recomendações
|
||||
1. Recomendação específica e accionável
|
||||
2. Recomendação específica e accionável
|
||||
```
|
||||
|
||||
### Para orientação flexível (quando a adaptação é útil)
|
||||
|
||||
```markdown
|
||||
## Estrutura do relatório
|
||||
|
||||
Formato sensato por defeito, adaptar com bom senso:
|
||||
|
||||
# [Título da Análise]
|
||||
|
||||
## Sumário executivo
|
||||
[Visão geral]
|
||||
|
||||
## Principais conclusões
|
||||
[Adaptar secções com base no que for descoberto]
|
||||
|
||||
## Recomendações
|
||||
[Adaptar ao contexto específico]
|
||||
|
||||
Ajustar secções conforme necessário para o tipo de análise.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Padrão de Exemplos
|
||||
|
||||
Para skills em que a qualidade do output depende de ver exemplos, fornecer pares input/output:
|
||||
|
||||
```markdown
|
||||
## Formato de mensagem de commit
|
||||
|
||||
Gerar mensagens de commit seguindo estes exemplos:
|
||||
|
||||
**Exemplo 1:**
|
||||
Input: Adicionada autenticação de utilizador com tokens JWT
|
||||
Output:
|
||||
```
|
||||
feat(auth): implementar autenticação JWT
|
||||
|
||||
Adicionar endpoint de login e middleware de validação de tokens
|
||||
```
|
||||
|
||||
**Exemplo 2:**
|
||||
Input: Corrigido erro em que as datas eram apresentadas incorrectamente nos relatórios
|
||||
Output:
|
||||
```
|
||||
fix(reports): corrigir formatação de datas na conversão de timezone
|
||||
|
||||
Usar timestamps UTC consistentemente em toda a geração de relatórios
|
||||
```
|
||||
|
||||
Seguir este estilo: tipo(âmbito): descrição breve, depois explicação detalhada.
|
||||
```
|
||||
|
||||
Exemplos ajudam o agente a compreender o estilo e nível de detalhe pretendidos melhor do que descrições isoladas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Templates de Output Específicos Descomplicar
|
||||
|
||||
### Template de comentário Desk CRM (HTML)
|
||||
|
||||
```html
|
||||
<h4>Descrição</h4>
|
||||
<ul>
|
||||
<li>[Alteração realizada]</li>
|
||||
</ul>
|
||||
<p><strong>Ficheiros:</strong> <code>[path do ficheiro]</code></p>
|
||||
<hr>
|
||||
<p><strong>Skill:</strong> /nome-da-skill | <strong>Data:</strong> YYYY-MM-DD</p>
|
||||
```
|
||||
|
||||
### Template de relatório de análise técnica
|
||||
|
||||
```markdown
|
||||
# Análise: [Tema]
|
||||
|
||||
## Contexto
|
||||
[Situação actual e motivação]
|
||||
|
||||
## Conclusões
|
||||
- [Conclusão com evidência]
|
||||
- [Conclusão com evidência]
|
||||
|
||||
## Recomendações
|
||||
1. [Acção específica] — Prioridade: Alta/Média/Baixa
|
||||
2. [Acção específica] — Prioridade: Alta/Média/Baixa
|
||||
|
||||
## Próximos passos
|
||||
- [ ] [Tarefa concreta] — Responsável: [quem]
|
||||
- [ ] [Tarefa concreta] — Data limite: DD-MM-YYYY
|
||||
|
||||
---
|
||||
**Gerado por:** /nome-da-skill | **Data:** DD-MM-YYYY
|
||||
```
|
||||
|
||||
### Template de user story (para skill-creator / planeamento)
|
||||
|
||||
```markdown
|
||||
## User Story: [Título]
|
||||
|
||||
**Como** [tipo de utilizador],
|
||||
**Quero** [acção/funcionalidade],
|
||||
**Para que** [benefício/valor].
|
||||
|
||||
### Critérios de aceitação (GIVEN-WHEN-THEN)
|
||||
|
||||
- **DADO** [contexto inicial]
|
||||
**QUANDO** [acção do utilizador]
|
||||
**ENTÃO** [resultado esperado]
|
||||
|
||||
### Estimativa: [story points Fibonacci]
|
||||
### Prioridade: Must/Should/Could/Won't
|
||||
### Dependências: [lista de dependências]
|
||||
```
|
||||
|
||||
### Template de output de skill para output de código
|
||||
|
||||
Quando a skill produz código, estruturar o output assim:
|
||||
|
||||
```
|
||||
[Breve explicação do que foi feito]
|
||||
|
||||
**Ficheiro:** `path/para/ficheiro.ext`
|
||||
|
||||
```[linguagem]
|
||||
[código com assinatura Descomplicar]
|
||||
```
|
||||
|
||||
**Notas de implementação:**
|
||||
- [nota importante 1]
|
||||
- [nota importante 2]
|
||||
|
||||
**Próximos passos:**
|
||||
- [ ] [verificação ou acção necessária]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Calibragem de Templates por Risco
|
||||
|
||||
| Situação | Template | Grau de liberdade |
|
||||
|----------|----------|-------------------|
|
||||
| Output para API / integração | Estrito, exacto | Baixo |
|
||||
| Relatório técnico interno | Flexível com estrutura | Médio |
|
||||
| Análise exploratória | Orientação geral | Alto |
|
||||
| Código de produção | Estrito com assinatura | Baixo |
|
||||
| Documentação interna | Flexível | Alto |
|
||||
181
dev-tools/skills/skill-creator/references/workflows.md
Normal file
181
dev-tools/skills/skill-creator/references/workflows.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Padrões de Workflow para Skills
|
||||
|
||||
## Sumário
|
||||
|
||||
1. Workflows Sequenciais
|
||||
2. Workflows Condicionais
|
||||
3. Workflow Completo de Criação de Skill Descomplicar
|
||||
4. Checklist de Entrega Final
|
||||
|
||||
---
|
||||
|
||||
## 1. Workflows Sequenciais
|
||||
|
||||
Para tarefas complexas, dividir operações em passos claros e sequenciais. É útil dar ao agente uma visão geral do processo no início do SKILL.md:
|
||||
|
||||
```markdown
|
||||
Preencher um formulário PDF envolve estes passos:
|
||||
|
||||
1. Analisar o formulário (executar analyze_form.py)
|
||||
2. Criar mapeamento de campos (editar fields.json)
|
||||
3. Validar mapeamento (executar validate_fields.py)
|
||||
4. Preencher o formulário (executar fill_form.py)
|
||||
5. Verificar output (executar verify_output.py)
|
||||
```
|
||||
|
||||
### Características de um bom workflow sequencial
|
||||
|
||||
- Cada passo é concreto e verificável
|
||||
- Dependências entre passos são explícitas
|
||||
- Artefactos de cada passo estão identificados
|
||||
- Passos opcionais estão claramente marcados
|
||||
|
||||
---
|
||||
|
||||
## 2. Workflows Condicionais
|
||||
|
||||
Para tarefas com lógica de ramificação, guiar o agente pelos pontos de decisão:
|
||||
|
||||
```markdown
|
||||
1. Determinar o tipo de modificação:
|
||||
**Criar novo conteúdo?** -> Seguir "Workflow de criação" abaixo
|
||||
**Editar conteúdo existente?** -> Seguir "Workflow de edição" abaixo
|
||||
|
||||
2. Workflow de criação:
|
||||
a. [passo 1]
|
||||
b. [passo 2]
|
||||
|
||||
3. Workflow de edição:
|
||||
a. [passo 1]
|
||||
b. [passo 2]
|
||||
```
|
||||
|
||||
### Árvore de decisão para tipo de skill
|
||||
|
||||
Ao criar uma nova skill, determinar primeiro o tipo:
|
||||
|
||||
```
|
||||
Skill nova ou actualização?
|
||||
├── Nova skill
|
||||
│ ├── Tem scripts reutilizáveis? -> incluir scripts/
|
||||
│ ├── Tem docs de referência detalhadas? -> incluir references/
|
||||
│ └── Tem templates/assets de output? -> incluir assets/
|
||||
└── Actualização de skill existente
|
||||
├── SKILL.md está >500 linhas? -> mover conteúdo para references/
|
||||
├── Description é vaga? -> melhorar com triggers explícitos
|
||||
└── Há duplicação SKILL.md / references? -> consolidar
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Workflow Completo de Criação de Skill Descomplicar
|
||||
|
||||
### Fase 1: Preparação (antes de escrever qualquer ficheiro)
|
||||
|
||||
```
|
||||
1. Clarificar com o utilizador:
|
||||
- Que tarefas concretas a skill executa?
|
||||
- Que diria o utilizador para activar a skill?
|
||||
- Que conhecimento o agente não tem por defeito?
|
||||
|
||||
2. Identificar recursos reutilizáveis:
|
||||
- Código que é reescrito repetidamente -> scripts/
|
||||
- Docs de referência, schemas, APIs -> references/
|
||||
- Templates, assets de output -> assets/
|
||||
|
||||
3. Escolher o plugin de destino:
|
||||
- dev-tools: skills de desenvolvimento (PHP, JS, DB, segurança)
|
||||
- gestao: skills operacionais (worklog, desk, today)
|
||||
- crm-ops: skills comerciais (orçamento, leads)
|
||||
- core-tools: skills core do sistema
|
||||
```
|
||||
|
||||
### Fase 2: Estrutura
|
||||
|
||||
```
|
||||
4. Criar directório da skill:
|
||||
~/.claude/plugins/cache/descomplicar-plugins/<plugin>/1.0.0/skills/<nome>/
|
||||
|
||||
5. Criar SKILL.md com:
|
||||
- Frontmatter: name + description (com triggers explícitos)
|
||||
- Corpo: workflow core, <500 linhas
|
||||
- Referencias a ficheiros de references/ (quando e por quê)
|
||||
|
||||
6. Criar references/ se necessário:
|
||||
- Um ficheiro por domínio/tema
|
||||
- Incluir índice no topo se >100 linhas
|
||||
- Sem duplicação com SKILL.md
|
||||
```
|
||||
|
||||
### Fase 3: Validação
|
||||
|
||||
```
|
||||
7. Verificar checklist de qualidade:
|
||||
[ ] Frontmatter: apenas name + description
|
||||
[ ] Description: triggers explícitos incluídos
|
||||
[ ] Corpo SKILL.md: <500 linhas
|
||||
[ ] Sem secção "Quando Usar" no corpo
|
||||
[ ] References documentadas com contexto sobre quando ler
|
||||
[ ] PT-PT estrito (verificar acentuação e vocabulário)
|
||||
[ ] Sem emojis nos ficheiros
|
||||
[ ] Sem ficheiros auxiliares (README, CHANGELOG, etc.)
|
||||
[ ] Graus de liberdade calibrados ao risco
|
||||
[ ] Assinatura Descomplicar® no código (se aplicável)
|
||||
|
||||
8. Empacotar (se scripts disponíveis):
|
||||
python scripts/package_skill.py <path/para/skill>
|
||||
```
|
||||
|
||||
### Fase 4: Iteração
|
||||
|
||||
```
|
||||
9. Testar em uso real:
|
||||
- Activar a skill numa tarefa real
|
||||
- Notar onde o agente hesita ou erra
|
||||
- Identificar informação em falta ou excessiva
|
||||
|
||||
10. Actualizar baseado em feedback:
|
||||
- Se o agente pede informação -> adicionar a references/
|
||||
- Se o agente ignora informação -> remover ou mover para references/
|
||||
- Se a skill activa nos momentos errados -> refinar description
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Checklist de Entrega Final
|
||||
|
||||
Antes de considerar uma skill completa, validar:
|
||||
|
||||
### Frontmatter
|
||||
- [ ] Apenas `name` e `description` (sem campos extra não documentados)
|
||||
- [ ] `description` inclui o domínio e tecnologias principais
|
||||
- [ ] `description` inclui triggers explícitos ("Usar quando...")
|
||||
- [ ] `description` lista casos de uso concretos numerados
|
||||
|
||||
### Corpo SKILL.md
|
||||
- [ ] Abaixo de 500 linhas (contar com `wc -l SKILL.md`)
|
||||
- [ ] Sem secção "Quando Usar" no corpo
|
||||
- [ ] References documentadas: nome do ficheiro + quando ler
|
||||
- [ ] Forma imperativa/infinitivo nas instruções
|
||||
- [ ] Sem emojis
|
||||
|
||||
### Língua e estilo
|
||||
- [ ] PT-PT estrito (verificar: utilizador, palavra-passe, eliminar, calendarizar)
|
||||
- [ ] Acentuação correcta (verificar: descrição, criação, configuração, autenticação)
|
||||
- [ ] Monetário sem casas decimais desnecessárias
|
||||
- [ ] Negrito para ênfase, não MAIÚSCULAS
|
||||
|
||||
### Estrutura de ficheiros
|
||||
- [ ] Apenas ficheiros que o agente precisa para o trabalho
|
||||
- [ ] Sem README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
|
||||
- [ ] References com índice se >100 linhas
|
||||
- [ ] Scripts testados se incluídos
|
||||
|
||||
### Padrões Descomplicar
|
||||
- [ ] MCPs relevantes referenciados (se aplicável)
|
||||
- [ ] Assinatura Descomplicar® no código produzido (se aplicável)
|
||||
- [ ] Graus de liberdade calibrados ao risco da operação
|
||||
|
||||
### Validação técnica (Regra #49)
|
||||
- [ ] Código auditado: segurança, erros, boas práticas, performance
|
||||
- [ ] Score 10/10 antes de entregar
|
||||
Reference in New Issue
Block a user