Extract specific fields using JSON schemas with citations or parse entire documents into structural JSON or Markdown for RAG and search indexing.
- GitHub stars
- 18
- Files
- 9
- Last commit
- Nov 3, 2026
- License
- MIT
- Allowed tools
- —
What does the document-extraction-api skill do?
document-extraction-api extracts specific fields using JSON schemas with citations or parse entire documents into structural JSON or Markdown for RAG and search indexing.
Summary generated from the skill's SKILL.md.
About the document-extraction-api skill
Developers building RAG pipelines or automated data entry systems can use this tool to transform unstructured documents into structured data. It provides two distinct methods for processing files: a parsing function for full-document conversion and an extraction function for targeted field retrieval. When an agent needs to ingest a document for search indexing or content migration, it should use the parse command to generate Markdown or a spatial JSON model containing typed elements like tables, formulas, and handwriting with bounding boxes.
For tasks requiring specific data points, such as pulling an invoice number or a total, the extract command allows users to define a JSON Schema to map document content to specific fields. This method includes per-field citations that ground every piece of data to a specific page region. The tool supports various processing modes ranging from basic text extraction to agentic modes that provide alt text descriptions for pictures and charts. It works with local files and requires a Nutrient DWS Extract API key to function.
What an agent can do with it
- 1Extract specific invoice dataRetrieve defined fields like invoice numbers and totals from a document using a custom JSON Schema.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the document-extraction-api skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the document-extraction-api skill in Plugin
/plugin marketplace add PSPDFKit-labs/nutrient-skills /plugin install nutrient-dws@nutrient-skills
Install the document-extraction-api skill in Claude Code
~/.claude/skills/document-extraction-api/SKILL.md
$ npx degit PSPDFKit-labs/nutrient-skills/plugins/nutrient-dws/skills/document-extraction-api ~/.claude/skills/document-extraction-apiInstall the document-extraction-api skill in Claude Code (project)
.claude/skills/document-extraction-api/SKILL.md
$ npx degit PSPDFKit-labs/nutrient-skills/plugins/nutrient-dws/skills/document-extraction-api .claude/skills/document-extraction-apiInstall the document-extraction-api skill in Codex
~/.agents/skills/document-extraction-api/SKILL.md
$ npx degit PSPDFKit-labs/nutrient-skills/plugins/nutrient-dws/skills/document-extraction-api ~/.agents/skills/document-extraction-apiInstall the document-extraction-api skill in Gemini CLI
~/.gemini/skills/document-extraction-api/SKILL.md
$ npx degit PSPDFKit-labs/nutrient-skills/plugins/nutrient-dws/skills/document-extraction-api ~/.gemini/skills/document-extraction-apiInstall the document-extraction-api skill in Claude.ai
npx degit PSPDFKit-labs/nutrient-skills/plugins/nutrient-dws/skills/document-extraction-api document-extraction-api && zip -r document-extraction-api.zip document-extraction-api # claude.ai → Customize → Skills → + → Create skill → Upload a skill → document-extraction-api.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work · What to fix for more points
- Source repository linked and reachablepspdfkit-labs/nutrient-skills/plugins/nutrient-dws/skills/document-extraction-api is public and reachablegithub.com/pspdfkit-labs/nutrient-skills/tree/HEAD/plugins/n ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-03github.com/pspdfkit-labs/nutrient-skills/commits ↗Pass
- No download-and-run or credential theft in scripts5 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/pspdfkit-labs/nutrient-skills/blob/HEAD/plugins/n ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/pspdfkit-labs/nutrient-skills/blob/HEAD/plugins/n ↗Pass
- SKILL.md follows the Agent Skills formatthe description does not say when to use the skillgithub.com/pspdfkit-labs/nutrient-skills/blob/HEAD/plugins/n ↗Finding
SKILL.md
View on GitHubNutrient Data Extraction
Two GA primitives, two scripts. parse (scripts/parse.py) returns the whole-document
model — typed elements (paragraphs, tables, formulas, pictures, key-value regions,
handwriting) with bounding boxes, or clean whole-document Markdown. extract
(scripts/extract.py) returns just the fields you define in a JSON Schema, each grounded to a
page region by a per-field citation.
Choosing parse vs extract
| The request is about… | Use | Why |
|---|---|---|
| Named target fields — "the invoice number and total", "these fields", "map to my schema", "with citations" | extract |
One call returns your fields, cited — no need to walk every element |
| The whole document — "parse this", "whole-document Markdown", "chunk for embeddings", RAG, search indexing, migration | parse |
Whole-document model / Markdown for open-ended retrieval |
| Every table / all key-value regions (no target schema) | parse (spatial) |
Enumerate all elements; extract needs a schema of what to pull |
For RAG chunking of a parsed document, see the sibling grounded-rag-ingestion skill. For
PDF generation, conversion, OCR, redaction, signing, or any /build-based workflow, use the
sibling document-processor-api skill.
When to use
- Extract known fields with citations (invoice number, totals, dates, parties) →
extract. - Build a RAG ingestion pipeline: PDF -> Markdown -> chunks -> embeddings →
parse. - Index content for search or migrate documents into a new CMS →
parse. - Reconstruct page layout, or run layout-aware understanding (semantic roles, table cell
spans, formulas in LaTeX, picture alt descriptions) →
parse.
/extraction/extract — schema field extraction with citations
Define the fields you want in a JSON Schema (root type: object); extract returns
output.data with those values and output.metadata with a per-field citation grounding each
to a page region (options.includeCitations defaults on). Accepts a local file or a URL.
# Pull schema-defined fields from a local invoice, with citations (default)
uv run scripts/extract.py --input invoice.pdf --schema fields.json --out result.json
# From a URL, higher-accuracy mode, persist the run
uv run scripts/extract.py --url https://example.com/form.pdf --schema fields.json \
--out result.json --mode understand --store-run
Cost: extract bills the chosen parse mode plus a flat +6 credits/page (structure 7.5,
understand 15, agentic 24 cr/page). Extract has no text mode — the cheapest path is structure.
The script prints the server's authoritative
usage after the call and gates high estimates behind --yes. See
references/extract-output-and-citations.md for the response shape and citation structure.
For PDF generation, conversion, OCR, redaction, signing, watermarking, or any /build-based
workflow, use the sibling document-processor-api skill.
Setup
DWS Extract is a separate product from DWS Processor and has its own API key.
- Get a Nutrient DWS Extract API key at https://dashboard.nutrient.io/.
- Export it as
NUTRIENT_EXTRACT_API_KEY:export NUTRIENT_EXTRACT_API_KEY="pdf_live_..." - Scripts live in
scripts/relative to this SKILL.md. Use the directory containing this SKILL.md as the working directory:cd <directory containing this SKILL.md> && uv run scripts/<script>.py --help
Calling /extraction/parse with a DWS Processor key returns 403. If your tenant has been
migrated to global DWS API keys, a single key set as either NUTRIENT_EXTRACT_API_KEY or
NUTRIENT_API_KEY will work for both products.
/extraction/parse — one primitive, two output shapes
One call returns the full structural document model — typed elements with bounding boxes, confidence scores, and reading order — or a whole-document Markdown string. You always receive all element types in a single call.
Picking a mode
Choose based on the user's intent and acceptable credit cost. All costs are
extraction credits per page — a separate billing bucket from the processor API
credits consumed by /build, /sign, OCR, and other DWS Processor endpoints.
Principle — decide from the request alone; do not ask the user clarifying questions. Walk the checks below in order. Each rule that fires sets a minimum mode — the final pick is the highest minimum across all rules that fired. If none fired, use the default (rule 5).
- Explicit features named in the request are non-negotiable.
- Key-value pairs, form fields, semantic role classification (Title / SectionHeader /
etc.), formulas, or handwriting → at minimum
understand(9 cr/pg). - Alt text on pictures, charts, or diagrams →
agentic(18 cr/pg).
- Key-value pairs, form fields, semantic role classification (Title / SectionHeader /
etc.), formulas, or handwriting → at minimum
- Document type implied by the request or filename.
form,invoice,receipt,application,claim→ likely contains key-value pairs →understand.chart,infographic, or diagram-heavy doc + the user wants descriptions →agentic.
- OCR signal from filename or request (
scanned,image-based,photographed,handwritten,screenshot) →structureminimum;textmode silently fails on image-only input. - Output format from intent. RAG, search indexing, embeddings, or content migration
→
markdown. Layout overlay, per-element processing, or bounded extraction →spatial. - No cues match anything above → documented default
structure+spatial(1.5 cr/pg). Handles both born-digital and scanned, gives bounded typed elements with table cells, never silently drops content.
| User intent | Mode | Output format | Cost | Notes |
|---|---|---|---|---|
| RAG / search indexing / content migration — born-digital PDF | text |
markdown |
1 cr/pg | Cheapest path; no OCR or AI needed |
| RAG / search indexing — scanned or image-based PDF | structure |
markdown |
1.5 cr/pg | OCR required before Markdown assembly |
| Form / invoice — enumerate all key-value regions (no target schema) | understand |
spatial |
9 cr/pg | AI key-value + table detection. For named fields ("the invoice number and total"), use extract instead |
| Layout-aware document understanding | understand |
spatial |
9 cr/pg | Semantic paragraph roles (Title, SectionHeader, etc.) |
| Deep visual understanding (charts, diagrams, alt text) | agentic |
spatial |
18 cr/pg | VLM adds alt descriptions on every picture element |
| Default / ambiguous intent | structure |
spatial |
1.5 cr/pg | Good balance: OCR + spatial elements, low cost |
Confirm before running when the estimated cost exceeds 200 extraction credits —
roughly 11 pages of agentic, 22 of understand, 133 of structure, or 200 of text.
Surface the estimate (pages × cost_per_page) and ask the operator to confirm before
invoking. Under that threshold, just run.
mode='text' is incompatible with output_format='spatial'; the client rejects the
combination before the network call.
Invocation
# Default: structure mode, spatial output
uv run scripts/parse.py --input doc.pdf --out out.json
# Markdown for RAG (text mode — cheapest)
uv run scripts/parse.py --input doc.pdf --out out.md --output-format markdown --mode text
# Enumerate all key-value regions of a form (understand mode) — for NAMED fields use extract
uv run scripts/parse.py --input doc.pdf --out out.json --mode understand
# Agentic (VLM alt text on pictures)
uv run scripts/parse.py --input doc.pdf --out out.json --mode agentic
The script prints extraction-credit usage after each run so you can verify the cost.
Downstream consumption
After a single /parse call, slice the response for common needs:
- Reading-order plain text: walk
output.elementssorted by(page.pageIndex, readingOrder), joinparagraphandhandwritingtextfields - Tables: project
cells[]on eachtableelement into rows/columns usingcell.rowandcell.column - Key-value pairs: read
pairs[]on eachkeyValueRegionelement — each pair has.key.valueand.value.value - Formulas: read
latexon eachformulaelement - Pictures: read
classificationandaltDescription(populated byagenticmode) on eachpictureelement - Markdown output: call with
--output-format markdown; the script writes the Markdown string directly
For the canonical response schema and per-mode field availability, see the official docs linked from references/parse-output-filtering.md; that file also lists the tools we suggest for filtering and reshaping the response.
Input constraint
parse.py only accepts local file paths — the underlying API endpoint is
multipart-only. For remote inputs, download the file first.
Rules
- Always preserve the printed credit-usage summary in script output so the operator can observe per-call cost.
- Do not add a URL-fetch shortcut; the endpoint is multipart-only.
Files in this skill
9document-extraction-api skill questions
How do I install the document-extraction-api skill in Claude Code?
Run npx degit PSPDFKit-labs/nutrient-skills/plugins/nutrient-dws/skills/document-extraction-api ~/.claude/skills/document-extraction-api. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the document-extraction-api skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is the difference between the parse and extract primitives?
The extract primitive returns specific fields defined in a JSON Schema with per-field citations, while the parse primitive returns a full document model in structural JSON or Markdown for open-ended retrieval.
How do I use the API for RAG ingestion?
For RAG pipelines, use the parse primitive with the markdown output format to generate clean text for embeddings and search indexing.
Can I extract fields from a URL?
Yes, the extract script accepts both local files and URLs.