Melhores práticas de autoria de Skills

Skills boas são concisas, bem estruturadas e testadas com uso real. Este guia fornece decisões práticas de autoria para ajudá-lo a escrever Skills que Claude possa descobrir e usar efetivamente.

Para informações conceituais sobre como Skills funcionam, consulte a visão geral de Skills.

Princípios fundamentais

Concisão é fundamental

A janela de contexto é um bem público. Sua Skill compartilha a janela de contexto com tudo mais que Claude precisa saber, incluindo:

• O prompt do sistema
• Histórico de conversas
• Metadados de outras Skills
• Sua solicitação real

Nem todo token em sua Skill tem um custo imediato. Na inicialização, apenas os metadados (nome e descrição) de todas as Skills são pré-carregados. Claude lê SKILL.md apenas quando a Skill se torna relevante, e lê arquivos adicionais conforme necessário. No entanto, ser conciso em SKILL.md ainda é importante: uma vez que Claude o carrega, cada token compete com o histórico de conversas e outro contexto.

Suposição padrão: Claude já é muito inteligente

Adicione apenas contexto que Claude ainda não possui. Questione cada informação:

• "Claude realmente precisa dessa explicação?"
• "Posso assumir que Claude sabe disso?"
• "Este parágrafo justifica seu custo em tokens?"

Bom exemplo: Conciso (aproximadamente 50 tokens):

## Extrair texto de PDF

Use pdfplumber para extração de texto:

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Mau exemplo: Muito verboso (aproximadamente 150 tokens):

## Extrair texto de PDF

PDF (Portable Document Format) são um formato de arquivo comum que contém
texto, imagens e outro conteúdo. Para extrair texto de um PDF, você precisará
usar uma biblioteca. Existem muitas bibliotecas disponíveis para processamento
de PDF, mas pdfplumber é recomendado porque é fácil de usar e lida bem com
a maioria dos casos. Primeiro, você precisará instalá-la usando pip. Então
você pode usar o código abaixo...

A versão concisa assume que Claude sabe o que são PDFs e como bibliotecas funcionam.

Defina graus apropriados de liberdade

Corresponda o nível de especificidade à fragilidade e variabilidade da tarefa.

Alta liberdade (instruções baseadas em texto):

Use quando:

• Múltiplas abordagens são válidas
• Decisões dependem do contexto
• Heurísticas guiam a abordagem

Exemplo:

## Processo de revisão de código

1. Analise a estrutura e organização do código
2. Verifique possíveis bugs ou casos extremos
3. Sugira melhorias para legibilidade e manutenibilidade
4. Verifique a aderência às convenções do projeto

Liberdade média (pseudocódigo ou scripts com parâmetros):

Use quando:

• Um padrão preferido existe
• Alguma variação é aceitável
• A configuração afeta o comportamento

Exemplo:

## Gerar relatório

Use este modelo e customize conforme necessário:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Processar dados
    # Gerar saída no formato especificado
    # Opcionalmente incluir visualizações
```

Baixa liberdade (scripts específicos, poucos ou nenhum parâmetro):

Use quando:

• Operações são frágeis e propensas a erros
• Consistência é crítica
• Uma sequência específica deve ser seguida

Exemplo:

## Migração de banco de dados

Execute exatamente este script:

```bash
python scripts/migrate.py --verify --backup
```

Não modifique o comando ou adicione flags adicionais.

Analogia: Pense em Claude como um robô explorando um caminho:

• Ponte estreita com penhascos em ambos os lados: Há apenas um caminho seguro para frente. Forneça guardrails específicos e instruções exatas (baixa liberdade). Exemplo: migrações de banco de dados que devem ser executadas em sequência exata.
• Campo aberto sem perigos: Muitos caminhos levam ao sucesso. Dê direção geral e confie que Claude encontrará a melhor rota (alta liberdade). Exemplo: revisões de código onde o contexto determina a melhor abordagem.

Teste com todos os modelos que você planeja usar

Skills atuam como adições aos modelos, então a eficácia depende do modelo subjacente. Teste sua Skill com todos os modelos que você planeja usá-la.

Considerações de teste por modelo:

• Claude Haiku (rápido, econômico): A Skill fornece orientação suficiente?
• Claude Sonnet (equilibrado): A Skill é clara e eficiente?
• Claude Opus (raciocínio poderoso): A Skill evita sobre-explicar?

O que funciona perfeitamente para Opus pode precisar de mais detalhes para Haiku. Se você planeja usar sua Skill em múltiplos modelos, procure instruções que funcionem bem com todos eles.

Estrutura de Skill

Convenções de nomenclatura

Use padrões de nomenclatura consistentes para facilitar a referência e discussão de Skills. Considere usar forma de gerúndio (verbo + -ing) para nomes de Skills, pois isso descreve claramente a atividade ou capacidade que a Skill fornece.

Lembre-se de que o campo name deve usar apenas letras minúsculas, números e hífens.

Bons exemplos de nomenclatura (forma de gerúndio):

• processing-pdfs
• analyzing-spreadsheets
• managing-databases
• testing-code
• writing-documentation

Alternativas aceitáveis:

• Frases nominais: pdf-processing, spreadsheet-analysis
• Orientado por ação: process-pdfs, analyze-spreadsheets

Evite:

• Nomes vagos: helper, utils, tools
• Muito genérico: documents, data, files
• Palavras reservadas: anthropic-helper, claude-tools
• Padrões inconsistentes dentro de sua coleção de skills

Nomenclatura consistente facilita:

• Referenciar Skills em documentação e conversas
• Entender o que uma Skill faz à primeira vista
• Organizar e pesquisar através de múltiplas Skills
• Manter uma biblioteca de skills profissional e coesa

Escrevendo descrições eficazes

O campo description permite descoberta de Skill e deve incluir tanto o que a Skill faz quanto quando usá-la.

Seja específico e inclua termos-chave. Inclua tanto o que a Skill faz quanto gatilhos/contextos específicos para quando usá-la.

Cada Skill tem exatamente um campo de descrição. A descrição é crítica para seleção de skill: Claude a usa para escolher a Skill certa de potencialmente 100+ Skills disponíveis. Sua descrição deve fornecer detalhes suficientes para Claude saber quando selecionar esta Skill, enquanto o resto de SKILL.md fornece os detalhes de implementação.

Exemplos eficazes:

Skill de processamento de PDF:

description: Extrai texto e tabelas de arquivos PDF, preenche formulários, mescla documentos. Use ao trabalhar com arquivos PDF ou quando o usuário menciona PDFs, formulários ou extração de documentos.

Skill de análise de Excel:

description: Analisa planilhas Excel, cria tabelas dinâmicas, gera gráficos. Use ao analisar arquivos Excel, planilhas, dados tabulares ou arquivos .xlsx.

Skill de auxiliar de commit Git:

description: Gera mensagens de commit descritivas analisando diffs do git. Use quando o usuário pede ajuda para escrever mensagens de commit ou revisar mudanças preparadas.

Evite descrições vagas como estas:

description: Ajuda com documentos

description: Processa dados

description: Faz coisas com arquivos

Padrões de divulgação progressiva

SKILL.md serve como uma visão geral que aponta Claude para materiais detalhados conforme necessário, como um índice em um guia de integração. Para uma explicação de como a divulgação progressiva funciona, consulte Como Skills funcionam na visão geral.

Orientação prática:

• Mantenha o corpo de SKILL.md com menos de 500 linhas para desempenho ideal
• Divida o conteúdo em arquivos separados ao se aproximar deste limite
• Use os padrões abaixo para organizar instruções, código e recursos efetivamente

Visão geral visual: Do simples ao complexo

Uma Skill básica começa com apenas um arquivo SKILL.md contendo metadados e instruções:

Conforme sua Skill cresce, você pode agrupar conteúdo adicional que Claude carrega apenas quando necessário:

A estrutura de diretório completa de Skill pode parecer assim:

pdf/
├── SKILL.md              # Instruções principais (carregadas quando acionadas)
├── FORMS.md              # Guia de preenchimento de formulários (carregado conforme necessário)
├── reference.md          # Referência de API (carregada conforme necessário)
├── examples.md           # Exemplos de uso (carregados conforme necessário)
└── scripts/
    ├── analyze_form.py   # Script utilitário (executado, não carregado)
    ├── fill_form.py      # Script de preenchimento de formulários
    └── validate.py       # Script de validação

Padrão 1: Guia de alto nível com referências

---
name: pdf-processing
description: Extrai texto e tabelas de arquivos PDF, preenche formulários e mescla documentos. Use ao trabalhar com arquivos PDF ou quando o usuário menciona PDFs, formulários ou extração de documentos.
---

# Processamento de PDF

## Início rápido

Extraia texto com pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Recursos avançados

**Preenchimento de formulários**: Consulte [FORMS.md](FORMS.md) para guia completo
**Referência de API**: Consulte [REFERENCE.md](REFERENCE.md) para todos os métodos
**Exemplos**: Consulte [EXAMPLES.md](EXAMPLES.md) para padrões comuns

Claude carrega FORMS.md, REFERENCE.md ou EXAMPLES.md apenas quando necessário.

Padrão 2: Organização específica de domínio

Para Skills com múltiplos domínios, organize o conteúdo por domínio para evitar carregar contexto irrelevante. Quando um usuário pergunta sobre métricas de vendas, Claude só precisa ler esquemas relacionados a vendas, não dados de finanças ou marketing. Isso mantém o uso de tokens baixo e o contexto focado.

bigquery-skill/
├── SKILL.md (visão geral e navegação)
└── reference/
    ├── finance.md (receita, métricas de faturamento)
    ├── sales.md (oportunidades, pipeline)
    ├── product.md (uso de API, recursos)
    └── marketing.md (campanhas, atribuição)

# Análise de dados BigQuery

## Conjuntos de dados disponíveis

**Finanças**: Receita, ARR, faturamento → Consulte [reference/finance.md](reference/finance.md)
**Vendas**: Oportunidades, pipeline, contas → Consulte [reference/sales.md](reference/sales.md)
**Produto**: Uso de API, recursos, adoção → Consulte [reference/product.md](reference/product.md)
**Marketing**: Campanhas, atribuição, email → Consulte [reference/marketing.md](reference/marketing.md)

## Pesquisa rápida

Encontre métricas específicas usando grep:

```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```

Padrão 3: Detalhes condicionais

Mostre conteúdo básico, vincule a conteúdo avançado:

# Processamento DOCX

## Criando documentos

Use docx-js para novos documentos. Consulte [DOCX-JS.md](DOCX-JS.md).

## Editando documentos

Para edições simples, modifique o XML diretamente.

**Para mudanças rastreadas**: Consulte [REDLINING.md](REDLINING.md)
**Para detalhes OOXML**: Consulte [OOXML.md](OOXML.md)

Claude lê REDLINING.md ou OOXML.md apenas quando o usuário precisa desses recursos.

Evite referências profundamente aninhadas

Claude pode ler parcialmente arquivos quando eles são referenciados de outros arquivos referenciados. Ao encontrar referências aninhadas, Claude pode usar comandos como head -100 para visualizar conteúdo em vez de ler arquivos inteiros, resultando em informações incompletas.

Mantenha referências um nível de profundidade de SKILL.md. Todos os arquivos de referência devem vincular diretamente de SKILL.md para garantir que Claude leia arquivos completos quando necessário.

Mau exemplo: Muito profundo:

# SKILL.md
Consulte [advanced.md](advanced.md)...

# advanced.md
Consulte [details.md](details.md)...

# details.md
Aqui está a informação real...

Bom exemplo: Um nível de profundidade:

# SKILL.md

**Uso básico**: [instruções em SKILL.md]
**Recursos avançados**: Consulte [advanced.md](advanced.md)
**Referência de API**: Consulte [reference.md](reference.md)
**Exemplos**: Consulte [examples.md](examples.md)

Estruture arquivos de referência mais longos com índice

Para arquivos de referência com mais de 100 linhas, inclua um índice no topo. Isso garante que Claude possa ver o escopo completo de informações disponíveis mesmo ao visualizar com leituras parciais.

Exemplo:

# Referência de API

## Conteúdo
- Autenticação e configuração
- Métodos principais (criar, ler, atualizar, deletar)
- Recursos avançados (operações em lote, webhooks)
- Padrões de tratamento de erros
- Exemplos de código

## Autenticação e configuração
...

## Métodos principais
...

Claude pode então ler o arquivo completo ou pular para seções específicas conforme necessário.

Para detalhes sobre como essa arquitetura baseada em sistema de arquivos permite divulgação progressiva, consulte a seção Ambiente de tempo de execução na seção Avançado abaixo.

Fluxos de trabalho e loops de feedback

Use fluxos de trabalho para tarefas complexas

Divida operações complexas em etapas claras e sequenciais. Para fluxos de trabalho particularmente complexos, forneça uma lista de verificação que Claude possa copiar em sua resposta e marcar conforme progride.

Exemplo 1: Fluxo de trabalho de síntese de pesquisa (para Skills sem código):

## Fluxo de trabalho de síntese de pesquisa

Copie esta lista de verificação e acompanhe seu progresso:

```
Progresso da Pesquisa:
- [ ] Etapa 1: Leia todos os documentos de origem
- [ ] Etapa 2: Identifique temas principais
- [ ] Etapa 3: Referência cruzada de afirmações
- [ ] Etapa 4: Crie resumo estruturado
- [ ] Etapa 5: Verifique citações
```

**Etapa 1: Leia todos os documentos de origem**

Revise cada documento no diretório `sources/`. Anote os argumentos principais e evidências de apoio.

**Etapa 2: Identifique temas principais**

Procure por padrões entre fontes. Quais temas aparecem repetidamente? Onde as fontes concordam ou discordam?

**Etapa 3: Referência cruzada de afirmações**

Para cada afirmação principal, verifique se ela aparece no material de origem. Anote qual fonte apoia cada ponto.

**Etapa 4: Crie resumo estruturado**

Organize descobertas por tema. Inclua:
- Afirmação principal
- Evidência de apoio de fontes
- Pontos de vista conflitantes (se houver)

**Etapa 5: Verifique citações**

Verifique se cada afirmação referencia o documento de origem correto. Se as citações estiverem incompletas, retorne à Etapa 3.

Este exemplo mostra como fluxos de trabalho se aplicam a tarefas de análise que não requerem código. O padrão de lista de verificação funciona para qualquer processo complexo e multi-etapas.

Exemplo 2: Fluxo de trabalho de preenchimento de formulário PDF (para Skills com código):

## Fluxo de trabalho de preenchimento de formulário PDF

Copie esta lista de verificação e marque itens conforme os completa:

```
Progresso da Tarefa:
- [ ] Etapa 1: Analise o formulário (execute analyze_form.py)
- [ ] Etapa 2: Crie mapeamento de campos (edite fields.json)
- [ ] Etapa 3: Valide mapeamento (execute validate_fields.py)
- [ ] Etapa 4: Preencha o formulário (execute fill_form.py)
- [ ] Etapa 5: Verifique saída (execute verify_output.py)
```

**Etapa 1: Analise o formulário**

Execute: `python scripts/analyze_form.py input.pdf`

Isso extrai campos de formulário e suas localizações, salvando em `fields.json`.

**Etapa 2: Crie mapeamento de campos**

Edite `fields.json` para adicionar valores para cada campo.

**Etapa 3: Valide mapeamento**

Execute: `python scripts/validate_fields.py fields.json`

Corrija quaisquer erros de validação antes de continuar.

**Etapa 4: Preencha o formulário**

Execute: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**Etapa 5: Verifique saída**

Execute: `python scripts/verify_output.py output.pdf`

Se a verificação falhar, retorne à Etapa 2.

Etapas claras impedem que Claude pule validação crítica. A lista de verificação ajuda tanto Claude quanto você a acompanhar o progresso através de fluxos de trabalho multi-etapas.

Implemente loops de feedback

Padrão comum: Execute validador → corrija erros → repita

Este padrão melhora muito a qualidade da saída.

Exemplo 1: Conformidade com guia de estilo (para Skills sem código):

## Processo de revisão de conteúdo

1. Rascunhe seu conteúdo seguindo as diretrizes em STYLE_GUIDE.md
2. Revise contra a lista de verificação:
   - Verifique consistência de terminologia
   - Verifique que exemplos seguem o formato padrão
   - Confirme que todas as seções obrigatórias estão presentes
3. Se problemas encontrados:
   - Anote cada problema com referência de seção específica
   - Revise o conteúdo
   - Revise a lista de verificação novamente
4. Proceda apenas quando todos os requisitos forem atendidos
5. Finalize e salve o documento

Isso mostra o padrão de loop de validação usando documentos de referência em vez de scripts. O "validador" é STYLE_GUIDE.md, e Claude realiza a verificação lendo e comparando.

Exemplo 2: Processo de edição de documento (para Skills com código):

## Processo de edição de documento

1. Faça suas edições em `word/document.xml`
2. **Valide imediatamente**: `python ooxml/scripts/validate.py unpacked_dir/`
3. Se a validação falhar:
   - Revise a mensagem de erro cuidadosamente
   - Corrija os problemas no XML
   - Execute a validação novamente
4. **Proceda apenas quando a validação passar**
5. Reconstrua: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Teste o documento de saída

O loop de validação captura erros cedo.

Diretrizes de conteúdo

Evite informações sensíveis ao tempo

Não inclua informações que se tornarão desatualizadas:

Mau exemplo: Sensível ao tempo (se tornará errado):

Se você está fazendo isso antes de agosto de 2025, use a API antiga.
Após agosto de 2025, use a nova API.

Bom exemplo (use seção "padrões antigos"):

## Método atual

Use o endpoint da API v2: `api.example.com/v2/messages`

## Padrões antigos

<details>
<summary>API v1 legada (descontinuada 2025-08)</summary>

A API v1 usava: `api.example.com/v1/messages`

Este endpoint não é mais suportado.
</details>

A seção de padrões antigos fornece contexto histórico sem poluir o conteúdo principal.

Use terminologia consistente

Escolha um termo e use-o em toda a Skill:

Bom - Consistente:

• Sempre "endpoint de API"
• Sempre "campo"
• Sempre "extrair"

Ruim - Inconsistente:

• Misture "endpoint de API", "URL", "rota de API", "caminho"
• Misture "campo", "caixa", "elemento", "controle"
• Misture "extrair", "puxar", "obter", "recuperar"

Consistência ajuda Claude a entender e seguir instruções.

Padrões comuns

Padrão de modelo

Forneça modelos para formato de saída. Corresponda o nível de rigidez às suas necessidades.

Para requisitos rigorosos (como respostas de API ou formatos de dados):

## Estrutura de relatório

SEMPRE use esta estrutura de modelo exata:

```markdown
# [Título da Análise]

## Resumo executivo
[Visão geral de uma parágrafo das descobertas principais]

## Descobertas principais
- Descoberta 1 com dados de apoio
- Descoberta 2 com dados de apoio
- Descoberta 3 com dados de apoio

## Recomendações
1. Recomendação acionável específica
2. Recomendação acionável específica
```

Para orientação flexível (quando adaptação é útil):

## Estrutura de relatório

Aqui está um formato padrão sensato, mas use seu melhor julgamento com base na análise:

```markdown
# [Título da Análise]

## Resumo executivo
[Visão geral]

## Descobertas principais
[Adapte seções com base no que você descobrir]

## Recomendações
[Adapte ao contexto específico]
```

Ajuste seções conforme necessário para o tipo de análise específico.

Padrão de exemplos

Para Skills onde a qualidade da saída depende de ver exemplos, forneça pares entrada/saída assim como em prompting regular:

## Formato de mensagem de commit

Gere mensagens de commit seguindo estes exemplos:

**Exemplo 1:**
Entrada: Adicionado autenticação de usuário com tokens JWT
Saída:
```
feat(auth): implementar autenticação baseada em JWT

Adicionar endpoint de login e middleware de validação de token
```

**Exemplo 2:**
Entrada: Corrigido bug onde datas eram exibidas incorretamente em relatórios
Saída:
```
fix(reports): corrigir formatação de data na conversão de fuso horário

Usar timestamps UTC consistentemente em toda a geração de relatórios
```

**Exemplo 3:**
Entrada: Atualizadas dependências e refatorado tratamento de erros
Saída:
```
chore: atualizar dependências e refatorar tratamento de erros

- Atualizar lodash para 4.17.21
- Padronizar formato de resposta de erro em todos os endpoints
```

Siga este estilo: tipo(escopo): descrição breve, depois explicação detalhada.

Exemplos ajudam Claude a entender o estilo desejado e nível de detalhe mais claramente do que apenas descrições.

Padrão de fluxo de trabalho condicional

Guie Claude através de pontos de decisão:

## Fluxo de trabalho de modificação de documento

1. Determine o tipo de modificação:

   **Criando novo conteúdo?** → Siga "Fluxo de trabalho de criação" abaixo
   **Editando conteúdo existente?** → Siga "Fluxo de trabalho de edição" abaixo

2. Fluxo de trabalho de criação:
   - Use biblioteca docx-js
   - Construa documento do zero
   - Exporte para formato .docx

3. Fluxo de trabalho de edição:
   - Desempacote documento existente
   - Modifique XML diretamente
   - Valide após cada mudança
   - Reempacote quando completo

Avaliação e iteração

Construa avaliações primeiro

Crie avaliações ANTES de escrever documentação extensa. Isso garante que sua Skill resolva problemas reais em vez de documentar imaginários.

Desenvolvimento orientado por avaliação:

1. Identifique lacunas: Execute Claude em tarefas representativas sem uma Skill. Documente falhas específicas ou contexto faltante
2. Crie avaliações: Construa três cenários que testem essas lacunas
3. Estabeleça linha de base: Meça o desempenho de Claude sem a Skill
4. Escreva instruções mínimas: Crie apenas conteúdo suficiente para abordar as lacunas e passar nas avaliações
5. Itere: Execute avaliações, compare contra linha de base, e refine

Esta abordagem garante que você está resolvendo problemas reais em vez de antecipar requisitos que podem nunca se materializar.

Estrutura de avaliação:

{
  "skills": ["pdf-processing"],
  "query": "Extraia todo o texto deste arquivo PDF e salve-o em output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Lê com sucesso o arquivo PDF usando uma biblioteca apropriada de processamento de PDF ou ferramenta de linha de comando",
    "Extrai conteúdo de texto de todas as páginas no documento sem perder nenhuma página",
    "Salva o texto extraído em um arquivo chamado output.txt em um formato claro e legível"
  ]
}

Desenvolva Skills iterativamente com Claude

O processo mais eficaz de desenvolvimento de Skill envolve Claude em si. Trabalhe com uma instância de Claude ("Claude A") para criar uma Skill que é usada por outras instâncias ("Claude B"). Claude A ajuda você a projetar e refinar instruções, enquanto Claude B as testa em tarefas reais. Isso funciona porque modelos Claude entendem tanto como escrever instruções eficazes de agente quanto que informações agentes precisam.

Criando uma nova Skill:

1. Complete uma tarefa sem uma Skill: Trabalhe através de um problema com Claude A usando prompting normal. Conforme você trabalha, você naturalmente fornecerá contexto, explicará preferências e compartilhará conhecimento procedural. Observe que informações você fornece repetidamente.

2. Identifique o padrão reutilizável: Após completar a tarefa, identifique que contexto você forneceu que seria útil para tarefas futuras similares.

   Exemplo: Se você trabalhou através de uma análise BigQuery, você pode ter fornecido nomes de tabelas, definições de campos, regras de filtragem (como "sempre excluir contas de teste"), e padrões de consulta comuns.

3. Peça a Claude A para criar uma Skill: "Crie uma Skill que capture este padrão de análise BigQuery que acabamos de usar. Inclua os esquemas de tabela, convenções de nomenclatura, e a regra sobre filtragem de contas de teste."

   Modelos Claude entendem o formato e estrutura de Skill nativamente. Você não precisa de prompts de sistema especiais ou uma "skill de escrita de skills" para conseguir que Claude ajude a criar Skills. Simplesmente peça a Claude para criar uma Skill e ele gera conteúdo SKILL.md adequadamente estruturado com frontmatter apropriado e conteúdo de corpo.

4. Revise por concisão: Verifique que Claude A não adicionou explicações desnecessárias. Pergunte: "Remova a explicação sobre o que taxa de vitória significa - Claude já sabe disso."

5. Melhore arquitetura de informação: Peça a Claude A para organizar o conteúdo mais efetivamente. Por exemplo: "Organize isso para que o esquema de tabela esteja em um arquivo de referência separado. Podemos adicionar mais tabelas depois."

6. Teste em tarefas similares: Use a Skill com Claude B (uma instância fresca com a Skill carregada) em casos de uso relacionados. Observe se Claude B encontra a informação certa, aplica regras corretamente, e lida com a tarefa com sucesso.

7. Itere com base em observação: Se Claude B lutar ou perder algo, retorne a Claude A com especificidades: "Quando Claude usou esta Skill, esqueceu de filtrar por data para Q4. Devemos adicionar uma seção sobre padrões de filtragem de data?"

Iterando em Skills existentes:

O mesmo padrão hierárquico continua ao melhorar Skills. Você alterna entre:

• Trabalhar com Claude A (o especialista que ajuda refinar a Skill)
• Testar com Claude B (o agente usando a Skill para realizar trabalho real)
• Observar comportamento de Claude B e trazer insights de volta a Claude A

1. Use a Skill em fluxos de trabalho reais: Dê a Claude B (com a Skill carregada) tarefas reais, não cenários de teste

2. Observe o comportamento de Claude B: Anote onde ele lutar, sucede, ou faz escolhas inesperadas

   Exemplo de observação: "Quando pedi a Claude B por um relatório de vendas regional, ele escreveu a consulta mas esqueceu de filtrar contas de teste, mesmo que a Skill mencione esta regra."

3. Retorne a Claude A para melhorias: Compartilhe o SKILL.md atual e descreva o que você observou. Pergunte: "Notei que Claude B esqueceu de filtrar contas de teste quando pedi um relatório regional. A Skill menciona filtragem, mas talvez não seja proeminente o suficiente?"

4. Revise sugestões de Claude A: Claude A pode sugerir reorganizar para tornar regras mais proeminentes, usar linguagem mais forte como "DEVE filtrar" em vez de "sempre filtrar", ou reestruturar a seção de fluxo de trabalho.

5. Aplique e teste mudanças: Atualize a Skill com refinamentos de Claude A, depois teste novamente com Claude B em solicitações similares

6. Repita com base em uso: Continue este ciclo de observar-refinar-testar conforme você encontra novos cenários. Cada iteração melhora a Skill com base em comportamento real de agente, não suposições.

Coletando feedback de equipe:

1. Compartilhe Skills com colegas de equipe e observe seu uso
2. Pergunte: A Skill é acionada quando esperado? As instruções são claras? O que está faltando?
3. Incorpore feedback para abordar pontos cegos em seus próprios padrões de uso

Por que esta abordagem funciona: Claude A entende necessidades de agente, você fornece expertise de domínio, Claude B revela lacunas através de uso real, e refinamento iterativo melhora Skills com base em comportamento observado em vez de suposições.

Observe como Claude navega Skills

Conforme você itera em Skills, preste atenção em como Claude realmente as usa na prática. Observe:

• Caminhos de exploração inesperados: Claude lê arquivos em uma ordem que você não antecipou? Isso pode indicar que sua estrutura não é tão intuitiva quanto você pensou
• Conexões perdidas: Claude falha em seguir referências para arquivos importantes? Seus links podem precisar ser mais explícitos ou proeminentes
• Dependência excessiva de certas seções: Se Claude repetidamente lê o mesmo arquivo, considere se esse conteúdo deveria estar no SKILL.md principal em vez disso
• Conteúdo ignorado: Se Claude nunca acessa um arquivo agrupado, pode ser desnecessário ou mal sinalizado nas instruções principais

Itere com base nessas observações em vez de suposições. O 'name' e 'description' nos metadados de sua Skill são particularmente críticos. Claude usa estes ao decidir se acionar a Skill em resposta à tarefa atual. Certifique-se de que descrevem claramente o que a Skill faz e quando deve ser usada.

Anti-padrões a evitar

Evite caminhos de estilo Windows

Sempre use barras para frente em caminhos de arquivo, mesmo no Windows:

• ✓ Bom: scripts/helper.py, reference/guide.md
• ✗ Evite: scripts\helper.py, reference\guide.md

Caminhos de estilo Unix funcionam em todas as plataformas, enquanto caminhos de estilo Windows causam erros em sistemas Unix.

Evite oferecer muitas opções

Não apresente múltiplas abordagens a menos que necessário:

**Mau exemplo: Muitas escolhas** (confuso):
"Você pode usar pypdf, ou pdfplumber, ou PyMuPDF, ou pdf2image, ou..."

**Bom exemplo: Forneça um padrão** (com escape hatch):
"Use pdfplumber para extração de texto:
```python
import pdfplumber
```

Para PDFs digitalizados que requerem OCR, use pdf2image com pytesseract em vez disso."

Avançado: Skills com código executável

As seções abaixo focam em Skills que incluem scripts executáveis. Se sua Skill usa apenas instruções markdown, pule para Lista de verificação para Skills eficazes.

Resolva, não transfira

Ao escrever scripts para Skills, lide com condições de erro em vez de transferir para Claude.

Bom exemplo: Lide com erros explicitamente:

def process_file(path):
    """Processa um arquivo, criando-o se não existir."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Crie arquivo com conteúdo padrão em vez de falhar
        print(f"Arquivo {path} não encontrado, criando padrão")
        with open(path, "w") as f:
            f.write("")
        return ""
    except PermissionError:
        # Forneça alternativa em vez de falhar
        print(f"Não é possível acessar {path}, usando padrão")
        return ""

Mau exemplo: Transfira para Claude:

def process_file(path):
    # Apenas falhe e deixe Claude descobrir
    return open(path).read()

Parâmetros de configuração também devem ser justificados e documentados para evitar "constantes voodoo" (lei de Ousterhout). Se você não sabe o valor certo, como Claude o determinará?

Bom exemplo: Auto-documentado:

# Requisições HTTP normalmente completam em 30 segundos
# Timeout mais longo leva em conta conexões lentas
REQUEST_TIMEOUT = 30

# Três tentativas equilibram confiabilidade vs velocidade
# A maioria das falhas intermitentes se resolvem na segunda tentativa
MAX_RETRIES = 3

Mau exemplo: Números mágicos:

TIMEOUT = 47  # Por que 47?
RETRIES = 5  # Por que 5?

Forneça scripts utilitários

Mesmo que Claude pudesse escrever um script, scripts pré-feitos oferecem vantagens:

Benefícios de scripts utilitários:

• Mais confiáveis do que código gerado
• Economizam tokens (sem necessidade de incluir código em contexto)
• Economizam tempo (sem geração de código necessária)
• Garantem consistência entre usos

O diagrama acima mostra como scripts executáveis funcionam junto com arquivos de instrução. O arquivo de instrução (forms.md) referencia o script, e Claude pode executá-lo sem carregar seu conteúdo em contexto.

Distinção importante: Deixe claro em suas instruções se Claude deve:

• Executar o script (mais comum): "Execute analyze_form.py para extrair campos"
• Lê-lo como referência (para lógica complexa): "Consulte analyze_form.py para o algoritmo de extração de campo"

Para a maioria dos scripts utilitários, execução é preferida porque é mais confiável e eficiente. Consulte a seção Ambiente de tempo de execução abaixo para detalhes sobre como execução de script funciona.

Exemplo:

## Scripts utilitários

**analyze_form.py**: Extrai todos os campos de formulário de PDF

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

Formato de saída:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: Verifica caixas delimitadoras sobrepostas

```bash
python scripts/validate_boxes.py fields.json
# Retorna: "OK" ou lista conflitos
```

**fill_form.py**: Aplica valores de campo a PDF

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

Use visual analysis

When inputs can be rendered as images, have Claude analyze them:

## Form layout analysis

1. Convert PDF to images:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually

Claude's vision capabilities help understand layouts and structures.

Create verifiable intermediate outputs

When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.

Example: Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.

Solution: Use the workflow pattern shown above (PDF form filling), but add an intermediate changes.json file that gets validated before applying changes. The workflow becomes: analyze → create plan file → validate plan → execute → verify.

Why this pattern works:

• Catches errors early: Validation finds problems before changes are applied
• Machine-verifiable: Scripts provide objective verification
• Reversible planning: Claude can iterate on the plan without touching originals
• Clear debugging: Error messages point to specific problems

When to use: Batch operations, destructive changes, complex validation rules, high-stakes operations.

Implementation tip: Make validation scripts verbose with specific error messages like "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed" to help Claude fix issues.

Package dependencies

Skills run in the code execution environment with platform-specific limitations:

• claude.ai: Can install packages from npm and PyPI and pull from GitHub repositories
• Claude API: Has no network access and no runtime package installation

List required packages in your SKILL.md and verify they're available in the code execution tool documentation.

Runtime environment

Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see The Skills architecture in the overview.

How this affects your authoring:

How Claude accesses Skills:

1. Metadata pre-loaded: At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt
2. Files read on-demand: Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed
3. Scripts executed efficiently: Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens
4. No context penalty for large files: Reference files, data, or documentation don't consume context tokens until actually read

• File paths matter: Claude navigates your skill directory like a filesystem. Use forward slashes (reference/guide.md), not backslashes
• Name files descriptively: Use names that indicate content: form_validation_rules.md, not doc2.md
• Organize for discovery: Structure directories by domain or feature
  • Good: reference/finance.md, reference/sales.md
  • Bad: docs/file1.md, docs/file2.md
• Bundle comprehensive resources: Include complete API docs, extensive examples, large datasets; no context penalty until accessed
• Prefer scripts for deterministic operations: Write validate_form.py rather than asking Claude to generate validation code
• Make execution intent clear:
  • "Run analyze_form.py to extract fields" (execute)
  • "See analyze_form.py for the extraction algorithm" (read as reference)
• Test file access patterns: Verify Claude can navigate your directory structure by testing with real requests

Example:

bigquery-skill/
├── SKILL.md (overview, points to reference files)
└── reference/
    ├── finance.md (revenue metrics)
    ├── sales.md (pipeline data)
    └── product.md (usage analytics)

When the user asks about revenue, Claude reads SKILL.md, sees the reference to reference/finance.md, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires.

For complete details on the technical architecture, see How Skills work in the Skills overview.

MCP tool references

If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.

Format: ServerName:tool_name

Example:

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

Where:

• BigQuery and GitHub are MCP server names
• bigquery_schema and create_issue are the tool names within those servers

Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.

Avoid assuming tools are installed

Don't assume packages are available:

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"

Technical notes

YAML frontmatter requirements

The SKILL.md frontmatter requires name and description fields with specific validation rules:

• name: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words
• description: Maximum 1024 characters, non-empty, no XML tags

See the Skills overview for complete structure details.

Token budgets

Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the Skills overview.

Checklist for effective Skills

Before sharing a Skill, verify:

Core quality

• Description is specific and includes key terms
• Description includes both what the Skill does and when to use it
• SKILL.md body is under 500 lines
• Additional details are in separate files (if needed)
• No time-sensitive information (or in "old patterns" section)
• Consistent terminology throughout
• Examples are concrete, not abstract
• File references are one level deep
• Progressive disclosure used appropriately
• Workflows have clear steps

Code and scripts

• Scripts solve problems rather than punt to Claude
• Error handling is explicit and helpful
• No "voodoo constants" (all values justified)
• Required packages listed in instructions and verified as available
• Scripts have clear documentation
• No Windows-style paths (all forward slashes)
• Validation/verification steps for critical operations
• Feedback loops included for quality-critical tasks

Testing

• At least three evaluations created
• Tested with Haiku, Sonnet, and Opus
• Tested with real usage scenarios
• Team feedback incorporated (if applicable)

Next steps