/guizang-sports-skill

name: fit-ride-studio
description: Analyze one or more cycling, running, or hiking FIT/KML activity tracks, generate evidence-based single or aggregate reports, open the bundled local Ride Relief report page when the environment supports it, enrich results with user-confirmed public location context, and create shareable PNG or H.264 MP4 route stories on request. Use whenever a user wants to analyze, compare, visualize, or export .fit or .kml activities, including requests that mention a workout but do not yet include track files.

FIT & KML Activity Studio

Turn local cycling, running, and hiking tracks into an evidence-based report and local visual experience. Follow this sequence:

1. Ask for FIT/KML files when none were provided, or use the bundled synthetic demo when requested. 2. Check the installation, install missing locked dependencies automatically, and analyze every valid file. 3. Present the result, stage private runtime files, and open the bundled Ride Relief report page when local browser access is available.

Enter the export composer only when the user asks for a shareable image, animation, or video. Ride Relief is the web app bundled inside this Skill, not a separate product to install.

Workflow

1. Get the track files

• When the user explicitly asks for a demo, use `<skill-root>/samples/demo.kml`. State that it is fictional data.
• Otherwise, if no readable `.fit` or `.kml` was supplied, ask in the user's language for either an attachment or a local path. Example in Chinese: “请把 `.fit` 或 `.kml` 拖进对话，或告诉我文件路径（例如 `~/Downloads/ride.fit`）；可以一次给多个。”
• Stop after requesting missing input. Do not invent activity data and do not ask the user to configure the project.
• Proceed immediately when at least one file is accessible. Infer single versus aggregate mode from valid files.
• Accept a directory only when the user placed it in scope; expand only top-level FIT/KML files.
• Process tracks locally. Do not upload exact GPS tracks or expose coordinates in the response.
• Continue a batch when one file is corrupt, provided another track is valid. Report skipped basenames.
• Detect likely duplicates by start time, distance, and duration. Exclude them from totals and identify them.

2. Check readiness and analyze

Resolve `<skill-root>` as the directory containing this `SKILL.md`. Run from that directory:

node scripts/check-install.mjs

Handle its single-line status deterministically:

• `OK` — continue.
• `NEED_INSTALL` — run `npm ci`, rerun the check, then continue. Use the lock file; do not substitute `npm install`.
• `UNSUPPORTED_NODE` — explain the reported Node requirement and stop before running the app.
• `ERROR` — report the missing/broken Skill files and reinstall or update the Skill before continuing.

Treat `npm ci` as internal preparation, not a routine user step. If a sandbox blocks network access, request network permission when the environment supports approvals. If permission is unavailable, tell the user to run `npm ci` once from `<skill-root>`. If the Skill directory is read-only, explain that a writable installation or checkout is required; do not loop on installation or claim success.

Run the deterministic analyzer:

node scripts/analyze-fit.mjs --format json <fit-or-kml-path> [more-track-paths...]

Use `--format markdown` when a ready-to-read local report is sufficient. Use `--keep-duplicates` only after the user confirms matching activities are distinct. Read [references/report-contract.md](references/report-contract.md) when interpreting fields, checking weighting rules, or changing report behavior.

3. Present the result

Start with the result, not dependency or parser details.

For one activity, present:

1. A compact terrain/route verdict and the most important observation. 2. Distance and ascent when available; show duration, speed/pace, calories, and pauses only when supported. 3. Sport-appropriate recorded metrics: cycling speed/cadence, running pace/step cadence, hiking elevation/ascent, plus heart rate, power, temperature, and grade when present. 4. Data-quality coverage, especially cadence, heart rate, power, and grade. 5. Two to eight concrete suggestions ordered by impact.

For multiple activities, present:

1. Overall totals and date range. 2. A per-activity table with sport and source format. 3. Longest, most climbing, and fastest only within comparable activities with time data. 4. Earliest-to-latest deltas as observations, not proof of fitness improvement. 5. Sensor consistency, duplicates, and skipped files. 6. Aggregate suggestions plus important activity-specific exceptions.

Keep absent data distinct from zero. Say “未记录” / “not recorded” or “覆盖不足” / “insufficient coverage,” never zero when a sensor was unavailable. Do not invent FTP, power zones, heart-rate zones, VO₂max, training load, recovery status, or medical conclusions unless the user supplies the necessary thresholds and explicitly requests that analysis.

Apply these rules:

• Compute aggregate average speed as total distance divided by total moving time.
• Never infer duration, speed, pace, pauses, or photo-time matching from geometry-only KML.
• Prefer KML document metadata for declared sport, distance, ascent, and descent. Use the longest `LineString` or `gx:Track` and retain the source basename.
• Weight cadence, heart rate, power, and temperature by valid sample counts.
• Treat calories as device estimates and temperature as ambient/device temperature.
• Describe cadence as an activity-pattern observation, not a universal prescription. Confirm the running-cadence convention before interpreting spm.
• When grade coverage is adequate, report distance-weighted grade bands, smoothed P99 representative grade, and up to three continuous climbs; label the device maximum as raw.
• Match heat/hydration suggestions to recorded moving duration.
• Warn before sharing a highly closed route; recommend hiding the first and last 300–500 m.