Mejores prácticas para la creación de Skills

## Extraer texto de PDF

Usa pdfplumber para extracción de texto:

```python
import pdfplumber

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

## Extraer texto de PDF

PDF (Formato de Documento Portátil) son archivos en un formato común que contiene
texto, imágenes y otro contenido. Para extraer texto de un PDF, necesitarás
usar una biblioteca. Hay muchas bibliotecas disponibles para procesamiento de PDF, pero
recomendamos pdfplumber porque es fácil de usar y maneja la mayoría de casos bien.
Primero, necesitarás instalarla usando pip. Luego puedes usar el código a continuación...

## Proceso de revisión de código

1. Analiza la estructura y organización del código
2. Verifica posibles errores o casos extremos
3. Sugiere mejoras para legibilidad y mantenibilidad
4. Verifica la adherencia a las convenciones del proyecto

## Generar informe

Usa esta plantilla y personaliza según sea necesario:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Procesar datos
    # Generar salida en formato especificado
    # Opcionalmente incluir visualizaciones
```

## Migración de base de datos

Ejecuta exactamente este script:

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

No modifiques el comando ni agregues banderas adicionales.

description: Extrae texto y tablas de archivos PDF, completa formularios, fusiona documentos. Úsalo cuando trabajes con archivos PDF o cuando el usuario mencione PDFs, formularios o extracción de documentos.

description: Analiza hojas de cálculo de Excel, crea tablas dinámicas, genera gráficos. Úsalo cuando analices archivos de Excel, hojas de cálculo, datos tabulares o archivos .xlsx.

description: Genera mensajes de commit descriptivos analizando diffs de git. Úsalo cuando el usuario pida ayuda escribiendo mensajes de commit o revisando cambios preparados.

description: Ayuda con documentos

description: Procesa datos

description: Hace cosas con archivos

pdf/
├── SKILL.md              # Instrucciones principales (cargadas cuando se activan)
├── FORMS.md              # Guía de llenado de formularios (cargada según sea necesario)
├── reference.md          # Referencia de API (cargada según sea necesario)
├── examples.md           # Ejemplos de uso (cargados según sea necesario)
└── scripts/
    ├── analyze_form.py   # Script de utilidad (ejecutado, no cargado)
    ├── fill_form.py      # Script de llenado de formularios
    └── validate.py       # Script de validación

---
name: pdf-processing
description: Extrae texto y tablas de archivos PDF, completa formularios y fusiona documentos. Úsalo cuando trabajes con archivos PDF o cuando el usuario mencione PDFs, formularios o extracción de documentos.
---

# Procesamiento de PDF

## Inicio rápido

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

## Características avanzadas

**Llenado de formularios**: Consulta [FORMS.md](FORMS.md) para la guía completa
**Referencia de API**: Consulta [REFERENCE.md](REFERENCE.md) para todos los métodos
**Ejemplos**: Consulta [EXAMPLES.md](EXAMPLES.md) para patrones comunes

bigquery-skill/
├── SKILL.md (descripción general y navegación)
└── reference/
    ├── finance.md (ingresos, métricas de facturación)
    ├── sales.md (oportunidades, pipeline)
    ├── product.md (uso de API, características)
    └── marketing.md (campañas, atribución)

# Procesamiento de DOCX

## Crear documentos

Usa docx-js para nuevos documentos. Consulta [DOCX-JS.md](DOCX-JS.md).

## Editar documentos

Para ediciones simples, modifica el XML directamente.

**Para cambios rastreados**: Consulta [REDLINING.md](REDLINING.md)
**Para detalles de OOXML**: Consulta [OOXML.md](OOXML.md)

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

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

# details.md
Aquí está la información real...

# SKILL.md

**Uso básico**: [instrucciones en SKILL.md]
**Características avanzadas**: Consulta [advanced.md](advanced.md)
**Referencia de API**: Consulta [reference.md](reference.md)
**Ejemplos**: Consulta [examples.md](examples.md)

# Referencia de API

## Contenidos
- Autenticación y configuración
- Métodos principales (crear, leer, actualizar, eliminar)
- Características avanzadas (operaciones por lotes, webhooks)
- Patrones de manejo de errores
- Ejemplos de código

## Autenticación y configuración
...

## Métodos principales
...

## Flujo de trabajo de síntesis de investigación

Copia esta lista de verificación y rastrea tu progreso:

```
Progreso de investigación:
- [ ] Paso 1: Leer todos los documentos fuente
- [ ] Paso 2: Identificar temas clave
- [ ] Paso 3: Hacer referencias cruzadas de afirmaciones
- [ ] Paso 4: Crear resumen estructurado
- [ ] Paso 5: Verificar citas
```

**Paso 1: Leer todos los documentos fuente**

Revisa cada documento en el directorio `sources/`. Anota los argumentos principales y la evidencia de apoyo.

**Paso 2: Identificar temas clave**

Busca patrones en todas las fuentes. ¿Qué temas aparecen repetidamente? ¿Dónde están de acuerdo o en desacuerdo las fuentes?

**Paso 3: Hacer referencias cruzadas de afirmaciones**

Para cada afirmación importante, verifica que aparezca en el material fuente. Anota qué fuente apoya cada punto.

**Paso 4: Crear resumen estructurado**

Organiza los hallazgos por tema. Incluye:
- Afirmación principal
- Evidencia de apoyo de fuentes
- Puntos de vista conflictivos (si los hay)

**Paso 5: Verificar citas**

Verifica que cada afirmación haga referencia al documento fuente correcto. Si las citas están incompletas, vuelve al Paso 3.

## Flujo de trabajo de llenado de formularios PDF

Copia esta lista de verificación y marca elementos a medida que los completes:

```
Progreso de tarea:
- [ ] Paso 1: Analizar el formulario (ejecutar analyze_form.py)
- [ ] Paso 2: Crear mapeo de campos (editar fields.json)
- [ ] Paso 3: Validar mapeo (ejecutar validate_fields.py)
- [ ] Paso 4: Llenar el formulario (ejecutar fill_form.py)
- [ ] Paso 5: Verificar salida (ejecutar verify_output.py)
```

**Paso 1: Analizar el formulario**

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

Esto extrae campos de formulario y sus ubicaciones, guardando en `fields.json`.

**Paso 2: Crear mapeo de campos**

Edita `fields.json` para agregar valores para cada campo.

**Paso 3: Validar mapeo**

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

Corrige cualquier error de validación antes de continuar.

**Paso 4: Llenar el formulario**

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

**Paso 5: Verificar salida**

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

Si la verificación falla, vuelve al Paso 2.

## Proceso de revisión de contenido

1. Redacta tu contenido siguiendo las directrices en STYLE_GUIDE.md
2. Revisa contra la lista de verificación:
   - Verifica consistencia de terminología
   - Verifica que los ejemplos sigan el formato estándar
   - Confirma que todas las secciones requeridas estén presentes
3. Si se encuentran problemas:
   - Anota cada problema con referencia de sección específica
   - Revisa el contenido
   - Revisa la lista de verificación nuevamente
4. Solo procede cuando se cumplan todos los requisitos
5. Finaliza y guarda el documento

## Proceso de edición de documentos

1. Realiza tus ediciones en `word/document.xml`
2. **Valida inmediatamente**: `python ooxml/scripts/validate.py unpacked_dir/`
3. Si la validación falla:
   - Revisa el mensaje de error cuidadosamente
   - Corrige los problemas en el XML
   - Ejecuta la validación nuevamente
4. **Solo procede cuando la validación pase**
5. Reconstruye: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Prueba el documento de salida

Si estás haciendo esto antes de agosto de 2025, usa la API antigua.
Después de agosto de 2025, usa la nueva API.

## Método actual

Usa el endpoint de API v2: `api.example.com/v2/messages`

## Patrones antiguos

<details>
<summary>API v1 heredada (deprecada 2025-08)</summary>

La API v1 usaba: `api.example.com/v1/messages`

Este endpoint ya no es compatible.
</details>

## Estructura del informe

SIEMPRE usa esta estructura de plantilla exacta:

```markdown
# [Título del análisis]

## Resumen ejecutivo
[Descripción general de un párrafo de hallazgos clave]

## Hallazgos clave
- Hallazgo 1 con datos de apoyo
- Hallazgo 2 con datos de apoyo
- Hallazgo 3 con datos de apoyo

## Recomendaciones
1. Recomendación accionable específica
2. Recomendación accionable específica
```

## Estructura del informe

Aquí hay un formato predeterminado sensato, pero usa tu mejor criterio basado en el análisis:

```markdown
# [Título del análisis]

## Resumen ejecutivo
[Descripción general]

## Hallazgos clave
[Adapta secciones basadas en lo que descubras]

## Recomendaciones
[Personaliza al contexto específico]
```

Ajusta secciones según sea necesario para el tipo de análisis específico.

## Formato de mensaje de commit

Genera mensajes de commit siguiendo estos ejemplos:

**Ejemplo 1:**
Entrada: Agregó autenticación de usuario con tokens JWT
Salida:
```
feat(auth): implementar autenticación basada en JWT

Agregar endpoint de inicio de sesión y middleware de validación de token
```

**Ejemplo 2:**
Entrada: Corregido error donde las fechas se mostraban incorrectamente en informes
Salida:
```
fix(reports): corregir formato de fecha en conversión de zona horaria

Usar timestamps UTC consistentemente en toda la generación de informes
```

**Ejemplo 3:**
Entrada: Dependencias actualizadas y manejo de errores refactorizado
Salida:
```
chore: actualizar dependencias y refactorizar manejo de errores

- Actualizar lodash a 4.17.21
- Estandarizar formato de respuesta de error en todos los endpoints
```

Sigue este estilo: tipo(alcance): descripción breve, luego explicación detallada.

## Flujo de trabajo de modificación de documentos

1. Determina el tipo de modificación:

   **¿Creando contenido nuevo?** → Sigue "Flujo de trabajo de creación" a continuación
   **¿Editando contenido existente?** → Sigue "Flujo de trabajo de edición" a continuación

2. Flujo de trabajo de creación:
   - Usa biblioteca docx-js
   - Construye documento desde cero
   - Exporta a formato .docx

3. Flujo de trabajo de edición:
   - Desempaqueta documento existente
   - Modifica XML directamente
   - Valida después de cada cambio
   - Reempaqueta cuando esté completo

{
  "skills": ["pdf-processing"],
  "query": "Extrae todo el texto de este archivo PDF y guárdalo en output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Lee exitosamente el archivo PDF usando una biblioteca de procesamiento de PDF apropiada o herramienta de línea de comandos",
    "Extrae contenido de texto de todas las páginas en el documento sin perder ninguna página",
    "Guarda el texto extraído en un archivo llamado output.txt en un formato claro y legible"
  ]
}

**Mal ejemplo: Demasiadas opciones** (confuso):
"Puedes usar pypdf, o pdfplumber, o PyMuPDF, o pdf2image, o..."

**Buen ejemplo: Proporciona un predeterminado** (con escape hatch):
"Usa pdfplumber para extracción de texto:
```python
import pdfplumber
```

Para PDFs escaneados que requieren OCR, usa pdf2image con pytesseract en su lugar."

def process_file(path):
    """Procesa un archivo, creándolo si no existe."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Crea archivo con contenido predeterminado en lugar de fallar
        print(f"Archivo {path} no encontrado, creando predeterminado")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # Proporciona alternativa en lugar de fallar
        print(f"No se puede acceder a {path}, usando predeterminado")
        return ''

def process_file(path):
    # Solo falla y deja que Claude lo resuelva
    return open(path).read()

# Las solicitudes HTTP típicamente se completan dentro de 30 segundos
# Un timeout más largo cuenta para conexiones lentas
REQUEST_TIMEOUT = 30

# Tres reintentos equilibra confiabilidad vs velocidad
# La mayoría de fallos intermitentes se resuelven en el segundo reintento
MAX_RETRIES = 3

TIMEOUT = 47  # ¿Por qué 47?
RETRIES = 5   # ¿Por qué 5?

## Scripts de utilidad

**analyze_form.py**: Extrae todos los campos de formulario de PDF

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

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

**validate_boxes.py**: Verifica cajas de delimitación superpuestas

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

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

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

## Análisis de diseño de formulario

1. Convierte PDF a imágenes:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Analiza cada imagen de página para identificar campos de formulario
3. Claude puede ver ubicaciones y tipos de campos visualmente

bigquery-skill/
├── SKILL.md (descripción general, apunta a archivos de referencia)
└── reference/
    ├── finance.md (métricas de ingresos)
    ├── sales.md (datos de pipeline)
    └── product.md (análisis de uso)

Usa la herramienta BigQuery:bigquery_schema para recuperar esquemas de tabla.
Usa la herramienta GitHub:create_issue para crear problemas.

**Mal ejemplo: Asume instalación**:
"Usa la biblioteca pdf para procesar el archivo."

**Buen ejemplo: Explícito sobre dependencias**:
"Instala paquete requerido: `pip install pypdf`

Luego úsalo:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"