agentleFS
totorototototorototo/ledger/.claude/skills/race-predictor/SKILL.md

race-predictor

Skill0 starsChanged 12 days agoMITView on GitHub

Predict the runner's race times for 5 km, 10 km, half marathon and marathon from their best efforts of the last 12 weeks (Daniels' VDOT), say how far to trust each one, and how the score has moved month by month. Use when asked "what could I run", for a race time prediction, a goal time, a pacing target, or "am I getting faster".

  • Reads credentials

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 1 is distinctive, and 8 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.

  • 8

    Very specific

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

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

    Every number comes from data/metrics.json, written by npm run export from the same sums the app shows (src/utils/insights.js, …

    line 8
  2. Very specific:

    Read data/metrics.json. If it's missing, its until isn't today, its version isn't 1, or it has no race, run npm run export (it needs …

    line 15
  3. Very specific:

    If empty is true, say there are no activities and stop.

    line 18
  4. Very specific:

    If effort is null, say no run of the last 12 weeks carries a split and stop.

    line 39
  5. Distinctive:

    Leave out efforts from runs far longer than the split (an ultra's half split) or easy ones: they say nothing about racing that distance.

    line 61
  6. Very specific:

    Outlier: If top[0] scores well over top[1] and the others and sits alone in its run, it may be a GPS fault: say so and name top[1] as the …

    line 63
  7. Very specific:

    After the write-up, the same reading as a page in Ledger's style (scripts/reports/race-predictor.html).

    line 103
  8. Very specific:

    Write data/reports/race-predictor.notes.json (shape below).

    line 106
  9. Very specific:

    Run npm run report -- race-predictor.

    line 108

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

Race predictor

Every number comes from data/metrics.json, written by npm run export from the same sums the app shows (src/utils/insights.js, src/utils/race.js). Never compute a figure yourself: no time, pace, percentage or adjustment of your own. Quote it, or say it isn't there. Your job is to interpret.

1. Get fresh numbers

  1. Read data/metrics.json. If it's missing, its until isn't today, its version isn't 1, or it has no race, run npm run export (it needs GARMIN_PERSONAL_API_KEY in .env; if that fails, say so and stop, never guess numbers).
  2. If empty is true, say there are no activities and stop.

2. Read

race, for the 12 weeks from–until:

FieldMeaning
effortthe best effort: date, name, distance (5k, 10k, half, marathon), time, pace, vdot, and the run it sits in: runKm, averageHR, easy, effect (Garmin's label)
predictions[]distance, time, pace: what effort's score gives at each distance
bestByDistance[]the best effort at each distance, same fields as effort
top[]the 5 best efforts, best first
runs, runsWithSplitsruns in the window, and how many carry Garmin's splits
longestRunKm, runsOver25Km, weeklyRunKmthe long runs and the weekly running volume (12-week average) a half or a marathon rests on

An effort is Garmin's fastest stretch of that distance inside a run, not the run itself: runKm is the whole run's length; easy, effect and averageHR are the whole run's too.

months[].bestVdot: each month's best score; null in a month without a split (Garmin has them from 2024 on). plan.nextRace and plan.races[] (null without data/plan.md).

If effort is null, say no run of the last 12 weeks carries a split and stop.

3. How far to trust each prediction

VDOT (Daniels & Gilbert, Oxygen Power, 1979; Daniels, Daniels' Running Formula) assumes the effort was all out, on a flat road, and that the runner has trained for the distance predicted. Check each:

  • All out? Training splits are rarely races. effect VO2MAX, LACTATE_THRESHOLD or ANAEROBIC_CAPACITY, or a name that reads as a race: close to a race effort. TEMPO: probably a little held back. AEROBIC_BASE, RECOVERY or easy: true: well short of all out. Short of all out, every prediction is a floor: the runner could race faster. Say so; don't say by how much.
  • Distance from the effort. The further a prediction sits from effort.distance, the less it holds: from a 5k, the 10k is close, the half fair, the marathon a long stretch.
  • Trained for it? Predictions from short efforts run too fast over the marathon for runners on low volume (Vickers & Vertosick, BMC Sports Sci Med Rehabil 2016). Read the half against longestRunKm and the marathon against weeklyRunKm and runsOver25Km: under about 50 km a week, or no run over 25 km in the window, call the marathon time the best case, not a target. Under about 30 km a week, the same for the half.
  • Speed against endurance. Compare bestByDistance: a 10k scoring well under the 5k when both were hard runs says endurance lags speed, so the longer predictions run fast. Leave out efforts from runs far longer than the split (an ultra's half split) or easy ones: they say nothing about racing that distance.
  • Outlier. If top[0] scores well over top[1] and the others and sits alone in its run, it may be a GPS fault: say so and name top[1] as the safer reference.
  • Terrain. Splits on hilly or trail runs are slower than the runner's flat pace, so they rarely set effort; but a trail or ultra race in the plan is out of VDOT's reach (climb, terrain, hours): say no road prediction applies to it.

4. Trend

The last 12 months[].bestVdot, oldest first. A month without a hard run reads low, so read the trend over several months, not one; name the best month and how far effort.vdot sits from it, in VDOT points as the numbers stand.

5. Write

**Race predictor, <until>** — from <effort.distance> in <effort.time> on <effort.date> (VDOT <effort.vdot>, <effect>)

| Distance | Time | Pace | Trust |
|----------|------|------|-------|
| 5 km | … | … | <high / fair / low, a few words why> |
(one row per prediction)

Next race: <plan.nextRace.text> in <daysTo> days: <the matching prediction, or "trail/ultra: no road prediction applies"> (only with a plan)

**Reading it**
- <all out or not, and what that makes the times: estimate or floor>
- <half and marathon against the volume and long runs, quoting them>
- <speed against endurance, if bestByDistance says something>

**Trend** <months and their scores, in one or two lines>

**To sharpen it**
<one line: the effort that would make the prediction firmer, e.g. a 5 km or 10 km time trial or race>

End with: Predicted from Garmin's fastest splits with Daniels' VDOT tables, assuming a flat road race run all out and training for the distance; an estimate, not a promise.

6. Publish the page

After the write-up, the same reading as a page in Ledger's style (scripts/reports/race-predictor.html). The page takes its numbers from metrics.json itself: you write only words.

  1. Write data/reports/race-predictor.notes.json (shape below). Text may quote numbers from metrics.json, as the write-up does; never one of your own.
  2. Run npm run report -- race-predictor. It checks the notes, writes data/reports/race-predictor.html and prints the page's link, if it has one. On an error, fix the notes it names and run it again.
  3. Publish data/reports/race-predictor.html with the Artifact tool. With a link: read that artifact first, then publish with it as url, so the page updates in place. Without one: publish it new (icon chart), then record its link with npm run report -- race-predictor --url <link>.
  4. 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.
{
  "takeaway": "one sentence: what the runner could run, and how far to trust it",
  "trust": {
    "5k": { "level": "high | fair | low", "why": "a few words, from step 3" },
    "10k": { "level": "…", "why": "…" },
    "half": { "level": "…", "why": "…" },
    "marathon": { "level": "…", "why": "…" }
  },
  "reading": ["the Reading it bullets, one sentence or two each"],
  "trend": "the Trend line",
  "sharpen": "the To sharpen it line"
}

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.