Health Data

---

name: health-data description: Analyze Apple Health exports (export.zip or the exported folder) using xmlstarlet/jq to summarize activity, steps, sleep, and source counts. Trigger this skill when users ask about "health data", "sleep analysis", "activity summary", "Apple Health export", "steps report", or other Apple Health record audits.

---

Purpose

The health-data skill provides deterministic helpers to read and summarize Apple Health backup exports. The bundled health-data.sh script understands the zipped export Apple Health lets you download and can also work against the unzipped folder with export.xml. Use this skill when you need to inspect record types, compute totals (steps, distance, sleep), or extract JSON for further analysis without sending the sensitive XML off-box.

Safety

Apple Health exports contain PII/PHI (biometric, sleep, location, heart-rate, etc.). Never publish the raw XML, upload the zip, or paste any values into third-party services without explicit consent and legal review.

The script only reads data locally and cleans up its temporary extraction. Keep the exported zip/folder on disk-free space you control and delete it when the analysis is done.

Running summary or export-json now emits a runtime PHI warning banner to stderr; treat every derived artifact as PHI/PII unless you have an explicit legal/research justification.

The export-json command streams records instead of slurping them, warns on stderr after emitting 100,000 records without --limit, and supports --out so you can save the JSON to a file created with 600 permissions instead of dumping to stdout.

Request explicit confirmation before writing any derived health reports if the values are later shared with others (medical, legal, or employment contexts).

Quick start

# List which HealthKit record types appear most often
health-data/health-data.sh list-types ~/Downloads/export.zip
Summarize range, totals, and common sources
health-data/health-data.sh summary ~/Downloads/export.zip
Get JSON records for steps (use jq to filter further)
health-data/health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/Downloads/export.zip --limit 20
Or save to a restricted file (600-permission) instead of stdout
health-data/health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/Downloads/export.zip --limit 20 --out ~/Documents/steps.json

Commands

list-types

Prints every identifier in the export, sorted by frequency. Use this to understand which categories (steps, workouts, heart rate, etc.) are available before you dig into payloads.

summary

Reports:

total record count and date coverage

step count and walking/running distance sums (meters by default)

counts of sleep analysis categories (asleep/in-bed)

top five data sources by record volume

This command relies on xmlstarlet to query the XML so it stays fast even on large exports.

export-json [--limit N] [--out ]

Pulls the requested record type into JSON so you can pipe it to jq, Python, or other tools. The command emits a runtime PHI warning banner on stderr, streams records instead of slurping them, warns after 100,000 emitted records when --limit is omitted, and supports --out to save the JSON to a file created with 600 permissions. Supply --limit to avoid overwhelming the reader (default: unlimited). Examples:

health-data/health-data.sh export-json HKCategoryTypeIdentifierSleepAnalysis ~/Downloads/export.zip --limit 5

health-data/health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/Downloads/export.zip --limit 20 --out ~/Documents/step-records.json

Advanced filtering

Because the output from export-json is valid JSON, use jq for additional insights:

health-data/health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/Downloads/export.zip --limit 50 \
  | jq '[.[] | {value, startDate}]'

Combine jq selectors (like map(select(.unit == "count"))) to focus on specific fields without writing additional parsing logic.

Examples

"What record types did my Health export include?" → health-data.sh list-types ~/path/to/export.zip

"Show me step totals and sleep breakdown for my export" → health-data.sh summary ~/path/to/export.zip

"I want the raw step records for the last week" → health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/path/to/export.zip --limit 100 and pipe through jq '.[].startDate | select(startswith("2026-03"))'

"Save a slice of the export to a local file" → health-data.sh export-json HKQuantityTypeIdentifierStepCount ~/path/to/export.zip --limit 50 --out ~/Documents/step-records.json

Troubleshooting

no such file or directory: Ensure the export path points to either apple_health_export/export.xml or the zipped export produced by Apple Health.

zip ... does not contain export.xml: Re-export from the Health app—sometimes partial exports omit the XML if interrupted.

Missing dependencies: Install xmlstarlet, jq, and unzip via Homebrew (brew install xmlstarlet jq unzip).