apple-health-analyst

Category: Data & AI | Uploader: RuochenLyu | Downloads: 0 | Version: v1.0（Latest）
Analyze Apple Health export ZIP. Run local prepare to generate structured insights, then produce a professional health report based on cross-metric analysis and historical context.
Changelog: Source: GitHub https://github.com/RuochenLyu/apple-health-analyst
Directory Structure

Current level: tree/main/.agents/skills/apple-health-analyst/
📁 references/
- 📄 analysis-framework.md 5.6 KB
- 📄 report-llm-json.md 4.1 KB
- 📄 safety-boundaries.md 1.5 KB
📄 SKILL.md 9.0 KB
SKILL.md

---
name: apple-health-analyst
description: Analyze Apple Health export ZIP. Run local prepare to generate structured insights, then produce a professional health report based on cross-metric analysis and historical context.
---

# 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` in `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:

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

## Workflow

1. Confirm the input is an official Apple Health export ZIP and that it contains an XML whose root node is `HealthData`.
2. Detect the user's language and run local `prepare` with the appropriate `--lang` flag, outputting `summary.json` and `insights.json`.
3. Read `summary.json` for stable facts, then read `insights.json` for the keys listed below.
4. Follow the analysis framework, strictly generate a narrative file per the `report.llm.json` schema v2. The narrative language MUST match `narrativeContext.language`.
5. 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/导出.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:

1. **Check `crossMetric.compositeAssessment`** — overall status, scores across three dimensions (sleep/recovery/activity)
2. **Check `crossMetric.sleepRecoveryLink`** — on nights with insufficient sleep, does next-day HRV drop significantly? Is this person's body sensitive to sleep deprivation?
3. **Check `crossMetric.sleepConsistency`** — is the schedule regular? How much do bedtime/wake times vary? (Research shows regularity matters more than duration)
4. **Check `crossMetric.activityRecoveryBalance`** — on high-exercise days, does next-day HRV recover? Does training load match recovery capacity?
5. **Check `crossMetric.recoveryCoherence`** — are RHR and HRV trends aligned? What does misalignment indicate?
6. **Check `crossMetric.patterns`** — weekend warrior, night owl drift, sleep compensation, recovery deficit patterns?
7. **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](references/report-llm-json.md) — narrative schema
- [references/safety-boundaries.md](references/safety-boundaries.md) — safety boundaries
- [references/analysis-framework.md](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 that it cannot find a `HealthData` XML, confirm the user provided an official Apple Health export ZIP. The main XML filename is not fixed: it may be localized (for example `导出.xml`), and some ZIP tools may display it as mojibake. `export_cda.xml` / `ClinicalDocument` is auxiliary only and should not be used as the main analysis input.
- **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
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
apple-health-analyst

Directory Structure

SKILL.md

Report

Notice
