Orient 代码库导读生成器
为新接手的代码库自动生成一份高屋建瓴的 orientation.md，让开发者不必逐行通读也能快速建立整体心智模型。
技能只写一个 orientation.md，写前检查目标目录且不覆盖已有文件；默认路径仅用 Read/Glob/Grep/Bash(只读 git/find) 加 Write，最小权限基本合理；showboat 路径会通过 uvx 从网络拉取第三方 CLI（showboat）并执行，属外部依赖与执行面，且未向用户明确提示该网络获取行为；无敏感数据处理风险，无回滚说明。扣分点：uvx 拉取执行第三方工具缺少确认与来源校验说明。
指令内部一致：参数分支清晰，showboat 模式有 uv 缺失时的明确失败提示并停止，文档结构模板精确。但为静态评审，无测试、无示例输出、无对异常输入（如无 README、非标准仓库布局）的处理说明，关键路径未经验证复现，故按锚点低于 10。
触发条件明确（仅用户显式调用，disable-model-invocation: true，避免误触发），受众（新接手代码库的开发者）清晰，输出格式有精确模板。扣分点：能力边界与不适用场景（如超大 monorepo、多根工作区）未声明；showboat 依赖 uvx 从外部源拉取工具，对中国大陆网络可达性存在风险，未提供替代方案。
CC-BY-4.0 许可证齐全，作者归属明确（Dr. Michael Mullarkey），方法论有独立参考文献文件，文档分层（SKILL.md + bibliography）结构良好，维护者提示清楚。扣分点：技能本身无版本号、无 changelog、无已知限制章节，更新路径仅隐含于仓库维护。
核心任务（生成结构化 orientation.md 并供 learning-opportunities 使用）描述完整、模板可直接产出可用文件，含练习设计准则（好/坏练习示例）降低低质输出风险。扣分点：静态评审无法验证实际产出质量与 showboat 命令序列可运行性，边际价值缺少实测证据。
方法论引用具体学术文献（Spinellis、Hermans、Storey 等）并附独立文献页，来源可审计；但无测试套件、无 CI 证据、无第三方执行或示例输出验证，方法论对产出效果的主张未经复现。按静态上限从严计 4 分。
- showboat 模式会通过 uvx 从网络自动拉取并执行第三方 CLI 工具 showboat，企业环境使用前应确认允许该外部依赖及网络行为。
- 该技能面向 Claude Code / Codex 平台，未验证其在其他环境的兼容性；对中国大陆用户，uvx 拉取外部工具可能受网络可达性影响。
- orientation.md 写入项目级 .claude 或 .codex 目录，属新增未跟踪文件，提交前请审查内容。
- 静态评审，未执行；实际产出质量与 showboat 命令序列可运行性未验证，置信度为低。
这个 Skill 能做什么，适合哪些场景？
orient 是 learning-opportunities 仓库中的一个独立技能，作者为 Dr. Michael Mullarkey。它读取仓库的 README、目录结构、清单文件、入口点、测试和近期 git 历史，然后写出一份结构化的 orientation.md，包含一行用途说明、关键文件、核心概念、常见陷阱和恰好两个导读练习。其探索方法学基于 Spinellis《Code Reading》、Hermans《The Programmer's Brain》等程序理解研究。文件写入项目级技能目录，可提交版本控制并与团队共享；另有 showboat 模式可生成带代码清单附录的线性代码走读文档。
运行时它会：检测项目主要语言（通过 pyproject.toml、package.、go.mod 等 10 类清单文件并完整阅读对应清单）；按专家阅读策略依次考察 README/docs、目录树、语言相关入口文件、2-3 个集成测试、5-8 个核心模块以及 git log 高频修改文件；随后按固定模板生成 orientation.md，写入 .claude/skills/learning-opportunities/resources/ 或 .codex/skills/learning-opportunities/resources/（仅新建该文件，不触碰其他内容）；最后向用户报告写入位置、识别的关键文件与概念数量，并提示用 /learning-opportunities orient 调用配套课程。传入 showboat 参数时改用 uvx showboat CLI 构建带编号代码清单和验证的线性走读文档，缺 uv 则终止并给出安装指引。
- 新加入团队的开发者想在几天内而非几周内理解一个陌生代码库的整体结构
- 接手他人遗留项目的维护者需要一份指出关键文件和高频修改热点的导读
- 用 agentic 编码在多种不熟悉语言间切换、想系统建立项目心智模型的个人开发者
- 团队 onboarding：生成的 orientation.md 可提交版本库，供新成员复用
- 教学场景中需要一份'读什么、读完回答什么综合问题'的定向学习路径
这个 Skill 有哪些优点和局限？
- 探索步骤有明确学术依据（Spinellis、Hermans、Storey 等），而非泛泛的'读读代码'
- 练习设计原则具体：先读指定短文件再综合回答，避免让学习者凭空预测
- 输出写入项目级目录，可版本控制、可团队共享、跨项目不冲突
- 写作位置策略明确：只写 orientation.md，不改动目录中已有文件
- showboat 模式生成带锚点链接和代码清单的正式走读文档，并用 showboat verify 自检
- 依赖外部工具：showboat 模式必须有 uv，缺失时直接终止
- 质量完全依赖底层模型执行探索步骤的好坏，仓库未提供测试套件验证输出质量
- frontmatter 使用 disable-model-invocation、$ARGUMENTS、argument-hint 等平台特定扩展，直接移植到其他 Agent Skills 客户端需改动
- 核心价值在于配套的 learning-opportunities 技能，单独使用只得到一份静态文档
- 语言检测表覆盖 10 类清单，但对清单外的语言或非常规仓库结构没有兜底说明
如何安装这个 Skill？
作为 learning-opportunities 插件市场的一部分安装。Claude Code：先执行 /plugin marketplace add https://github.com/DrCatHicks/learning-opportunities.git，再执行 /plugin install orient@learning-opportunities，然后重启 Claude Code。Codex：执行 codex plugin marketplace add https://github.com/DrCatHicks/learning-opportunities.git（Codex 市场清单中含 orient）。源文件位于仓库 orient/skills/orient/SKILL.md。仓库未说明手动复制安装的具体步骤。
如何使用这个 Skill？
进入你想了解的仓库目录后：/orient 运行默认模式；/orient showboat 运行代码走读模式（需先安装 uv）。生成完成后，用 /learning-opportunities orient 获取两个导读课程。代码库演进后可随时重新运行 orient 再生成交档。
这个 Skill 与同类方案有什么区别？
与同仓库的主技能 learning-opportunities（基于学习科学、在完成架构性工作后提供练习）是配套关系：orient 负责生成仓库导读文档，learning-opportunities orient 负责据此授课。README 还推荐搭配 DrCatHicks/learning-goal 技能用于学习目标设定。