Emanuel Almeida
6b3a6f2698
- 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>
259 lines
8.8 KiB
Markdown
259 lines
8.8 KiB
Markdown
# 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
|