Health Skill

A health workspace and longevity companion for Claude — connects your labs, medications, training, sleep, and family history so you can get more out of every conversation and every doctor's visit.

Claude that remembers your health history — and reasons across all of it.

Most health conversations with AI start from scratch. Health Skill gives Claude a persistent workspace that connects your labs to your medications, your sleep to your pain, your family history to your screening schedule — so every conversation builds on the last.

It's also a daily longevity companion: log check-ins, track your cycle, design training plans, monitor preventive care, sync your watch automatically, and discover patterns across your entire health picture.

Setup for Claude Cowork
Wearable & Apple Health Sync
Setup for Claude Code
What You Get
Key Features
Longevity Companion (v1.7)
What's new in v1.8
Who This Is For
What It Is Not
Documentation

Setup for Claude Cowork

Step 1: Install the skill

Open Claude Code (terminal) and paste:

Install the health-skill from https://github.com/googlarz/health-skill as a local skill

Claude will clone it and set it up. That's it.

Or do it manually in one line:

git clone https://github.com/googlarz/health-skill.git ~/.claude/skills/health-skill

Step 2: Create a health project

Create a folder for each person — one person per folder:
```
~/Health/
  mom/
  dad/
  me/
```
Open Claude Cowork → Start new project → Use existing folder → pick a person folder (e.g. ~/Health/mom/)

In the project instructions, add:

Use /health-skill

This is a health workspace for Mom.
Always read HEALTH_DOSSIER.md before answering health questions.
Generate a query-dashboard for every health question before responding.

Tell Claude: "Initialize this folder"

That's it. The skill is now active for every conversation in that project.

Step 3: Start using it

Drop lab PDFs, discharge notes, or visit summaries into the inbox/ folder
Tell Claude: "Process the inbox" — it extracts labs, medications, follow-ups automatically
Ask questions: "What do my labs mean?", "Help me prepare for my appointment", "What's overdue?"
Claude generates focused dashboards, tracks trends, and keeps everything organized across sessions

Updating

cd ~/.claude/skills/health-skill && git pull

Wearable & Apple Health Sync

Health Skill can import data from any fitness watch or wearable. There are two paths:

Suunto users: there's a dedicated suunto-mcp server that connects your Suunto watch directly to Claude via the official Suunto API — live workouts, HRV, sleep, and GPX export without any manual export steps. Install it alongside Health Skill for a fully automated pipeline.

Option A — Via Apple Health (iPhone users)
Most watches (Garmin, Suunto, Polar, Whoop, Oura, Amazfit, Withings) sync to Apple Health through their companion app. From Apple Health you can export data and drop it into your workspace inbox/wearable/ folder, or use an Apple Health export app of your choice to automate the transfer to iCloud Drive.

Option B — Direct from your watch app
Many watch brands let you export workouts or health data directly from their app as CSV or JSON — no Apple Health needed. Drop the file into inbox/wearable/ and run import-wearable.

Option C — Manual CSV/JSON drop
Any CSV or JSON with columns for date, steps, heart rate, sleep, etc. is accepted. Drop it in inbox/wearable/ and run import-wearable.

Once files land in inbox/wearable/, install the background watcher to import them automatically:

python3 ~/.claude/skills/health-skill/scripts/care_workspace.py setup-watch \
  --root ~/Health/me \
  --person-id me

Check that it's running:

python3 ~/.claude/skills/health-skill/scripts/care_workspace.py setup-watch \
  --root ~/Health/me --person-id me --status

See the logs:

tail -f ~/Health/me/logs/wearable-sync.log

Uninstall:

python3 ~/.claude/skills/health-skill/scripts/care_workspace.py setup-watch \
  --root ~/Health/me --person-id me --uninstall

What gets imported

Metric	Source
Steps	Garmin, Suunto, Polar, Whoop, Oura, Amazfit, Withings, iPhone
Resting heart rate	All watches
Heart rate variability (HRV)	Garmin, Whoop, Oura, Polar
VO2 max	Garmin, Polar, Apple Watch
Weight	Withings scale, Garmin scale, manual entry
Blood pressure	Withings BP monitor, Omron (via Health)
Sleep hours	All watches with sleep tracking
SpO2	Garmin, Oura, Whoop, Amazfit, Apple Watch

Multiple people, multiple watches

Each person folder gets its own watcher:

# Install watcher for mom's folder
python3 ~/.claude/skills/health-skill/scripts/care_workspace.py setup-watch \
  --root ~/Health/mom --person-id mom

# Install watcher for your own folder
python3 ~/.claude/skills/health-skill/scripts/care_workspace.py setup-watch \
  --root ~/Health/me --person-id me

Each runs independently. If you manage data for a parent who doesn't have their own Mac, drop their exports manually into their inbox folder — the watcher will pick them up on the next cycle.

Troubleshooting

iCloud folder not syncing to Mac
Open System Settings → Apple ID → iCloud → iCloud Drive → make sure iCloud Drive is enabled and "Optimize Mac Storage" is OFF (otherwise files may not be local).

Health Auto Export not writing files
Open the app → tap your export → tap Export Now to test manually. Check that iCloud Drive is selected as the destination.

Watcher installed but no data coming in

# Check the error log
cat ~/Health/me/logs/wearable-sync-error.log

# Run manually to see output
python3 ~/.claude/skills/health-skill/scripts/care_workspace.py sync-wearable \
  --root ~/Health/me --person-id me

Watch data not appearing in Apple Health
In the Health app on iPhone, go to Sharing → Apps → find your watch app → make sure it has permission to write the metrics you care about.

Auto-ingest hooks

Health Skill includes Claude Code hooks that automatically save health data from every message — workouts, check-ins, labs, weight, symptoms, medication mentions — without you having to run a command.

What gets saved:

Text: "ran 5km in 28 min" → workout entry with date
Text: "I feel sick, weight 85kg" → symptom check-in + weight entry
File reads: lab CSV, workout export → structured entries extracted from content
Photos: Claude extracts data and saves it (see photo-handling.md)

Install:

git clone https://github.com/googlarz/health-skill.git
bash health-skill/hooks/install.sh

Data is saved to your workspace as dated entries in HEALTH_TIMELINE.md (markdown workspaces) or directly into the structured profile (JSON workspaces). After each response, Claude shows what was auto-saved.

Works with any workspace layout — the hooks detect your workspace root and the right person automatically from the current project directory.

Setup for Claude Code

# Clone and install
git clone https://github.com/googlarz/health-skill.git ~/.claude/skills/health-skill

# Initialize a person folder
python3 ~/.claude/skills/health-skill/scripts/care_workspace.py init-project \
  --root ~/Health/mom --name "Mom"

Reference it in any project's CLAUDE.md:

Use /health-skill

This is a health workspace for Mom.
Always read HEALTH_DOSSIER.md before answering health questions.

CLI Quick Reference

I want to...	Command
Set up a new person folder	`init-project --root . --name "Name"`
Run onboarding	`onboard --root .`
Process new documents	Drop into `inbox/`, then `process-inbox --root .`
See what's important now	Open `TODAY.md` or `HEALTH_HOME.md`
Prepare for an appointment	`query-dashboard --root . --query "visit prep"`
Ask a health question	`query-dashboard --root . --query "your question"`
Log a daily check-in (full)	`daily-checkin --root . --note "mood 8, slept 7h, energy good"`
Log a daily check-in (shorthand)	`daily-checkin --root . --note "m8 s7 e7 p2"`
Log a workout	`workout-log --root . --type strength --duration 45 --notes "squats, deadlifts"`
Generate a training plan	`workout-plan --root . --goals "build strength" --days 3`
Log a screening	`screening-log --root . --name mammogram --date 2024-06-01`
See overdue screenings	`preventive-check --root .`
Discover cross-domain patterns	`connections --root .`
Get proactive nudges	`nudges --root .`
Generate weekly recap	`weekly-recap --root .`
Set a longevity goal	`add-goal --root . --title "LDL under 130" --metric ldl --target 130`
Show goals & progress	`goals --root .`
Add a care-team provider	`add-provider --root . --name "Dr Smith" --role pcp`
Import wearable data	`import-wearable --root . --file inbox/export.xml`
Run structured triage	`triage --root . --summary "knee pain" --q1 "..." --q2 "..."`
Forecast labs and weight	`forecast --root .`
Generate lab-to-action plan	`lab-actions --root .`
Log a meal	`log-meal --root . --text "chicken 200g, rice 1 cup, broccoli"`
Nutrition trends	`nutrition --root .`
HRT / statin / screening decision aid	`decide --root . --topic hrt`
Auto-sync wearable inbox	`sync-wearable --root .`
Add household member	`household-add-member --root . --id self --name "Anna" --folder anna`
Cascade family history	`household-cascade --root .`
Check extraction accuracy	`extraction-audit --root .`
Check drug interactions	`check-interactions --root .`
Medication side-effect timeline	`side-effects --root .`
Monthly insight report	`monthly-report --root .`
Import FHIR from patient portal	`import-fhir --root . --file inbox/fhir.json`
Mental health screen	`mental-health --root .`
Personalised lab range	`lab-range --root . --marker LDL --value 155`

See docs/commands.md for the full reference.

What You Get

File	What it does
`HEALTH_HOME.md`	Visual home screen — status bar, priorities, patterns, progress
`TODAY.md`	Smallest useful set of actions with ☐ checkboxes
`NEXT_APPOINTMENT.md`	Visit prep — 30-second summary, portal message draft, questions
`HEALTH_TRENDS.md`	Lab trends with sparklines and directional arrows
`WEIGHT_TRENDS.md`	Weight series with visual sparkline chart
`START_HERE.md`	Dynamic entry point — shows what changed since last session
`HEALTH_DOSSIER.md`	Comprehensive context for Claude to read first
`REVIEW_WORKLIST.md`	Conversational review: "Items I'm Confident About" / "Items That Need Your Eye"

See docs/files.md for the complete list.

Key Features

Query-relevant dashboards — Ask any health question and get a focused view with only the relevant data, not the full dossier. Dashboards can be saved and reused for similar future queries.

Trust-aware extraction — Facts extracted from documents are labeled by confidence. OCR-derived data is flagged for review. You confirm what matters.

Medication safety — Adding a medication that conflicts with a known allergy triggers a warning automatically.

Pattern detection — Connects labs to medications to follow-ups over time. Flags stale tests, temporal side-effect correlations, and overdue follow-ups.

Visual outputs — Status chips (✅/⚠️), sparkline charts, trend arrows, and bold key numbers. Designed for scanning when tired or stressed.

Caregiver dashboard — One view across multiple person folders with urgency scoring and follow-up reminders.

What's new in v1.8

Thirteen new features across safety, clinical depth, ambient monitoring, equal coverage for men and women, and an interactive HTML dashboard.

Core safety & insights

💊 Drug-drug interaction checker — check-interactions scans your full medication list against 20+ clinically significant interactions. Warfarin + ibuprofen, SSRIs + MAOIs, statins + clarithromycin, metformin + contrast dye, and more. Each alert includes mechanism, risk, and exactly what to do.
🎯 Personalised lab reference ranges — lab-range adjusts your LDL target for diabetes (→ <100), TSH for levothyroxine (→ 0.5–2.5), haemoglobin by sex, and dozens more condition × medication × sex combinations.
📈 Medication side-effect timeline — side-effects correlates medication start dates with your daily check-ins. Pain up 3 points after starting a statin? Sleep disrupted after an SSRI? Signal surfaces automatically.
📅 Monthly insight report — monthly-report produces a one-page 30-day summary: mood/sleep/energy/pain sparklines, training, labs, weight delta, and one action item.
🏥 FHIR R4 import — import-fhir pulls conditions, medications, allergies, immunisations, and observations directly from Epic MyChart, Cerner, and Apple Health Records exports.
🧠 Mental health layer — mental-health runs PHQ-2 (depression) and GAD-2 (anxiety) proxies from check-in data, plus a burnout detector. Includes crisis resources.
🔔 Continuous pattern alerts — integrated into nudges: chronic sleep deficit, sustained low mood + energy, consistently high pain, rapid weight gain.

Pharmacogenomics

🧬 23andMe / AncestryDNA integration — import-pgx parses your raw genotype file and calls phenotypes for CYP2C19, CYP2D6, CYP2C9, SLCO1B1, VKORC1, MTHFR, and DPYD. pgx-report cross-references your current medications — clopidogrel + CYP2C19 poor metaboliser is a critical flag, statin + SLCO1B1 variant triggers myopathy warning.

Appointment workflow

📆 Appointment management — add-appointment tracks upcoming visits. pre-visit auto-generates a structured brief: active conditions, medications, recent labs, recent check-in trends, and specialty-specific questions to ask your doctor.
📝 Post-visit note processor — post-visit parses free-text visit notes to extract new diagnoses, new medications, stopped medications, labs ordered, referrals, and follow-up intervals — then merges them into your profile automatically.

Men's health (equal depth to women's module)

♂ Men's health module — mens-health provides equivalent depth to the menopause module: testosterone symptom scoring, T-level staging (normal / borderline / hypogonadism), PSA trend interpretation with age-adjusted thresholds and velocity flags, erectile dysfunction as cardiovascular sentinel, full male preventive care schedule (testicular self-exam, PSA, colorectal, AAA ultrasound), and male-specific CV risk framing.

Interactive HTML dashboard

📊 Visual health dashboard — dashboard generates a single self-contained HEALTH_DASHBOARD.html file you can open in any browser. Includes: 30-day KPI cards (mood, energy, sleep, pain with trend deltas), a 90-day daily trends line chart, weight timeline, lab results plotted against your personalised reference ranges (green = normal, red = out of range), active medications with duration, upcoming appointments, and condition badges. No server required — everything is embedded including Chart.js.

What's new in v2.0

The skill is no longer a filing cabinet — it predicts, recommends actions, supports decisions, and works for whole households.

🔮 Forecasting — forecast projects each lab marker and weight forward 3–6 months using linear regression with 95% confidence intervals. "At this rate you hit your LDL goal by August."
⚙️ Lab-to-action — lab-actions turns every abnormal lab into a clinician question + lifestyle consideration + recheck cadence + drafted portal message. The loop from result to action becomes one click.
🍽 Nutrition tracker — log-meal "chicken 200g, rice 1 cup, broccoli" parses ~80 common foods into calories/protein/fiber/sodium, aggregates 14-day trends, coaches on gaps.
🧭 Decision support — decide --topic hrt|statin|screening produces structured shared-decision-making aids personalised to your data: pros, cons, what's missing, questions to bring.
⌚ Live wearable sync — sync-wearable processes everything in inbox/wearable/. Pair with the iOS Shortcut recipe in references/wearable-sync.md for daily auto-sync from your Apple Watch.
👨‍👩‍👧 Household / family graph — household-add-member + household-cascade push a parent's diagnosed cancer or cardiac event into every connected member's family history automatically, which adjusts their preventive screening dates.

Previous features (also in v1.8)

📸 Photo input — paste a posture photo, skin lesion, medication bottle, lab screenshot, or food photo. See references/photo-handling.md for the full protocol.
🔔 Proactive nudges — nudges scans the workspace for overdue items, stale labs, missed check-ins, open conflicts, and surfaces what to act on next.
📅 Weekly recap — weekly-recap summarises your last 7 days: mood/sleep/energy/pain trends, training volume, weight delta, and one thing to action.
🎯 Goal tracking — set quantified goals (LDL <130, deadlift 60kg, sleep 7+h) with add-goal. Baseline captured automatically; progress computed from your actual data.
⌚ Wearable import — drop Apple Health export.xml or any CSV in inbox/, run import-wearable. Imports steps, RHR, VO2 max, SpO2, weight, BP, sleep.
👪 Family-history-aware screening — adding "Mom: breast cancer at 48" pulls your mammogram start age forward to 38 automatically.
🩺 Provider directory — store your care team (PCP, gyno, cardio, PT, dentist) with add-provider.
🧭 Structured triage — describe a symptom, get walked through 5 questions, returns urgency band + red-flag detection + drafted clinician handoff.
⚡ Shorthand check-ins — m7 s7 e6 p2 works as well as a sentence. Lower friction = more data.
💡 Smart in-conversation suggestions — Claude offers concrete next steps when you mention symptoms, sleep, new meds, family history, or goals.

Longevity Companion (v1.7)

Health Skill isn't just for paperwork. It's a daily companion for people who want to stay healthy over the long term.

Daily check-ins

Log how you feel in plain language. Claude parses it and stores structured data:

"mood 7, slept 6 hours, knee hurts 3/10, energy low"

Trends surface over time — sleep vs energy, pain vs training load, mood across the cycle.

Cycle tracking (opt-in)

Log periods, symptoms, and cycle events. Claude predicts your next period, tracks cycle length, and connects cycle phase to mood and energy data if you log check-ins. Fully opt-in — set track_cycles: true in your profile.

Training plans

Tell Claude your goals and constraints. It generates a weekly plan:

"fix my posture, 3 days a week, 30 minutes, bad lower back"

Plans are injury-aware and include progression. Log workouts with workout-log. PRs tracked automatically.

Menopause & hormonal health

Health Skill has specific knowledge of perimenopause and menopause:

HRT context — explains estrogen, progesterone, and testosterone therapy options; connects HRT to labs (lipids, bone markers); flags when symptoms warrant a conversation with a clinician
Symptom tracking — hot flashes, sleep disruption, mood, joint pain, brain fog tracked in daily check-ins and connected to cycle data
Exercise guidance — recommends compound/strength training for bone density preservation, explains why resistance training matters more post-menopause than cardio alone
Lab interpretation — FSH, LH, estradiol, SHBG in context of where you are in the transition

Preventive care

Tracks screenings by age and sex: mammogram, colonoscopy, bone density (DEXA), cervical cancer, blood pressure, cholesterol, diabetes, skin checks, eye exams, and more. Tells you what's overdue and when things are due next.

Cross-domain connections

The connections engine looks across all your data and surfaces patterns you wouldn't notice manually:

Sleep quality → next-day pain level
Training frequency → resting heart rate trend
Cycle phase → mood and energy check-ins
LDL trend → exercise frequency correlation
Weight → sleep quality over time

Who This Is For

Managing your own recurring appointments, labs, and medications
Helping a parent, partner, or child with health admin
Keeping Claude useful across months, not just one conversation

What It Is Not

Not a doctor, diagnostic system, or prescribing tool
Not a HIPAA-compliant platform
Not a replacement for emergency care or licensed clinicians

See references/safety-protocol.md for the full safety model.

Documentation

Doc	Purpose
SKILL.md	How Claude uses the skill at runtime
docs/setup-guide.md	Step-by-step for non-technical users
docs/commands.md	Full CLI reference
docs/files.md	Every workspace file explained
CONTRIBUTING.md	How to contribute

Tests

python3 -m unittest discover tests -v   # 110 tests, ~1.5s

License

MIT

health-skill