来源项目：aihero.dev & mattpocock/skills
作者背景：Matt Pocock（Total TypeScript 创始人、前 Vercel 开发者体验团队、XState 核心成员）

核心设计理念

AI Hero 是一套面向专业开发者的 AI 编程工程化技能库，支持 Claude Code、Cursor、Codex、Copilot 等主流 Agent。

它的核心理念是反“Vibe Coding”（感觉流盲目生成），主张通过一系列小而锋利、标准链条化、可复用的 Skill 命令，将资深工程师的严谨工程纪律注入 Agent：

1. 统一领域语言（Ubiquitous Language）：通过项目专有的 GLOSSARY.md 术语表（v1.3 由 CONTEXT.md 破坏性更名），固化业务与架构专有名词，减少 Agent 猜测黑话带来的冗长与失真。
2. 架构决策记录（ADR）：在写代码前强制澄清并固化关键技术决策。
3. 需求盘问（Grilling）：在动手编码前，让 Agent 反向深度质询人类，暴露逻辑死角与边界遗漏。
4. 规范驱动与切片（Spec-first & Tickets）：先立 Spec 再切成带阻塞关系的微型工单任务图，防止 Agent 上下文溢出或幻觉。
5. 测试驱动开发（TDD）：严格红-绿-重构循环，杜绝无测试无保障的腐化代码。
6. 自进化工程闭环（Retro & Standards）：编码完成后对会话进行复盘，将偶发错误转化为确定性的 Lint 检查与 Hook 门禁，持续精炼 AGENTS.md。

安装与配置方式

1. 安装方式

• 方式 A：Claude Code 官方插件（推荐，只读托管）

claude plugins install mattpocock-skills

或者在会话中直接执行：

/plugin install mattpocock-skills

• 方式 B：本地源码引入（通用，可任意修改）

适用于 Cursor、Codex、Claude Code 或其他 Agent：

npx skills@latest add mattpocock/skills

文件会写入项目本地，可自行定制；后续通过 npx skills update 更新。

2. 初始化项目

在项目根目录运行一次配置命令：

/setup-matt-pocock-skills

按提示配置：

• 使用的工单系统（GitHub Issues / Linear / 本地 Markdown 文件）；
• 工单分类标签规则；
• 文档/规格说明书的保存路径。

git mv CONTEXT.md GLOSSARY.md
git mv CONTEXT-MAP.md GLOSSARY-MAP.md  # 若存在

27 个 Skill 全面详解（6 大工程场景分类）

01. Getting Started（环境配置与导航）

• /setup-matt-pocock-skills (User-invoked)

• 作用：项目初始化配置向导。

• 场景：首次在某个仓库使用本技能集时运行，向 Agent 声明该仓库的工单系统、标签体系及文档存放约定。

• /ask-matt (User-invoked)

• 作用：技能路由顾问。

• 场景：当你面对当前开发阶段不确定该使用哪个 Skill 时输入，描述当前处境，由它推荐下一步的最佳 Skill。

02. The Main Flow（交付主骨架：从想法到交付的自进化闭环）

主干技能相互衔接，形成从需求构想到环境自进化的完整敏捷交付链：

• /grill-with-docs (User-invoked)

• 作用：基于项目既有文档与规范，对开发方案进行深度技术盘问，并同步沉淀 GLOSSARY.md 与 ADR。

• 场景：当你有一个粗略的功能想法时，让 Agent 像资深架构师一样对你进行反向极限质询，排查漏洞并生成架构决策记录（ADR）。

• /to-spec (User-invoked)

• 作用：将对话中达成的共识沉淀为严谨的书面规格说明书（Spec）。

• 场景：在盘问对齐后执行，固化需求边界、技术约束与验收标准。

• /to-tickets (User-invoked)

• 作用：将大 Spec 拆解为带阻断关系（blocking edges）的微型工单任务图（Tickets）。

• 场景：避免让 Agent 一次性处理过大任务导致幻觉或上下文超载，将 Spec 切成低耦合、高内聚的小任务列表。

• /implement (User-invoked)

• 作用：单工单交互式推进（人类作为调度器）。

• 场景：输入指定 Ticket ID，强制 Agent 遵循“红-绿-重构”法则，先写必然失败的测试，再编写实现代码，直到所有测试通过。

• /implement-spec (User-invoked) 【v1.3 新增】

• 作用：全套 Spec 自动化并发交付（AFK 挂机模式）。

• 场景：读取工单依赖关系计算前沿（Frontier）无阻塞任务，并发派生 Implementer 子代理在独立的 Git Worktrees 中使用 /tdd 编码，并由 Merger 子代理自动合并至 integration 集成分支，最终自动闭环调用 /code-review。

• /code-review (Model-invoked)

• 作用：双轴代码审查（Standards 规范轴与 Spec 需求轴并行评审）。

• 场景：在提交 PR 前运行，由两个独立上下文的子代理分别比对工程规范与原始 Spec，剔除 AI 冗余与架构坏味道。

• /pr (Model-invoked) 【v1.3 新增】

• 作用：生成高可读性、极简审查负担的标准化 PR 说明。

• 场景：在代码提交审查前自动触发，包含三段式黄金模板：

1. Summary（以图代文）：强制用最小视觉元素（Mermaid 架构/时序图、伪代码、调用树或 diff 草图）直观呈现，拒绝冗长套话；

2. Evidence（前后证据）：必须提供变更前失败（Red）、变更后通过（Green）的硬性测试证据；

3. Merge Danger（危险度评估）：判定单向门（不可逆，如数据库删字段、发送外部通知）还是双向门（易回滚），并标明爆炸半径（Blast radius）。

• /retro (User-invoked) 【v1.3 新增】

• 作用：Agent 运行环境与工程纪律复盘（Retrospective）。

• 场景：在编码会话结束后运行，不修改业务代码，专门优化 Agent 工作环境。从导航便利性、确定性检查、编码规范、AGENTS.md 健康度、工具 Token 经济性等 7 个维度进行体检，将犯错点固化为确定性 Lint 规则或 CI 门禁，实现“遇到问题 -> /retro -> 彻底封死该类错误”的自进化闭环。

03. Shaping（方案塑形与前期探索）

• /wayfinder (User-invoked)

• 作用：复杂技术工程的决策导航地图。

• 场景：面对庞大、多依赖的复杂架构改造时，梳理出所有未决的关键决策项及其依赖路径，指引团队逐个敲定。

• /prototype (Model-invoked)

• 作用：抛弃型原型试验（Spike）。

• 场景：用“验证完即删”的代码快速摸清某个第三方库、API 或技术方案的可行性，避免半成品污染主代码库。

• /research (Model-invoked)

• 作用：基于一手资料的深度技术调研。

• 场景：针对复杂问题让 Agent 深入官方文档和第一手源码查找依据，输出带有明确引用出处的权威结论。

04. Upkeep（工程维护与代码库健康）

• /improve-codebase-architecture (User-invoked)

• 作用：代码库架构健康度诊断与模块解耦建议。

• 场景：分析模块依赖关系与复杂度，输出可视化报告并指引深层模块（Deep Modules）重构。

• /diagnosing-bugs (Model-invoked)

• 作用：疑难 Bug 根因精准排查。

• 场景：从编写一个最小失败复现（Repro）测试用例开始，自底向上排查隐蔽缺陷。

• /triage (User-invoked)

• 作用：积压 Issue 的智能分流与状态机流转。

• 场景：批量清洗杂乱的用户 Issue，补全复现信息、打上分类标签并整理成开发者可接手的 Ticket。

• /wizard (Model-invoked)

• 作用：交互式环境搭建/配置向导生成器。

• 场景：为项目生成一步步引导人类完成环境安装、密钥注入或首次部署的终端交互脚本。

05. Productivity Skills（人机协作与日常效率）

• /grill-me (User-invoked)

• 作用：纯思维/逻辑层面的压力测试（非代码场景）。

• 场景：头脑风暴、业务策略或设计方案阶段，由 Agent 充当批判性思考者连续质询。

• /handoff (User-invoked)

• 作用：长会话上下文交接包生成。

• 场景：当会话长度逼近上下文上限或需要切换到新窗口时，提炼当前工程状态与待办清单，供下一个 Agent 无缝接力。

• /to-questionnaire (User-invoked)

• 作用：将未决事项整理为结构化问卷。

• 场景：把零散模糊的疑问统一归纳为选项/问卷清单，方便快速发送给产品经理或团队决策者填写。

• /teach (User-invoked)

• 作用：交互式阶梯式技术带练导师。

• 场景：针对特定复杂技术主题（如 TypeScript 复杂类型、并发控制等）展开分阶段、跨会话的系统化教学。

• /wait-what (User-invoked)

• 作用：学术/晦涩黑话的大白话重述。

• 场景：当 Agent 生成的回答过于复杂抽象时，一键要求其用通俗易懂的平实语言重新阐述，并联动 GLOSSARY.md。

• /writing-for-agents (Model-invoked)

• 作用：面向 Agent 的提示词与规范文档编写指南。

• 场景：学习如何撰写易于被大模型准确理解、严格遵守且精简 Token 的规范文件（如 AGENTS.md）或自定义 Skill。

06. Reference Skills（底层通用范式模块）

供上层 Skill 自动引用或作为编码通用准则：

• /codebase-design (Model-invoked)

• 作用：深层模块（Deep Modules）设计标准，指导构建小接口、大功能的低耦合高内聚模块。

• /domain-modeling (Model-invoked)

• 作用：领域建模与统一语言标准，指导定义业务专有名词，更新 GLOSSARY.md 与 ADR。

• /grilling (Model-invoked)

• 作用：质询与盘问底层引擎（为 /grill-me 与 /grill-with-docs 提供驱动范式）。

• /tdd (Model-invoked)

• 作用：红-绿-重构测试驱动开发循环的执行标准规范。

技能调度模式与调用哲学

1. 严格的权限分层（User-invoked vs Model-invoked）：

• User-invoked（人类调度）：如 /implement-spec、/retro、/grill-me，只能由人类输入触发，承担流程编排与决策入口职责。

• Model-invoked（模型自动调度）：如 /tdd、/pr、/domain-modeling，既可手动触发，也可由模型在执行任务时根据场景自主调用，承载复用工程纪律。

1. 跨 Harness 标准化解耦：

• v1.3 移除了对 Claude Code / 命令语法的强制绑定，技能间协作统一规范为 Call the Skill tool with "<skill-name>"，增强了在 Codex、Cursor 及其他 Agent 运行时的通用性。

典型工程流水线流转图

[ 初始想法 / 粗略需求 ]
                 │
                 ▼
         /grill-with-docs    (深度盘问，理清边界，沉淀 ADR 与 GLOSSARY.md)
                 │
                 ▼
             /to-spec        (输出严谨工程规范 Spec)
                 │
                 ▼
            /to-tickets      (切解为带阻塞关系的任务图 Tickets)
                 │
       ┌─────────┴─────────┐
       ▼                   ▼
  /implement         /implement-spec
(单工单交互式推进)    (全自动化挂机：Task Graph + Worktrees 并发交付)
       └─────────┬─────────┘
                 │
                 ▼
           /code-review      (Spec 与 Standards 双轴并行审查)
                 │
                 ▼
               /pr           (生成包含 Summary 架构图、测试 Evidence、Merge Danger 的 PR)
                 │
                 ▼
              /retro         (环境复盘：沉淀 Lint/Hook，精简 AGENTS.md，构建自进化闭环)

• 复杂工程遇阻：使用 /wayfinder 梳理决策路径；
• 技术不确定性：使用 /prototype 快速验证可行性；
• 会话窗口饱和：使用 /handoff 导出状态并在新会话继续；
• 缺陷根因定位：使用 /diagnosing-bugs 修复缺陷后，联动 /retro 固化防范规则。