aerobic-progress
Skill0 starsChanged 12 days agoMITView on GitHub
Show how the runner's aerobic fitness is trending through easy-run efficiency (grade-adjusted speed per heartbeat) month by month, season against season and year against year. Use when asked "am I getting fitter", about aerobic base, efficiency, heart rate at a given pace, or progress over months.
- Reads credentials
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- load-checkSkill
- race-predictorSkill
- refresh-reportsSkill
- trail-predictorSkill
- weekly-reviewSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Every number comes from data/metrics.json, written by npm run export from the same sums the app shows (src/utils/insights.js, metrics.js's …
- Very specific: line 14
Read data/metrics.json. If it's missing, its until isn't today, or its version isn't 1, run npm run export (it needs …
- Very specific: line 17
If empty is true, say there are no activities and stop.
- Distinctive: line 65
Zones: if the runner says their max HR or zones changed, months before the change were classed as easy against other bounds: name the …
- Very specific: line 98
After the write-up, the same reading as a page in Ledger's style (scripts/reports/aerobic-progress.html).
- Very specific: line 101
Write data/reports/aerobic-progress.notes.json (shape below).
- Very specific: line 103
Run npm run report -- aerobic-progress.
≈ “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
Aerobic progress
Every number comes from data/metrics.json, written by npm run export from the same sums
the app shows (src/utils/insights.js, metrics.js's efficiency). Never compute a figure
yourself: quote it, or say it isn't there. Your job is to interpret.
1. Get fresh numbers
- Read
data/metrics.json. If it's missing, itsuntilisn't today, or itsversionisn't1, runnpm run export(it needsGARMIN_PERSONAL_API_KEYin.env; if that fails, say so and stop, never guess numbers). - If
emptyis true, say there are no activities and stop.
2. Read
months[], one entry per calendar month since first:
| Field | Meaning |
month | "YYYY-MM" |
efficiency | median metres per minute (grade adjusted when the watch has it) per heartbeat, over the month's easy runs; null under 3 easy runs: a gap, not a zero |
easyRuns | how many easy runs (≥ 80% of HR time in Z1–2) that median rests on |
runKm, hours | the month's volume, to set efficiency against |
intensity | easyPct / moderatePct / hardPct % of heart-rate time |
cadence | median steps per minute over every run of the month (not only easy ones) |
power | median average power (W) over every run with power; runsWithPower says how many |
hrv | the month's nights: average (ms), belowBand / aboveBand against the runner's own band; null with no reading |
restingHr | the month's average resting heart rate (bpm); null with no reading |
sleep | the month's averageHours and under7h nights; null with no reading |
Also coverage.runsWithHR and coverage.runsWithZones against coverage.runs: runs without
zones can't be classed as easy, so they never count.
zones is the running zones as set now (floors: each zone's lowest bpm, maxHR,
method): "easy" is under floors[2] bpm today. Garmin keeps no history of them, and each
run was classed with the zones of its day.
plan.races (with a plan): races ahead, for context.
3. Interpret
- Higher is better: more ground covered per heartbeat at easy effort. This is the "efficiency factor" idea (speed ÷ heart rate) used in endurance coaching; the app's version is grade-adjusted and kept to easy runs so terrain and effort move it less.
- Compare like with like. Heat, humidity and altitude raise heart rate at the same speed, so a summer dip is expected. Put each recent month beside the same month a year earlier before calling a trend.
- Size of a change: month-to-month moves under about 3% are noise; a change that holds for three months or more, or a year-on-year change above about 5%, is worth naming. These thresholds are a reading guide for this metric, not published cut-offs: say so if asked.
- Thin months: a month on 3–4 easy runs is weak evidence. Say how many runs a claim rests on.
- Where efficiency has gaps (no easy runs),
cadenceandpowercarry on, but they are over every run: a month of harder running has higher power for that reason alone. Read them withintensity, and as context, never as a fitness verdict by themselves. Power before mid-2023 rests on few runs (runsWithPower). - Terrain moves cadence most: long trail runs and ultras include walking, so their
cadence (and power) sits far under road running's. A month of a few long trail runs (high
runKmover fewruns) isn't comparable with a road month: say so rather than call it a drop. - Zones: if the runner says their max HR or zones changed, months before the change were classed as easy against other bounds: name the change before comparing across it.
- Resting HR over months: a slow fall in the monthly
averageis a classic sign of aerobic fitness; month-to-month moves of 1–2 bpm are noise. It starts atcoverage.restingHrFirst. A month of short sleep (under7hhigh) can hold it up. - HRV over months: a monthly
averagerising with fewer nights under band is the recovery side of getting fitter; it starts atcoverage.hrvFirst. - Context: set efficiency next to
runKm. A rise after a block of steady volume is the classic aerobic-base signal; a rise while volume collapsed may be fewer, flatter, cooler runs.
4. Write
**Aerobic progress, <first month shown> – <until's month>**
Latest: <efficiency> m/min per beat in <month> (<easyRuns> easy runs)
Same month last year: <efficiency or "no data"> → <better / worse / about the same>
| Month | Efficiency | Easy runs | Run km | Cadence | Power | HRV | Resting HR |
|-------|------------|-----------|--------|---------|-------|-----|------------|
(last 12 months, gaps shown as —)
**Trend**
<2–4 sentences: direction, seasonality, what it rests on>
**Worth trying** (optional, one line)End with: Based on Garmin's activity and wellness summaries; heat, terrain and sensor accuracy move these numbers; not medical advice.
5. Publish the page
After the write-up, the same reading as a page in Ledger's style (scripts/reports/aerobic-progress.html).
The page takes its numbers from metrics.json itself: you write only words.
- Write
data/reports/aerobic-progress.notes.json(shape below). Text may quote numbers frommetrics.json, as the write-up does; never one of your own. - Run
npm run report -- aerobic-progress. It checks the notes, writesdata/reports/aerobic-progress.htmland prints the page's link, if it has one. On an error, fix the notes it names and run it again. - Publish
data/reports/aerobic-progress.htmlwith the Artifact tool. With a link: read that artifact first, then publish with it asurl, so the page updates in place. Without one: publish it new (iconchart), then record its link withnpm run report -- aerobic-progress --url <link>. - End the reply with the link. The page uploads the account's data to claude.ai, private until the runner shares it: never share it yourself.
{
"headline": "two to four words: the state of the trend (\"Up on last year\", \"Unread since July\")",
"takeaway": "one sentence: latest against the same month a year earlier",
"trend": ["the Trend sentences, one per item"],
"worthTrying": "the Worth trying line, or null"
}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.

