cycling-training/README.md

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):

# 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:

  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.