Skill: ivangdavila/apple-health (version 1.0.0)

--- name: Apple Health slug: apple-health version: 1.0.0 homepage: https://clawic.com/skills/apple-health description: Connect agents to Apple Health exports with MCP setup, schema validation, and privacy-safe analysis. changelog: Initial release with Apple Health MCP integration workflow and guarded query patterns. metadata: {"clawdbot":{"emoji":"❤️","requires":{"bins":["node","npx"],"env":["HEALTH_DATA_DIR"]},"install":[{"id":"npm","kind":"npm","package":"@neiltron/apple-health-mcp","bins":["apple-health-mcp"],"label":"Install Apple Health MCP Server (npm)"}],"os":["darwin","linux","win32"]}} --- ## Setup On first use, read `setup.md` for integration guidelines. ## When to Use User wants agents to read Apple Health data for trends, summaries, or SQL analysis. Agent handles export validation, MCP server wiring, and safe query/report flows without exposing private health records. ## Architecture Memory lives in `~/apple-health/`. See `memory-template.md` for setup. ``` ~/apple-health/ |-- memory.md # Status, client integration state, latest export path |-- integrations.md # Connected MCP clients and validation notes |-- query-log.md # Reusable SQL/report prompts and known-good outputs `-- archive/ # Retired paths and old troubleshooting notes ``` ## Quick Reference Use these files on demand instead of overloading the main instructions. | Topic | File | |-------|------| | Setup process | `setup.md` | | Memory template | `memory-template.md` | | MCP client wiring | `mcp-config.md` | | Query recipes | `query-recipes.md` | | Fallback CLI paths | `fallback-cli.md` | ## Core Rules ### 1. Confirm Integration Mode Before Doing Anything Start by clarifying one of these modes: - `csv-export` using Apple Health CSV exports and MCP - `not-now` if user is only planning and does not want setup yet Never imply direct HealthKit API access from terminal agents. This skill works from exported data. ### 2. Validate Local Export Before MCP Wiring Require a real export folder before configuration: - Must exist locally and be readable - Must include files matching `HKQuantityTypeIdentifier*.csv`, `HKCategoryTypeIdentifier*.csv`, or `HKWorkoutActivityType*.csv` - Must not be an empty unzip folder If validation fails, stop and fix data path first. ### 3. Run Runtime Preflight Before MCP Configuration Before wiring MCP, verify runtime: - `node -v` should be an LTS line (18, 20, or 22) - If `npx @neiltron/apple-health-mcp` fails with missing `duckdb.node`, switch to LTS Node and retry - Confirm `HEALTH_DATA_DIR` is available as an absolute path Do not continue while runtime is incompatible. ### 4. Configure MCP With Explicit Path and Command Use the MCP server command from `mcp-config.md`: - Command: `npx` - Args: `[@neiltron/apple-health-mcp]` - Env: [REDACTED_SECRET] Never continue with placeholders or relative paths that are not verified. ### 5. Schema First, Then Queries First run schema discovery (`health_schema`) and map available tables. Only then run `health_query` or `health_report`. If table names differ from expectation, adapt SQL to discovered schema instead of forcing guessed names. ### 6. Use Date-Bounded Queries By Default Every analytical query should include time bounds and clear units. Prefer rolling windows (`last 7d`, `30d`, `90d`) and compare at most two windows at once. Avoid unbounded full-history scans unless user explicitly asks. ### 7. Track Data Freshness and Refresh Points Log last export timestamp in memory and warn when data is stale. If user needs current-day insights, request a new iPhone export before claiming "latest" trends. ## Common Traps - Assuming live HealthKit access from CLI agents -> setup fails because only exported data is available - Using wrong export path in MCP env -> server starts but returns no data - Running SQL before schema discovery -> queries fail on wrong table names - Unbounded queries on large exports -> slow analysis and noisy output - Reporting "today" metrics from stale export -> inaccurate recommendations - Running MCP package on non-LTS Node -> DuckDB native module errors can break startup ## External Endpoints | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | https://registry.npmjs.org | Package install metadata only | Download MCP server package | | https://raw.githubusercontent.com | Public markdown only | Read validated fallback skill docs | | https://apps.apple.com | Manual app download traffic | Install CSV export app on iPhone | No health record rows should be sent externally by default. ## Security & Privacy Data that leaves your machine: - Package install requests to npm - Optional app download traffic from App Store Data that stays local: - Apple Health CSV exports - MCP query outputs and summaries - Skill memory in `~/apple-health/` This skill does NOT: - Access iCloud Health data directly - Bypass Apple permission prompts - Upload health CSVs unless the user asks for that explicitly ## Trust By using this skill, you rely on third-party tooling (`@neiltron/apple-health-mcp` and the chosen iPhone export app). Only install and run if you trust those tools. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `health` - General health guidance boundaries and framing - `ios` - iOS-specific setup and platform troubleshooting - `sleep` - Sleep trend interpretation workflows - `api` - Reliable API and integration debugging habits - `swift` - HealthKit-side implementation context when app code is involved ## Feedback - If useful: `clawhub star apple-health` - Stay updated: `clawhub sync`

path: fallback-cli.md
content: # Fallback CLI Paths (Validated on GitHub)

Use these if MCP startup is blocked by runtime issues.

## 1) `healthkit-sync` (published skill)

GitHub source:
- https://raw.githubusercontent.com/openclaw/skills/main/skills/mneves75/healthkit-sync/SKILL.md

What it gives:
- Local CLI command flow (`healthsync discover`, `healthsync scan`, `healthsync fetch`)
- Secure pairing and local-network sync patterns
- Detailed query examples for steps, heart rate, sleep, and workouts

## 2) `apple-watch` (published skill)

GitHub source:
- https://raw.githubusercontent.com/openclaw/skills/main/skills/lainnet-42/apple-watch/SKILL.md

What it gives:
- End-to-end Health Auto Export setup from iPhone to local server
- Persistent server operations and troubleshooting checklist
- Query and dashboard workflow for agent consumption

## Fallback Decision Rule

- Prefer MCP path when `@neiltron/apple-health-mcp` starts cleanly.
- If MCP fails because of runtime/native module issues, switch to a validated CLI workflow above.
- Keep the same privacy guardrails: local data first, bounded queries, explicit freshness.


path: mcp-config.md
content: # MCP Configuration — Apple Health

Use this server in MCP-compatible clients:

```json
{
  "mcpServers": {
    "apple-health": {
      "command": "npx",
      "args": ["@neiltron/apple-health-mcp"],
      "env": {
        "HEALTH_DATA_DIR": "/absolute/path/to/health-export"
      }
    }
  }
}
```

## Runtime Compatibility

- Prefer Node LTS (`18`, `20`, or `22`).
- If startup fails with `duckdb.node` missing, switch Node version and retry.
- Validate once with: `npx -y @neiltron/apple-health-mcp`

## Minimum Validation Checklist

- Path is absolute and exists.
- Folder contains `HK*` CSV files.
- `HEALTH_DATA_DIR` points to unzipped export root, not a parent folder.
- `health_schema` returns at least one table.

## Optional Environment Variables

- `MAX_MEMORY_MB` (default `1024`)
- `CACHE_SIZE` (default `100`)

Only increase memory if large exports actually require it.


path: memory-template.md
content: # Memory Template — Apple Health

Create `~/apple-health/memory.md` with this structure:

```markdown
# Apple Health Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending
mode: csv-export

## Integration Snapshot
client: unknown
mcp_server: @neiltron/apple-health-mcp
health_data_dir: not_set
last_export_date: unknown
freshness: unknown

## User Intent
<!-- What they want from Apple Health data -->
<!-- Examples: sleep trends, resting heart rate baseline, workout consistency -->

## Constraints
<!-- Privacy constraints, reporting preferences, no-go topics -->

## Notes
<!-- Query caveats, unit normalization choices, schema oddities -->

---
*Updated: YYYY-MM-DD*
```

## integrations.md Template

Create `~/apple-health/integrations.md`:

```markdown
# Apple Health Integrations

## Active Client
- Client: [name]
- Config file: [path]
- Validation: pass | fail
- Last checked: YYYY-MM-DD

## MCP Command
- command: npx
- args: @neiltron/apple-health-mcp
- HEALTH_DATA_DIR: /absolute/path

## Known Issues
- [Issue]: [Fix]
```

## query-log.md Template

Create `~/apple-health/query-log.md`:

```markdown
# Apple Health Query Log

## YYYY-MM-DD
- Goal:
- Query/report used:
- Date window:
- Result summary:
- Caveats:
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Normal state | Keep refining integration and analysis habits |
| `complete` | Stable setup | Skip setup prompts, go straight to analysis |
| `paused` | User postponed integration | Do not push setup, only answer planning questions |
| `never_ask` | User declined setup | Never re-prompt integration unless user requests |

## Key Principles

- Prefer reproducible queries over ad-hoc analysis.
- Record freshness to avoid misleading "latest" claims.
- Keep health data handling minimal and privacy-first.


path: query-recipes.md
content: # Query Recipes — Apple Health MCP

Use these patterns after `health_schema` confirms table names.

## 1) Resting Heart Rate Last 30 Days

```sql
SELECT date_trunc('day', startDate) AS day,
       AVG(CAST(value AS DOUBLE)) AS avg_rhr
FROM hkquantitytypeidentifierrestingheartrate
WHERE startDate >= now() - INTERVAL 30 DAY
GROUP BY 1
ORDER BY 1;
```

## 2) Sleep Duration Last 14 Days

```sql
SELECT date_trunc('day', startDate) AS day,
       SUM(date_diff('minute', startDate, endDate)) / 60.0 AS sleep_hours
FROM hkcategorytypeidentifiersleepanalysis
WHERE startDate >= now() - INTERVAL 14 DAY
GROUP BY 1
ORDER BY 1;
```

## 3) Workouts Per Week (12 Weeks)

```sql
SELECT date_trunc('week', startDate) AS week,
       COUNT(*) AS workouts
FROM hkworkoutactivitytype
WHERE startDate >= now() - INTERVAL 84 DAY
GROUP BY 1
ORDER BY 1;
```

## Reporting Guardrails

- Always show the exact date window used.
- Always keep units visible (bpm, hours, counts).
- If table names differ, map from `health_schema` output and retry.


path: setup.md
content: # Setup — Apple Health

Read this silently when `~/apple-health/` does not exist or is empty.
Start the conversation naturally and focus on enabling the connection fast.

## Priority Order

### 1. Confirm Goal and Client
Ask what the user wants first:
- connect now
- only evaluate options
- troubleshoot existing MCP setup

Then confirm the MCP client (for example Claude Desktop, Cursor, or another MCP-compatible client).

### 2. Confirm Data Source
State this clearly: terminal agents do not read live HealthKit directly.
This workflow uses Apple Health exports in CSV format.

If user has no export yet:
1. Ask them to export Apple Health CSV data from iPhone.
2. Ask where the unzipped export folder is on their computer.
3. Continue only after they provide a concrete local path.

### 3. Wire MCP Server
Use the config from `mcp-config.md` with:
- command `npx`
- package `@neiltron/apple-health-mcp`
- env `HEALTH_DATA_DIR` set to a verified absolute path

If configuration is partial or placeholder-based, fix it before testing queries.

Preflight before first run:
1. Check `node -v` and prefer LTS (18, 20, or 22).
2. Run `npx -y @neiltron/apple-health-mcp` once.
3. If startup fails with missing `duckdb.node`, switch Node version and retry.

### 4. Run Verification Sequence
After wiring:
1. Run `health_schema`
2. Run one bounded query from `query-recipes.md`
3. Confirm expected date range and units

If any step fails, do not proceed to analysis. Fix integration first.

If MCP still fails after Node LTS switch, use the fallback flow in `fallback-cli.md`.

## What to Save

| Save to | Content |
|---------|---------|
| `memory.md` | Status, integration mode, last validated export path, freshness timestamp |
| `integrations.md` | MCP client config decisions and known working command/env |
| `query-log.md` | Queries that worked, plus caveats on units and table names |

## Guardrails

- Never claim real-time Apple Health sync from terminal-only setup.
- Never expose raw CSV rows unless user asks.
- Always disclose when analysis comes from old exports.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)