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

health-setup

Skill2 starsChanged 8 months agoMITView on GitHub

Interactive first-time setup and onboarding for Personal Health Fitbit — guides user through Supabase, Fitbit, initial sync, health personalization, and generates tailored HEALTH_CONTEXT.md + AGENTS.md

  • 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. mycelium-hq/ai-brain-starter★ 50same 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

28 rules. About 0 are common, 18 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈18

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask one thing, wait for the answer, execute, verify, then move to the next.

    line 10
  2. Distinctive:

    When the user needs to do something in a web UI, give exact click paths.

    line 15
  3. Distinctive:

    After each credential or step, verify it worked before moving on.

    line 16
  4. Distinctive:

    If something fails, diagnose it immediately — don't move forward with a broken step.

    line 17
  5. Distinctive:

    Wait for confirmation before proceeding.

    line 54
  6. Distinctive:

    After receiving them, verify immediately:

    line 68
  7. Distinctive:

    If this fails, help debug (trailing slash?

    line 74
  8. Very specific:

    Should return [] (empty array = tables exist, just no data yet).

    line 124
  9. Distinctive:

    Ask exactly this — copy the table verbatim, all 10 rows:

    line 135
  10. Very specific:

    After getting the client ID and secret, update .env:

    line 160
  11. Distinctive:

    If Supabase PAT is configured, tokens are also pushed to Supabase secrets for the Edge Function auto-sync

    line 180
  12. Very specific:

    If port 8080 is busy, tell the user to free it: lsof -ti:8080 | xargs kill

    line 183
  13. Distinctive:

    If this fails with "npx not found", tell the user:

    line 209
  14. Very specific:

    Should return {"error":"patient_id is required"} — deployed and running.

    line 221
  15. Very specific:

    Update the TIMEZONE value in .env with the user's answer from Question 9.

    line 330
  16. Very specific:

    Create HEALTH_CONTEXT.md (the actual file, NOT the template) with the user's real information.

    line 391
  17. Distinctive:

    After the backfill completes, compute baselines from actual data:

    line 395
  18. Very specific:

    Write those computed baselines into HEALTH_CONTEXT.md alongside the user's answers.

    line 430
  19. Very specific:

    Do NOT write personal health data into AGENTS.md — it is a public, git-tracked file.

    line 439
  20. Very specific:

    All user-specific context (patient ID, conditions, baselines, goals) lives ONLY in HEALTH_CONTEXT.md, which is gitignored.

    line 440
  21. Distinctive:

    No changes to AGENTS.md are needed.

    line 444
  22. Distinctive:

    Run the full diagnostic:

    line 450
  23. Distinctive:

    ALL 13 checks should pass.

    line 456
  24. Distinctive:

    Ensure the Fitbit/Pixel Watch app on the phone has synced recently.

    line 492
  25. Distinctive:

    Only one process can write at a time.

    line 500
  26. Very specific:

    Run phf sync --days 13 (143 requests, just under limit)

    line 512
  27. Distinctive:

    Run again (it picks up from checkpoint)

    line 514
  28. Distinctive:

    If paused: go to Supabase dashboard → Restore project.

    line 518

≈ “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 Setup Skill

You are guiding a user through first-time setup of Personal Health Fitbit. This is a conversational, one-step-at-a-time onboarding. Never dump multiple requests at once. Ask one thing, wait for the answer, execute, verify, then move to the next.

Tone

  • Friendly but efficient. Explain WHY when it's not obvious, skip the why when it is.
  • When the user needs to do something in a web UI, give exact click paths.
  • After each credential or step, verify it worked before moving on.
  • If something fails, diagnose it immediately — don't move forward with a broken step.

Before You Start

Run detection:

cd <project_root>
export $(cat .env 2>/dev/null | grep -v '^#' | xargs) 2>/dev/null
python3 -m src.cli.main doctor 2>&1 || echo "DOCTOR_FAILED"

Based on the output, tell the user where they are:

  • Fresh install (most checks fail) → Start at Phase 2
  • Partial setup (some pass) → Skip to the first failing phase
  • Already configured (all pass) → Ask if they want to re-personalize (Phase 5)

Phase 1 (Prerequisites) is checked silently — only mention if something fails.


Phase 2: Supabase Setup

This phase has 4 sub-steps. Do them ONE AT A TIME.

Step 2a: Create a Supabase project

Ask:

First, we need a database. Supabase gives you a free PostgreSQL database in the cloud — it's where your Fitbit data lives.

Do you already have a Supabase account? If so, just create a new project for this. If not, head to https://supabase.com and sign up (it's free). Then create a new project — name it whatever you like (e.g., "health-tracker").

Let me know when your project is created.

Wait for confirmation before proceeding.

Step 2b: Get your Project URL and Service Key

Ask:

Great! Now I need two things from your Supabase dashboard.

  1. Go to Settings (gear icon, left sidebar) → API
  2. Copy the Project URL — it looks like https://abcdefgh.supabase.co
  3. Scroll down to Project API Keys → copy the service_role key (it starts with eyJ...). NOT the anon/public key — the service_role one.

Paste the URL and service key here.

After receiving them, verify immediately:

curl -s "<URL>/rest/v1/" -H "apikey: <KEY>" -H "Authorization: Bearer <KEY>" | head -c 100

If this fails, help debug (trailing slash? wrong key? project paused?).

Step 2c: Get your PAT and Project Ref

Ask:

Two more things (last Supabase step, I promise):

  1. Project Ref — this is the abcdefgh part of your URL (e.g., if URL is https://abcdefgh.supabase.co, the ref is abcdefgh)
  2. Personal Access Token (PAT) — this is different from the service key.
    • Click your avatar (top right) → Account → Access Tokens
    • Generate a new token, name it "health-tracker"
    • Copy it — it starts with sbp_...

Paste both here.

Step 2d: Create .env and apply schema

Once you have all 4 values, create the .env file:

cat > .env << 'ENVEOF'
# Supabase
SUPABASE_URL=<URL>
SUPABASE_SERVICE_KEY=<service_role key>
SUPABASE_PROJECT_REF=<project ref>
SUPABASE_PAT=<PAT>

# Fitbit (filled in next phase)
FITBIT_CLIENT_ID=
FITBIT_CLIENT_SECRET=
TIMEZONE=UTC
ENVEOF

Then apply the database schema:

export $(cat .env | grep -v '^#' | xargs)
python3 scripts/setup_supabase.py schema

Verify it worked:

curl -s "$SUPABASE_URL/rest/v1/patients?select=id&limit=1" \
  -H "apikey: $SUPABASE_SERVICE_KEY" -H "Authorization: Bearer $SUPABASE_SERVICE_KEY"

Should return [] (empty array = tables exist, just no data yet).

Tell the user:

Supabase is ready — 23 tables created. Now let's connect your Fitbit.


Phase 3: Fitbit Setup

Step 3a: Register a Fitbit developer app

Ask exactly this — copy the table verbatim, all 10 rows:

Now we need to connect your Fitbit account. Go to https://dev.fitbit.com/apps/new and fill in every field like this:

FieldWhat to enter
Application NamePersonal Health Tracker
DescriptionPersonal health data sync
Application Website URLhttps://github.com/somiljain7/personal-health-fitbit
OrganizationPersonal
Organization Website URLhttps://github.com/somiljain7/personal-health-fitbit
Terms of Service URLhttps://github.com/somiljain7/personal-health-fitbit
Privacy Policy URLhttps://github.com/somiljain7/personal-health-fitbit
OAuth 2.0 Application TypePersonal
Redirect URLhttp://127.0.0.1:8080/callback
Default Access TypeRead-Only

Check these scope checkboxes: activity, heartrate, sleep, profile, oxygen_saturation, respiratory_rate, temperature, cardio_fitness, weight.

Click Register. Share your Client ID and Client Secret.

Step 3b: Authorize with Fitbit

After getting the client ID and secret, update .env:

# Add/update these lines in .env:
# FITBIT_CLIENT_ID=<their client ID>
# FITBIT_CLIENT_SECRET=<their client secret>

Then run the OAuth2 authorization:

export $(cat .env | grep -v '^#' | xargs)
python3 -m src.cli.main auth

This will:

  1. Open their browser to Fitbit's login page
  2. They log in and click "Allow"
  3. Fitbit redirects back to a local server
  4. Tokens are saved to .fitbit_tokens (gitignored)
  5. If Supabase PAT is configured, tokens are also pushed to Supabase secrets for the Edge Function auto-sync

If port 8080 is busy, tell the user to free it: lsof -ti:8080 | xargs kill

Verify it worked:

export $(cat .env | grep -v '^#' | xargs)
python3 -c "from src.auth.oauth import FitbitAuth; a = FitbitAuth(); print('Token:', a.get_token()[:20] + '...')"

Tell the user:

You're connected to Fitbit! Now let's deploy the auto-sync.


Phase 4: Deploy Cloud Infrastructure

Step 4a: Deploy Edge Function

export $(cat .env | grep -v '^#' | xargs)
python3 scripts/setup_supabase.py deploy

This uses supabase functions deploy --use-api which bundles server-side (no Docker needed) and uploads to Supabase. It also pushes the Fitbit tokens as secrets automatically.

If this fails with "npx not found", tell the user:

Install Node.js from https://nodejs.org (LTS version). Let me know when done.

Verify:

export $(cat .env | grep -v '^#' | xargs)
curl -s -X POST "https://$SUPABASE_PROJECT_REF.supabase.co/functions/v1/fitbit-sync" \
  -H "Authorization: Bearer $SUPABASE_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' 2>&1 | head -c 200

Should return {"error":"patient_id is required"} — deployed and running.

Tell the user:

Auto-sync deployed. We'll set up the schedule after creating your profile. Now let's get to know you.


Phase 5: Get to Know the User

This is where the system becomes personal. Ask these questions in a NATURAL, CONVERSATIONAL way. Do NOT fire them one by one like a form. Instead, batch them into 2-3 natural groups.

Group A: "Tell me about yourself" (ask all at once)

Now for the fun part — I need to understand your health context so I can give you personalized analysis instead of generic advice.

Tell me:

  1. Your name (for your health profile)
  2. Age and gender (affects HR and HRV baselines)
  3. Any health conditions you're managing — things like ADHD, post-COVID, thyroid issues, GI problems, sleep disorders, anxiety, etc.
  4. Medications or supplements you take regularly (with dosage if you know it)

Don't worry about being complete — you can always update this later.

Group B: "What are your goals?" (ask after Group A)

Thanks! Now: 5. What are your top 2-3 health goals? For example:

  • Better sleep
  • Lower resting heart rate
  • More consistent exercise
  • Improve HRV
  • Lose weight
  • Just general awareness
  1. Do you exercise regularly? What kind and how often?
  2. Any patterns you already know about? Things like:
    • "Late meals spike my heart rate"
    • "I sleep terribly if I skip exercise"
    • "My sleep schedule is chaotic"

Group C: "Data preferences" (ask after Group B)

Almost done with questions!

  1. How far back should I sync your Fitbit data?
    • 1 week (quick test)
    • 1 month (basic trends)
    • 3 months (good baseline)
    • 6 months (strong history)
    • 1 year (comprehensive)
    You can always pull more later with phf sync --days N.
  2. What timezone are you in? (e.g., America/New_York, Asia/Kolkata)
  3. Any data gaps I should know about? (times you didn't wear your watch, sensors that don't work on your device, etc.)

Phase 6: Create Patient + Backfill

Create patient record

export $(cat .env | grep -v '^#' | xargs)
curl -s -X POST "$SUPABASE_URL/rest/v1/patients" \
  -H "apikey: $SUPABASE_SERVICE_KEY" -H "Authorization: Bearer $SUPABASE_SERVICE_KEY" \
  -H "Content-Type: application/json" -H "Prefer: return=representation" \
  -d '{
    "name": "<name>",
    "date_of_birth": "<YYYY-MM-DD or null>",
    "gender": "<gender>",
    "known_conditions": ["<condition1>", "<condition2>"],
    "fitbit_user_id": "<fitbit_user_id or null>"
  }'

Save the returned id — this is the patient_id used everywhere.

Add medications to database

For each medication the user listed:

curl -s -X POST "$SUPABASE_URL/rest/v1/medications" \
  -H "apikey: $SUPABASE_SERVICE_KEY" -H "Authorization: Bearer $SUPABASE_SERVICE_KEY" \
  -H "Content-Type: application/json" -H "Prefer: return=representation" \
  -d '{
    "patient_id": "<patient_id>",
    "name": "<med_name>",
    "dosage": "<dosage>",
    "frequency": "<frequency>",
    "active": true
  }'

Add PATIENT_ID to .env

Append PATIENT_ID=<patient_id> to .env so phf sync can find it.

Update TIMEZONE in .env

Update the TIMEZONE value in .env with the user's answer from Question 9.

Then push TIMEZONE to Supabase secrets so the Edge Function uses the correct timezone:

export $(cat .env | grep -v '^#' | xargs)
python3 -c "
import subprocess, os, json
ref = os.environ['SUPABASE_PROJECT_REF']
pat = os.environ['SUPABASE_PAT']
tz = os.environ.get('TIMEZONE', '')
if tz:
    subprocess.run(['curl', '-s', '-X', 'POST',
        f'https://api.supabase.com/v1/projects/{ref}/secrets',
        '-H', f'Authorization: Bearer {pat}',
        '-H', 'Content-Type: application/json',
        '-d', json.dumps([{'name': 'TIMEZONE', 'value': tz}])],
        capture_output=True)
    print(f'TIMEZONE={tz} pushed to Supabase secrets')
"

Set up pg_cron (auto-sync 4x/day)

This must run AFTER TIMEZONE is set so the cron schedules target the correct local times.

Note: pg_cron uses static UTC expressions. If your timezone observes DST, re-run this step after each DST transition to keep sync times aligned with your local clock.

export $(cat .env | grep -v '^#' | xargs)
python3 scripts/setup_supabase.py cron --patient-id <patient_id>

Run initial backfill

Map backfill choice to days: 1 week=7, 1 month=30, 3 months=90, 6 months=180, 1 year=365.

export $(cat .env | grep -v '^#' | xargs)
export PATIENT_ID="<patient_id>"
python3 -m src.cli.main sync --days <N>

Rate limit note: Fitbit allows 150 requests/hour. Each day uses ~11 requests.

  • 7 days: ~77 requests — fits in one run
  • 30 days: ~330 requests — may need 2-3 runs over ~2 hours
  • 90+ days: multiple runs spread over a few hours

Tell the user progress as it runs. If it hits rate limits:

The Fitbit API limits us to 150 requests/hour. I've synced up to [date] so far. Run phf sync --days <N> again in about an hour — it replays the full window but upserts are idempotent, so already-synced days are just updated in place.


Phase 7: Personalize

Generate three files from the user's answers.

7a: Generate HEALTH_CONTEXT.md

Create HEALTH_CONTEXT.md (the actual file, NOT the template) with the user's real information. Use the structure from HEALTH_CONTEXT.md.template but fill in every field.

After the backfill completes, compute baselines from actual data:

import duckdb
con = duckdb.connect('data/health.duckdb', read_only=True)

# RHR baselines
print(con.sql("""
    SELECT min(resting_hr) as best_rhr, round(avg(resting_hr),1) as avg_rhr,
           round(percentile_cont(0.25) WITHIN GROUP (ORDER BY resting_hr),1) as p25,
           round(percentile_cont(0.75) WITHIN GROUP (ORDER BY resting_hr),1) as p75
    FROM v_hr_clean
""").show())

# HRV baselines
print(con.sql("""
    SELECT round(max(daily_rmssd),1) as best_hrv, round(avg(daily_rmssd),1) as avg_hrv
    FROM v_hrv_clean
""").show())

# Sleep baselines
print(con.sql("SELECT round(avg(minutes_asleep)/60.0,1) as avg_hours FROM v_sleep_clean").show())

# Steps baselines
print(con.sql("SELECT round(avg(steps),0) as avg_steps FROM v_activity_clean").show())

# VO2 Max
print(con.sql("""
    SELECT min(vo2_max_low) as vo2_low, max(vo2_max_high) as vo2_high
    FROM daily_cardio_score WHERE vo2_max_low IS NOT NULL
""").show())

con.close()

Write those computed baselines into HEALTH_CONTEXT.md alongside the user's answers.

Include all personal fields from the user's Phase 5 responses: name, age, gender, timezone, known conditions, activity level, sleep pattern, and exercise routine (from Group B Question 6 — type, frequency, and any patterns the user described). Fill in the - **Exercise routine**: line in the "About Me" section with the user's answer.

7b: Note on AGENTS.md

Do NOT write personal health data into AGENTS.md — it is a public, git-tracked file. All user-specific context (patient ID, conditions, baselines, goals) lives ONLY in HEALTH_CONTEXT.md, which is gitignored.

AGENTS.md already instructs the agent to read HEALTH_CONTEXT.md at session start. No changes to AGENTS.md are needed.


Phase 8: Final Verification

Run the full diagnostic:

python3 -m src.cli.main doctor

ALL 13 checks should pass. If any fail, fix them before declaring setup complete.

Show the user a summary

Setup complete!

  Patient:     <name> (<patient_id>)
  Data range:  <earliest date> to <latest date> (<N> days)
  Auto-sync:   4x/day (6AM, 12PM, 6PM, 11PM <timezone>)
  Local DB:    data/health.duckdb (<size> MB)
  Goals:       <their goals>

  Quick stats from your data:
    Resting HR:  avg <X> bpm (best <Y>)
    HRV:         avg <X> ms
    Sleep:       avg <X> hours
    Steps:       avg <X>/day

  What to do next:
  - "Analyze my sleep quality this month"
  - "How's my resting heart rate trending?"
  - "Compare this week to last week"
  - Run `phf pull` anytime for fresh data

Troubleshooting Reference

"Token has been revoked" / OAuth2 Refresh Failure

Fitbit refresh tokens are one-time-use. If two processes refresh simultaneously, one invalidates the other. Fix: re-authorize from scratch.

"No data for today"

Fitbit data may not be available until the device syncs to the Fitbit app. Ensure the Fitbit/Pixel Watch app on the phone has synced recently.

Supabase Connection Refused

  • URL has no trailing slash
  • Key is service_role (starts with eyJ), not anon key
  • Project is not paused (free tier pauses after 7 days inactivity)

DuckDB "database is locked"

Only one process can write at a time. Close other terminals or processes.

Missing Intraday HR Data

App must be registered as Personal type at dev.fitbit.com. Server/Client types do not get intraday access.

Edge Function Timeout

Free tier: 150s limit. All 10 domains typically complete in ~10s. If backfilling, use phf sync from CLI instead (no timeout).

Rate Limits (Fitbit API)

150 requests/hour. Each day of sync uses ~11 requests. For large backfills:

  • Run phf sync --days 13 (143 requests, just under limit)
  • Wait 1 hour
  • Run again (it picks up from checkpoint)

Supabase Free Tier Pausing

Projects pause after 7 days of inactivity. The 4x/day pg_cron sync keeps it alive. If paused: go to Supabase dashboard → Restore project.

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.