Apple Health

Files (7)

• SKILL.md
• _meta.json
• fallback-cli.md
• mcp-config.md
• memory-template.md
• query-recipes.md
• setup.md

SKILL.md (first lines)

## 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 `~/Clawic/data/apple-health/`. See `memory-template.md` for setup.

```
~/Clawic/data/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: `HEALTH_DATA_DIR=/absolute/path/to/export`

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 `~/Clawic/data/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).

From clawic/skills, MIT.

More from clawic/skills