claude-plugins/dev-tools/skills/skill-creator/references/anthropic-patterns.md

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.

## 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.

## 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.

# 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

# 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:

# 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:

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:

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