feat: add cycling-training Claude skill (MCP companion)
Modular cycling-training skill: periodization logic, workout design, and research-backed protocols that companion an Intervals.icu MCP server (the server owns all data + computed metrics; the skill owns knowledge + reasoning). Structure: - SKILL.md router + README (companion-to-MCP architecture, install steps) - references/: durability, mtb-xco-demands, strength-for-cyclists, vo2max-intervals, periodization, data-confounds, citations - assets/: base + build plan templates, durability field-test protocol Every quantitative claim carries an inline citation; citations.md is the single source of truth with PMID/DOI, each verified against PubMed on 2026-07-20. Notable honesty flags baked in: - VO2 rep-length: running (Fleckenstein 2025) vs cycling (Ronnestad) conflict documented rather than asserted; cycling evidence favors short intervals. - 'Yu et al. 2025' (frequency > distribution) could not be found; not cited. - Under-researched doses (durability, taper TSB, CTL ramp) flagged 'track response'. - HR-confound doc forbids naive decoupling<5% / RHR+5 rules. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqrhBhC3GEcKyaw8RTk8G6
This commit is contained in:
@@ -0,0 +1,88 @@
|
||||
# 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 says pull it toward −5 to +5 by race day," or "this VO2 session accumulated little time
|
||||
≥90% VO2max; the interval doc says lengthen the reps."
|
||||
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
|
||||
│ ├── 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.ai / Claude Desktop:** upload or sync the folder as a skill per the current skills UI.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user