# Med PDF

> Reads medical PDFs (labs, radiology, MyChart/Epic exports, discharge summaries, pathology) and turns them into structured JSON Tula can reason over. Personal data is referenced from an external profile file, never embedded. USE FOR: the user sharing a health-related PDF, image, or screenshot, or asking to compare results across visits. DO NOT USE FOR: non-medical PDFs, generating new clinical reports, or sending PHI outside the workspace.

- Skill: `realactivity/med-pdf` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add realactivity/med-pdf`
- Raw SKILL.md: https://api.skillmd.com/api/skills/realactivity/med-pdf/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: realactivity (https://skillmd.com/u/realactivity)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/realactivity/med-pdf

---


# med-pdf

## When to Use

✅ Use when:

- The user sends a medical PDF (labs, radiology, discharge, pathology)
- The user shares a screenshot/image of clinical results
- The user asks to compare results across visits or trend a value
- A MyChart/Epic export needs parsing before reasoning

## When NOT to Use

❌ Don't use when:

- The PDF is non-medical (insurance, EOB, billing)
- The user wants to author a clinical message -> use `epic-note`
- Anything that would send PHI outside the workspace

## Setup

**Profile.** Resolve from the precedence in
[`references/profile-schema.md`](references/profile-schema.md#where-the-profile-lives)
(skill config -> env var -> `~/.openclaw/workspace/memory/profile.yaml`).
Use `identity.short_name` when addressing the user in summaries.
The skill never contains the profile.

## Workflow

1. **Extract** - `node {baseDir}/scripts/extract.mjs <input.pdf> <outDir>`
   - `outDir` must be inside `~/.openclaw/workspace/`. Suggested:
     `~/.openclaw/workspace/.med-pdf-cache/<slug>/`.
   - Outputs `text.txt`, `pageN.png`, `meta.json`. Stdout JSON has
     `numPages`, `hasText`, `textChars`.

2. **Branch on `hasText`:**
   - `true` -> skip OCR, feed `text.txt` to parsers.
   - `false` -> image-only (MyChart/Epic). Use the `image` tool on
     `pageN.png` for verbatim transcription. Save as `text.txt`, continue.

3. **Parse:**
   - Imaging -> `node {baseDir}/scripts/parse_imaging.mjs <outDir>`
   - Labs -> `node {baseDir}/scripts/parse_labs.mjs <outDir>`
   - Both can run on a mixed document.

4. **Reason.** Pull abnormal flags, compare to prior values, surface what
   matters for healthspan - see
   [`references/healthspan-priorities.md`](references/healthspan-priorities.md).
   Don't just summarize.

5. **Persist.** Append to `~/.openclaw/workspace/memory/YYYY-MM-DD.md` and
   update trends in `MEMORY.md`. PHI stays in workspace memory only.

## Scripts

See [`references/scripts.md`](references/scripts.md) for per-script flags,
output schemas, and dictionary maintenance for `parse_labs.mjs`.

## Examples

See [`references/examples.md`](references/examples.md) for end-to-end runs
(text-extractable Quest/LabCorp PDF, image-only MyChart CT export).

## Privacy

Medical PDFs contain PHI (name, DOB, MRN, providers).

- Cache stays under `~/.openclaw/workspace/.med-pdf-cache/`. Don't copy out.
- Never send raw PDFs or PHI to web search or external services.
- The `image` tool is acceptable - same trust boundary as the assistant.
- Redact MRN if a summary might leave the workspace.

## Troubleshooting

- `parse_labs.mjs` returns mostly `unmatchedLines` -> text wasn't transcribed
  well. Re-run `extract.mjs` with `--scale=3.0` and re-OCR.
- A labeled value sits in `unmatchedLines` -> add an alias to the dictionary
  in `parse_labs.mjs`. See
  [`references/scripts.md`](references/scripts.md#maintaining-the-dictionary).
- `hasText: true` but parsing yields garbage -> PDF has hidden Unicode
  ligatures; force OCR with `--images-only`.