把 AI 编程助手从“会写代码”调成“会做工程”:mattpocock/skills 保姆级教程-夜雨聆风

把 AI 编程助手从“会写代码”调成“会做工程”:mattpocock/skills 保姆级教程

如果你最近经常让 Claude Code、Codex、Cursor 这类 AI 编程助手改代码，大概率遇到过一个很熟悉的场景：它写得飞快，文件也改了一堆，但你一跑测试，发现方向偏了；你让它少说废话，它反而解释半屏；你让它修 bug，它看起来很努力，却没有先复现问题。

本周 GitHub 上火起来的 mattpocock/skills，解决的正是这个问题。它不是一个新模型，也不是一个“万能 Agent 框架”，而是一组可以装进 AI 编程助手里的工程工作流：需求澄清、TDD、问题诊断、架构改进、PRD、Issue 拆分、Git 防护、文章编辑等。我们可以把它理解成：给 AI 助手配一套“高级工程师工作习惯”。

![封面图](image_placeholder: 一名开发者在代码编辑器旁边调试 AI Agent，画面中有 SKILL.md、TDD、Diagnose、Architecture 等关键词，风格适合微信公众号封面)

项目介绍：它是什么？为什么这周这么火？

先交代本次选择依据。按 2026-04-29（周三）执行，本任务取 GitHub 本周热门 AI 项目第 3 名。根据 GitHub Trending weekly 页面，本周 AI 相关项目里，forrestchang/andrej-karpathy-skills、Alishahryar1/free-claude-code、mattpocock/skills 处在前列；其中 mattpocock/skills 显示约 36,581 Stars，本周新增约 10,757 Stars[1]。所以今天我们的目标项目就是：

项目名：mattpocock/skills
GitHub：https://github.com/mattpocock/skills
一句话简介：Skills for Real Engineers，来自 Matt Pocock 日常使用的 .claude 工程技能集合。

这个项目最核心的想法很简单：AI 编程助手不缺“生成代码”的能力，缺的是稳定的工程流程。真实开发里，高手不会一上来就乱写实现，而是会先问清楚需求、确认接口、写可验证的测试、构造复现路径、记录关键决策，再慢慢把复杂度收进合适的模块里。mattpocock/skills 把这些习惯写成一个个 SKILL.md，让 Agent 在合适的任务场景里自动加载对应工作流[2]。

它为什么火？原因主要有三个。

第一，Claude Code、Codex、Cursor 这类工具已经从“代码补全”走向“半自主改项目”。当 Agent 能批量改文件、跑命令、写测试时，最怕的不是它慢，而是它快但没有边界。这个项目正好踩中开发者痛点。

第二，Skills 这种形态正在变成 AI Agent 的新标准之一。Anthropic 官方文档把 Agent Skill 定义为一个包含 SKILL.md 的目录，可以附带脚本、参考资料、模板等资源；模型启动时先看技能名和描述，任务匹配时再加载完整内容[3]。官方工程博客也把这种机制称为 progressive disclosure，也就是“先放目录，必要时再展开细节”[4]。

第三，它不是演示玩具，而是围绕真实工程失败场景设计的。README 里直接点名了几个常见问题：Agent 没理解需求、输出太啰嗦、代码跑不起来、项目越改越乱[2]。这些不是炫技问题，而是每天都会发生的问题。

核心功能拆解：它到底能帮我们做什么？

mattpocock/skills 不是一个单点工具，而是一组可组合的技能包。我们可以按开发流程把它分成四类。

![核心模块图](image_placeholder: 四象限流程图，分别是需求澄清、开发验证、问题诊断、工程治理，每个象限列出对应 skill 名称)

1. 需求澄清：先把问题问清楚

最典型的是 /grill-me 和 /grill-with-docs。

/grill-me 的目标不是让 Agent 立刻写代码，而是让它追问你的计划、设计和边界条件，直到关键分支都被说清楚。它适合用在“我想做一个功能，但还没想透”的阶段。

/grill-with-docs 更进一步，会结合项目里的 CONTEXT.md 和 docs/adr/。它会检查你说的词和项目已有术语是否冲突，也会在决策稳定后更新上下文文档或 ADR。比如你说“账号”，它会追问到底是 Customer、User，还是 Billing Account。这个动作看起来小，但对长期项目很重要，因为 Agent 和人都需要同一套语言。

2. 开发验证：用 TDD 把 Agent 拉回现实

/tdd 是这个项目里最值得上手的技能之一。它强调测试应该验证公开接口和用户可观察行为，而不是锁死内部实现。它也明确反对“一口气写完所有测试，再一口气写实现”的横向切法，推荐一条一条走：

RED：先写一个会失败的测试
GREEN：写最少实现让它通过
REFACTOR：在测试通过后再整理代码

这正好对应 AI 编程助手的一个常见问题：它很容易脑补未来需求，然后一次性堆很多代码。/tdd 会把它限制在一个个 vertical slice 里：一次只证明一个行为，一次只写够当前测试通过的实现。

![TDD 流程图](image_placeholder: RED、GREEN、REFACTOR 三段循环图，中间标注“一个行为、一个测试、一次实现”)

3. 问题诊断：先复现，再修

/diagnose 是调试技能。它的核心不是“猜 bug 在哪里”，而是先建立一个稳定的反馈回路。可以是失败测试、HTTP 脚本、CLI fixture、Playwright 脚本、回放日志、最小 harness，甚至是 git bisect run。

这个思路和软件工程 Agent 研究也对得上。SWE-agent 论文指出，Agent 要完成真实软件工程任务，关键不只是语言模型能力，还包括它如何编辑文件、导航仓库、执行测试和使用工具[5]。2026 年的 SWE-chat 论文进一步观察到，真实开发里的 coding agent 仍然会出现大量返工、打断和纠正，只有一部分 Agent 生成代码最终进入提交[6]。所以让 Agent 先构造可重复验证的回路，比让它“凭感觉修一下”可靠得多。

4. 工程治理：让项目越改越清楚

/improve-codebase-architecture 用来找架构摩擦点。它关注的不是“把代码变漂亮”，而是寻找浅模块、隐藏耦合、难测试接口，把复杂度收到更深的模块里。这个技能适合每隔几天跑一次，尤其适合 AI 助手已经改过多轮、项目开始变得难懂的时候。

此外还有：

• /to-prd：把当前讨论整理成 PRD，并提交成 GitHub Issue。
• /to-issues：把计划拆成可独立处理的垂直切片 Issue。
• /triage：按状态机方式整理 backlog。
• /zoom-out：让 Agent 从系统视角解释一段代码。
• /git-guardrails-claude-code：给 Claude Code 增加 Git 操作防护。
• /write-a-skill：帮你写自己的 Skill。

保姆级上手教程

下面我们从零开始。本文以 Windows PowerShell 为主，macOS/Linux 用户可以直接复用 npx 命令；文件路径按自己的系统替换即可。

Step 0：环境准备

你需要准备三样东西：

• Node.js 和 npm，用来运行 npx skills@latest。
• 一个支持 Skills 的 AI 编程助手，最直接的是 Claude Code；如果你的工具兼容 Agent Skills，也可以参考同样思路。
• 一个真实项目仓库，最好有测试命令，例如 npm test、pytest、pnpm test。

先检查本机环境：

node --version
npm --version
git --version

如果没有 Node.js，先到 Node.js 官网安装 LTS 版本。安装后重新打开终端，再运行上面的命令确认。

Step 1：安装 mattpocock/skills

项目 README 给出的快速安装命令如下[2]：

npx skills@latest add mattpocock/skills

运行后会出现交互选择。建议第一次至少选上：

• /setup-matt-pocock-skills
• /grill-with-docs
• /tdd
• /diagnose
• /improve-codebase-architecture
• /zoom-out

安装完成后，进入你的项目目录，打开 AI 编程助手，执行：

/setup-matt-pocock-skills

它会询问几个初始化问题，比如 backlog 用 GitHub、Linear 还是本地文件，triage 用哪些标签，文档希望保存在哪里。这里不要随便跳过，因为后续技能会依赖这些配置。

Step 2：确认 Skill 是否装好

我们写一个小脚本，扫描常见的 Skill 目录，并打印每个 SKILL.md 的名称和描述。

from pathlib import Path


def find_skill_roots():
    candidates = [
        Path.home() / ".claude" / "skills",
        Path.cwd() / ".claude" / "skills",
    ]
    return [path for path in candidates if path.exists()]


def parse_frontmatter(text):
    if not text.startswith("---"):
        return {}

    end = text.find("\n---", 3)
    if end == -1:
        return {}

    data = {}
    for line in text[3:end].strip().splitlines():
        if ":" not in line:
            continue
        key, value = line.split(":", 1)
        data[key.strip()] = value.strip().strip('"')
    return data


def main():
    roots = find_skill_roots()
    if not roots:
        print("No skill roots found.")
        print("Run: npx skills@latest add mattpocock/skills")
        return

    for root in roots:
        print(f"\nSkill root: {root}")
        for skill_file in sorted(root.glob("*/SKILL.md")):
            meta = parse_frontmatter(skill_file.read_text(encoding="utf-8"))
            name = meta.get("name", skill_file.parent.name)
            description = meta.get("description", "no description")
            print(f"- {name}: {description[:120]}")


if __name__ == "__main__":
    main()

把它保存为 check_skills.py，在项目根目录运行：

python .\check_skills.py

如果能看到 tdd、diagnose、grill-with-docs 等条目，就说明安装路径基本没问题。

Step 3：第一次实战：让 Agent 用 TDD 加一个小功能

假设我们有一个 Python 项目，要加一个订单金额格式化函数。不要直接说“帮我写函数”。更好的提示是：

Use the tdd skill. Add a public function format_order_total(amount_cents: int, currency: str) -> str.
Behavior:
1. 1234 and "USD" returns "$12.34"
2. 500 and "CNY" returns "¥5.00"
3. Negative amount raises ValueError
Please confirm the public interface and test behaviors before editing code.

这段提示的重点有三个：

第一，我们明确要求使用 tdd。虽然 Skills 可以由模型自动触发，但第一次练习时显式点名更稳。

第二，我们说的是公开接口和行为，而不是内部怎么实现。

第三，我们要求它先确认接口和测试行为。这样 Agent 不会一上来就改一堆文件。

一个理想流程是：

1. Agent 确认 format_order_total 的输入、输出和异常规则。
2. Agent 写第一个失败测试，例如 USD 分支。
3. Agent 写最少实现让测试通过。
4. Agent 加 CNY 测试，再补实现。
5. Agent 加负数测试，再补异常。
6. 所有测试通过后，再做小范围重构。

如果它试图一次性写完全部实现，你可以直接拉回来：

Stay in the tdd loop. Write one failing test first, then the minimal implementation for that test only.

Step 4：第二次实战：用 diagnose 修一个偶发 bug

现在换一个更真实的场景：你线上发现“保存草稿偶尔丢字段”，但本地不稳定复现。

不要让 Agent 直接猜原因。可以这样说：

Use the diagnose skill.
Bug: saving a draft sometimes drops the tags field.
Goal: build a repeatable feedback loop first.
Try a failing test, a CLI fixture, or a replayed payload before proposing a fix.
Do not edit production code until the bug is reproduced.

diagnose 的价值就在这里：它会先想办法提高复现率，再列假设，再用日志、断点、fixture 或测试去验证。它不是不修，而是先把“修对”的概率提高。

这也呼应了近期关于 coding agent 测试行为的研究。2026 年一篇关于 Agent 生成测试的论文指出，Agent 写测试这件事本身并不必然提高最终修复率；很多测试更像观察反馈，而不是真正的断言验证[7]。所以我们的重点不是“让 Agent 多写测试”，而是让它建立有效反馈：能复现、能区分假设、能确认修复。

进阶使用示例：写一个自己的团队 Skill

用别人的 Skills 是第一步，更重要的是把团队自己的流程沉淀下来。比如你们每次发版都要写 release notes，要求包含用户影响、迁移说明、测试结果和回滚方案。我们可以写一个小 Skill。

下面这个 Python 脚本会在当前项目里创建 .claude/skills/release-notes-helper/SKILL.md：

from pathlib import Path


skill_dir = Path.cwd() / ".claude" / "skills" / "release-notes-helper"
skill_dir.mkdir(parents=True, exist_ok=True)

skill_text = """---
name: release-notes-helper
description: Draft release notes from git diff, changelog entries, and test results. Use when preparing a release, writing changelogs, or summarizing shipped changes.
---

# Release Notes Helper

## Instructions

1. Read the relevant git diff and recent changelog entries.
2. Group changes by user-visible impact.
3. Call out migration steps, risks, and rollback notes.
4. Include verification commands that were actually run.
5. Do not claim tests passed unless command output confirms it.

## Output Format

- Summary
- User-visible changes
- Migration notes
- Verification
- Rollback plan
"""

(skill_dir / "SKILL.md").write_text(skill_text, encoding="utf-8")
print(f"Created {skill_dir / 'SKILL.md'}")

运行：

python .\create_release_notes_skill.py

然后你可以对 Agent 说：

Use release-notes-helper. Draft release notes for the current branch using the staged diff and the test output in this chat.

这就是 Skills 的真正用法：不是把所有知识塞进一个超长 Prompt，而是把可复用流程拆成小文件，按需加载。

原理简析：为什么一个 Markdown 文件能改变 Agent 行为？

Agent Skills 的原理并不神秘。你可以把它拆成三层。

![原理架构图](image_placeholder: 三层架构图，第一层 metadata name/description，第二层 SKILL.md instructions，第三层 scripts/references/templates，箭头表示按需加载)

第一层是 metadata。SKILL.md 顶部有 YAML frontmatter，通常包含 name 和 description。模型启动或扫描技能时，先看到这些轻量信息，用它判断“什么时候该用这个 Skill”[3]。

第二层是完整说明。当用户任务命中某个 Skill，Agent 才读取完整 SKILL.md。这里会写具体工作流、检查清单、禁止事项、输出格式等。比如 tdd 会告诉 Agent：测试公共行为，不要测私有实现；一次只写一个测试；红灯时不要重构。

第三层是附加资源。复杂 Skill 可以带 scripts/、references/、templates/。官方博客把这种方式称为 progressive disclosure：Agent 不需要一次性把所有资料塞进上下文，只有任务需要时才继续打开更细的文件[4]。

这个设计对 AI 编程特别重要。真实代码仓库已经很大，如果我们再把几十页流程说明全部塞给模型，只会挤占上下文。Skills 的好处是：平时只暴露很短的描述，真正用到时才展开。

它和 MCP、工具调用也不是一回事。MCP 更像“给 Agent 接上外部工具和数据源”，Skills 更像“教 Agent 什么时候、按什么流程使用能力”。一个项目完全可以同时用 MCP 和 Skills：MCP 提供能力，Skills 规定做事方法。

使用建议：别把它当魔法

mattpocock/skills 很有用，但它不是“装上就自动变强”的插件。我们建议按下面方式落地：

第一，先从 2-3 个高频技能开始。最推荐 /grill-with-docs、/tdd、/diagnose。这三个覆盖了需求、开发、调试三个最容易翻车的环节。

第二，给项目补 CONTEXT.md。AI 助手最怕术语不一致。把核心业务词、边界、反例写下来，grill-with-docs 和架构类技能才有材料可用。

第三，不要让 Agent 跳过验证。无论它说得多像已经修好，都要让它跑测试、贴命令结果，或者说明为什么没法验证。

第四，定期把团队习惯写成自己的 Skill。比如发版说明、数据库迁移规范、PR 检查清单、客服工单分析流程，都可以沉淀下来。

第五，注意安全。官方文档也提醒，只使用可信来源的 Skills，因为 Skill 可能附带脚本或引导 Agent 执行命令[3]。第三方 Skill 装进项目前，至少看一遍 SKILL.md 和脚本目录。

总结与展望

mattpocock/skills 之所以值得关注，不是因为它用了多复杂的技术，而是因为它把 AI 编程拉回了工程基本功：问清楚、写测试、先复现、再修复、记录决策、控制复杂度。

它最适合三类人：

• 已经在用 Claude Code、Codex、Cursor 做真实项目的开发者。
• 想把 AI 编程从“试试看”推进到团队流程的人。
• 经常被 Agent 跑偏、啰嗦、乱改、难验证折磨的人。

未来这类项目大概率会继续变热。模型能力越强，越需要流程约束；Agent 越能自主改项目，越需要可复用的团队知识。mattpocock/skills 给我们的启发是：真正有价值的 AI 工具，不一定是再造一个复杂平台，也可能只是把工程师每天做对的事，写成 Agent 能稳定执行的步骤。

如果你只准备今天做一件事，我们建议：先装 mattpocock/skills，然后在自己的项目里用 /tdd 跑完一个小功能。只要你看到 Agent 被限制在“一个测试、一个行为、一次实现”的节奏里，就能理解这个项目为什么会突然爆火。

参考资料

[1] GitHub Trending weekly，2026-04-29 访问：https://github.com/trending?since=weekly
[2] mattpocock/skills GitHub README：https://github.com/mattpocock/skills
[3] Anthropic Claude Code Agent Skills 文档：https://docs.claude.com/en/docs/claude-code/skills
[4] Anthropic Engineering Blog，Equipping agents for the real world with Agent Skills：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
[5] Yang et al., SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering, arXiv:2405.15793：https://arxiv.org/abs/2405.15793
[6] Baumann et al., SWE-chat: Coding Agent Interactions From Real Users in the Wild, arXiv:2604.20779：https://arxiv.org/abs/2604.20779
[7] Chen et al., Rethinking the Value of Agent-Generated Tests for LLM-Based Software Engineering Agents, arXiv:2602.07900：https://arxiv.org/abs/2602.07900