• 更好适配中文大语言模型
• 方便中文母语开发者
• 方便接入中文开发流程

这是 mattpocock/skills 的简体中文本地化版本。文档和技能说明已翻译；目录名、技能名、命令、代码块、路径和工具标识保持不变，以免破坏安装和运行行为。

中文版本不只是为了阅读方便。对中文母语用户来说，中文说明能减少概念转换成本；对以中文为主要交互语言或中文语料优化的模型来说，中文 prompt 和 skill instructions 也更容易贴合中文上下文，减少中英混杂带来的歧义。

本仓库按内容刷新方式同步上游，不同步上游 Git 历史或仓库管理状态。维护规则见 .skills/translate-skill/SKILL.md。

本仓库的最近一次同步翻译由 OpenAI Codex（GPT-5 coding agent）执行，并由仓库维护者通过提交记录纳入 main。翻译策略是 skill-guided content localization：把上游 mattpocock/skills 当作英文内容来源，只翻译自然语言说明，保留目录名、skill name、frontmatter key、命令、代码块、路径、URL、package/tool/API identifiers 和行为关键 labels。用户可见的安装路径统一保持为 vinvcn/mattpocock-skills-zh-CN。

• 2026-06-16：同步上游 mattpocock/skills@694fa30，本地提交 6b594d2。将 teach 从 in-progress 提升到 productivity，并更新 teaching workspace 指南：lessons/、reference/、storage strength、primary source、follow-up questions 和 quiz 答案长度约束。
• 2026-06-05：同步上游 mattpocock/skills@aaf2453，本地提交 0f36f6d。更新 to-prd 的 seam-based 测试决策指导，并强化 in-progress teach explainers 的 citations 与 interactivity 要求。
• 2026-05-29：同步上游 mattpocock/skills@e3b90b5，本地提交 fb2000f。新增 in-progress teach skill 的中文翻译，并更新 CONTEXT.md template 规则。
• 2026-05-22：同步上游 mattpocock/skills@b8be62f，本地提交 f0b4bd3。新增 architecture HTML report 指南，更新 handoff 临时文件与 redaction 规则，并收紧 CONTEXT.md template。
• 2026-05-15：同步上游 mattpocock/skills@e74f006，本地提交 c323a74。收紧 CONTEXT.md glossary 边界，并更新 prototype 的设计细化表述。
• 2026-05-11：同步上游 mattpocock/skills@9f2e0bd，本地提交 210cbac。将 handoff 提升到 productivity，新增 review 草稿，并更新 writing skills。
• 2026-05-09：同步上游 mattpocock/skills@733d312，本地提交 c9fe120。新增 prototype 与 in-progress 内容的中文翻译，并更新公开 skill 索引。

针对 mattpocock/skills@694fa30 的同步结果：

• node scripts/check-translation.mjs 通过。
• 公开 skill 索引一致：engineering/、productivity/、misc/ 已同步到顶层 README 和 .claude-plugin/plugin.json，personal/、in-progress/、deprecated/ 未进入 plugin。
• 上游 in-scope 文件完整：没有缺失上游文件，也没有 stale translated upstream files。
• 66 个共同 Markdown 文件的保护性检查通过：frontmatter name 未漂移，frontmatter key 未缺失，fenced code blocks 平衡。
• git diff --check 和 git diff --cached --check 通过。
• README 同步记录指向最新上游 694fa30，并记录本地同步提交 6b594d2。
• 行为关键扫描未发现旧安装路径或旧 skill 路径，例如旧的 vinvcn 短仓库路径、已移除的 triage skill 名、已移除的 domain-model 相对路径等。
• [!] node scripts/audit-english.mjs 仍会列出大量英文内容；这些主要是保留的 identifiers、命令、示例、触发词和工程术语，作为人工复核队列，不作为阻塞项。

npx skills@latest add vinvcn/mattpocock-skills-zh-CN

选择你想安装的 skills，以及要安装到哪些 coding agents。首次安装时请确保选择 /setup-matt-pocock-skills，然后在 agent 中运行它来完成 issue tracker、labels 和 docs 目录配置。

我每天用于真实工程工作的 agent skills，不是 vibe coding。

开发真实应用很难。GSD、BMAD、Spec-Kit 这类方法试图通过接管流程来帮你。但它们在接管流程的同时，也拿走了你的控制权，并让流程里的 bug 更难解决。

这些 skills 被设计得小、易改、可组合。它们适用于任何模型，背后是数十年的工程经验。你可以 hack 它们，让它们变成自己的东西。

如果你想跟进这些 skills 的更新，以及我后续创建的新 skill，可以加入大约 60,000 名开发者订阅的 newsletter：

订阅 Newsletter

1. 运行 skills.sh installer：

npx skills@latest add vinvcn/mattpocock-skills-zh-CN

2. 选择你想安装的 skills，以及要安装到哪些 coding agents。确保选择 /setup-matt-pocock-skills。

3. 在你的 agent 中运行 /setup-matt-pocock-skills。它会：

   • 询问你要使用哪个 issue tracker（GitHub、Linear 或 local files）
   • 询问你 triage issues 时使用哪些 labels（/triage 会使用这些 labels）
   • 询问要把创建的 docs 保存到哪里

4. 完成后即可开始使用。

我创建这些 skills，是为了解决我在 Claude Code、Codex 和其他 coding agents 中反复看到的常见失败模式。

"No-one knows exactly what they want"

David Thomas & Andrew Hunt, The Pragmatic Programmer

问题：软件开发中最常见的失败模式是 misalignment。你以为开发者理解了你想要什么；等看到做出来的东西，才发现对方完全没理解。

AI 时代也是一样。你和 agent 之间存在沟通缺口。修复方式是一次 grilling session，让 agent 针对你要构建的东西提出详细问题。

解决方式是使用：

• /grill-me — 用于非代码场景
• /grill-with-docs — 与 /grill-me 类似，但会加入更多文档能力（见下文）

这些是我最常用的 skills。它们帮助你在开始前和 agent 对齐，并深入思考你要做的变更。每次想做变更时都值得使用。

With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.

Eric Evans, Domain-Driven-Design

问题：项目开始时，开发者和真正使用软件的人（domain experts）通常说着不同语言。

我在 agents 身上也感受到同样张力。Agents 往往被丢进一个项目，然后被要求边做边弄懂术语。于是它们用 20 个词解释本来 1 个词就够的东西。

解决方式是 shared language。它是一份帮助 agents 解码项目术语的文档。

这已经内置在 /grill-with-docs 中。它是一场 grilling session，同时帮助你和 AI 建立 shared language，并把难解释的决策记录到 ADR 中。

很难解释这件事有多强。它可能是这个 repo 里最酷的技术之一。试试看就知道。

"Always take small, deliberate steps. The rate of feedback is your speed limit. Never take on a task that’s too big."

David Thomas & Andrew Hunt, The Pragmatic Programmer

问题：假设你和 agent 已经对要构建什么达成一致。那如果 agent 仍然产出一堆不能用的东西呢？

这时要看你的 feedback loops。没有对生成代码真实运行情况的反馈，agent 就是在盲飞。

解决方式：你需要常规的一组 feedback loops：static types、browser access 和 automated tests。

对 automated tests 来说，red-green-refactor 循环非常关键。Agent 先写一个失败测试，再修到测试通过。这能给 agent 稳定反馈，最终得到更好的代码。

我做了一个可以放进任何项目的 /tdd skill。它鼓励 red-green-refactor，并给 agent 足够多关于好测试和坏测试的指导。

调试方面，我也做了一个 /diagnose skill，把最佳调试实践包装成一个简单循环。

"Invest in the design of the system every day."

Kent Beck, Extreme Programming Explained

"The best modules are deep. They allow a lot of functionality to be accessed through a simple interface."

John Ousterhout, A Philosophy Of Software Design

问题：大多数用 agents 构建的应用都复杂且难以修改。因为 agents 能极大加速编码，它们也会以空前速度加速软件熵增。Codebase 会变得越来越复杂。

解决方式是 AI-powered development 的一种新办法：关心代码设计。

这些 skills 的每一层都内置了这种思路：

• /to-prd 会在创建 PRD 前追问你要触碰哪些 modules
• /zoom-out 会要求 agent 从整个系统的上下文解释代码

更重要的是，/improve-codebase-architecture 能帮助你拯救已经变成 ball of mud 的 codebase。我建议每隔几天就在你的 codebase 上跑一次。

软件工程基本功比以往任何时候都更重要。这些 skills 是我把这些基本功压缩成可重复实践的一次尝试，目标是帮你交付职业生涯中最好的应用。

我每天用于代码工作的 skills。

• diagnose — 面向棘手 bug 和性能回退的纪律化诊断循环：reproduce → minimise → hypothesise → instrument → fix → regression-test。
• grill-with-docs — 对照现有 domain model 挑战你的计划，收紧术语，并在决策成形时内联更新 CONTEXT.md 和 ADR。
• triage — 通过 triage roles state machine 分诊 issues。
• improve-codebase-architecture — 根据 CONTEXT.md 中的 domain language 和 docs/adr/ 中的决策，发现 codebase 中可以 deepen 的机会。
• setup-matt-pocock-skills — 搭建其他 engineering skills 会消费的每仓库配置：issue tracker、triage label vocabulary 和 domain doc layout。首次使用 to-issues、to-prd、triage、diagnose、tdd、improve-codebase-architecture 或 zoom-out 前运行一次。
• tdd — 使用 red-green-refactor 循环做 test-driven development。一次一个 vertical slice 地构建功能或修 bug。
• to-issues — 使用 vertical slices，把任意计划、spec 或 PRD 拆成可独立领取的 issue tracker issues。
• to-prd — 将当前对话上下文整理成 PRD，并发布到项目 issue tracker。不做访谈，只综合已经讨论过的内容。
• zoom-out — 让 agent zoom out，对不熟悉的代码区域给出更广的上下文或更高层视角。
• prototype — 在承诺方案前构建 throwaway prototype 来细化设计：可以是用于 state/business-logic 问题的可运行终端 app，也可以是在同一路由上切换的多种 UI 变体。

通用工作流工具，不限于代码。

• caveman — 超压缩沟通模式。去掉废话但保留完整技术准确性，token 使用量约减少 75%。
• grill-me — 围绕计划或设计持续追问，直到决策树的每个分支都被解决。
• handoff — 将当前对话压缩成 handoff document，让另一个 agent 可以继续工作。
• teach — 使用当前目录作为 stateful teaching workspace，在多个 sessions 中教用户一个新 skill 或概念。
• write-a-skill — 用正确结构、progressive disclosure 和 bundled resources 创建新的 skills。

我保留但很少使用的工具。

• git-guardrails-claude-code — 设置 Claude Code hooks，在危险 git 命令（push、reset --hard、clean 等）执行前阻止它们。
• migrate-to-shoehorn — 将测试文件中的 as 类型断言迁移到 @total-typescript/shoehorn。
• scaffold-exercises — 创建包含 sections、problems、solutions 和 explainers 的练习目录结构。
• setup-pre-commit — 设置 Husky pre-commit hooks，集成 lint-staged、Prettier、type checking 和 tests。