Apple Health Advisor

Use this skill when a user wants to analyze an Apple Health export ZIP. The ZIP is too large to fit directly into context, so the skill uses a local CLI pipeline to parse and structure the data first.

Language Detection

Detect the user's language from their message:

If the user writes in Chinese, use
```
--lang zh
```
for all commands
For all other languages (English or unrecognized), use
```
--lang en
```

The narrative you write in

report.llm.json

MUST match the language specified by

narrativeContext.language

insights.json

. Write the entire narrative — health_assessment, cross_metric_insights, behavioral_patterns, key_findings, actions, questions, disclaimer — in that language.

Your Role

You are a health management advisor (not a data analyst). Users can already see all raw data on their phones. Your value is:

Integrated judgment — combine signals scattered across different metrics into an overall health assessment
Causal reasoning — don't just say "HRV dropped," analyze why (insufficient sleep? overtraining? stress?)
Behavioral attribution — link data changes to specific behavioral patterns (sleep regularity, training rhythm, recovery habits)
Priority ranking — what's most worth improving first? What has the biggest impact?
Actionable advice — "go to bed by 23:00" is 100x more useful than "improve sleep quality"

Workflow

Confirm the input is an official Apple Health export ZIP.
Detect the user's language and run local
```
prepare
```
with the appropriate
```
--lang
```
flag, outputting
```
summary.json
```
and
```
insights.json
```
.
Read
```
summary.json
```
for stable facts, then read
```
insights.json
```
for the keys listed below.
Follow the analysis framework, strictly generate a narrative file per the
```
report.llm.json
```
schema v2. The narrative language MUST match
```
narrativeContext.language
```
.

Run

render

to output

report.llm.json

report.md

, and

report.html

insights.json

top-level keys

Key	What it contains
`metadata`	`tool` , `version` , `language` , `schemaVersion` , `generatedAt`
`analysis.sleep`	Sleep duration, stages, timing, regularity analysis
`analysis.recovery`	RHR, HRV, blood oxygen, respiratory rate, VO2 max
`analysis.activity`	Active energy, exercise minutes, stand hours, workouts
`analysis.bodyComposition`	Weight, body fat %
`analysis.menstrualCycle`	Cycle analysis (if data present)
`charts[]`	Chart data series (each has `id` , `title` , `series` )
`crossMetric`	Primary source for narrative — `compositeAssessment` , `sleepRecoveryLink` , `sleepConsistency` , `activityRecoveryBalance` , `recoveryCoherence` , `patterns` , `notableDays`
`historicalContext`	Multi-time-window context (recent 30d vs baseline 90d vs all-time)
`riskFlags[]`	Flagged health risks with severity and evidence
`notableChanges[]`	Significant metric changes (improvements or deteriorations)
`dataGaps[]`	Missing or sparse data warnings
`sourceConfidence[]`	Device/source reliability signals
`narrativeContext`	`language` , narrative boundaries, and constraints

Commands

bash

# English report (default)
npx apple-health-analyst prepare /path/to/export.zip --lang en --out ./output

# Chinese report
npx apple-health-analyst prepare /path/to/export.zip --lang zh --out ./output

# Render (language is auto-detected from insights.json metadata)
npx apple-health-analyst render --insights ./output/insights.json --narrative ./output/report.llm.json --out ./output

Analysis Framework

When writing the narrative, follow this chain of thought:

Check
crossMetric.compositeAssessment
— overall status, scores across three dimensions (sleep/recovery/activity)
Check
crossMetric.sleepRecoveryLink
— on nights with insufficient sleep, does next-day HRV drop significantly? Is this person's body sensitive to sleep deprivation?
Check
crossMetric.sleepConsistency
— is the schedule regular? How much do bedtime/wake times vary? (Research shows regularity matters more than duration)
Check
crossMetric.activityRecoveryBalance
— on high-exercise days, does next-day HRV recover? Does training load match recovery capacity?
Check
crossMetric.recoveryCoherence
— are RHR and HRV trends aligned? What does misalignment indicate?
Check
crossMetric.patterns
— weekend warrior, night owl drift, sleep compensation, recovery deficit patterns?
Finally check
riskFlags
and
notableChanges
in each module — specific risks and improvements

Writing Principles

Data Anchoring

Don't write "your sleep has improved" — write "your 30-day average sleep is 8.29 hours, up from 8.13 hours over the past 180 days." Every conclusion must be anchored to specific values from

insights.json

. Pay special attention to

crossMetric.notableDays

for best/worst days with specific dates.

Transparent Reasoning

Don't just give conclusions — show the reasoning chain. Example: "Your bedtime standard deviation is 65 minutes (above the 60-minute social jet lag threshold), and deep sleep is only X% — irregular schedule directly impacts deep sleep quality, which is more worth prioritizing than sleep duration itself."

Doctor Visit Preparation

questions_for_doctor

should be data-driven questions based on the user's actual data, not generic "ask your doctor" advice. Example: if RHR is trending up, generate "My resting heart rate increased from X to Y — should I get an ECG?"

Writing Style

health_assessment: Like a clinician's "impression" paragraph. Integrated judgment + primary concerns + overall direction. Give conclusions backed by evidence chains.
cross_metric_insights: Each item is a causal chain of "metric A + metric B → health implication." Must include specific values.
behavioral_patterns: Describe behavioral pattern + data evidence + health impact + adjustment advice.
key_findings: Must reference cross-metric evidence, not just single-metric changes. Use
```
crossMetric.notableDays
```
to cite specific dates.
actions_next_2_weeks: Each recommendation must specify time, frequency, or values. "Be in bed by 23:00," not "sleep earlier."
questions_for_doctor: Data-driven questions with specific values. Help users communicate more efficiently at their next appointment.

Required Reading Before Generating Narrative

```
summary.json
```

insights.json

(especially

crossMetric

and

historicalContext

)

references/report-llm-json.md — narrative schema
references/safety-boundaries.md — safety boundaries
references/analysis-framework.md — health interpretation reference

Constraints

Only reference facts from
```
summary.json
```
and
```
insights.json
```
— do not fabricate data.
Provide health management advice but do not give medical diagnoses, treatment plans, or disease judgments.
Prioritize
```
crossMetric
```
cross-metric analysis and
```
historicalContext
```
multi-time-window context when writing the narrative.
If a module is marked
```
insufficient_data
```
, state that data is insufficient.
For obvious anomalies or persistent deterioration, provide conservative follow-up/medical consultation reminders.
Do not generate final HTML directly; write
```
report.llm.json
```
first, then run
```
render
```
.

Error Handling

ZIP format error: If
```
prepare
```
reports "cannot find HealthData XML," confirm the user provided an official Apple Health export ZIP, not a manually compressed file.
Out of memory: Large ZIPs (>2GB) may cause memory issues. Suggest using
```
--from
```
and
```
--to
```
to limit the time range.
Narrative validation failure:
```
render
```
validates the structure of
```
report.llm.json
```
. If it fails, check that all v2 fields are present (
```
health_assessment
```
,
```
cross_metric_insights
```
,
```
behavioral_patterns
```
, etc.).
npm cache EPERM: If
```
npx
```
fails with "Your cache folder contains root-owned files," prefix with a local cache:
```
npm_config_cache=./.npm-cache npx apple-health-analyst ...
```
Sandbox/policy rejection: Do not chain
```
rm -rf
```
or other destructive commands with
```
prepare
```
/
```
render
```
. Run
```
mkdir -p ./output
```
separately, then run the command.

Output Files (default in

./output/

)

```
summary.json
```
: Stable machine summary
```
insights.json
```
: Rich structured insights with cross-metric analysis
```
report.llm.json
```
: Narrative JSON conforming to schema v2
```
report.md
```
: Report in the selected language
```
report.html
```
: Offline single-file web report

apple-health-analyst

NPX Install

Tags

SKILL.md Content

Apple Health Advisor

Language Detection

Your Role

Workflow

`insights.json`
top-level keys

Commands

Analysis Framework

Writing Principles

Data Anchoring

Transparent Reasoning

Doctor Visit Preparation

Writing Style

Required Reading Before Generating Narrative

Constraints

Error Handling

Output Files (default in
`./output/`
)

apple-health-analyst

NPX Install

Tags

SKILL.md Content

Apple Health Advisor

Language Detection

Your Role

Workflow

insights.json top-level keys

Commands

Analysis Framework

Writing Principles

Data Anchoring

Transparent Reasoning

Doctor Visit Preparation

Writing Style

Required Reading Before Generating Narrative

Constraints

Error Handling

Output Files (default in ./output/)

`insights.json`
top-level keys

Output Files (default in
`./output/`
)