PDF Deep Reader Skill

English · Español

---

English

pdf-deep-reader is an Agent Skills compatible skill for local-first, token-frugal PDF understanding. It extracts and structures PDFs or long pasted PDF text into cached Markdown/JSON files, then lets an agent retrieve only the relevant fragments for cited answers.

The helper code is now TypeScript. PDF extraction uses local pdftotext from Poppler; pasted/extracted text can be indexed without PDF tooling.

Repository layout

pdf-deep-reader-skill/
├── package.json
├── tsconfig.json
├── README.md
├── SECURITY.md
├── scripts/
│   └── validate.ts
└── skills/
    └── pdf-deep-reader/
        ├── package.json
        ├── tsconfig.json
        ├── SKILL.md
        └── scripts/
            └── pdf_tool.ts

Installation

Pi, from GitHub

pi install git:github.com/manrods/pdf-deep-reader-skill

Restart Pi after installing so the skill is discovered.

Manual install for Pi or compatible agents

Copy the skill directory:

mkdir -p ~/.pi/agent/skills
cp -r skills/pdf-deep-reader ~/.pi/agent/skills/
pnpm --dir ~/.pi/agent/skills/pdf-deep-reader install
pnpm --dir ~/.pi/agent/skills/pdf-deep-reader build

Repository development

pnpm install
pnpm run typecheck
pnpm run build
pnpm run validate

Usage examples from the repository root

Prepare a PDF:

pnpm run build
pnpm pdf-tool -- prepare "file.pdf"

Prepare a directory of PDFs:

pnpm pdf-tool -- prepare "path/to/folder"

Prepare long pasted PDF text saved to a text file:

pnpm pdf-tool -- prepare-text --text-file pasted.txt --name source-name

Search cached chunks:

pnpm pdf-tool -- search "file.pdf" "your question" --top 8

Show selected chunks:

pnpm pdf-tool -- show "file.pdf" p0012-c00

Print diagnostics or the document map:

pnpm pdf-tool -- manifest "file.pdf"
pnpm pdf-tool -- map "file.pdf"

Generated cache files

By default, cache files are written to .pi/pdf-cache/ in the current project. You can use a global cache with --cache global.

Each processed document may generate:

• manifest.json — diagnostics, parser, confidence, warnings;
• document.md — extracted readable document, unless --no-raw-text is used;
• document-map.md — compact page/section/table/figure map;
• pages.jsonl — per-page extracted text and confidence;
• sections.jsonl — detected sections;
• tables.jsonl — extracted tables when possible;
• figures.jsonl — detected/extracted figures and captions when possible;
• chunks.jsonl — retrieval chunks with metadata;
• assets/ — extracted images, when supported by the local helper.

Local dependencies

• Node.js 20+ and pnpm for building/running the TypeScript helper.
• Poppler pdftotext for direct PDF extraction.

The helper does not install system dependencies automatically. If pdftotext is unavailable, use prepare-text with already extracted text or install Poppler manually.

Security and privacy summary

• Local-first: no cloud upload behavior is built into the helper script.
• No automatic dependency installation.
• PDF/text contents are treated as untrusted data.
• The skill does not pre-approve shell execution via allowed-tools.
• Runtime caches and extracted PDF content are ignored by git.

Read SECURITY.md before installing or running the helper on sensitive documents.

---

Español

pdf-deep-reader es una skill compatible con Agent Skills para entender PDFs de forma local y minimizando tokens. Extrae y estructura PDFs o texto largo pegado desde un PDF en archivos Markdown/JSON cacheados, y luego permite que el agente recupere solo los fragmentos relevantes para responder con citas.

El código auxiliar ahora está en TypeScript. La extracción directa de PDFs usa pdftotext de Poppler de forma local; el texto pegado o ya extraído puede indexarse sin herramientas de PDF.

Estructura del repositorio

pdf-deep-reader-skill/
├── package.json
├── tsconfig.json
├── README.md
├── SECURITY.md
├── scripts/
│   └── validate.ts
└── skills/
    └── pdf-deep-reader/
        ├── package.json
        ├── tsconfig.json
        ├── SKILL.md
        └── scripts/
            └── pdf_tool.ts

Instalación

Pi, desde GitHub

pi install git:github.com/manrods/pdf-deep-reader-skill

Reinicia Pi después de instalar para que detecte la skill.

Instalación manual para Pi o agents compatibles

Copia la carpeta de la skill:

mkdir -p ~/.pi/agent/skills
cp -r skills/pdf-deep-reader ~/.pi/agent/skills/
pnpm --dir ~/.pi/agent/skills/pdf-deep-reader install
pnpm --dir ~/.pi/agent/skills/pdf-deep-reader build

Desarrollo del repositorio

pnpm install
pnpm run typecheck
pnpm run build
pnpm run validate

Ejemplos de uso desde la raíz del repositorio

Preparar un PDF:

pnpm run build
pnpm pdf-tool -- prepare "archivo.pdf"

Preparar una carpeta con PDFs:

pnpm pdf-tool -- prepare "ruta/a/carpeta"

Preparar texto largo pegado desde un PDF y guardado como archivo:

pnpm pdf-tool -- prepare-text --text-file pegado.txt --name nombre-fuente

Buscar chunks cacheados:

pnpm pdf-tool -- search "archivo.pdf" "tu pregunta" --top 8

Mostrar chunks seleccionados:

pnpm pdf-tool -- show "archivo.pdf" p0012-c00

Imprimir diagnóstico o mapa del documento:

pnpm pdf-tool -- manifest "archivo.pdf"
pnpm pdf-tool -- map "archivo.pdf"

Archivos de caché generados

Por defecto, la caché se guarda en .pi/pdf-cache/ dentro del proyecto actual. Puedes usar caché global con --cache global.

Cada documento procesado puede generar:

• manifest.json — diagnóstico, parser, confianza, advertencias;
• document.md — documento legible extraído, salvo que se use --no-raw-text;
• document-map.md — mapa compacto de páginas/secciones/tablas/figuras;
• pages.jsonl — texto extraído por página y confianza;
• sections.jsonl — secciones detectadas;
• tables.jsonl — tablas extraídas cuando sea posible;
• figures.jsonl — figuras/captions detectadas o extraídas cuando sea posible;
• chunks.jsonl — fragmentos recuperables con metadata;
• assets/ — imágenes extraídas, cuando el helper local lo soporte.

Dependencias locales

• Node.js 20+ y pnpm para compilar/ejecutar el helper TypeScript.
• Poppler pdftotext para extracción directa de PDFs.

El helper no instala dependencias del sistema automáticamente. Si pdftotext no está disponible, usa prepare-text con texto ya extraído o instala Poppler manualmente.

Resumen de seguridad y privacidad

• Local-first: el script auxiliar no incluye comportamiento de subida a la nube.
• No instala dependencias automáticamente.
• El contenido de PDFs/textos se trata como dato no confiable.
• La skill no preautoriza ejecución de shell mediante allowed-tools.
• Las cachés runtime y el contenido extraído de PDFs están ignorados por git.

Lee SECURITY.md antes de instalar o ejecutar el helper sobre documentos sensibles.