---
name: extraccion-documentos
description: >
  Extracción de contenido de documentos binarios (PDF, DOCX, PPTX, imágenes)
  a Markdown usando MinerU. Soporta MCP (parse_documents), CLI (mineru-open-api)
  y modo flash sin token. Cargar cuando el usuario pida leer, analizar o extraer
  contenido de archivos PDF, Word, PowerPoint o imágenes con texto.
version: "1.0.0"
herramientasPermitidas: [Read, Bash, Grep]
evolvable: true  # default para skill estandar
exclusiones:
  - "No cargar para leer archivos de texto plano (.txt, .md, .csv, .json) — el Read tool los maneja directamente sin necesidad de MinerU."
  - "No cargar para OCR de imágenes de alta precisión con modelos propios — para pipelines OCR especializados (Tesseract, Azure Form Recognizer) cargar el skill del proveedor correspondiente."
  - "No cargar para extracción de datos estructurados de PDFs con formularios (XFA, AcroForm) — MinerU convierte a Markdown pero no preserva la estructura de formularios."
  - "No cargar si la tarea es convertir documentos a formatos distintos de Markdown (DOCX→HTML, PDF→DOCX) — para conversión de formatos cargar `swl-markitdown` o el skill del pipeline de documentos."
---
# Extracción de documentos con MinerU

## Cuándo NO cargar

- La tarea es leer un archivo `.txt`, `.md`, `.csv` o `.json`: usar el Read tool directamente.
- El pipeline requiere OCR con modelo propio (Tesseract, Azure Form Recognizer, AWS Textract): cargar el skill del proveedor correspondiente.
- El PDF es un formulario con campos XFA o AcroForm y se necesita preservar la estructura de campos: MinerU no soporta esto.
- La conversión requerida es de formato (DOCX→HTML, PDF→DOCX), no extracción de contenido: cargar `swl-markitdown` o el skill de conversión de documentos.

## Cuándo activar

- El usuario pide leer, analizar o extraer contenido de un PDF
- El usuario proporciona un archivo .docx, .pptx, .doc, .ppt
- El usuario quiere convertir un documento a Markdown
- Se necesita leer una especificación, contrato o documento de requisitos
- El investigador-swl o arquitecto-swl necesitan analizar documentación existente
- El usuario dice "extrae", "lee este PDF", "convierte a texto", "analiza este documento"

## Estrategia de extracción (orden de prioridad)

### 1. MCP MinerU (preferido si está configurado)

Verificar si el MCP está disponible:

```
Buscar en .mcp.json la entrada "mineru"
```

Si existe, usar directamente:

```
mcp__mineru__parse_documents(file_sources=["ruta/al/archivo.pdf"])
```

Ventajas: integrado en Claude Code, sin salir del flujo, soporta múltiples archivos.

### 2. CLI mineru-open-api (alternativa sin MCP)

Verificar si el CLI está instalado:

```bash
mineru-open-api version 2>/dev/null
```

Si existe, usar según el caso:

| Situación | Comando |
|-----------|---------|
| Archivo pequeño (< 10 MB, < 20 págs) | `mineru-open-api flash-extract archivo.pdf` |
| Archivo grande o con tablas | `mineru-open-api extract archivo.pdf` (requiere token) |
| Página web | `mineru-open-api crawl https://url` |
| Múltiples archivos | `mineru-open-api extract *.pdf -o ./salida/` |

### 3. Herramienta Read nativa (último recurso)

Si no hay MCP ni CLI, la herramienta Read de Claude Code puede leer PDFs
directamente (con limitaciones de páginas). Usar como último recurso.

> **Dependencia externa**: MinerU (MCP o CLI) no se incluye en la instalación
> de SWL. Es un componente externo que cada equipo debe instalar por separado.
> SWL instala la configuración del MCP y este skill, pero el servidor o CLI
> de MinerU es responsabilidad del equipo. El skill detecta automáticamente
> la disponibilidad y selecciona el mejor modo sin intervención del usuario.

## Decisión flash-extract vs extract

| Usar flash-extract cuando | Usar extract cuando |
|--------------------------|-------------------|
| No hay token configurado | Hay token y se necesita precisión |
| Archivo < 10 MB y < 20 páginas | Archivo > 10 MB o > 20 páginas |
| Solo se necesita Markdown | Se necesita DOCX, HTML o LaTeX |
| No importan tablas/fórmulas | Hay tablas o fórmulas importantes |
| Primera vez del usuario | El usuario ya tiene token |
| Documento digital (texto nativo) | Documento escaneado o con firmas/sellos |
| Texto simple sin formato denso | Texto legal, actas o documentos oficiales |

> **Limitación conocida de flash-extract**: En documentos escaneados, con firmas
> manuscritas, sellos oficiales o texto legal denso en español, flash-extract
> produce resultados con texto truncado, palabras fusionadas y caracteres faltantes.
> Para estos documentos, se recomienda usar `extract` con token (registro gratuito
> en https://mineru.net/apiManage/token). Si el usuario reporta mala calidad de
> extracción y no tiene token, sugerir el registro y configurar con
> `mineru-open-api auth`.

## Configuración del MCP

Para habilitar el MCP de MinerU en un proyecto, agregar a `.mcp.json`:

```json
{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": ["mineru-open-mcp"],
      "env": {
        "MINERU_API_TOKEN": "tu_token_aqui"
      }
    }
  }
}
```

Sin token, el MCP usa modo Flash automáticamente (gratis, sin registro).

Con token (obtener en https://mineru.net/apiManage/token), habilita extracción
de precisión con tablas, fórmulas y formatos adicionales.

## Configuración del token para extract

El modo `extract` requiere un token gratuito de https://mineru.net/apiManage/token.

**Configurar vía variable de entorno** (recomendado — funciona en Claude Code):

```bash
# Linux / macOS — agregar a ~/.bashrc o ~/.zshrc
export MINERU_TOKEN="tu_token_aqui"

# Windows PowerShell — persistente a nivel de usuario
[System.Environment]::SetEnvironmentVariable("MINERU_TOKEN", "tu_token_aqui", "User")
```

**Verificar que el token funciona**:

```bash
mineru-open-api auth --verify
# Debe mostrar: Token format is valid / Source: env
```

> **Nota**: El comando `mineru-open-api auth` (modo interactivo) no funciona
> dentro de Claude Code porque requiere entrada interactiva. Usar siempre la
> variable de entorno `MINERU_TOKEN` como método de configuración.

Para el MCP, el token se configura en `.mcp.json` con la variable `MINERU_API_TOKEN`
como se muestra en la sección anterior.

## Instalación del CLI

```bash
# Linux / macOS
curl -fsSL https://cdn-mineru.openxlab.org.cn/open-api-cli/install.sh | sh

# Windows (PowerShell) — descargar, inspeccionar y ejecutar
Invoke-WebRequest -Uri https://cdn-mineru.openxlab.org.cn/open-api-cli/install.ps1 -OutFile install-mineru.ps1
Get-Content install-mineru.ps1   # inspeccionar
.\install-mineru.ps1             # ejecutar
Remove-Item install-mineru.ps1   # limpiar
```

> Algunos antivirus bloquean `irm URL | iex` con detección heurística. La alternativa manual de arriba evita el bloqueo.

## Formatos soportados

| Formato | flash-extract | extract |
|---------|:---:|:---:|
| PDF (.pdf) | Sí | Sí |
| Imágenes (.png, .jpg, .jpeg) | Sí | Sí |
| Word (.docx) | Sí | Sí |
| Word (.doc) | No | Sí |
| PowerPoint (.pptx) | Sí | Sí |
| PowerPoint (.ppt) | No | Sí |
| HTML (.html) | No | Sí |
| URLs remotas | Sí | Sí |

## Integración con agentes SWL

| Agente | Uso de extracción |
|--------|------------------|
| `investigador-swl` | Leer especificaciones, papers, documentos de referencia en PDF |
| `arquitecto-swl` | Analizar documentos de arquitectura existentes |
| `mapear-codebase` | Incluir documentación no-código del proyecto |
| `producto-prd-swl` | Extraer requisitos de documentos del cliente |
| `revisor-seguridad-swl` | Leer políticas de seguridad en PDF |

## Idiomas soportados

| Código | Idiomas |
|--------|---------|
| `ch` | Chino, Inglés (predeterminado) |
| `en` | Inglés |
| `latin` | Español, Francés, Alemán, Portugués, Italiano y 40+ idiomas latinos |
| `arabic` | Árabe, Persa, Urdu |
| `cyrillic` | Ruso, Ucraniano, Búlgaro |
| `devanagari` | Hindi, Marathi, Nepali |

Para documentos en español: usar `--language latin` en el CLI.

## Manejo de errores

| Error | Causa | Solución |
|-------|-------|---------|
| Archivo > 10 MB en flash | Límite de flash-extract | Usar `extract` con token |
| Archivo > 20 páginas en flash | Límite de flash-extract | Usar `extract` con token |
| HTTP 429 | Rate limit por IP | Esperar o usar `extract` con token |
| "no API token found" | Token no configurado | `mineru-open-api auth` o variable `MINERU_TOKEN` |
| Tablas no extraídas | flash-extract no soporta tablas | Usar `extract` con token |

## Gotchas / Errores comunes no obvios

**`flash-extract` en documentos escaneados en español produce texto con palabras fusionadas y caracteres faltantes aunque el PDF parezca digital**: muchos PDFs "digitales" en México (contratos, actas) son en realidad imágenes escaneadas incrustadas. Flash no tiene OCR de precisión y entrega texto ilegible sin error visible. Causa: `flash-extract` no distingue si el PDF contiene texto nativo o imágenes rasterizadas. Fix: si el output de flash tiene palabras sin espacios o texto truncado, cambiar a `extract` con token inmediatamente. Señal temprana: `mineru-open-api flash-extract` devuelve Markdown con menos de 50 palabras para un documento de 10+ páginas.

**El MCP de MinerU falla silenciosamente cuando `MINERU_API_TOKEN` está vacío en `.mcp.json`**: si la variable de entorno `MINERU_API_TOKEN` no está configurada, el MCP arranca en modo flash pero no emite error — simplemente produce output de menor calidad sin advertir. Causa: el MCP asume que la ausencia de token es intencional (modo gratuito). Fix: verificar que el MCP está usando token con `claude-notifications-go status` o inspeccionando el output: si `parse_documents` devuelve chunks de menos de 100 tokens para páginas densas, el token no está activo. Configurar `MINERU_API_TOKEN` en el `.env` del proyecto y reiniciar el MCP.

**`mineru-open-api extract *.pdf` procesa los archivos en paralelo y puede saturar la quota de la API si hay más de 5 PDFs**: el comando acepta glob pero lanza todas las peticiones concurrentemente. Con 10+ PDFs, el servidor devuelve HTTP 429 y algunos archivos quedan con extracción incompleta sin error claro. Causa: el CLI no tiene rate limiting incorporado. Fix: procesar en lotes secuenciales con un bucle: `for f in *.pdf; do mineru-open-api extract "$f" -o ./salida/; sleep 2; done`.

**La ruta de salida por defecto de `extract` crea subdirectorios por archivo y el agente no encuentra el Markdown resultante**: `mineru-open-api extract contrato.pdf` crea `./contrato/contrato.md` (no `./contrato.md`). Si el agente busca `contrato.md` directamente, no lo encuentra. Causa: MinerU crea un directorio con el nombre del archivo para agrupar el Markdown y los recursos (imágenes, tablas). Fix: usar `-o ./salida/` y luego buscar con `find ./salida -name "*.md"`, o especificar la ruta completa de destino con `--output-file` si la versión del CLI lo soporta.
