Chris Farhood
cced0ea6b8
The skill had mtb-xco-demands.md but road/TT demands were only diffused through the general docs — an asymmetry given the balanced MTB+road scope. Add two dedicated, self-contained demand profiles (kept separate because mass-start racing and TT differ as much as XCO differs from marathon MTB): - references/road-racing-demands.md: stochastic power profile (Vogt 2007, Ebert 2005/2006, Sanders/van Erp 2021), drafting economics (Blocken 2018), fatigued finishing sprint (Menaspà 2013/2015, Etxebarria 2019), durability as a success determinant (van Erp/Sanders/Lamberts 2021); power governs, HR unreliable (intermittent) — mirrors the MTB doc. - references/tt-demands.md: aero drag dominance + CdA as the top lever (Crouch 2017, Martin 1998, García-López 2008), critical power as predictor (Smith 1999), even-vs-variable pacing (Swain 1997, Atkinson 2007), long-TT durability (Maunder 2021); HR more usable than MTB but still secondary. All new quantitative claims carry verified PMIDs/DOIs (verified via PubMed/ CrossRef); citations.md gains Road-racing and Time-trial sections. Honesty flags: Blocken 2018 and Martin 1998 have no PMID (DOI only); the '~90% aero' soundbite (Kyle & Burke 1984) is unverifiable and marked approximate; criterium-specific literature flagged as a gap; no unverified HR-reliability citation added (TT HR defers to data-confounds.md). Router (SKILL.md) and README layout updated with both docs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqrhBhC3GEcKyaw8RTk8G6
119 lines
6.5 KiB
Markdown
119 lines
6.5 KiB
Markdown
# cycling-training
|
||
|
||
A modular **Claude skill** that provides periodization logic, workout design, research-backed
|
||
protocols, and interpretation guidance for endurance and off-road cycling training — designed to
|
||
**companion an Intervals.icu MCP server**, not replace it.
|
||
|
||
## The companion-to-MCP architecture
|
||
|
||
This skill deliberately holds **no data and no calculators**. It is the *reasoning* half of a
|
||
two-part system:
|
||
|
||
| Layer | Owns | Examples |
|
||
|-------|------|----------|
|
||
| **Intervals.icu MCP server** (data + computed metrics) | Fetching and computing everything numeric | activities, wellness, power curves, CTL / ATL / TSB, training-load ramp, zones, TSS, best efforts, streams |
|
||
| **`cycling-training` skill** (knowledge + reasoning) | Deciding what the numbers *mean* and what to do next | periodization logic, workout design, research-backed protocols, interpretation of trends, confound-aware caveats |
|
||
|
||
**The split is a hard rule.** If a script would only reproduce math the MCP API already returns
|
||
(zones, TSS, load metrics, CTL/ATL/TSB), it is intentionally absent. Ask the MCP server for the
|
||
number; ask this skill what to do about it.
|
||
|
||
### How they work together (typical flow)
|
||
|
||
1. **MCP** returns the data — e.g. `get_athlete_summary` (CTL/ATL/TSB), `get_wellness_data`
|
||
(HRV, RHR, sleep), `get_athlete_power_curves`, `get_activities`.
|
||
2. **Skill** supplies the reasoning — e.g. "TSB is −25 eight days out from an A-race; the taper
|
||
doc targets +5 to +15 by race day, so shed fatigue," or "this VO2 session banked little time
|
||
≥90% VO2max; the interval doc says check whether rep length / work:rest kept power in the band."
|
||
3. **You (Claude)** combine them into a recommendation, always citing which layer supplied what.
|
||
|
||
## Repository layout
|
||
|
||
```
|
||
cycling-training/
|
||
├── SKILL.md # Router — loads the right reference doc by need
|
||
├── README.md # This file
|
||
├── references/
|
||
│ ├── durability.md # Fatigue resistance as a trainable quality + field test
|
||
│ ├── mtb-xco-demands.md # MTB/XCO demand profile; power governs, HR caveat
|
||
│ ├── road-racing-demands.md # Mass-start road/crit: stochastic power, drafting, sprint
|
||
│ ├── tt-demands.md # Time trial: aerodynamics/CdA, critical power, pacing
|
||
│ ├── strength-for-cyclists.md # Heavy strength; masters rationale; from-zero ramp
|
||
│ ├── vo2max-intervals.md # Maximizing time ≥90% VO2max; work:rest; rep length
|
||
│ ├── periodization.md # Distribution philosophy; base/build/peak; CTL ramp; taper
|
||
│ ├── data-confounds.md # HR reliability; power-governs; decoupling/RHR caveats
|
||
│ └── citations.md # Master citation list with PMID/DOI — single source of truth
|
||
└── assets/
|
||
├── plan-template-base.md # Backward-mapped base mesocycle skeleton (3:1 / 2:1)
|
||
├── plan-template-build.md # Build block: VO2 + durability + strength integration
|
||
└── field-test-durability.md # The ~1,500 kJ → 1-min hill durability field test
|
||
```
|
||
|
||
## Installing as a Claude skill
|
||
|
||
A Claude skill is a directory containing a `SKILL.md` with YAML frontmatter (`name` +
|
||
`description`). To install:
|
||
|
||
**Claude Code (project or personal):**
|
||
```bash
|
||
# Personal (available in every project):
|
||
git clone <this-repo> ~/.claude/skills/cycling-training
|
||
|
||
# Or project-scoped (checked in with a repo):
|
||
git clone <this-repo> .claude/skills/cycling-training
|
||
```
|
||
|
||
Claude auto-discovers any `SKILL.md` under a `skills/` directory. The `description` field in the
|
||
frontmatter is what Claude matches against to decide when to load the skill, so keep it intact.
|
||
|
||
**Claude Desktop / claude.ai (import a zip):** the skill ships as a packaged `.zip` whose single
|
||
top-level `cycling-training/` folder holds `SKILL.md` and the docs — the layout Claude expects. Get
|
||
the zip one of two ways, then import it in **Settings → Skills**:
|
||
|
||
- **From a release:** download `cycling-training-<version>.zip` from the repo's Releases (produced
|
||
automatically — see *Packaging & releases* below).
|
||
- **From the packages registry:** the same zip is published to the Gitea generic packages registry:
|
||
```
|
||
https://git.farh.net/api/packages/farhoodlabs/generic/cycling-training-skill/<version>/cycling-training-<version>.zip
|
||
```
|
||
- **Build it yourself:**
|
||
```bash
|
||
scripts/build-skill-zip.sh v1.0.0 # -> dist/cycling-training-v1.0.0.zip
|
||
```
|
||
|
||
Once installed, this skill loads automatically when you ask cycling-training questions, and it
|
||
pairs with your connected Intervals.icu MCP server for the live data.
|
||
|
||
## Packaging & releases
|
||
|
||
`scripts/build-skill-zip.sh [version]` stages the installable files and produces
|
||
`dist/cycling-training-<version>.zip` (validating that `SKILL.md` carries `name`/`description`
|
||
frontmatter). A Gitea Actions workflow, `.gitea/workflows/release-skill.yml`, runs it:
|
||
|
||
- **Push a tag `v*`** (e.g. `git tag v1.0.0 && git push origin v1.0.0`) → builds the zip,
|
||
**attaches it to a Gitea release** for that tag, and **publishes it to the packages registry**.
|
||
- **Run the workflow manually** (workflow_dispatch) → builds the zip and uploads it as a run
|
||
artifact you can download.
|
||
|
||
The workflow uses two Actions secrets: `RELEASE_TOKEN` (repo write — creates the release and
|
||
uploads the asset) and `REGISTRY_TOKEN` (package write — publishes to the generic packages
|
||
registry). A registered Actions runner and Actions-enabled repo are also required.
|
||
|
||
## How to read the docs
|
||
|
||
- **`SKILL.md` is a router, not a manual.** It points to the one reference doc that answers the
|
||
question at hand. Load docs on demand; don't read them all up front.
|
||
- **Every quantitative claim carries a citation** (author/year, with PMID/DOI in `citations.md`).
|
||
This is deliberate: it lets future-you *verify* rather than trust.
|
||
- **Where the mechanism is established but the optimal dose is not, the docs say so** — marked
|
||
`⚠️ under-researched — track individual response`. Treat those as hypotheses to test on
|
||
yourself, not settled protocol.
|
||
|
||
## Scope & honesty notes
|
||
|
||
- Content is written for **balanced road/TT and MTB** use; discipline-specific numbers are
|
||
labelled and not over-transferred (small-n elite XCO data ≠ masters marathon reality).
|
||
- This skill gives **general training-science reasoning, not individualized medical advice.**
|
||
Nothing here overrides a physician, and readiness/overtraining calls should use the
|
||
confound-aware logic in `references/data-confounds.md`, never naive single-number rules.
|