strava-sync
Skill0 starsChanged 4 months agoMITView on GitHub
Pull the athlete's Strava activities, match runs to training-plan days, auto-complete confirmed sessions, grade each run against its blended target pace, and recompute the 28-day fitness block. Use when the athlete says "sync", "pull my runs", or "did Strava get my run", after any day a planned run should have happened, or before a daily check-in, weekly review, or dashboard refresh needs fresh data.
- Reads credentials
- Sends data out
In this repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- daily-checkinSkill
- dashboardSkill
- deploy-webappSkill
- food-logSkill
- healthkit-importSkill
- nutrition-setupSkill
- onboardingSkill
- plan-adjustSkill
- plan-builderSkill
- race-prepSkill
- weekly-reviewSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Before plan-builder grounds a new plan in real data (it needs the fitness block this skill computes).
- Very specific: line 44
Run date +%F for today. Build the weekday-to-date table for this week and next (per the COACH.md ritual) and pair every weekday you mention …
- Very specific: line 48
Read athlete/plan.json and athlete/log.json.
- Very specific: line 146
Write athlete/log.json (done + activities + fitness).
- Very specific: line 147
Write the updated athlete/plan.json (statuses + actuals.
- Very specific: line 179
Truthfulness guard: never say "Synced" or "Marked complete" unless the file writes happened this turn.
- Very specific: line 180
All matching, grading, fitness, and streak math follows reference/tracking.md — do not restate thresholds from memory.
- Distinctive: line 199
Run a daily check-in for today's session brief.
- Very specific: line 200
If the season delta is well behind plan or several runs graded "slower", offer a weekly review or plan-adjust conversation.
≈ “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.
Files
Strava sync
Strava confirms, the athlete doesn't log. Any planned run day with a matched Strava activity is marked complete automatically, credited with its actual distance and pace, and graded against its target — the athlete never types in a run their watch already recorded. This skill is the bridge between the athlete's real training and the plan files.
When to run
- The athlete asks to sync, mentions a recent run, or asks how training is going.
- A daily check-in or weekly review is about to report on training (sync first so numbers are current).
- The dashboard is about to be regenerated.
- Before plan-builder grounds a new plan in real data (it needs the fitness block this skill computes).
- It has been more than ~3 days since
fitness.syncedDateinathlete/log.json.
Inputs
Files read:
athlete/plan.json— the plan (schema:templates/plan.schema.json). If it does not exist yet, sync still works: pull the last 75 days for fitness context only and skip matching.athlete/log.json— existing done map, activities map, fitness block. If missing, create it as{ "done": {}, "activities": {}, "fitness": null }.athlete/profile.md— declared units and timezone.
Tools, in priority order:
- Strava MCP connector (best):
list_activities. Exact prefixes vary by harness — on claude.ai the tool ismcp__claude_ai_Strava__list_activities; discover what is available (ToolSearch in Claude Code) and adapt. Related tools you may use for enrichment:get_athlete_profile,get_athlete_zones,get_activity_performance. - Manual Strava API (fallback): requires a one-time OAuth bootstrap — walk the athlete through the cookbook in
guides/02-getting-your-data.md(Path C), which producesSTRAVA_CLIENT_ID,STRAVA_CLIENT_SECRET, andSTRAVA_REFRESH_TOKENin an untracked.env. - Paste or export (last resort): the athlete pastes activities from the Strava app or drops a CSV/GPX export; normalize to the same shape as everything else and continue from step 5.
What to ask the athlete: normally nothing. The only question this skill asks is about past planned runs with no Strava match (step 9).
Procedure
Compute everything with python — never do date, pace, or mileage arithmetic in your head.
0. Connector check
Look for the Strava MCP tools before anything else — in Claude Code, search the available tools (ToolSearch) for strava; on claude.ai, check for mcp__claude_ai_Strava__*. If nothing surfaces, do not jump to the manual API: the connector is a five-minute setup, and walking the athlete through it beats maintaining OAuth credentials forever. Follow Path A in guides/02-getting-your-data.md — enable the Strava connector on claude.ai (Settings → Connectors → Strava → Connect); in Claude Code, the same account's connectors surface as mcp__claude_ai_Strava__* tools (exact mechanics vary by version — re-check the tool list after connecting). Only when the connector genuinely can't be enabled do you fall back to the manual-API cookbook (Path C) or paste/export.
1. Date ritual
Run date +%F for today. Build the weekday-to-date table for this week and next (per the COACH.md ritual) and pair every weekday you mention with its date.
2. Load state
Read athlete/plan.json and athlete/log.json. Note the plan's meta.start_date and meta.race_date (or meta.end_date for non-race plans).
3. Choose the sync window
- With a plan: from
start_dateminus 35 days torace_date/end_date. The 35-day widening exists so the 28-day fitness window has data during week 1 — without it the fitness block is empty at the exact moment the athlete most wants to see their base. - Without a plan: the last 75 days (covers the 28-day fitness window plus the 4-week trend).
4. Fetch activities
MCP first. The shipped web app called its connector with:
{ "first": 100, "range_start": "YYYY-MM-DDT00:00:00", "range_end": "YYYY-MM-DDT23:59:59", "ordering": "StartDateLocalAsc" }Expect the claude.ai connector's parameter schema to differ slightly — inspect the tool schema and map the same intent (date-bounded, ascending, ~100 per page). If you get exactly 100 activities back, the window may be clipped: page or re-query the remainder.
Manual API fallback — two calls, secrets stay in .env, never echo them:
# 1. refresh-token -> access token
curl -s -X POST https://www.strava.com/oauth/token \
-d client_id=$STRAVA_CLIENT_ID -d client_secret=$STRAVA_CLIENT_SECRET \
-d grant_type=refresh_token -d refresh_token=$STRAVA_REFRESH_TOKEN
# 2. list activities — `after` is epoch SECONDS, not milliseconds
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://www.strava.com/api/v3/athlete/activities?after=$AFTER_EPOCH&per_page=100"Rate limits are per application: 200 reads per 15 minutes, 2,000 per day. On a 429, read the X-ReadRateLimit-Usage header and back off until the next quarter-hour window (:00/:15/:30/:45). One sync is two requests — never poll in a loop.
5. Normalize the wire fields
Map every activity to one shape:
| Field | Source | Gotcha |
sport_type | a.sport_type || a.type | older responses only have the legacy type |
date | (a.start_local || a.start_date_local).slice(0, 10) | local wall-clock with no timezone suffix — take the first 10 chars, never parse as UTC or evening runs shift a day |
dist_m | a.summary.distance or a.distance | meters |
sec | moving_time | never elapsed_time |
name, id | as-is |
Filter to sport_type === "Run" (exact string) for plan matching. VirtualRun and TrailRun are excluded by default — if the athlete runs on trails or a treadmill, ask once and widen the filter, recording the choice in athlete/profile.md. If the plan contains Walk days, additionally match sport_type === "Walk" activities to planned Walk days by local date (duration ≥ 60% of the planned duration_min) and mark them done; bonus walks on other days stay ignored, as ever.
6. Match runs to plan days
Per the rules in reference/tracking.md (## Activity matching):
- Key runs by local date. If two runs share a date, the longest (by raw meters) wins — note that a shakeout plus a long run on the same day collapses to one entry; the main run survives.
- A run matches the plan day with the same
dateonly if that day hastotal_miles > 0. A run on a Rest, Lift, or Cross-Train day never checks anything. - Pace math (
## Pace mathinreference/tracking.md):miles = dist_m / 1609.34;pace_sec_per_mi = round((sec / 60 / miles) * 60); format asM:SSby splitting the rounded total seconds — rounding minutes and seconds separately produces9:60. Pace is--when miles is 0.
For each matched date:
log.json: setdone[date] = true; upsertactivities[date] = { "dist_mi": <1dp>, "pace": "M:SS", "name": ..., "id": ..., "source": "strava" }.plan.json: set that day'sstatusto"completed"and fillactual:
{ "distance_mi": 6.9, "pace": "8:41", "source": "strava", "grade": "on", "activity_id": 123456 }Merging discipline: the done map is additive — never un-check a day (manual check-offs stay valid). In the activities map, a fresh Strava entry overwrites a manual one for the same date (device evidence wins); entries for dates Strava returned nothing for are left alone.
7. Grade each newly matched run
Use the blended-expectation grade from reference/tracking.md (## Run grading): build expectedAvgSec — a mileage-weighted blend of warm-up and cool-down at easy pace, reps at rep pace, recovery jogs at recovery pace — and compare the run's whole-session average with ±15 s/mi tolerance. Never grade a structured workout's average against the rep pace alone, or every interval day reads "slower".
Verdicts are exactly three, neutral, never scolding:
grade | Shown as |
faster | Faster than target |
on | On target |
slower | Slower than target |
8. Recompute the fitness block
Per reference/tracking.md (## Current fitness), over all synced runs (windows are relative to today):
"fitness": {
"weeklyMiles": 21.5,
"runs7": 4,
"avgPace": "9:02",
"longest": 8.3,
"totalRuns28": 10,
"totalMiles28": 59.4,
"weekly": [14.3, 17.0, 6.5, 21.5],
"lastRun": { "name": "Morning Run", "dist": "3.1", "pace": "9:19", "date": "2026-06-27" },
"syncedDate": "2026-06-28"
}avgPace is duration-weighted (total seconds / total miles over 28 days, then formatted). weekly is four 7-day buckets, oldest first — index 3 is the current 7 days. longest is the biggest single run in 28 days. Always carry syncedDate so stale data is visible everywhere it is rendered.
9. Write files and reconcile gaps
- Write
athlete/log.json(done + activities + fitness). - Write the updated
athlete/plan.json(statuses + actuals; completed days from earlier syncs are preserved untouched). - Upsert synced activities into
athlete/health/workouts.csv(id,date,start,end,duration_min,type,kcal,distance_km,source), sourcestrava, type mapped to the shared vocabulary: Run→running, Walk→walking, Ride/VirtualRide→cycling, Swim→swimming, WeightTraining→strength, Yoga→yoga, Rowing/Elliptical/Workout→cross_training, else→other.end= start + moving time when no elapsed time is available; leavekcalblank unless the connector suppliedtotal_calories(the raw REST list endpoint has no calories field). Skip an activity if a HealthKit row already exists with start within ±3 minutes and the same type — one workout, one row. - Collect past plan days with
total_miles > 0,date < today, and no match and not done. These are not failures — they get a gentle "not yet on Strava" line in the digest, and you ask: run missed, or did the watch just not upload? If the athlete says they ran, mark the day done manually (it credits the planned distance per## Completion statsinreference/tracking.md).
10. Print the sync digest
Compute first, then narrate. The digest:
- Synced N runs and the window, labeled with provenance:
Synced from Strava · <date>. - This week: miles run vs. planned miles due by today (run days this week with date ≤ today, excluding
Race), and runs done of runs due. - Season: total credited miles, the date-to-date ahead/behind delta (
round(actual_to_date − planned_due_to_date)per## Completion stats), and the current training streak per## Adherence and streaksinreference/tracking.md(an unchecked today never breaks the streak — the run may still happen or sync tonight; an unchecked past planned day does). - New matches: one line per newly matched run with its grade.
- Not yet on Strava: the gap list from step 9, if any.
Example shape:
Synced 4 runs from Strava · 2026-07-06
This week (W7, Mon 07-06 – Sun 07-12): 6.9 of 7 mi due · 1 of 1 run done
Season: 148 mi logged · 4 mi ahead of plan · 9-day training streak
New matches
Sat 07-04 Long · 12 mi 12.2 mi @ 9:18 On target
Sun 07-05 Recovery · 4 mi 4.0 mi @ 9:58 On target
Mon 07-06 Tempo · 5 mi @ threshold 6.9 mi @ 8:07 Faster than target
Not yet on Strava: Thu 07-02 (Easy · 5 mi) — run missed, or didn't upload?Rules
- Truthfulness guard: never say "Synced" or "Marked complete" unless the file writes happened this turn. If a fetch fails, say so and show the last-synced data with its
syncedDate— degrade gracefully, never invent. - All matching, grading, fitness, and streak math follows
reference/tracking.md— do not restate thresholds from memory; the constants live there (1609.34 m/mi, ±15 s/mi blend tolerance, 28/7-day windows, 35-day pre-plan widening). - Compute totals and dates programmatically (python or
date), including the weekday of every date you print. - Render distances and paces in the athlete's declared units from
athlete/profile.md. - Secrets hygiene:
STRAVA_CLIENT_ID,STRAVA_CLIENT_SECRET, andSTRAVA_REFRESH_TOKENlive only in an untracked.env. Never print them, never write them into any file under version control. Note for the manual-API path: Strava sometimes rotates the refresh token — if a refresh response contains a newrefresh_token, tell the athlete to update.env, or the connection eventually bricks. - Non-run activities never inflate run mileage: they go to
workouts.csv, not the activities map or fitness block.
Compliance note
Strava's API Agreement (policy effective June 2026, §5.3) prohibits using Strava API data in connection with the development, training, evaluation, or operation of AI applications, including retrieval-augmented generation. What that means here:
- Syncing your own data through the official claude.ai Strava connector is Strava's own supported integration path — that is this skill's primary mode.
- The manual-API fallback is the pattern the original web app used for its author's own single-athlete training. Use it for yourself, on your own data.
- If you adapt this repo into a product that coaches other people, do not route Strava API data into AI context. Instruct users to enable Strava's own relay instead — Strava app → Settings → Applications, Services, and Devices → Health → connect → "Send workouts to Health" — so workouts arrive as Apple Health data, then use the healthkit-import skill. Details and the full compliance picture are in
guides/02-getting-your-data.md.
Output
The sync digest from step 10, in chat. If unmatched past run days exist, end with the step 9 question and stop there. Otherwise suggest 2–3 next actions, for example:
- Refresh the dashboard (
dashboardskill) so the charts pick up today's sync. - Run a daily check-in for today's session brief.
- If the season delta is well behind plan or several runs graded "slower", offer a weekly review or
plan-adjustconversation.
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
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.

