mapping-documents
/mapping-documents
Generate navigable semantic maps from PDF documents. Extracts section structure via font analysis, then runs LLM extraction per section for claims, symbols, and dependencies — all page-anchored. Produces _MAP.md (progressive disclosure), .symbols.json (definition index), .anchors.json (claim references), and a _USAGE.md snippet for CLAUDE.md. Use when analyzing papers, specs, or legal docs; when asked to "map this document", "index this PDF", "what does this paper say"; or when a coding agent needs grounded reference material from a PDF source. Analogous to tree-sitting but for prose documents
- Author
- oaustegard ↗
- Repository
- claude-skills ↗
- Licence
- MIT
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/docmap.py
What it does and when to use it
Generate navigable semantic maps from PDF documents. Extracts section structure via font analysis, then runs LLM extraction per section for claims, symbols, and dependencies — all page-anchored. Produces _MAP.md (progressive disclosure), .symbols.json (definition index), .anchors.json (claim references), and a _USAGE.md snippet for CLAUDE.md. Use when analyzing papers, specs, or legal docs; when asked to "map this document", "index this PDF", "what does this paper say"; or when a coding agent needs grounded reference material from a PDF source. Analogous to tree-sitting but for prose documents
Triggers from the description
Original author description
Generate navigable semantic maps from PDF documents. Extracts section structure via font analysis, then runs LLM extraction per section for claims, symbols, and dependencies — all page-anchored. Produces _MAP.md (progressive disclosure), .symbols.json (definition index), .anchors.json (claim references), and a _USAGE.md snippet for CLAUDE.md. Use when analyzing papers, specs, or legal docs; when asked to "map this document", "index this PDF", "what does this paper say"; or when a coding agent needs grounded reference material from a PDF source. Analogous to tree-sitting but for prose documents
How it works
- Installation
- Generate Maps
- Output Artifacts
- After Generating: Wire It Up
- Navigate Via Maps
- Genre Support
- Limitations (v0.1.x)
- CLI Reference
SKILL.md preview
---
name: mapping-documents
description: Generate navigable semantic maps from PDF documents. Extracts section structure via font analysis, then runs LLM extraction per section for claims, symbols, and dependencies — all page-anchored. Produces _MAP.md (progressive disclosure), .symbols.json (definition index), .anchors.json (claim references), and a _USAGE.md snippet for CLAUDE.md. Use when analyzing papers, specs, or legal docs; when asked to "map this document", "index this PDF", "what does this paper say"; or when a coding agent needs grounded reference material from a PDF source. Analogous to tree-sitting but for prose documents.
metadata:
version: 0.2.0
---
# Mapping Documents
Generate `_MAP.md` files providing hierarchical document structure with semantic annotations. Maps show section summaries, typed claims (result/definition/method/caveat/open-question), symbol definitions, and cross-section dependencies — all anchored to page numbers.
The structural analog to `tree-sitting`: tree-sitter parses code via grammar, docmap parses documents via font analysis + LLM extraction.
## Installation
```bash
pip install pdfplumber anthropic --break-system-packages -q
```
## Generate Maps
```bash
# Full run (structure + semantic extraction via Claude API)
python /mnt/skills/user/mapping-documents/scripts/docmap.py paper.pdf \
--out docs/ --genre paper --workers 4
# Structure only (no API calls, no cost)
python /mnt/skills/user/mapping-documents/scripts/docmap.py paper.pdf \
--out docs/ --structure-only
```
API key resolution: `--api-key` flag > `ANTHROPIC_API_KEY` env > `API_KEY` env.
## Output Artifacts
Four files, forming a three-layer progressive-disclosure stack:
```
CLAUDE.md / project instructions ← curated invariants (you write this)
↕ (_USAGE.md bridges the gap)
_MAP.md + JSON indexes ← navigable document map (docmap generates)
↕
raw PDF ← the source document
```
| File | Purpose | When to read |
|------|---------|--------------|
| `{stem}_USAGE.md` | Snippet for pasting into CLAUDE.md / AGENTS.md / project knowledge. Describes the reading order and JSON query patterns. | Once, at setup |
| `{stem}_MAP.md` | Section map: TOC with summaries, typed claims, defined symbols, dependencies. All page-anchored. | Any question about what the document says |
| `{stem}.symbols.json` | Flat symbol index: where defined, where used, what it means. | "Where is X defined?" |
| `{stem}.anchors.json` | Every claim: section ID, type, text, page number. | "What caveats exist?" / "What does §3 claim?" |
## After Generating: Wire It Up
Generating the map is step 1. Step 2 is telling the agent the map exists.
**For a code repo (CLAUDE.md / AGENTS.md):**
```bash
# Paste the generated usage snippet into your agent instructions
cat docs/paper_USAGE.md >> CLAUDE.md
```
**For Claude.ai project knowledge:**
Upload `_MAP.md` as a project knowledge file, or paste the `_USAGE.md` content into project instructions.
The `_USAGE.md` snippet includes copy-pasteable query commands for the JSON indexes. Replace `QUERY` and `SECTION_ID` placeholders with actual values.
## Navigate Via Maps
After generating and wiring up, use the map for navigation — read `_MAP.md`, not the raw PDF.
**Workflow:**
1. Read `_USAGE.md` block in CLAUDE.md for orientation
2. Read top-level TOC in `_MAP.md` for structure and section summaries
3. Drill into relevant sections for typed claims and symbol definitions
4. Query `.symbols.json` for "where is X defined?" lookups
5. Query `.anchors.json` for claim filtering by type or section
6. Read the raw PDF only when exact wording or figures are needed
**Querying the JSON indexes:**
```bash
# Symbol lookup
python3 -c "import json; [print(f'§{s[\"defined_in\"]} p.{s[\"defined_at_page\"]}') \
for s in json.load(open('docs/paper.symbols.json')) if 'edl' in s['symbol']]"
# All caveats in the document
python3 -c "import json; [print(f'p.{c[\"page\"]} {c[\"text\"]}') \
for c in json.load(open('docs/paper.anchors.json')) if c['type'] == 'caveat']"
# All claims in a section
python3 -c "import json; [print(f'[{c[\"type\"]}] {c[\"text\"]}') \
for c in json.load(open('docs/paper.anchors.json')) if c['section'] == '4.3']"
```
## Genre Support
Genre controls the claim taxonomy used in semantic extraction.
| Genre | Claim types | Best for |
|-------|-------------|----------|
| `paper` (default) | definition, result, method, claim, caveat, open-question | Academic papers, arXiv preprints |
| `spec` | requirement, definition, constraint, example, note | RFCs, API specs, technical standards |
| `legal` | definition, obligation, right, exception, condition, reference | Contracts, policy documents, regulations |
## Limitations (v0.1.x)
- **PDF-only.** No DOCX, HTML, or plain text input yet.
- **Single-column layout assumed.** Two-column papers may mis-order text within sections.
- **No caching.** Re-running re-extracts everything.
- **No citation cross-referencing.**
- **Genre must be specified manually.**
- **Semantic extraction can hallucinate.** Every claim is page-anchored, but the page number comes from the LLM. Verify critical claims against the source.
## CLI Reference
```
python docmap.py paper.pdf [options]
Options:
--genre {paper,spec,legal} Claim taxonomy (default: paper)
--structure-only Skip LLM pass (free, fast)
--out DIR Output directory (default: .)
--api-key KEY Anthropic API key
--model MODEL Model (default: claude-sonnet-5-5)
--workers N Parallel workers (default: 4)
--no-usage-snippet Skip _USAGE.md generation
-v Verbose structural parsing
```
Files in this package (4)
- CHANGELOG.md 1 KB
- README.md 1 KB
- SKILL.md 6 KB
- scripts/docmap.py 27 KB
Versions
The database has no other skills named mapping-documents.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 7f0c95d6dac7 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100pdf-processing
Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. - 100document-processing-expert
Read, generate and modify office documents and PDFs from code: PDF extraction and forms, Word documents, Excel workbooks and PowerPoint decks. Use when the user mentions PDF, DOCX, XLSX, PPTX, Word, Excel, PowerPoint or spreadsheets, wants data extracted from documents, needs a… - 95pdf-processing
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. - 90pdf-processing
Process and extract information from PDF documents. Use this skill when the user asks to read, analyze, or extract data from PDF files. - 100doc-read
Read a PDF already on this machine. Returns a section index first, then any named section in full — the same way fetch-text reads a paper from a URL, for the case where the file is a local path instead. Use it when the user says they have downloaded or saved a document. - 100pdf-extractor
This skill should be used when the user asks to "extract text from PDF", "convert PDF to text", "parse PDF", "read PDF contents", "extract data from documents", "batch PDF extraction", "PDF to markdown", "OCR PDF", "get text from PDF files", "I have a PDF", "can you read this…