Run Analysis Skill

A comprehensive running performance analysis tool that parses workout files, stores data in DuckDB, and generates insights using established training science principles (Jack Daniels VDOT, Pfitzinger HR zones).

Features

• Workout Parsing: FIT and GPX file support with full telemetry
• Cloud Sync: MotherDuck integration for multi-device access
• Training Plans: Create and track periodized training plans
• Performance Analysis: VDOT-based pace recommendations and race predictions
• Historical Tracking: VO2 max trends, PRs, and progress monitoring
• Training Science: Evidence-based insights from Jack Daniels and Pfitzinger methodologies

Quick Start

For Claude Desktop Users

This skill integrates with Claude Desktop via the MotherDuck MCP server to give Claude access to your running data.

1. Get MotherDuck token: Sign up at motherduck.com and get your token from settings
2. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

   {
     "mcpServers": {
       "motherduck": {
         "command": "uvx",
         "args": ["mcp-server-motherduck", "--db-path", "md:runs_db", "--motherduck-token", "YOUR_TOKEN_HERE"]
       }
     }
   }

3. Restart Claude Desktop - Claude can now analyze your runs!

For detailed setup and migration instructions, see Claude Desktop Integration below.

For Developers

Installation

# Clone the repository
git clone https://github.com/mz462/run-skill.git
cd run-skill

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Basic Usage

from scripts.parsers.gpx_parser import parse_gpx_file
from scripts.db_manager import RunDatabaseManager
from scripts.run_analyzer import RunAnalyzer

# Parse a workout file
run_data = parse_gpx_file("path/to/workout.gpx")

# Store in database
db = RunDatabaseManager()
run_id = db.insert_run(run_data)

# Analyze the run
analyzer = RunAnalyzer()
analysis = analyzer.analyze_run(run_id)
print(analysis)

Cloud Sync (Optional)

Enable cloud sync with MotherDuck for multi-device access:

Setup

1. Sign up for MotherDuck: https://motherduck.com (free tier: 10GB)
2. Get your token: https://app.motherduck.com/settings/tokens
3. Configure:

# Option 1: Environment variable
export MOTHERDUCK_TOKEN="your_token_here"

# Option 2: Config file (recommended for Claude Desktop)
cp data/config.json.example data/config.json
# Edit data/config.json and add your token

Migration

If you have existing local data, migrate it to cloud:

source .venv/bin/activate
python3 scripts/migrate_to_motherduck.py

Claude Desktop Integration

This skill works seamlessly with Claude Desktop using the MotherDuck MCP server.

Setup Instructions

1. Install MotherDuck MCP:

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:runs_db",
        "--motherduck-token",
        "YOUR_MOTHERDUCK_TOKEN_HERE"
      ]
    }
  }
}

Note: uvx is part of the uv Python package manager. Install with:

# macOS/Linux
brew install uv
# OR
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Restart Claude Desktop

Now Claude can:

• Analyze your runs with full historical context
• Create and track training plans
• Query your MotherDuck database directly via MCP
• Generate insights across all your devices

Training Science

VDOT System (Jack Daniels)

Calculate training paces based on race performance:

from scripts.training_science import TrainingScience

# Calculate VDOT from race
vdot = TrainingScience.calculate_vdot(
    distance_km=21.1,    # Half marathon
    time_sec=5460        # 1:31:00
)

# Get training paces
paces = TrainingScience.get_training_paces(vdot)
print(paces['easy'])      # Easy run pace
print(paces['tempo'])     # Threshold pace
print(paces['intervals']) # VO2 max pace

Heart Rate Zones (Pfitzinger)

hr_zones = TrainingScience.calculate_hr_zones_pfitzinger(
    max_hr=185,
    resting_hr=60
)

Training Plans

Create periodized training plans:

from scripts.training_plan_manager import TrainingPlanManager

manager = TrainingPlanManager()
plan = manager.create_plan(
    name="Spring Marathon 2026",
    goal_race="Boston Marathon",
    goal_distance_km=42.2,
    goal_date="2026-04-20",
    goal_time="3:30:00"
)

# Add phases
manager.add_phase({
    'name': 'base',
    'start_date': '2025-12-01',
    'end_date': '2026-01-31',
    'weekly_volume_km': 65,
    'long_run_km': 25,
    'key_workouts': ['easy', 'long'],
    'focus': 'Build aerobic base'
})

Database Schema

The skill uses DuckDB with the following tables:

Run Data:

• runs - Core workout metrics
• splits - Lap/kilometer splits
• hr_zones - Heart rate distribution
• vo2max_history - VO2 max over time

User Data:

• user_profile - Settings, physiology, PRs
• training_plans - Training plan metadata
• training_plan_phases - Phase configurations

File Formats

GPX Files

• GPS tracks from Apple Health, Garmin Connect export
• Includes: distance, pace, elevation
• Missing: heart rate, cadence

FIT Files

• Full telemetry from Garmin, Wahoo, etc.
• Includes: HR, cadence, power, advanced metrics
• Recommended for complete analysis

Development

# Run tests
pytest tests/

# Check database
python3 scripts/db_manager.py

# Test analysis
python3 scripts/run_analyzer.py

Project Structure

run-skill/
├── scripts/
│   ├── db_manager.py              # Database operations
│   ├── run_analyzer.py            # Analysis engine
│   ├── training_science.py        # VDOT, HR zones
│   ├── training_plan_manager.py   # Plan management
│   ├── report_generator.py        # Report formatting
│   ├── config_manager.py          # Configuration
│   ├── migrate_to_motherduck.py   # Cloud migration
│   ├── migrate_json_to_db.py      # JSON to DB migration
│   └── parsers/
│       ├── gpx_parser.py          # GPX file parsing
│       └── fit_parser.py          # FIT file parsing
├── data/
│   ├── config.json.example        # Config template
│   └── runs.duckdb               # Local database (auto-created)
├── SKILL.md                       # Detailed documentation
└── README.md                      # This file

Privacy & Security

• All data stored locally by default
• Optional cloud sync requires explicit MotherDuck token
• No tracking or analytics
• Your data belongs to you

When using MotherDuck:

• Data encrypted in transit and at rest
• GDPR/SOC2 compliant
• Private by default
• Optional sharing with coaches/friends

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Credits

Training Science:

• Jack Daniels' Running Formula (VDOT system)
• Pete Pfitzinger's Advanced Marathoning (HR zones)

Built with:

• DuckDB - Embedded analytics database
• MotherDuck - Cloud-native DuckDB
• fitparse - FIT file parsing
• pandas/numpy - Data analysis

Support

• Documentation: See SKILL.md
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built for runners, by runners. 🏃‍♂️💨