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:
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
|
||||
Reference in New Issue
Block a user