# 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 --path ``` 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 # Com directório de output opcional: python scripts/package_skill.py ./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