code-tour-github-awesome-copilot

1. 基本信息

项目	内容	数据来源
名称	code-tour（合集仓库子技能，识别名 `code-tour-github-awesome-copilot`）	—
作者/维护者	社区贡献者 vaddisrinivas 撰写，于 2026-04-12 经 `github/awesome-copilot` 维护者 aaronpowell 审阅后合并；作者另在个人仓库 `vaddisrinivas/code-tour` 有同名项目	GitHub API（PR #1277）
来源链接	https://github.com/github/awesome-copilot/tree/main/skills/code-tour	—
许可证	MIT（合集仓库级）	GitHub API
GitHub Stars / Forks	39,145 / 4,971（属整个 awesome-copilot 合集仓库，不代表本技能自身热度）	GitHub API
最新版本	无独立版本号；该子技能目录最近一次改动为 2026-04-12（新增当日）	GitHub API（按路径过滤的提交记录）
安装方式	`npx skills add https://github.com/github/awesome-copilot --skill code-tour`，或手动复制 `skills/code-tour/` 目录	skills.sh 页面

2. 功能介绍与亮点

code-tour 让 agent 为一个代码库生成 CodeTour 导览文件（.tours/*.tour，JSON）：一组带真实文件路径和行号的分步讲解，可在 VS Code 的 CodeTour 扩展里逐步跳转播放。

按受众定制：内置 20 种读者角色（新人上手、修 bug、架构师、PR 评审、安全评审、vibecoder 快速浏览等），并按“意图表”从一句话请求里推断角色与深度（quick / standard / deep）。
覆盖全部步骤类型：内容、目录、文件+行号、代码选区、正则匹配、外部链接（如 PR）、面板聚焦、VS Code 命令；支持 ref、isPrimary、nextTour 组成多篇导览系列。
按仓库类型调整重点：服务/API、库、CLI、monorepo、框架、数据管线、前端应用各有关注点；大仓库只深读 2–3 个相关模块，其余在开场步骤里声明“不在本导览范围”。
自带两个本地脚本：validate_tour.py 检查 JSON、路径是否存在、行号是否越界、nextTour 引用、叙事结构；generate_from_docs.py 从 README/文档生成待填充骨架。另附 JSON Schema 与 8 个真实生产仓库的 .tour 范例。
边界克制：明文规定只创建 .tour 文件、不改动任何源码；commands 步骤只能触发 VS Code 命令，不能执行 shell。

3. 适用场景

固定分类：内容创作与知识管理

适合接手陌生代码库的开发者、需要给新成员写上手指引的团队维护者、想把一次 RCA 或一个 PR 讲清楚的评审者。产出是“讲解型代码库导览”，读它是为了理解代码本身，而不是执行任何构建或部署。

4. 跨 Agent 兼容性

Claude Code：✅ 原生支持——遵循 Agent Skills 规范（SKILL.md + YAML front matter），放入 .claude/skills/ 即可加载。
Codex CLI：⚠️ 需适配——Codex 不会自动扫描 ~/.codex/skills，需在会话中手动引用 SKILL.md 内容。
OpenClaw：❓ 未验证——未查到其加载第三方 SKILL.md 的官方说明。
Hermes Agent：✅ 原生支持——按 tap 路径扫描子目录探测 SKILL.md，兼容标准 Agent Skills 规范。
与 agent 无关的一点：生成的 .tour 是纯 JSON，播放需要 VS Code 与 CodeTour 扩展（microsoft/codetour，MIT，4,578 stars，最近推送 2026-05-05，未归档）。

5. 推荐理由

“带我读一遍这个代码库”通常靠口头讲解，说完即散，下一个新人还得再讲一遍。code-tour 把讲解固化成可入库、可复播、可校验的文件，行号和路径由脚本核对，避免导览指向不存在的位置。对需要反复给新人、评审者或值班同事做代码走读的人，它把“讲一次”变成“写一次、播多次”。

6. 评分

维度	分数	说明
受欢迎程度	6	skills.sh 累计 757 次安装（2026-04-13 首次出现）；已收入 GitHub 官方 awesome-copilot 合集；合集仓库 stars 不代表本技能自身热度，作者个人仓库尚无 star
可用性	8	一条 `npx` 命令安装，文档详尽（432 行指令 + Schema + 范例 + 两个脚本）；实测在临时仓库跑通校验脚本（能报出行号越界）与骨架生成脚本。扣分：播放需 VS Code + 扩展；SKILL.md 内脚本路径有 `~/.agents/skills/...` 与 `skills/code-tour/...` 两种写法；最近改动距今约 5 个月
安全性	9	见下方清单：纯提示词 + 两个仅用 Python 标准库的本地脚本，无联网、无凭据、MIT

安全检查清单：①执行本地 Python 脚本，仅读取仓库文件并写出 .tour；commands 步骤只触发 VS Code 命令，文档明确不支持 shell ②运行时无联网外发（SKILL.md 建议参考的示例 .tour 为公开 GitHub 链接，属只读参考）③不需要 API key 或凭据 ④SKILL.md 与两个脚本未见可疑指令、混淆代码或夹带推广；skills.sh 上 Gen Agent Trust Hub、Socket、Snyk 三项安全审计均为 PASS ⑤作者为社区贡献者，合并前经官方维护者两轮修改要求后批准 ⑥License 明确（MIT，合集级） ⑦合集仓库近日仍在提交，该子技能目录自 2026-04-12 后无改动。综合 = 三项均值。

7. 跟同类 Skills 相比的优势

方案	定位	与本技能的差异
CodeTour 扩展本体（microsoft/codetour）	VS Code 里手动录制、播放导览	只提供录制与播放，导览内容需人工逐步写；本技能让 agent 读代码后自动生成并校验
wiki 类文档生成（如 microsoft/skills 的 wiki-onboarding）	生成 Markdown 形式的讲解文档	产出是可阅读的文档页；本技能产出可在编辑器内逐步跳转到具体行的导览，路径与行号可机器校验
直接让 agent 口头讲解代码库	零配置，即问即答	无持久产物、无法复播、无法校验；本技能牺牲一点配置换来可入库复用的成品

核心差异：面向“把讲解做成可复播文件”，并按读者角色组织叙事，而不是泛泛的代码库问答。

8. 用户评价

该技能目前在第三方平台尚无具名用户使用评价。可核实的公开痕迹：skills.sh 累计 757 次安装；三项自动化安全审计通过；贡献 PR（github/awesome-copilot#1277）经维护者 aaronpowell 两轮修改要求（补 README 构建产物、补缺失引用文件）后于 2026-04-12 批准合并，自动 lint 通过。以上是代码评审与审计记录，不是使用者评价。

9. 其他补充

正文为英文，无多语言版本。skills.sh 页面标注该技能“来源自 affaan-m/ecc”，说明同一内容也随其他 agent 套件分发；本报告评估的是 awesome-copilot 目录下的这一份。

10. 安装使用方式

安装技能：npx skills add https://github.com/github/awesome-copilot --skill code-tour，或手动复制 skills/code-tour/ 到你的 skills 目录。
在 VS Code 安装 CodeTour 扩展（vsls-contrib.codetour），用于播放生成的导览。
使用：对 agent 说“为这个仓库做一个新人上手导览”或“给这个 PR 做导览”即可触发；产物写到仓库根的 .tours/。
校验：python <技能目录>/scripts/validate_tour.py .tours/<name>.tour --repo-root .；从 README 起骨架：python <技能目录>/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour（骨架里的 [TODO: ...] 需由 agent 读真实文件后填满）。

安装后无需重启。

11. 注意事项

导览只在装有 VS Code + CodeTour 扩展的环境里能“播放”；其他编辑器只能把 .tour 当 JSON 阅读。
SKILL.md 约 5.6k tokens，自动 lint 曾提示“偏长的技能可能拖累表现”；说明里脚本路径有两种写法，按你的实际安装目录替换。
行号会随代码变动漂移；导览建议入库后随重大重构重新生成，或改用 pattern/stepMarker 锚点（后者需要改源码注释，文档建议仅在用户明确要求时使用）。
references/examples.md 引导 agent 读取 GitHub 上的公开示例，运行时如需联网取例请确认环境允许。