Melhores práticas de autoria de Skills

## 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()
```

## 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 recomendamos pdfplumber porque é fácil de usar e funciona bem na
maioria dos casos. Primeiro, você precisará instalá-la usando pip. Então você
pode usar o código abaixo...

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

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

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

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.

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

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

description: Ajuda com documentos

description: Processa dados

description: Faz coisas com arquivos

pdf/
├── SKILL.md              # Instruções principais (carregadas quando acionadas)
├── FORMS.md              # Guia de preenchimento de formulário (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ário
    └── validate.py       # Script de validação

---
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ário**: 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

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)

# Processamento de 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 alterações rastreadas**: Consulte [REDLINING.md](REDLINING.md)
**Para detalhes de OOXML**: Consulte [OOXML.md](OOXML.md)

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

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

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

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

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

## Fluxo de trabalho de síntese de pesquisa

Copie esta lista de verificação e rastreie 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 suporte.

**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 aparece no material de origem. Anote qual fonte suporta cada ponto.

**Etapa 4: Crie resumo estruturado**

Organize descobertas por tema. Inclua:
- Afirmação principal
- Evidência de suporte 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.

## 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 campo (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 campo**

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

**Etapa 3: Valide mapeamento**

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

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

## 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 se exemplos seguem o formato padrão
   - Confirme que todas as seções necessá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

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

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

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

## Estrutura de relatório

SEMPRE use esta estrutura de modelo exata:

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

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

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

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

## 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
[Personalize para o contexto específico]
```

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

## Formato de mensagem de commit

Gere mensagens de commit seguindo estes exemplos:

**Exemplo 1:**
Entrada: Adicionada 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.

## 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 alteração
   - Reempacote quando completo

{
  "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"
  ]
}

**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."

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 ''

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

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

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

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

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

## Análise de layout de formulário

1. Converta PDF em imagens:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Analise cada imagem de página para identificar campos de formulário
3. Claude pode ver localizações e tipos de campo visualmente

bigquery-skill/
├── SKILL.md (visão geral, aponta para arquivos de referência)
└── reference/
    ├── finance.md (métricas de receita)
    ├── sales.md (dados de pipeline)
    └── product.md (análise de uso)

Use a ferramenta BigQuery:bigquery_schema para recuperar esquemas de tabela.
Use a ferramenta GitHub:create_issue para criar problemas.

**Mau exemplo: Assume instalação**:
"Use a biblioteca pdf para processar o arquivo."

**Bom exemplo: Explícito sobre dependências**:
"Instale pacote necessário: `pip install pypdf`

Então use-o:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"