真正工程师的技能集

我每天都在使用这些代理技能来做真正的工程 —— 而不是氛围编码。

开发真实应用非常困难。像 GSD、BMAD 和 Spec-Kit 这样的方法试图通过掌控整个流程来帮忙。但它们在这样做的时候，也夺走了你的控制权，并且让过程中出现的 bug 难以解决。

这些技能的设计原则是：小巧、易于适配且可组合。它们能与任何模型一起工作。它们建立在数十年的工程经验之上。你可以自由改造它们，让它们变成你自己的东西。享受这个过程吧。

如果你想了解这些技能的更新，以及我创建的任何新技能，可以加入我通讯录中约 60,000 名开发者：

订阅通讯

快速开始（30 秒安装）

1. 运行 skills.sh 安装程序：

npx skills@latest add mattpocock/skills

2. 选择你想要的技能，以及要安装到哪些编码代理上。请确保选中 /setup-matt-pocock-skills。

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

   • 询问你想使用哪个问题跟踪器（GitHub、Linear 或本地文件）
   • 询问你在分类工单时应用哪些标签（/triage 会用到标签）
   • 询问你希望将我们创建的任何文档保存在哪里

4. Bam —— 准备就绪。

作为 Claude Code 插件安装

更喜欢一种即插即用、无需手动维护的安装方式？这些技能也以原生 Claude Code 插件的形式发布。与将可编辑文件复制到你的仓库不同，插件将整个技能集作为受管理的捆绑包安装，并在我发布新版本时更新 —— 你采用的是订阅模式，而非分叉模式。

在 Claude Code 中：

/plugin marketplace add mattpocock/skills /plugin install mattpocock-skills@mattpocock

或者从你的 shell：

claude plugin marketplace add mattpocock/skills claude plugin install mattpocock-skills@mattpocock

然后每个仓库运行一次 /setup-matt-pocock-skills，与上述快速开始完全一样。

两种安装方式，两种哲学：

• skills.sh 会将技能复制到你的项目中，让你可以直接修改它们，变成你自己的版本。
• 插件 将它们保持为只读、始终最新的捆绑包，你无法编辑 —— 最适合你只想让我的这套开箱即用，并随之演进。

使用 Codex 或其他代理？skills.sh 安装器 已经支持将这些技能安装到 Codex 和其他符合 Agent-Skills 标准的工具中。原生的 Codex 插件已在路线图上 —— 详见 .agents/adr/0002-ship-as-a-claude-code-plugin.md。

我构建这些技能，是为了解决我在使用 Claude Code、Codex 以及其他编码代理时常见的失败模式。

#1: 代理没有做到我想要的效果

“没有人确切知道自己想要什么”

David Thomas & Andrew Hunt，《程序员修炼之道》

问题所在。软件开发中最常见的失败模式是对齐偏差。你以为开发者明白你想要什么。然后你看到他们构建出来的东西 —— 才意识到它根本没有理解你。

这在 AI 时代同样如此。你与代理之间存在沟通鸿沟。解决这个问题的方法是进行一次 严丝合缝的质询 —— 让代理就你正在构建的内容提出详细问题。

解决方案 是使用：

这是我最受欢迎的几项技能。它们帮助你在开始之前就与代理对齐思路，并深入思考你要做的变更。请 每次 想做变更时都使用它们。

#2: 代理过于啰嗦

有了通用语言，开发者之间的对话以及代码的表达，都源自同一个领域模型。

Eric Evans，《领域驱动设计》

问题所在：在项目初期，开发人员和软件所服务的对象（领域专家）通常说着不同的语言。

我在与代理协作时也感受到了同样的张力。代理通常被直接丢进项目，要求在摸索中自行理解术语。因此，一个词就能说清楚的事，它们常常会用到 20 个词。

解决方案 是建立一种共享语言。这是一份帮助代理解码项目术语的文档。

示例

这里有一个来自我的 course-video-manager 仓库的 CONTEXT.md 示例。哪个更容易阅读？

• 之前：“当课程某个章节中的一课被置为‘真实’（即在文件系统中获得一个位置）时，会出现一个问题”
• 之后：“物化级联过程存在一个问题”

这种简洁在一次又一次的会话中带来回报。

这已内置于 /grill-with-docs。这是一个质询会话，但能帮助你与 AI 建立共享语言，并将难以解释的决策记录在 ADR 中。

很难表述这有多强大。这可能是这个仓库中最酷炫的一项技术。试试看就知道了。

提示

共享语言除了减少冗余，还有其他许多好处：

• 变量、函数和文件的命名保持一致，均使用共享语言
• 因此，代码库对代理来说更易于导航
• 代理在思考上也花费更少的 token，因为它可以使用更简洁的语言

#3: 代码无法工作

“始终采取小步、深思熟虑的步骤。反馈的速度就是你的速度上限。绝不要接手过于庞大的任务。”

David Thomas & Andrew Hunt，《程序员修炼之道》

问题所在：假设你和代理已经就构建内容达成一致。当代理仍然产出垃圾代码时，会发生什么？

是时候审视你的反馈回路了。如果代理得不到关于其产出代码实际运行情况的反馈，就如同盲飞。

解决方案：你需要常用的反馈回路组合：静态类型、浏览器访问以及自动化测试。

在自动化测试中，红-绿-重构循环至关重要。即代理先编写一个失败的测试，然后修复该测试。这能为代理提供一致级别的反馈，从而产出好得多的代码。

我构建了一个 /tdd 技能，可以插入到任何项目中使用。它鼓励红-绿-重构，并给予代理大量关于测试好坏标准的指导。

针对调试，我还构建了一个 /diagnosing-bugs 技能，它将最佳调试实践包装在一个简洁的循环之中。

#4: 我们构建了一团乱麻

“每天都要投资于系统设计。”

Kent Beck，《解析极限编程》

“最好的模块是深层的。它们允许通过简单的接口访问大量功能。”

John Ousterhout，《软件设计的哲学》

问题所在：使用代理构建的应用大多复杂且难以修改。因为代理可以极大地加快编码速度，它们也加速了软件熵增。代码库以史无前例的速度变得复杂。

解决方案 是一种对 AI 驱动开发的全新激进方法：关注代码的设计。

这已内置在这些技能的每一层中：

• /to-spec 在创建规格说明之前，会询问你正在触碰哪些模块

至关重要的一点是，/improve-codebase-architecture 能帮助你将已变成一团乱麻的代码库抢救回来。我建议每隔几天就在你的代码库上运行一次。

软件工程的基础原则比以往任何时候都重要。这些技能是我将这些基础原则浓缩为可重复实践的竭诚努力，旨在帮助你交付职业生涯中最棒的应用程序。享受它吧。

—— 以下技能沿着一条轴线划分 —— 谁能调用它们。用户调用的技能只有当你主动输入（例如 /grill-me）时才能触发；它们的职责是编排。模型调用的技能既可以被你调用，也可以在任务匹配时代理自动获取；它们承载着可复用的纪律。一个用户调用的技能可以调用模型调用的技能，但绝不会调用另一个用户调用的技能。

我日常编码工作使用的技能。

用户调用

• ask-matt — 询问哪个技能或流程适合你的情况。一个通往本仓库中用户调用技能的路由器。
• grill-with-docs — 质询会话，同时构建项目的领域模型，精炼术语并实时更新 CONTEXT.md 和 ADR。
• triage — 令工单按分类角色状态机流转。
• improve-codebase-architecture — 扫描代码库寻找可深化设计的机会，呈现为可视化的 HTML 报告，然后质询你选中的任何一个点。
• setup-matt-pocock-skills — 针对工程技能配置此仓库（问题跟踪器、分类标签、领域文档布局）。在对其他工程技能使用之前，每个仓库运行一次。
• to-spec — 将当前对话转化为一份规格说明并发布到问题跟踪器。无需面谈 —— 仅综合已有的讨论内容。
• to-tickets — 将任何计划、规格或对话分解为一组跟踪子弹工单，每个工单都声明其阻塞边界 —— 可以写成本地文件中的文本，或实际跟踪器上的原生阻塞链接。
• implement — 构建由规格或工单集描述的工作，在预先商定的接缝处驱动 /tdd，并在提交前通过 /code-review 完成闭环。
• wayfinder — 规划一个超出单次代理会话能力的大型工作，作为问题跟踪器上的一组共享的调研工单，一次解决它们，直到通往目标的路径变得清晰。

模型调用

• prototype — 构建一个可抛弃的原型来回答设计问题 —— 针对状态/逻辑问题可使用可运行的终端应用，或在一个路由下切换几种截然不同的 UI 变体。
• diagnosing-bugs — 为棘手的 bug 和性能衰退设计的纪律化诊断循环：重现 → 最小化 → 假设 → 观测 → 修复 → 回归测试。
• research — 参考高可信度的一手资料调研问题，并将发现以带引用的 Markdown 文件形式捕获到仓库中，作为后台代理运行。
• tdd — 带有红-绿-重构循环的测试驱动开发。每次构建一个垂直切片的特性或修复 bug。
• domain-modeling — 主动构建并精炼项目的领域模型 —— 依照术语表挑战术语，用边界案例场景进行压力测试，并实时更新 CONTEXT.md 和 ADR。
• codebase-design — 设计深层模块的共享纪律与词汇：大量行为隐藏在小接口之后，置于清晰的接缝处，并通过该接口可测试。
• code-review — 从固定点以来的 diff 进行双轴评审：标准轴（是否遵循仓库的编码标准，加上 Fowler 的坏味道基线？）和规格轴（是否忠实地实现了原始问题/PRD？），以并行子代理方式运行，避免相互污染。
• resolving-merge-conflicts — 逐步处理进行中的 git 合并或 rebase 冲突，逐块解决，追溯各方意图至其原始来源，然后完成操作 —— 绝不 --abort。

通用工作流工具，非代码专用。

用户调用

• grill-me — 就某个计划或设计接受无情地质询，直到决策的每一个分支都被遍历。

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.

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

Quickstart (30-second setup)

1. Run the skills.sh installer:

npx skills@latest add mattpocock/skills

2. Pick the skills you want, and which coding agents you want to install them on. Make sure you select/setup-matt-pocock-skills.

3. Run /setup-matt-pocock-skills in your agent. It will:

   • Ask you which issue tracker you want to use (GitHub, Linear, or local files)
   • Ask you what labels you apply to tickets when you triage them (/triage uses labels)
   • Ask you where you want to save any docs we create

4. Bam - you're ready to go.

Install as a Claude Code plugin

Prefer a plug-and-play install you don't maintain by hand? These skills also ship as a native Claude Code plugin. Instead of copying editable files into your repo, the plugin installs the whole skill set as a managed bundle that updates when I ship a new version — you subscribe rather than fork.

Inside Claude Code:

/plugin marketplace add mattpocock/skills
/plugin install mattpocock-skills@mattpocock

Or from your shell:

claude plugin marketplace add mattpocock/skills
claude plugin install mattpocock-skills@mattpocock

Then run /setup-matt-pocock-skills once per repo, exactly as in the quickstart above.

Two ways to install, two philosophies:

• skills.sh copies the skills into your project so you can hack on them and make them your own.
• The plugin keeps them as a read-only, always-current bundle you don't edit — best when you just want my set to work and follow along as it evolves.

Using Codex or another agent? The skills.sh installer already installs these skills into Codex and other Agent-Skills-standard harnesses today. A native Codex plugin is on the roadmap — see .agents/adr/0002-ship-as-a-claude-code-plugin.md.

I built these skills as a way to fix common failure modes I see with Claude Code, Codex, and other coding agents.

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

"No-one knows exactly what they want"

David Thomas & Andrew Hunt, The Pragmatic Programmer

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. The fix for this is a grilling session - getting the agent to ask you detailed questions about what you're building.

The Fix is to use:

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

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

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.

The Fix for this is 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?

• 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"

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.

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

#3: The Code Doesn't Work

"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

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.

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 /diagnosing-bugs skill that wraps best debugging practices into a simple loop.

#4: We Built A Ball Of Mud

"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

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 for this is 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:

• /to-spec quizzes you about which modules you're touching before creating a spec

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.

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.

These split on one axis — who can invoke them. User-invoked skills are reachable only when you type them (e.g. /grill-me); their job is to orchestrate. Model-invoked skills can be invoked by you or reached for automatically by the agent when the task fits; they hold the reusable discipline. A user-invoked skill may invoke model-invoked skills, but never another user-invoked one.

Skills I use daily for code work.

User-invoked

• ask-matt — Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo.
• grill-with-docs — Grilling session that also builds your project's domain model, sharpening terminology and updating CONTEXT.md and ADRs inline.
• triage — Move issues through a state machine of triage roles.
• improve-codebase-architecture — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
• setup-matt-pocock-skills — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills.
• to-spec — Turn the current conversation into a spec and publish it to the issue tracker. No interview — just synthesizes what you've already discussed.
• to-tickets — Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges — written as text in a local file, or as native blocking links on a real tracker.
• implement — Build the work described by a spec or set of tickets, driving /tdd at pre-agreed seams and closing out with /code-review before committing.
• wayfinder — Plan a huge chunk of work, more than one agent session can hold, as a shared map of investigation tickets on the issue tracker — resolve them one at a time until the way to the destination is clear.

Model-invoked

• prototype — Build a throwaway prototype to answer a design question — a runnable terminal app for state/logic questions, or several radically different UI variations toggleable from one route.
• diagnosing-bugs — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test.
• research — Investigate a question against high-trust primary sources and capture the findings as a cited Markdown file in the repo, run as a background agent.
• tdd — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time.
• domain-modeling — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update CONTEXT.md and ADRs inline.
• codebase-design — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface.
• code-review — Two-axis review of the diff since a fixed point: Standards (does it follow the repo's coding standards, plus a Fowler smell baseline?) and Spec (does it faithfully implement the originating issue/PRD?), run as parallel sub-agents so neither pollutes the other.
• resolving-merge-conflicts — Work through an in-progress git merge or rebase conflict hunk by hunk, resolving by intent traced to each side's primary source, then finish the operation — never --abort.

General workflow tools, not code-specific.

User-invoked

• grill-me — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved.
• handoff — Compact the current conversation into a handoff document so another agent can continue the work.
• teach — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace.
• writing-great-skills — Reference for writing and editing skills well: the vocabulary and principles that make a skill predictable.

Model-invoked

• grilling — Interview the user relentlessly about a plan, decision, or idea until every branch of the decision tree is resolved. The reusable loop behind grill-me and grill-with-docs.