Back to search
guizang-sports-skill
SkillGitHub
🚴 Claude Code / Codex skill for FIT & KML sports analysis — cycling, running, hiking, sensor and grade insights, local 3D route reports, PNG & H.264 MP4 exports. 运动轨迹分析与 3D 路线故事
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/op7418--guizang-sports-skill)HTML
<a href="/listings/op7418--guizang-sports-skill"><img src="/api/listings/op7418--guizang-sports-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 153 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- 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:
- ```bash
- 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:
- ```bash
- 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.
- Choose two to six evidence-backed deep dives. Omit empty or speculative dimensions.
- When place-aware advice would materially improve the result, read [references/location-enrichment.md](references/location-enrichment.md). Confirm ambiguous public place names, search by the confirmed name rather than coordinates, and time-stamp live conditions. Do not treat an old activity as evidence that a route is currently open.
- ### 4. Stage and open the report page
- Attempt this automatically after successful analysis, but adapt to the environment.
- 1. Read [references/ui-report-contract.md](references/ui-report-contract.md).
- 2. Write the model-authored report contract to a writable temporary JSON file. Do not store per-user analysis in `public/skill-analysis.json`.
- 3. For a batch, select the user's requested activity; otherwise use the longest non-duplicate as the representative route while keeping the text response aggregate.
- 4. Stage the selected track and analysis in the private OS temporary directory:
- ```bash
- node scripts/prepare-report.mjs --track <selected-track> --analysis <temporary-report-json>
- ```
- 5. Read the returned JSON object. Keep its `url` and `session`; the URL expires after 24 hours, stale files are cleaned on the next staging run, and nothing is stored in the repository.
- 6. Fetch `http://127.0.0.1:5174/` and treat it as this project only when the returned HTML contains both `<title>Route Relief` and `id="fit-input"`. Otherwise start `npm run dev` from `<skill-root>`. The server uses port 5174 with `strictPort`; if another application owns the port, report the conflict instead of silently switching ports.
- 7. Use any available browser-opening or browser-automation capability to open the returned URL. The URL auto-loads the track and analysis; do not rely on setting a file input.
- 8. With screenshot/visual capability, verify the loaded source, the `Fit Ride Studio Skill` analysis badge, recommendation layout, and clipping. Without visual capability, skip visual claims and ask the user to inspect the opened page.
- Apply these fallbacks honestly:
- - If the Agent can open URLs but cannot automate page controls, open the URL; no further interaction is required for the report.
- - If no browser tool exists but the user shares the same machine, provide the returned URL and say to open it manually.
- - If running remotely or in a cloud container where the user's browser cannot reach that loopback address, deliver the text report and temporary analysis JSON instead. Do not claim the page opened.
- - If staging is impossible because every writable temporary location is blocked, fall back to the existing file-input workflow and give concise manual steps.
- Track the terminal/process handle used to start Vite. Before finishing, state whether the local server remains running and how to stop that exact process (for example, `Ctrl+C` in its terminal). Do not use a broad kill command. Clean a staged report after the user is finished when practical:
- ```bash
- node scripts/prepare-report.mjs --cleanup <session-id>
- ```
- Opening the report page does not authorize export or switching to **导出创作**.
- ### 5. Handle export requests
- Read [references/export-workflow.md](references/export-workflow.md) before operating the export UI.
- - Follow the user's activity selection; otherwise use a clear preference such as latest, longest, or most climbing.
- - Prefer user media. Disclose when a built-in abstract background will be used.
- - Default to 9:16, H.264 MP4 for motion, whole-activity summary card, watermark enabled, and safe placement. Use a 10-second single-background rotation or 2.5 seconds per route photo.
- - Before rendering, tell the user that Chromium may open a native save picker that requires their own click; otherwise the browser downloads folder is used.
- - Inspect the preview when visual capability exists. Without it, do not claim bounds were verified; ask the user to check the preview before the expensive render.
- - Choose PNG for a still and MP4 for animation/video.
- - Never claim success until rendering finishes and save/download is confirmed.
- ## Usability defaults
- - Use basenames in reports and watermarks; omit absolute paths.
- - Explain missing sensors once in the data-quality section.
- - Preserve the current export layout when revisiting the composer.
- - Avoid one “average activity” conclusion for mixed sports.
- - Keep user files and generated reports out of the repository. Runtime copies live in the OS temporary directory; npm packages live in the Skill directory and may be replaced by updates.
- ## Examples
- - “帮我分析一次运动。” with no file → Ask in Chinese for a dragged file or local path.
- - “Show me the demo.” → Use `samples/demo.kml`, state that it is synthetic, analyze it, and open the local report when reachable.
- - The user provides one FIT → Check/install, analyze, present, stage, and open the URL-loaded report.
- - “把这 8 次骑行综合分析一下。” → Analyze valid non-duplicates and open the longest ride as the representative report unless another is named.
- - “只看看数据,先别导出。” → Analyze and open the report page, but do not enter the export composer.
- - A remote Agent cannot expose loopback → Deliver the text report and JSON, explain why the local page is unavailable, and do not pretend it opened.
README.md · README · 158 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Guizang Sports Skill · FIT/KML 运动分析与 3D 路线故事
- 
- 
- 
- 
- 
- 
- 一个面向 Claude Code、Codex 等本地 Agent 环境的运动轨迹 Skill。把一个或多个 `.fit` / `.kml` 文件交给 Agent,它会分析骑行、跑步或徒步数据,生成有依据的结论与建议,并自动打开本地可视化报告页。需要分享时,还能继续制作带 3D 路线、数据卡片和沿途照片的 PNG / H.264 MP4。
- **Ride Relief 是这个 Skill 自带的本地报告网页,不需要另装软件。** 它只监听本机地址,轨迹和分析通过系统临时目录交给页面,不会复制进仓库。
- 
- ## 30 秒开始
- ```bash
- npx skills add https://github.com/op7418/guizang-sports-skill --skill fit-ride-studio
- ```
- 安装后直接对 Agent 说:
- ```text
- 帮我分析一次运动。
- ```
- 如果还没有收到轨迹文件,Agent 会请你把文件拖进对话,或直接告诉它本地路径(例如 `~/Downloads/ride.fit`)。收到后会自动检查运行依赖、完成分析并打开报告页,不需要你手动安装网页依赖或启动服务。
- 没有现成文件也可以立即体验:
- ```text
- 用示例数据演示一遍。
- ```
- 仓库内的 [`samples/demo.kml`](./samples/demo.kml) 是完全合成的闭环骑行,不包含真实运动者或住址数据;坐标仅供界面演示,不代表实际可骑行路线。
- 也可以把需求和文件一起发过去:
- ```text
- 分析这份 FIT,重点看看踏频、爬坡和数据质量。
- 把这几次骑行做一个综合分析,找出最长、爬升最多和传感器最完整的一次。
- 这是两步路导出的徒步 KML,分析路线强度和主要爬坡。
- 把最长的那次做成一个 9:16 的 3D 路线演示视频。
- 用这些沿途照片做路线故事,每张停留 2.5 秒。
- ```
- ## 使用流程
- 1. **索要轨迹**:请求里没有文件时,Agent 会请你把一个或多个 FIT / KML 拖进对话,或提供本地路径,不会让你先配置项目。
- 2. **自动分析**:收到文件后,Agent 会用锁定版本准备缺失依赖,解析轨迹并给出单次报告或多活动综合报告。
- 3. **打开报告页**:分析完成后,Agent 会生成临时链接并打开 Ride Relief;链接会自动加载轨迹,不依赖浏览器操作文件选择框。
- 4. **按需导出**:只有你提出图片、动画或视频需求时,Agent 才进入导出创作器,配置比例、背景、照片、图层和水印。
- 本地浏览器不可用时,Agent 会降级交付文字报告和分析 JSON;云端环境里的 `127.0.0.1` 通常无法从你的电脑访问,因此不会假装已经打开页面。
- ## 如何取得 FIT / KML
- 不同 App 的菜单会随版本调整,优先选择保留原始传感器数据的 FIT;只有路线几何时再用 KML。
- | 来源 | 常见取得方式 |
- | --- | --- |
- | Garmin Connect | 在网页版打开活动,点右上角齿轮并选择 **Export Original / 导出原始文件**;多数设备会得到 FIT。见 [Garmin 官方说明](https://support.garmin.com/en-IN/?=&faq=W1TvTPW8JZ6LfJSfK512Q8) |
- | 行者码表 | 用 USB 连接电脑,打开设备中的 `activities` 文件夹并取出 FIT。见 [行者帮助中心](https://hc.imxingzhe.com/hc/xing/articles/1708510246-fit) |
- | 两步路 | 在轨迹详情使用“下载轨迹 / 本地下载”,选择 KML;下载自己的轨迹时注意可见范围与隐私设置 |
- | Keep | 如果当前活动页没有 FIT/KML 导出入口,从记录活动的手表、码表或关联平台导出原始文件;分享图片不能代替轨迹文件 |
- ## 能做什么
- | 能力 | 说明 |
- | --- | --- |
- | 单次活动分析 | 距离、时间、速度或配速、爬升、海拔、暂停、热量与路线特征 |
- | 多活动综合分析 | 总量、日期范围、逐次对比、最长活动、最大爬升、同类运动趋势与异常 |
- | 专业传感器分析 | 踏频、步频、心率、功率、温度、坡度分布和字段覆盖率;未记录的数据不会伪装成 0 |
- | 爬坡识别 | 距离加权坡度分布、平滑 P99 代表坡度和最多三段连续爬坡 |
- | 地点信息增强 | 先确认公开地名,再查询路线背景、补给、交通、天气与安全信息;不使用精确轨迹公开搜索 |
- | 本地可视化报告 | 展示核心指标、坡度、主要爬坡、深度分析、行动建议和 3D 路线 |
- | 图片与视频导出 | 1080 级 PNG;H.264 MP4、30 FPS、12 Mbps;支持多种社交媒体比例 |
- | 沿途照片故事 | 照片可按 GPS / 拍摄时间匹配路线,也可手动定位、排序和选择封面 |
- ## 数据解释原则
- - 缺失值和数值 0 严格分开;没有心率带时显示“未记录”,不会显示“0 bpm”。
- - 综合平均速度使用总距离除以总移动时间,不直接平均每次活动的平均值。
- - 不同运动类型分组比较,不用骑行速度和徒步配速得出统一“进步”结论。
- - KML 没有时间戳时,不推测时长、速度、配速、停留或照片时间匹配。
- - 不凭轨迹虚构 FTP、心率区间、VO₂max、训练负荷、恢复状态或医疗结论。
- - 原始最大坡度保留为设备记录;路线难度优先参考平滑代表坡度和连续爬坡。
- ## 导出规格
- | 比例 | 输出尺寸 | 推荐用途 |
- | --- | ---: | --- |
- | 9:16 | 1080 × 1920 | 小红书、Reels、短视频竖屏 |
- | 3:4 | 1080 × 1440 | 小红书图文封面、运动卡片 |
- | 1:1 | 1080 × 1080 | 社交平台方形分享 |
- | 16:9 | 1920 × 1080 | 横屏视频、桌面展示 |
- 视频输出为 H.264 MP4、30 FPS、12 Mbps。单背景默认约 10 秒完成一圈地图旋转;多照片故事默认每张停留 2.5 秒,总时长按照片数量计算。
- ## 平台支持
- | 平台 | 状态 | 说明 |
- | --- | --- | --- |
- | Claude Code | 支持 | 可读取本地轨迹、执行分析并打开报告页 |
- | Codex | 支持 | 适合完整分析、浏览器操作和导出流程 |
- | Cursor / 其他本地 Agent | 可用 | 需要具备文件读写、Shell 和本地浏览器能力 |
- | 普通 Chatbot | 不推荐 | 无法稳定读取轨迹、运行解析器或打开本地报告 |
- 运行分析器需要 Node.js `^20.19.0` 或 `>=22.12.0`。Skill 会给出明确的版本或依赖状态,不会把安装失败误报为分析成功。
- ## 隐私
- - FIT、KML、照片和视频默认只在本机与本地浏览器中处理。
- - 对外分享闭环路线前,建议隐藏起终点前后 300–500 米。
- - 地点增强使用用户确认的公开地名,不把精确 GPS 轨迹上传到搜索服务。
- - 文件名可能出现在报告和导出水印中;如包含隐私信息,导出前请修改水印。
- - 报告页使用随机会话 ID 从系统临时目录读取轨迹;链接在 24 小时后失效,过期副本会在下次准备报告时清理,不随仓库更新保存。
- ## 常见问题
- **需要自己安装网页依赖吗?**
- 不需要。Skill 会在首次分析时检查关键模块;缺失时由 Agent 根据 `package-lock.json` 自动执行 `npm ci`。只有 Node 版本、权限、只读目录或网络失败时才会请你介入。
- **一次可以分析多个文件吗?**
- 可以。Agent 会自动进入综合分析,识别疑似重复活动,分别报告损坏或跳过的文件,并只在同类运动之间比较速度、配速和踏频。
- **分析后一定会导出视频吗?**
- 不会。分析后默认只打开本地报告页;只有你明确要求图片、动画或视频时才开始导出。
- **本地报告会一直在后台运行吗?**
- Agent 启动报告服务后会说明它是否仍在运行,以及如何停止对应进程。临时轨迹与分析不会写入仓库,并会自动过期。
- **导出时为什么还需要我点击?**
- Chromium 的原生保存窗口通常不能由 Agent 代点。开始渲染前 Agent 会提醒你;不支持保存窗口时,文件会进入浏览器下载目录。
- **如何更新?**
- 重新运行安装命令即可获取最新版。
- ## 贡献
- 欢迎通过 [Issues](https://github.com/op7418/guizang-sports-skill/issues) 报告解析、数据解释、页面显示或导出问题,也欢迎提交 Pull Request。修改指标定义、报告字段或导出参数时,请同步更新对应的 `references/` 约定并运行项目测试。
- ## 技术参考
- 网页端使用 Three.js 实现 3D 路线表达,概念参考 [Any Distance iOS 的 RouteScene.swift](https://github.com/Any-Distance/any-distance-ios/blob/main/ADAC/ADAC/Route%20Rendering/RouteScene.swift)。本项目不是对 Swift 源码的逐行翻译,也未使用 Any Distance 的品牌素材。
- ## License
- AGPL-3.0 © 2026 [op7418](https://github.com/op7418)
- 本项目采用 **GNU AGPL-3.0** 协议。修改、分发或通过网络服务提供修改版本时,需要按协议保留署名并公开相应源代码。完整条款见 [`LICENSE`](./LICENSE)。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.