document-granular-decompose — Claude Code skill: how to install
document-granular-decompose sends local documents to the TianGong AI Unstructure /mineru_with_images endpoint and returns raw fulltext without extra JSON markup.
MIT 113 installs ★ 11 updated 2026-10-19
npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a claude-codeWhat document-granular-decompose does
This skill triggers scripts/mineru_fulltext_extract.py to upload local files to the /mineru_with_images endpoint via a multipart request. It forces return_txt=true on every API call. The script pulls text directly from response.txt or falls back to joining non-empty chunks from response.result[].text. It also normalizes upstream Markdown underscores, converting \_ back to _.
A strict allowlist validates document types before making network calls. Supported formats include PDF, image formats like .png and .jpg, plus common Office files such as .docx or .xlsx. Any unlisted file extension causes an immediate local error.
Without UNSTRUCTURED_API_BASE_URL and UNSTRUCTURED_AUTH_TOKEN present in the environment, the script exits immediately. Overriding the backend model remains optional through UNSTRUCTURED_PROVIDER and UNSTRUCTURED_MODEL.
What it helps with
- extract plain fulltext from PDF and Office files using MinerU
- filter out unsupported extensions locally before making network calls
- pipe parsed text to stdout or write directly to a file
- configure Unstructure API authentication through environment variables
Example prompts for the agent
- Extract plain text from
annual_report.pdfusing document-granular-decompose - Parse
presentation.pptxwith document-granular-decompose and save the result tooutput.txt
How to install document-granular-decompose
1Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a claude-code2Manually: put the files in place
~/.claude/skills/document-granular-decompose/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/document-granular-decompose/
1Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a codex2Manually: put the files in place
.agents/skills/document-granular-decompose/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a cursor2Manually: put the files in place
.cursor/skills/document-granular-decompose/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install tiangong-ai/agent-skills document-granular-decompose2Manually: put the files in place
.github/skills/document-granular-decompose/SKILL.md1Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a gemini-cli2Platform CLI
gemini skills install https://github.com/tiangong-ai/agent-skills --path document-granular-decomposeManually: put the files in place
.devin/skills/document-granular-decompose/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about document-granular-decompose
How to install document-granular-decompose in Claude Code?
Run npx skills add tiangong-ai/agent-skills --skill document-granular-decompose -a claude-code. This saves the configuration to ~/.claude/skills/document-granular-decompose/SKILL.md.
What does document-granular-decompose do?
It sends local files to the TianGong AI Unstructure /mineru_with_images endpoint and outputs fulltext extracted with MinerU.
Which environment variables are required?
You must export UNSTRUCTURED_API_BASE_URL with your service endpoint and UNSTRUCTURED_AUTH_TOKEN with the bearer token. Settings for UNSTRUCTURED_PROVIDER and UNSTRUCTURED_MODEL are optional.
Source text
SKILL.md · MIT
--- name: document-granular-decompose description: Upload local documents to TianGong AI Unstructure `/mineru_with_images` API for fine-grained parsing and return only plain fulltext content. Use when a task needs document fulltext extraction with `return_txt=true`, strict file-type allowlist validation, API base URL/auth token from environment variables, and optional provider/model overrides. --- # Document Granular Decompose ## Core Goal - Parse a local document through `POST /mineru_with_images`. - Always force `return_txt=true`. - Read environment variables for endpoint, request identity, and model routing: - `UNSTRUCTURED_API_BASE_URL` (example: `https://your-unstructured-host:7770`) - `UNSTRUCTURED_AUTH_TOKEN` - `UNSTRUCTURED_PROVIDER` (optional) - `UNSTRUCTURED_MODEL` (optional) - Return only plain fulltext (prefer API `txt`; fallback to joined `result[].text`). ## Triggering Conditions - Need robust document fulltext extraction for PDF/Office/image files. - Need image-aware MinerU parsing but only textual output for downstream chunking/search/summarization. - Need to standardize provider/model/token input via environment variables instead of ad-hoc command parameters. ## Workflow 1. Prepare environment variables. ```bash export UNSTRUCTURED_AUTH_TOKEN="your-fastapi-bearer-token" export UNSTRUCTURED_API_BASE_URL="https://your-unstructured-host:7770" # Optional routing overrides. Omit them to let the server choose its defaults. export UNSTRUCTURED_PROVIDER="vllm" export UNSTRUCTURED_MODEL="Qwen/Qwen3.5-122B-A10B-FP8" ``` 2. Run extraction and print fulltext to stdout. ```bash python3 scripts/mineru_fulltext_extract.py \ --file "/absolute/path/to/document.pdf" ``` 3. Save fulltext to a local file when needed. ```bash python3 scripts/mineru_fulltext_extract.py \ --file "/absolute/path/to/document.pdf" \ --output "/absolute/path/to/fulltext.txt" ``` ## Request Contract - Endpoint resolution: - `--api-url` if provided - else `UNSTRUCTURED_API_BASE_URL + /mineru_with_images` - else fail fast with missing environment variable error - Method: `POST` multipart form. - Query params: - Force `return_txt=true` (always set by script). - Form fields sent: - `file` (required) - `provider` (optional, from `UNSTRUCTURED_PROVIDER` when set) - `model` (optional, from `UNSTRUCTURED_MODEL` when set) - Header sent: - `Authorization: Bearer $UNSTRUCTURED_AUTH_TOKEN` ## Supported File Types (Strict) - Supported file types: - `.bmp, .doc, .docm, .docx, .dot, .dotx, .gif, .jp2, .jpeg, .jpg, .odp, .odt, .pdf, .png, .pot, .potx, .pps, .ppsx, .ppt, .pptm, .pptx, .tiff, .webp, .xls, .xlsm, .xlsx, .xlt, .xltx` - Office formats: - `.doc, .docm, .docx, .dot, .dotx, .odp, .odt, .pot, .potx, .pps, .ppsx, .ppt, .pptm, .pptx, .xls, .xlsm, .xlsx, .xlt, .xltx` - Any other extension is rejected before sending API requests. ## Output Rules - Success output must be plain text fulltext only. - Normalize the confirmed upstream Markdown underscore escape (`\_` to `_`) in both supported response paths; preserve other backslashes and escapes. - Fulltext source priority: 1. `response.txt` 2. join non-empty `response.result[].text` by blank lines - Do not output chunk metadata/json unless the user explicitly requests debugging. ## Error Handling - Missing required env vars (`UNSTRUCTURED_API_BASE_URL`, `UNSTRUCTURED_AUTH_TOKEN`): fail fast with actionable message. - Missing `UNSTRUCTURED_PROVIDER` or `UNSTRUCTURED_MODEL`: omit the form field and let the service choose its default. - HTTP 401/403: report token/auth issue. - HTTP 4xx/5xx: print status and API error body if available. - Missing text in response: fail with explicit schema mismatch error. ## References - `references/env.md` - `references/request-response.md` ## Assets - `assets/config.example.env` ## Scripts - `scripts/mineru_fulltext_extract.py`
© tiangong-ai · MIT · tiangong-ai/agent-skills