agentleFS
somz22somz22/personal-health-fitbit/.agents/skills/health-sync/SKILL.md

health-sync

Skill2 starsChanged 8 months agoMITView on GitHub

Sync Fitbit health data to Supabase and local DuckDB — pull, backfill, check status, manage sync schedules

  • Reads credentials
  • Sends data out

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. tonydzi/second-brain-starter-kit★ 6same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 9 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use --full on pull when:

    line 84
  2. Distinctive:

    After fixing a sync issue that affected historical data

    line 87
  3. Distinctive:

    Weight: Only populated if the user logs weight manually or has a Fitbit-connected scale.

    line 109
  4. Very specific:

    Rate limit recovery: If you hit the limit, phf sync --days N replays the full window on re-run (safe because upserts are idempotent).

    line 170
  5. Very specific:

    Create a plist to run phf pull on schedule.

    line 193
  6. Distinctive:

    Check the error message:

    line 206
  7. Distinctive:

    Check if the watch was worn that day (wear quality view):

    line 225
  8. Distinctive:

    Check if Fitbit has the data (query API directly):

    line 229
  9. Distinctive:

    If Fitbit has data but DB does not, trigger a manual sync for that domain.

    line 233
  10. Distinctive:

    Do NOT retry multiple times rapidly — each failed attempt may consume the refresh token

    line 249
  11. Very specific:

    Run phf auth --reauth to get a fresh token pair

    line 250
  12. Distinctive:

    Verify no duplicate cron jobs or Edge Function invocations are running

    line 251
  13. Distinctive:

    All syncs use idempotent upserts:

    line 265

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Health Sync Skill

This skill manages the data pipeline: Fitbit API to Supabase (cloud) to DuckDB (local). It covers syncing, backfilling, status checking, and troubleshooting sync failures.

Architecture Overview

Fitbit Web API
      |
      v
Supabase Edge Function (fitbit-sync)    <-- Cloud, runs 4x/day via pg_cron
      |
      v
Supabase PostgreSQL (source of truth)
      |
      v
phf pull                                <-- Local, on demand or scheduled
      |
      v
DuckDB (data/health.duckdb)             <-- Fast local analytics

Cloud-first design: Supabase syncs 24/7 regardless of whether your laptop is open. The local DuckDB is a read-optimized cache that refreshes on demand.

How to Sync

Pull Latest Data (Supabase to Local DuckDB)

# Pull latest from Supabase into local DuckDB
phf pull

This is the most common operation. It pulls any new data from Supabase into your local DuckDB for fast querying by AI agents.

Trigger Cloud Sync (Fitbit to Supabase)

The cloud sync runs automatically 4x/day via pg_cron. To trigger it manually:

phf sync

# Via Edge Function directly (requires patient_id)
curl -s -X POST "$SUPABASE_URL/functions/v1/fitbit-sync" \
  -H "Authorization: Bearer $SUPABASE_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"patient_id": "YOUR_PATIENT_UUID", "sync_all": true}'

Sync a Single Domain

phf sync --domain heart_rate

# Via Edge Function
curl -s -X POST "$SUPABASE_URL/functions/v1/fitbit-sync" \
  -H "Authorization: Bearer $SUPABASE_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"patient_id": "YOUR_PATIENT_UUID", "domains": ["heart_rate"]}'

Backfill Historical Data

To sync more than the default 3 days:

phf sync --days 30           # Last 30 days, all domains
phf sync --days 90           # Last 90 days (may hit Fitbit rate limits)
phf sync --domain sleep --days 30  # Single domain, 30 days

The --full flag only affects the pull step (Supabase → DuckDB), not the Fitbit fetch:

phf sync --days 30 --full    # Fetch 30 days from Fitbit, then full re-pull to DuckDB
phf pull --full               # Just re-pull everything from Supabase (no Fitbit fetch)

Use --full on pull when:

  • You suspect local DuckDB is out of sync with Supabase
  • After schema changes
  • After fixing a sync issue that affected historical data

The 10 Data Domains

Each domain corresponds to a Fitbit API endpoint and a database table:

DomainTableWhat It ContainsAPI Endpoint
activitydaily_activitySteps, distance, floors, calories, active minutes, sedentary minutes/1/user/-/activities/date/{date}.json
heart_ratedaily_heart_rateResting HR, HR zone minutes and calories (out_of_range, fat_burn, cardio, peak)/1/user/-/activities/heart/date/{date}/1d/1min.json
sleepdaily_sleepSleep duration, efficiency, stages (deep, light, REM, wake), bed/wake times/1.2/user/-/sleep/date/{date}.json
hrvdaily_hrvHeart rate variability — daily RMSSD and deep sleep RMSSD/1/user/-/hrv/date/{date}.json
spo2daily_spo2Blood oxygen saturation (avg, min, max)/1/user/-/spo2/date/{date}.json
breathing_ratedaily_breathing_rateBreaths per minute during sleep stages/1/user/-/br/date/{date}.json
temperaturedaily_temperatureSkin temperature deviation from baseline/1/user/-/temp/skin/date/{date}.json
cardio_scoredaily_cardio_scoreVO2 Max estimate (low and high range)/1/user/-/cardioscore/date/{date}.json
weightdaily_weightWeight (kg), BMI, body fat %/1/user/-/body/log/weight/date/{date}.json
intraday_hrintraday_heart_rateMinute-by-minute heart rate (1440 readings/day max)/1/user/-/activities/heart/date/{date}/1d/1min.json

Known Data Gaps

  • SpO2: Most Fitbit/Pixel Watch devices produce very few readings. Expect sparse data.
  • Weight: Only populated if the user logs weight manually or has a Fitbit-connected scale.
  • Temperature: Requires wearing the watch during sleep consistently.

How to Check Sync Status

phf status

Via Supabase Query

curl -s "$SUPABASE_URL/rest/v1/sync_checkpoints?select=domain,last_synced_date,last_run_at,status,error_message&order=domain" \
  -H "apikey: $SUPABASE_SERVICE_KEY" -H "Authorization: Bearer $SUPABASE_SERVICE_KEY"

Via DuckDB

import duckdb
con = duckdb.connect('data/health.duckdb', read_only=True)
print(con.sql("""
    SELECT domain, last_synced_date, last_run_at, status, error_message
    FROM sync_checkpoints ORDER BY domain
""").show())

Freshness Check

To see how recent each domain's data is:

SELECT 'activity' as domain, max(date) as latest FROM daily_activity
UNION ALL SELECT 'heart_rate', max(date) FROM daily_heart_rate
UNION ALL SELECT 'sleep', max(date) FROM daily_sleep
UNION ALL SELECT 'hrv', max(date) FROM daily_hrv
UNION ALL SELECT 'spo2', max(date) FROM daily_spo2
UNION ALL SELECT 'breathing_rate', max(date) FROM daily_breathing_rate
UNION ALL SELECT 'temperature', max(date) FROM daily_temperature
UNION ALL SELECT 'cardio_score', max(date) FROM daily_cardio_score
UNION ALL SELECT 'weight', max(date) FROM daily_weight
UNION ALL SELECT 'intraday_hr', max(date(timestamp)) FROM intraday_heart_rate
ORDER BY domain;

How to Backfill Historical Data

Initial Backfill (After First Setup)

The setup process typically syncs the last 30 days. For older data:

phf sync --days 90            # Last 90 days
phf sync --days 180           # Last 6 months
phf sync --days 365           # Last year (will hit rate limits — see below)

Backfill Considerations

  • Fitbit rate limit: 150 requests/hour. Each day-domain pair is one request. Backfilling 30 days x 10 domains = 300 requests = ~2 hours at max rate.
  • Intraday HR is the largest: Each day produces up to 1,440 rows. A year of intraday = ~525,600 rows.
  • Rate limit recovery: If you hit the limit, phf sync --days N replays the full window on re-run (safe because upserts are idempotent). The cloud Edge Function uses checkpoint-based resume automatically. Just re-run after waiting an hour.
  • All writes are idempotent: Uses INSERT ON CONFLICT UPDATE (upsert), so re-running is safe.

Sync Schedule

Cloud Sync (pg_cron, Automatic)

By default, 4 sync times per day (computed from TIMEZONE in .env during setup):

Local TimePurpose
06:00Morning — captures overnight sleep + HR
12:00Midday — captures morning activity
18:00Evening — captures afternoon data
23:00Night — captures full day summary

The actual UTC cron expressions depend on your timezone. Check cron.job in Supabase if you need exact times.

Local DuckDB Pull (User-Managed)

Options for keeping local DuckDB fresh:

macOS (launchd): Create a plist to run phf pull on schedule.

Linux (cron):

0 7,12,18,23 * * * cd /path/to/project && phf pull >> data/logs/sync.log 2>&1

Manual: Just run phf pull whenever you want fresh data before analysis.

Troubleshooting Sync Failures

Sync Status Shows "error"

Check the error message:

curl -s "$SUPABASE_URL/rest/v1/sync_checkpoints?status=eq.error&select=domain,error_message" \
  -H "apikey: $SUPABASE_SERVICE_KEY" -H "Authorization: Bearer $SUPABASE_SERVICE_KEY"

Common Sync Errors

ErrorCauseFix
token_refresh_failedFitbit refresh token invalidatedRun phf auth --reauth
rate_limit_exceededMore than 150 requests/hourWait 1 hour, will auto-recover
fitbit_api_500Fitbit servers temporarily downWill auto-retry next scheduled run
edge_function_timeoutSync took >150s (large backfill)Use CLI for backfills: phf sync --days N
supabase_write_errorDatabase write failedCheck Supabase dashboard for DB status
stale_dataData not updating for a domainCheck if device is syncing to Fitbit app

Data Missing for Specific Days

  1. Check if the watch was worn that day (wear quality view):
    SELECT * FROM daily_wear_quality WHERE date = '2026-03-19'
  2. Check if Fitbit has the data (query API directly):
    phf sync --domain heart_rate --days 1
  3. If Fitbit has data but DB does not, trigger a manual sync for that domain.

DuckDB Out of Sync with Supabase

# Full re-pull from Supabase
phf pull --full

# Or single table
phf pull --table daily_heart_rate

OAuth2 Token Safety

Fitbit refresh tokens are one-time-use. The system is designed so only one process touches the token at a time (single-dispatcher Edge Function). If you see token_refresh_failed:

  1. Do NOT retry multiple times rapidly — each failed attempt may consume the refresh token
  2. Run phf auth --reauth to get a fresh token pair
  3. Verify no duplicate cron jobs or Edge Function invocations are running

Data Flow Details

Incremental Sync (Default)

Each sync:

  1. Reads last_synced_date from sync_checkpoints for each domain
  2. Fetches data from last_synced_date to today
  3. Upserts into the appropriate table (INSERT ON CONFLICT UPDATE)
  4. Updates sync_checkpoints with new date and timestamp

Upsert Strategy

All syncs use idempotent upserts:

  • Daily tables: ON CONFLICT (patient_id, source, date) DO UPDATE
  • Sleep table: ON CONFLICT (patient_id, source, log_id) DO UPDATE (supports multiple sleep entries per day)
  • Intraday HR: ON CONFLICT (patient_id, source, timestamp) DO UPDATE

This means re-running a sync is always safe — it will not create duplicates.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.