mattpocock / skills

Skills For Real Engineers

给真正工程师的技能

My agent skills that I use every day to do real engineering - not vibe coding. Developing real applications is hard. Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve. These skills are designed to be small, easy to adapt, and composable. They work with any model. They’re based on decades of engineering experience. Hack around with them. Make them your own. Enjoy. 这是我每天用于进行真正工程开发（而非“凭感觉编程”）的智能体技能。开发真正的应用程序非常困难。像 GSD、BMAD 和 Spec-Kit 这样的方法试图通过接管整个流程来提供帮助，但这样做会剥夺你的控制权，并使流程中的错误难以解决。这些技能被设计为小巧、易于适配且可组合的。它们适用于任何模型，并基于数十年的工程经验。你可以随意尝试、修改并将其变成你自己的工具。尽情享受吧。

If you want to keep up with changes to these skills, and any new ones I create, you can join ~60,000 other devs on my newsletter: Sign Up To The Newsletter 如果你想跟进这些技能的更新以及我创建的新技能，可以加入我的时事通讯，与约 60,000 名开发者一起交流：[订阅时事通讯]

Quickstart (30-second setup)

快速入门（30 秒设置）

Run the skills.sh installer: npx skills@latest add mattpocock/skills 运行安装程序：npx skills@latest add mattpocock/skills

Pick the skills you want, and which coding agents you want to install them on. Make sure you select /setup-matt-pocock-skills. 选择你想要的技能，以及你想在哪些编码智能体上安装它们。请确保选择 /setup-matt-pocock-skills。

Run /setup-matt-pocock-skills in your agent. It will: 在你的智能体中运行 /setup-matt-pocock-skills。它将：

Ask you which issue tracker you want to use (GitHub, Linear, or local files)
询问你想使用哪个问题追踪器（GitHub、Linear 或本地文件）
Ask what labels you apply to ticks when you triage them (/triage uses labels)
询问你在分类任务（triage）时使用什么标签（/triage 会用到这些标签）
Ask where you want to save any docs we create
询问你想将创建的文档保存在哪里

Bam - you’re ready to go. 搞定——你已经准备就绪。

Why These Skills Exist

为什么存在这些技能

I built these skills as a way to fix common failure modes I see with Claude Code, Codex, and other coding agents. 我构建这些技能是为了修复我在 Claude Code、Codex 和其他编码智能体中观察到的常见故障模式。

#1: The Agent Didn’t Do What I Want

#1：智能体没有按我的意愿行事

“No-one knows exactly what they want” — David Thomas & Andrew Hunt, The Pragmatic Programmer “没有人确切知道自己想要什么” —— David Thomas & Andrew Hunt，《程序员修炼之道》

The Problem: The most common failure mode in software development is misalignment. You think the dev knows what you want. Then you see what they’ve built - and you realize it didn’t understand you at all. This is just the same in the AI age. There is a communication gap between you and the agent. 问题： 软件开发中最常见的故障模式是“错位”。你以为开发者知道你想要什么，但当你看到他们构建的东西时，才发现他们根本没理解你的意图。在 AI 时代也是如此，你和智能体之间存在沟通鸿沟。

The Fix: The fix for this is a grilling session - getting the agent to ask you detailed questions about what you’re building. 解决方案： 解决办法是进行“拷问”环节——让智能体针对你正在构建的内容向你提出详细问题。

Use: 使用：

/grill-me - for non-code uses
/grill-me - 用于非代码用途
/grill-with-docs - same as /grill-me, but adds more goodies (see below)
/grill-with-docs - 与 /grill-me 相同，但增加了更多功能（见下文）

These are my most popular skills. They help you align with the agent before you get started, and think deeply about the change you’re making. Use them every time you want to make a change. 这些是我最受欢迎的技能。它们能帮助你在开始之前与智能体达成一致，并深入思考你所做的变更。每次你想进行修改时，都请使用它们。

#2: The Agent Is Way Too Verbose

#2：智能体过于啰嗦

“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 “通过通用语言，开发者之间的对话和代码的表达都源自同一个领域模型。” —— Eric Evans，《领域驱动设计》

The Problem: At the start of a project, devs and the people they’re building the software for (the domain experts) are usually speaking different languages. I felt the same tension with my agents. Agents are usually dropped into a project and asked to figure out the jargon as they go. So they use 20 words where 1 will do. 问题： 在项目初期，开发者和软件的使用者（领域专家）通常说着不同的语言。我在使用智能体时也感受到了同样的张力。智能体通常被直接投入项目中，并被要求边做边摸索术语。因此，它们往往用 20 个词来表达原本 1 个词就能说清的事。

The Fix: A shared language. It’s a document that helps agents decode the jargon used in the project. 解决方案： 共享语言。这是一份帮助智能体解码项目中术语的文档。

Example: Here’s an example CONTEXT.md, from my course-video-manager repo. Which one is easier to read? 示例： 这是我 course-video-manager 仓库中的一个 CONTEXT.md 示例。哪一个更容易阅读？

BEFORE: “There’s a problem when a lesson inside a section of a course is made ‘real’ (i.e. given a spot in the file system)”
修改前： “当课程章节中的一节课被‘实体化’（即在文件系统中分配了位置）时会出现问题”
AFTER: “There’s a problem with the materialization cascade”
修改后： “物化级联（materialization cascade）存在问题”

This concision pays off session after session. This is built into /grill-with-docs. It’s a grilling session, but that helps you build a shared language with the AI, and document hard-to-explain decisions in ADR’s. It’s hard to explain how powerful this is. It might be the single coolest technique in this repo. Try it, and see. 这种简洁性在每一次会话中都大有裨益。这已内置于 /grill-with-docs 中。它不仅是一个拷问环节，还能帮助你与 AI 建立共享语言，并在 ADR（架构决策记录）中记录那些难以解释的决策。很难用言语形容它有多强大，这可能是本仓库中最酷的技术。试一试就知道了。

Tip: A shared language has many other benefits than reducing verbosity: 提示： 共享语言除了减少啰嗦之外，还有许多其他好处：

Variables, functions and files are named consistently, using the shared language
变量、函数和文件的命名保持一致，使用共享语言
As a result, the codebase is easier to navigate for the agent
因此，智能体更容易导航代码库
The agent also spends fewer tokens on thinking, because it has access to a more concise language
智能体在思考时消耗的 Token 更少，因为它能使用更简洁的语言

#3: The Code Doesn’t Work

#3：代码无法运行

“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 “始终采取小而审慎的步骤。反馈率就是你的速度限制。永远不要承担过大的任务。” —— David Thomas & Andrew Hunt，《程序员修炼之道》

The Problem: Let’s say that you and the agent are aligned on what to build. What happens when the agent still produces crap? It’s time to look at your feedback loops. Without feedback on how the code it produces actually runs, the agent will be flying blind. 问题： 假设你和智能体在构建目标上达成了一致，但智能体产出的代码依然很烂，该怎么办？是时候审视你的反馈循环了。如果没有关于代码实际运行情况的反馈，智能体就是在盲目飞行。

The Fix: You need the usual tranche of feedback loops: static types, browser access, and automated tests. For automated tests, a red-green-refactor loop is critical. This is where the agent writes a failing test first, then fixes the test. This helps give the agent a consistent level of feedback that results in far better code. 解决方案： 你需要常规的反馈循环：静态类型、浏览器访问和自动化测试。对于自动化测试，“红-绿-重构”（red-green-refactor）循环至关重要。即让智能体先写一个失败的测试，然后再修复它。这有助于为智能体提供持续的反馈，从而产出更好的代码。

I’ve built a /tdd skill you can slot into any project. It encourages red-green-refactor and gives the agent plenty of guidance on what makes good and bad tests. For debugging, I’ve also built a /diagnose skill that wraps best debugging practices into a simple loop. 我构建了一个可以插入任何项目的 /tdd 技能。它鼓励“红-绿-重构”，并为智能体提供了大量关于什么是好测试、什么是坏测试的指导。对于调试，我还构建了一个 /diagnose 技能，将最佳调试实践封装成一个简单的循环。

#4: We Built A Ball Of Mud

#4：我们构建了一个“泥球”架构

“Invest in the design of the system every day.” — Kent Beck, Extreme Programming Explained “每天都要投资于系统设计。” —— Kent Beck，《解析极限编程》 “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 “最好的模块是深度的。它们允许通过简单的接口访问大量功能。” —— John Ousterhout，《软件设计哲学》

The Problem: Most apps built with agents are complex and hard to change. Because agents can radically speed up coding, they also accelerate software entropy. Codebases get more complex at an unprecedented rate. 问题： 大多数由智能体构建的应用程序都很复杂且难以修改。由于智能体可以极大地加快编码速度，它们也加速了软件熵的增加。代码库正以前所未有的速度变得复杂。

The Fix: A radical new approach to AI-powered development: caring about the design of the code. This is built in to every layer of these skills: 解决方案： 一种 AI 辅助开发的新方法：关注代码设计。这已内置于这些技能的每一层中：

/to-prd quizzes you about which modules you’re touching before creating a PRD
/to-prd 在创建 PRD（产品需求文档）之前，会询问你正在触及哪些模块
/zoom-out tells the agent to explain code in the context of the whole system
/zoom-out 让智能体在整个系统背景下解释代码
And crucially, /improve-codebase-architecture helps you rescue a codebase that has become a ball of mud. I recommend running it on your codebase once every few days.
最关键的是，/improve-codebase-architecture 可以帮助你拯救已经变成“泥球”的代码库。我建议每隔几天在你的代码库上运行一次。

Summary

总结

Software engineering fundamentals matter more than ever. These skills are my best effort at condensing these fundamentals into repeatable practices, to help you ship the best apps of your career. Enjoy. 软件工程基础比以往任何时候都重要。这些技能是我将这些基础知识浓缩为可重复实践的最佳尝试，旨在帮助你交付职业生涯中最棒的应用程序。尽情享受吧。

Reference: Engineering Skills I use daily for code 参考：我日常用于编码的工程技能