healthkit-pro

A reviewer-style agent skill for Claude Code that focuses on the HealthKit edge cases that bite production apps and surface only in TestFlight crash logs or "my route disappeared" support emails:

• Route-builder pitfalls — isProtectedDataAvailable check, builder lifecycle, endCollection → finishWorkout → session.end() → finishRoute sequence, seriesBuilder requirement, CLLocationUpdate quirks on iOS/watchOS 26, route-presence indicator (don't use workout.totalDistance as a proxy)
• Authorization drift — authorizationStatus vs. requestAuthorization, read-auth ambiguity, foreground re-validation, background-delivery entitlements

It reports only genuine problems (Hudson principle) — no nitpicking, no rephrasing, no inventing issues.

Install

As a Claude Code plugin (when published to a marketplace):

/plugin marketplace add eigenfunk/healthkit-pro-agent-skill
/plugin install healthkit-pro@healthkit-pro-agent-skill

Or as a user-global skill via symlink (development workflow):

git clone https://github.com/eigenfunk/healthkit-pro-agent-skill.git
ln -s "$(pwd)/healthkit-pro-agent-skill/skills/healthkit-pro" \
      ~/.claude/skills/healthkit-pro

Usage

The skill auto-invokes on calls to HKLiveWorkoutBuilder.endCollection, HKLiveWorkoutBuilder.finishWorkout, HKWorkoutRouteBuilder.finishRoute, HKWorkoutRouteBuilder.insertRouteData, HKWorkoutSession.end, or HealthKit authorization flows (requestAuthorization, authorizationStatus). It skips routine HKObjectQuery reads, sample saving, and non-workout HealthKit usage.

Manual triggers:

/healthkit-pro                          # full review (route-builder + authorization)
/healthkit-pro Focus on route           # only route-builder.md
/healthkit-pro Focus on auth            # only authorization.md

Output format per finding:

<file>:<line> · [<pattern-id>] · <one-line reason>

Pattern IDs map to the reference files: R1–R6 are route-builder checks; A1–A4 are authorization checks. Findings are grouped by reference area and end with a count summary.

Scope

Two reference areas are covered today; the broader HealthKit surface (background delivery, HKAnchoredObjectQuery for recovery streams, extended runtime sessions outside workouts, entitlements / Apple-Review medical-device disclosure) is on the roadmap.

The route-builder substance is grounded in a real-world investigation of an erratic GPS-route-loss bug — five suspected causes from the Apple developer forum, distilled into the five R* checks.

See also

This skill is a companion to other reviewer-style Swift skills:

• swift-clean-code — domain-layer code hygiene (mutation, state-vs-listener, pure-core/effectful-shell)
• swiftui-pro by Paul Hudson — UI layer (view composition, modifiers, navigation, accessibility)
• swift-concurrency-pro by Paul Hudson — concurrency (async/await, Sendable, actor isolation)
• claude-code-apple-skills by Rajesh Shankras — broader Apple-platform skill collection (includes a health-fitness.md reference inside the watchos skill, which complements but does not overlap with the workout-finish edge cases covered here)

In a typical HealthKit-aware Swift project you install several of these in parallel; they cover different layers and don't overlap meaningfully.

Contributing

Contributions are welcome — especially for HealthKit edge cases not yet covered. The contribution rule mirrors Hudson's: do not repeat things that LLMs already know. Focus on edge cases, silent failures, framework quirks confirmed in the Apple developer forum or feedback assistant.

License

MIT — see LICENSE.