Mapping Documents

What it does

When your agent uses it

• Analyzing papers
• Asked to map this document
• What does this paper say
• A coding agent needs grounded reference material from a PDF source

Example prompts

• “map this document”
• “index this PDF”
• “what does this paper say”
• “/mapping-documents”

Requirements

• Python 3
• A credential in ANTHROPIC_API_KEY
• A credential in API_KEY

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

1. 1Read _USAGE.md block in CLAUDE.md for orientation
2. 2Read top-level TOC in _MAP.md for structure and section summaries
3. 3Drill into relevant sections for typed claims and symbol definitions
4. 4Query .symbols.json for "where is X defined?" lookups
5. 5Query .anchors.json for claim filtering by type or section
6. 6Read the raw PDF only when exact wording or figures are needed

What it can do on your machine

Read from SKILL.md and the folder at commit 6fc82b8. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/ (Python), which the agent can run.

  Shell commands in SKILL.md call:

  • python
  • python3
  • pip

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use pip, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • ANTHROPIC_API_KEY
  • API_KEY

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Mapping Documents loads about 1.4k tokens when it runs. Until then it costs about 155 tokens; SKILL.md has 402 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~155

When it runs · the whole SKILL.md, loaded when a task matches

~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from oaustegard/claude-skills at commit 6fc82b8, republished under its MIT licence (© oaustegard). 402 words, ~1,442 tokens.

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

pip install pdfplumber anthropic --break-system-packages -q

# 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

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

# Paste the generated usage snippet into your agent instructions
cat docs/paper_USAGE.md >> CLAUDE.md

# 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']"

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

© oaustegard, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (scripts) in mapping-documents of oaustegard/claude-skills.

• SKILL.md
• CHANGELOG.md
• README.md
• scripts/docmap.py

Open the folder on GitHubat commit 6fc82b8