Matt Pocock Skills 安装与上手指南：让 AI 编程从“能跑“到“靠谱“

1. 这是什么？

用 Claude、Cursor 等 AI 编程工具开发，几乎人人都遇到过这种场景：你简单提一句需求，AI 秒速输出一大段代码，看着完整直接合并上线，等到落地才发现漏洞百出。

拿头像上传功能举例------代码瞬间生成，上线后才发现没有文件大小限制、未做裁剪适配、缺失兜底默认头像。你和 AI 看似聊的是同一个需求，实际双方理解完全割裂。

Matt Pocock Skills 是一套面向 AI 编程的标准化工作流，核心设计理念就一条：先追问，再动手。它不会像普通 Prompt 那样直接输出代码，而是像资深面试官一样层层追问，把所有细节确认完毕后再落地开发。目前该项目在 GitHub 已斩获 14 万 Star，足见开发者对"AI 编程工程化"的迫切需求。

2. 为什么需要它？四大 AI 编程失败模式

项目的 README 开篇就点明了设计初衷------AI 编程在四个环节反复出问题，Skills 逐一给出了工程化解法：

意图对齐失败 ：你说"加个头像上传"，AI 理解的是一张图存进去就完事。Skills 用 /grill-me 和 /grill-with-docs 强制前置需求调研，像资深面试官一样把存储路径、文件大小、裁剪规则、兜底方案全部问清楚，从源头杜绝跑偏。

项目术语断层 ：每开新对话就要解释一遍"什么是结算单""对账文件长什么样"，浪费大量 Token，代码命名也各起各的。Skills 自动把术语沉淀到 CONTEXT.md，新会话直接复用，命名风格全局统一。

缺少测试反馈回路 ：AI 说"我觉得没问题"，你就信了。Skills 强制推行 /tdd 测试驱动开发------先写失败测试，再写业务代码，最后重构。不靠主观感觉，靠红灯→绿灯说话。

架构持续腐化 ：AI 写代码太快了，需求来一个加一个，三个月后代码就成了一团乱麻。Skills 内置 /improve-codebase-architecture，建议每三天跑一次，自动扫描耦合点、冗余模块，输出优化报告。

3. 环境准备：安装 Node.js

Skills 通过 npm 包 skills 分发，需要 Node.js 环境。Windows 下推荐用 winget 一键安装：

winget install OpenJS.NodeJS.LTS --silent

安装完成后，PowerShell 默认执行策略可能阻止 npm 脚本。两种解决方式：

• 方式一 （推荐）：用 cmd 执行 npm/npx 命令
• 方式二 ：管理员身份运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

验证安装：

node --version   # 应输出 v24.x.x
npm --version    # 应输出 11.x.x

4. 快速安装 Skills

一行命令拉取全套技能：

npx skills@latest add mattpocock/skills

首次运行会提示安装 skills 包，输入 y 确认。随后弹出交互式选择界面，可勾选需要的技能和适配的编程 Agent------Cline、Codex、GitHub Copilot、Cursor 等均支持。

务必勾选 /setup-matt-pocock-skills，这是后续初始化配置的入口技能。

安装完成后，所有技能文件默认出现在当前工作目录的 .agents/skills/ 下，共 35+ 个技能，覆盖需求、开发、测试、架构、协作五大领域。

5. 技能迁移到统一目录（可选）

如果你已有其他 Copilot Skills 存放在 ~/.copilot/skills/，建议统一管理：

# 迁入统一目录
Get-ChildItem -Directory .\.agents\skills | ForEach-Object {
    $dest = "$env:USERPROFILE\.copilot\skills\$($_.Name)"
    Move-Item $_.FullName $dest -Force
}

# 清理空目录
Remove-Item .\.agents -Recurse -Force

迁移后 VS Code 自动识别，新旧技能并列显示，互不冲突。

6. 初始化配置：/setup-matt-pocock-skills

在 VS Code Copilot Chat 中输入 /setup-matt-pocock-skills，AI 会引导完成三项基础配置：

A. Issue Tracker（问题追踪器）：决定 Bug 和需求记录在哪里。选项包括 GitHub Issues（默认）、GitLab、本地 Markdown 文件、或 Jira / Linear。非 Git 仓库推荐选"本地 Markdown"。

B. Triage Labels（分类标签） ：定义五个标准状态------needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。用默认值或按团队习惯自定义均可。

C. Domain Docs（领域文档） ：确认项目是单上下文（一个 CONTEXT.md）还是多上下文（monorepo 场景的 CONTEXT-MAP.md），大部分项目选单上下文即可。

配置完成后自动生成 AGENTS.md（或 CLAUDE.md）及 docs/agents/ 下的三份配置文件。

7. 核心技能一览

README 将所有技能按 Engineering / Productivity / Misc 三类组织：

Engineering（工程类，日常高频）

技能	用途
/grill-with-docs	深度需求调研 + 自动生成 CONTEXT.md 和 ADR
/grill-me	纯需求追问，不产出文档
/to-prd	将对话整理为标准 PRD
/to-issues	拆分任务并同步到 Issue Tracker
/tdd	测试驱动开发，先写用例再写代码
/diagnosing-bugs	六阶段标准化排障：复现→最小化→假设→插桩→修复→回归
/improve-codebase-architecture	扫描架构问题，输出可视化 HTML 报告
/triage	Issue 状态机管理，按标签流转
/review	双轴审查：代码规范 + 需求匹配度
/codebase-design	深度模块设计------大功能藏在小接口背后
/domain-modeling	构建并打磨项目领域模型和通用语言
/design-an-interface	并行生成多种接口设计方案，对比择优
/prototype	快速搭建可丢弃原型，验证设计假设

Productivity（生产力类）

技能	用途
/handoff	生成会话摘要，无缝交接给新 AI 窗口
/teach	多会话渐进式教学新概念
/writing-great-skills	编写自定义 Skill 的规范参考
/ask-matt	路由助手，告诉你当前场景该用哪个技能

Misc（辅助工具类）

技能	用途
/setup-pre-commit	配置 Husky 提交钩子 + lint-staged
/git-guardrails	拦截 push --force、reset --hard 等危险命令
/migrate-to-shoehorn	类型断言迁移工具
/scaffold-exercises	生成新人上手练习脚手架
/qa	交互式 QA 对话，自动归档 GitHub Issue

8. 上手路径推荐

落地这套 Skills 不需要一次全用上，按场景选几个高频的就能见效：

项目启动 ：/grill-with-docs → /to-prd → /to-issues。三步走下来，需求边界清晰、文档完备、任务拆分明细。

日常编码 ：新功能用 /tdd 驱动，先写测试再写代码；遇到 Bug 跑 /diagnosing-bugs 而非盲目改代码。

长期维护 ：每三天一次 /improve-codebase-architecture 做架构体检，防止代码在不知不觉中腐化。

切换上下文 ：换 AI 窗口时跑 /handoff，一键带走当前会话的所有关键信息。

这套 Skills 虽然是 TypeScript 社区作者出品，但核心是软件工程方法论，不绑定任何技术栈。安装和配置流程在所有项目上完全一致------clone 仓库、一行 npx 命令、三问初始化，就能把工程化流程嵌入日常工作流。

---

写好需求比写好代码更重要。Skills 把软件工程几十年的基本功打包成了可复用的标准化流程------每次和 AI 协作前花五分钟跑一遍，省下的返工时间远超前期投入。