# 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
