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:

Span check. For every non-null field, confirm
```
span
```
appears verbatim in that note's source text. Attach
```
span_verified
```
.
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.

clinical-note-extract-skill

NPX Install

Tags

SKILL.md Content