clinical-note-extract-skill

name	clinical-note-extract-skill
description	Extract structured data from clinical notes with span-level provenance and null-safety. Use when users say "extract [variables] from this note", "abstract this chart", "pull structured data from these notes", "what does this note say about [field]", or when building a chart-abstraction, registry, or cohort dataset from unstructured clinical text.

Clinical Note Extraction

Structured extraction from clinical notes against a user-defined schema, with span citations for every value and explicit nulls for every absence. One note or many — the path is the same: an isolated no-tools worker extracts each note, then a deterministic validation pass verifies spans and codes.

This is the extraction primitive that care-gap reasoning, adverse-event detection, trial-eligibility screening, prior-auth evidence assembly, and registry abstraction sit on.

Steps

1  Define schema   — references/01-define-schema.md
2  Extract         — workflows/extract-batch.js (one isolated worker per note)
3  Validate        — span check + run each field's `check`
4  Report          — references/03-review.md

Step 1 — Define schema

Read references/01-define-schema.md. Turn the user's request into a schema: each field is {desc, finding?, check?}. desc says what to look for in the note's own terms; finding: true means classify assertion; check is how step 3 validates (open-ended — {kind: "terminology"|"range"|"date"|"pattern"|"enum"|..., ...params}). Confirm with the user before extracting.

Step 2 — Extract

However the user supplied notes — pasted text, file paths, a directory, PDFs, a FHIR connector, a database query — resolve each to plain text using whatever tools you have, then call the saved workflow with one {id, text} per note. The workflow's input contract is the only strict piece; how you get there is yours to figure out. It runs one note-extract-worker agent per note (no tools — note text is untrusted), each following references/rules.md, and returns one schema-enforced record per note:

Workflow({
  scriptPath: "<this skill dir>/workflows/extract-batch.js",
  args: {
    notes:  [{id, text}, ...],     // one or many
    schema: <the schema from step 1>,
    rules:  <Read references/rules.md verbatim>
  }
})

Workers have no tools — they return only what they read (value, span, presence/temporality/experiencer, null_reason, unit). All checks happen in step 3. Because note text rides inline in args, the workflow path tops out at a few dozen notes per call. For larger corpora, run bun <this skill dir>/scripts/batch.ts <notes-dir> <schema.json> records.jsonl instead — it reads files in trusted code and spawns one tool-disabled extraction per note with the same rules, then resume at step 3 over the resulting records.jsonl.

Step 3 — Validate

Runs here in the calling session. Deterministic — no model judgment. For every record:

1. Span check. For every non-null field, confirm span appears verbatim in that note's source text. Attach span_verified.
2. Run each field's check. Dispatch on check.kind:
   • terminology — dedupe (check.via, value) across all records, look each up via whatever connector answers to via, attach {code, code_status, display}. No connector for that via → code_status: "unvalidated", name it in the report.
   • range — value vs [min, max] and unit vs check.unit; attach range_flag.
   • date — confirm value parses as a date; attach date_ok.
   • pattern / enum — match; attach check_ok.
   • other / no check — nothing to attach.

A field is trustworthy when span_verified and its check (if any) passed. Adding a check kind = add a branch here; nothing upstream changes.

Step 4 — Report

Read references/03-review.md. Produce one row per (note, field): note_id | field | value | presence/temporality/experiencer | span | check. Below it, the completion summary: fields requested / populated / null, and per check.kind what passed vs flagged (name any terminology via that lacked a connector). Never let a failed check or unverified span pass silently.

Offer to write records + report to ~/.claude/data/healthcare/clinical-note-extract/<run-id>/. That directory is local working state, not an archive: do not copy it to shared drives or external systems without the user's explicit instruction, and tell the user it can be deleted once they have what they need — extracted records carry whatever PHI was in the source notes.

Output contract

Worker emits, per field: {value, span, location, presence?, temporality?, experiencer?, null_reason?, unit?} — only what it read. Step 3 attaches span_verified plus whatever the field's check produced (code/code_status/display for terminology, range_flag for range, etc.).

Optional — export as FHIR

If the user wants FHIR resources instead of flat records, the assertion axes map directly:

record	FHIR
experiencer != patient	FamilyMemberHistory.condition (not Condition)
presence: absent → verificationStatus: refuted; possible → unconfirmed; present → confirmed	Condition.verificationStatus
temporality: historical → inactive; current → active	Condition.clinicalStatus
temporality: hypothetical	no native field — omit, or use a RiskAssessment resource
value + terminology check result	Condition.code as a CodeableConcept ({text: value, coding: [{system, code, display}]})
span + location	Condition.note or a provenance extension

This is a deterministic transform over the validated records — no model call. Offer it when the user names FHIR as the target; otherwise the flat records are the default.

Prerequisites

Connectors for whatever check.via values the schema names. Missing ones don't block extraction — those fields stay unvalidated and the report names them.