{
  "markdown": "# Claude Running Race Coach\n\nAn AI-powered running coach built for [Claude Code](https://code.claude.com/) and [Claude Desktop](https://claude.ai/download) using the [Skills framework](https://code.claude.com/docs/skills). This project demonstrates how to combine Claude's capabilities with specialized training knowledge and training data to provide personalized running coaching assistance. Distributed as a plugin for easy installation.\n\n**For usage instructions, see [running-race-coach/README.md](running-race-coach/README.md).**\n\n## Overview\n\nClaude Running Race Coach uses Claude Code's Skills framework to provide intelligent running coaching that includes:\n- Evidence-based training plan generation\n- Multi-platform training data integration (Strava, Garmin, manual entry, conversational)\n- Weekly training analysis and coaching feedback\n- Scientific pace calculation and workout planning\n\n## Project Structure\n\n```\nclaude-coach/\n├── running-race-coach/         # Main plugin package\n│   ├── README.md              # User-facing documentation\n│   └── skills/                # Skill definitions\n│       ├── training-plan/     # Training plan generation skill\n│       │   ├── SKILL.md       # Skill definition and workflow\n│       │   ├── references/    # Coaching guides and principles\n│       │   │   └── coaches-guide.md\n│       │   └── scripts/       # Pace and distance calculators\n│       │       ├── calculate_paces.py\n│       │       └── interval_calculator.py\n│       ├── strava-sync/       # Strava data synchronization skill\n│       │   └── SKILL.md       # Sync workflow and formatting\n│       ├── training-dashboard/ # Training progress visualization\n│       │   └── SKILL.md       # Dashboard generation workflow\n│       └── running-coach/     # Weekly coaching analysis skill\n│           └── SKILL.md       # Coaching workflow and principles\n├── training-log/              # Generated weekly training summaries\n├── coaching-log/              # Coaching session notes\n├── training-plan.md          # Generated training plans\n├── package.py                # Plugin packaging script\n└── README.md                 # This file\n```\n\n## Skills Architecture\n\nThis project leverages Claude Code's [Skills framework](https://code.claude.com/docs/skills), which allows Claude to follow structured workflows for specific domains. Each skill is a combination of:\n\n### 1. Skill Definition (`SKILL.md`)\n\nEach `SKILL.md` file defines:\n- **Invocation patterns**: Keywords and phrases that trigger the skill\n- **Workflow steps**: Structured process Claude follows\n- **Best practices**: Domain-specific knowledge and principles\n- **Tool usage**: When to use Python scripts or MCP servers\n- **Output format**: How to structure the results\n\n### 2. Reference Documentation\n\nThe `references/` directory contains in-depth knowledge that Claude loads into context when needed. For example:\n- **coaches-guide.md**: Comprehensive training principles, periodization strategies, and workout guidelines\n\n### 3. Executable Tools\n\nPython scripts in the `scripts/` directories provide:\n- **calculate_paces.py**: Calculates training pace zones from race goal times\n- **interval_calculator.py**: Computes total distances for interval workouts\n\nThese are executed via Claude Code's terminal integration.\n\n### 4. Integration with MCP Servers\n\nSkills can leverage Model Context Protocol (MCP) servers for external data:\n- **Strava MCP server**: Fetches activity data, athlete info, and statistics\n- Extensible to other platforms (Garmin, Apple Health, etc.)\n\n## How It Works\n\n### Training Plan Generation\n\nWhen a user requests a training plan:\n1. **training-plan** skill is invoked\n2. Claude gathers requirements (race distance, goal time, current mileage, race date)\n3. Executes `calculate_paces.py` to determine training zones\n4. Applies periodization principles from `coaches-guide.md`\n5. Generates structured markdown training plan\n6. Uses `interval_calculator.py` to calculate workout distances\n7. Saves plan to `training-plan.md`\n\n### Training Data Synchronization\n\nThe **strava-sync** skill:\n1. Connects to Strava MCP server\n2. Fetches recent activities (configurable time range)\n3. Extracts detailed metrics (pace, heart rate, power, cadence, elevation)\n4. Parses lap data for interval workouts\n5. Formats data as structured markdown\n6. Saves to `training-log/week-n.md`\n\nThe system is flexible and also supports:\n- Manual markdown file creation\n- Data import from other platforms (Garmin, Apple Health, Polar Flow)\n- Conversational data input (describe workouts verbally)\n\n### Weekly Coaching Analysis\n\nThe **running-coach** skill:\n1. Loads the user's training plan\n2. Retrieves training log (from any source)\n3. Asks for subjective feedback (energy, fatigue, challenges)\n4. Compares planned vs. actual execution for each workout\n5. Analyzes:\n   - Pace accuracy (easy, threshold, intervals, race pace)\n   - Heart rate zones and effort levels\n   - Workout execution quality\n   - Weekly volume and progression\n6. Assesses progress toward race goal\n7. Provides specific recommendations\n8. Documents session in `coaching-log/week-n-coaching-notes.md`\n\n## Development Setup\n\n### Prerequisites\n\n- [Claude Code](https://code.claude.com/)\n- Python 3.8+ (for pace calculation scripts)\n- (Optional) Node.js 18+ (for Strava MCP server)\n\n### Local Development\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/ColinEberhardt/claude-running-coach.git\n   cd claude-running-coach\n   ```\n\n2. **Open in Claude Code**:\n   ```bash\n   code . --profile claude\n   ```\n\n3. **(Optional) Configure Strava MCP Server**:\n   \n   Add to `~/.claude/config.json`:\n   ```json\n   {\n     \"mcpServers\": {\n       \"strava\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@anthropic-ai/mcp-server-strava\"]\n       }\n     }\n   }\n   ```\n\n4. **Test skills**:\n   - Open Claude Code chat\n   - Ask: \"Create a 10-week 10K training plan for a 45:00 goal\"\n   - Verify the training-plan skill executes correctly\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\nThis project is provided as-is for educational purposes. Always consult qualified professionals for personalized training advice.\n",
  "bytes": 6180,
  "sha": "73ae5a2528770d41fb119d86e4022b84ee81968b4ab02c332393b79eb4e715db",
  "repo_slug": "colineberhardt/claude-running-coach",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_colineberhardt_claude_running_coach_runn_ea980cc3/readme"
}