1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | wayfinder（mattpocock/skills 合集仓库子技能；项目自述名称与正式名称一致） |
GitHub |
| 作者/维护者 | Matt Pocock（个人开发者/技术教育者，运营 aihero.dev，自述约 6 万订阅 newsletter） | 仓库 README |
| 来源链接 | https://github.com/mattpocock/skills/tree/main/skills/engineering/wayfinder | — |
| 许可证 | MIT（仓库根 LICENSE） | GitHub API |
| GitHub Stars / Forks | 所属 mattpocock/skills 仓库整体 219,310 stars / 18,884 forks；该数字属整个合集仓库，不代表本技能自身热度 |
GitHub API |
| 最新版本 | 插件包版本 1.2.3（仓库 Releases，2026-08-06 发布） | GitHub API |
| 安装方式 | Claude Code 官方插件市场 / Agent Skills 通用 CLI / 手动复制 | 仓库 README |
2. 功能介绍与亮点
wayfinder 解决的是一个具体痛点：一个想法太大，装不进一次 agent 会话，而且方向还没看清楚（作者称之为“雾中找路”）。它把这类工作组织成 issue tracker 上的一张共享地图——一个标记为 wayfinder:map 的顶层 issue，下面挂着若干决策票据（子 issue），每张票只解决一个具体问题，不是一段待执行的代码任务。
核心设计：
- 只规划，不动手：默认产出的是决策清单，不是交付物；地图画完、所有票据解决完即完成
- 票据分四种：Research（agent 独立调研）、Prototype（做一个便宜的原型供讨论）、Grilling（对话式追问，默认情形）、Task（必须由人执行的前置动作，如开通某项服务）——其中除 Task 外均明确区分“人在环内（HITL）“与”agent 独立完成（AFK）“，避免 agent 冒充人的判断
- “战争迷雾”机制：地图刻意不画出还看不清楚的部分，只在前沿票据被解决后才逐步显影，防止过早把模糊问题拆成假装精确的任务
- 票据阻塞关系用 tracker 原生依赖表达，可视化“当前哪些票可以领”，未配置 tracker 时自动降级为本地 markdown tracker，不强制要求 GitHub
亮点：仓库 issue 区可查证到至少十余位与作者无关联的外部用户专门就该技能提交过具体反馈（bug 报告、功能请求、真实使用体验），覆盖多个不同 AI 编码工具；被至少 6 个第三方 skill 目录站收录；作者本人为其撰写了独立的专题介绍文章；子目录级最近一次提交发生在 2026-08-15，两天前仍在被打磨。
3. 适用场景
固定分类：元技能与 Agent 增强
面向需要用编码 agent 处理“一次会话装不下”的大型工程或课程内容规划的开发者与技术团队——例如一次跨越多个模块的架构迁移、一份需要反复推敲的产品规格、或一场分阶段的数据结构改造。适合已经在用 GitHub（或其他 issue tracker）管理任务、习惯把决策留痕的团队；对只做小范围单次改动的场景没有必要引入。
4. 跨 Agent 兼容性
- Claude Code：原生支持——
mattpocock/skills是 Claude Code 官方插件市场收录的插件，/plugin install mattpocock-skills即可安装。 - Codex：支持——作者 README 将 Codex 列为“Codex, and other agents”安装分支的目标，经通用安装器
npx skills add mattpocock/skills安装；作者仓库自身的架构决策记录注明“原生 Codex 插件在路线图上”，即当前经通用安装器而非厂商原生渠道。 - OpenClaw：支持——经同一通用安装器安装；SKILL.md 正文未见 Claude 专属语法，“调用 Skill 工具”为 Agent Skills 通用约定。
- Hermes Agent：支持——同上，经通用安装器安装；未见任何厂商专属依赖。
- ⚠️ 无论哪个 agent，该技能都需手动显式调用（SKILL.md 声明
disable-model-invocation: true），不会被模型根据上下文自动触发。
5. 推荐理由
大部分“帮我规划”的技能停在一次性生成一份计划文档；wayfinder 解决的是计划本身太大、需要跨越多次会话且中途会有新决策冒出来的场景——用 issue tracker 原生的依赖关系把“现在能做什么”变得可视化，用“战争迷雾”机制防止过早把看不清的部分硬拆成假任务。它不要求团队换用新工具，直接长在已有的 GitHub issue 之上，且有大量真实外部用户的具体反馈在持续推动它迭代。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 该子技能自身在仓库 issue 区有 43 条标题直接提及的独立讨论，来自十余位具名外部用户（含具体 bug 报告与功能请求，如 bsadeh、davevangelderen、erikpr1994、tinesoft、wccrawford、timezyme 等）；另被至少 6 个第三方 skill 目录站收录，作者本人撰有专题介绍文章 |
| 可用性 | 7 | Claude Code 一条命令安装，未配置 issue tracker 时自动降级为本地 markdown tracker（非硬性前置条件）；文档详尽；子目录最近提交仅两天前，维护活跃；但概念较多（地图/票据/战争迷雾/HITL-AFK），面向的是“大型多会话规划”这一较窄场景，非开箱即用的单命令工具 |
| 安全性 | 9 | 见下方安全检查清单 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | SKILL.md 本身不直接执行 shell 命令，依赖调用其他 Skill（grilling / domain-modeling / research / prototype）完成子任务 |
| ② 运行时联网外发 | 仅对项目自身已配置的 issue tracker 做读写（创建/关联/关闭 issue、加标签、发评论），无未声明的外部网络请求 |
| ③ API Key/凭据存储 | 不涉及，本技能自身不索取或存储任何凭据 |
| ④ 可疑指令 | 全文通读未发现提示注入、混淆代码或与任务无关的夹带指令 |
| ⑤ 作者/组织信誉 | Matt Pocock，知名 TypeScript 技术教育者（Total TypeScript / aihero.dev 创始人），未发现刷星或造假迹象 |
| ⑥ License | 仓库级 MIT，明确 |
| ⑦ 最近维护 | 本子技能最近一次相关提交发生在 2026-08-15，仓库整体几乎每日都有提交 |
综合评分 = 三项均值 = 8.0
7. 跟同类 Skills 相比的优势
| 竞品 | 定位 | 与 wayfinder 的差异 |
|---|---|---|
| planning-with-files | 用本地文件（而非 issue tracker）承载计划与进度，单次会话内的轻量任务拆解 | 不处理“多会话、需要可视化阻塞关系”的大规模规划；wayfinder 把票据依赖关系交给 tracker 原生渲染，多方协作时任何人打开 issue 列表就能看到当前前沿，不需要打开某个文件 |
| planning-and-task-breakdown（addyosmani/agent-skills） | 把一个需求拆解成可执行任务清单，偏向“从需求到任务”的一次性转换 | 产出的是任务列表而非持续演进的地图；wayfinder 刻意保留“看不清的部分先不拆”的战争迷雾机制，且区分哪些决策必须由人到场（HITL）、哪些可交给 agent 独立完成（AFK） |
| mattpocock/skills 同仓库的 to-tickets / to-spec | 把已经谈妥的方向转成正式的实现工单或规格文档 | 是 wayfinder 流程里“路走清楚之后”的下一棒——wayfinder 负责把模糊想法谈清楚变成决策，to-tickets/to-spec 负责把决策变成可执行产出；两者衔接而非重叠 |
8. 用户评价
- wccrawford（GitHub issue #785）：在本地 llama.cpp 部署的 Qwen3-Coder 模型上通过 Pi 使用
/wayfinder，反馈给出一段项目描述后，技能直接开始写代码、创建地图和初始票据，却完全没有先向他提问澄清——指出这与“应先提问”的预期不符。 - timezyme（GitHub issue #794）：反馈在配合 Fable 使用 wayfinder 时，追问环节提出的问题质量不佳、不读代码库，且在用户中途补充信息后仍会跳出 wayfinder 既定流程，认为体验有待改善。
- erikpr1994（GitHub issue #859）：作为深度使用者提交了具体的功能改进提案——为“地图已清空”的状态补一个交接标签，使下一次会话能一眼看出该地图已完成而不必打开逐个清点票据，提案中引用了自己此前另外两次相关讨论（#823、#661）。
9. 其他补充
作者维护一份约 6 万订阅的技术 newsletter，同步该仓库技能集的更新；wayfinder 与仓库内 grilling、domain-modeling、research、prototype 等技能协同工作，安装同仓库全部技能可获得完整工作流，但 wayfinder 本身可独立安装使用。
10. 安装使用方式
方式一（推荐，Claude Code 官方插件市场）：
claude plugins install mattpocock-skills或在会话内执行：
/plugin install mattpocock-skills已在 Claude Code 官方市场上架，无需额外添加来源，后续更新自动到达。
方式二（Codex / OpenClaw / Hermes Agent 等，Agent Skills 通用 CLI）：
npx skills@latest add mattpocock/skills安装时可勾选仅安装 wayfinder。
方式三（手动复制）：
git clone https://github.com/mattpocock/skills /tmp/mattpocock-skills
mkdir -p ~/.claude/skills/wayfinder
cp -r /tmp/mattpocock-skills/skills/engineering/wayfinder/* ~/.claude/skills/wayfinder/安装后需手动调用：SKILL.md 声明 disable-model-invocation: true，不会被模型自动触发，需用户显式输入 /wayfinder 加一段想法描述来启动“画地图”模式，或带着已有地图的 issue 编号来启动“推进地图”模式。若已配置同仓库的 setup-matt-pocock-skills，可接入 GitHub/GitLab 原生依赖关系；未配置时自动退化为本地 markdown tracker，仍可正常使用。
11. 注意事项
- 面向的是“大型、跨会话”的规划场景，日常小范围改动直接让 agent 动手即可，引入 wayfinder 反而增加流程负担。
- 用户评价显示，不同底座模型/agent 对“先提问澄清”这条约定的遵循程度不一致（见第 8 章 wccrawford、timezyme 反馈），实际效果与所用模型的指令遵循能力相关。
- 完整工作流（画地图 → 解决票据 → 转 to-tickets/to-spec 落地）需要同仓库其他技能配合；仅安装 wayfinder 也可独立完成“把模糊想法整理成决策清单”这一段。