Agent Skills 实战第一课：别急着让 AI 写代码，先把安装和项目初始化做对

先说几个核心判断。很多团队引入一套 Agent Skills 时，最容易跳过的恰恰是第一步。

大家看到 /grill-with-docs、/to-spec、/tdd，很自然地想马上拿需求试一遍。结果跑到一半，Agent 开始反问：工单建在哪里？项目用什么标签？领域文档去哪找？

这不是后面的 skill 不好用，而是前面的安装和初始化没有做完。

这一课不谈怎么写需求，也不谈怎么生成代码。我们只解决两个基础问题：

先分清两个动作：安装和初始化不是一回事

安装，是让 Claude Code、Codex 或其他兼容 Agent 能找到这些 skill。安装成功后，你能在对话中调用 /setup-matt-pocock-skills。

初始化，是让这套 skill 认识当前项目。它会把 issue tracker、triage 标签和领域文档位置写成项目级配置，供后续 /triage、/to-spec、/to-tickets、/qa 等 skill 读取。

不妨把这两层关系理清楚：

 复制代码安装一次：让 Agent 拥有这套能力
每个项目初始化一次：让这套能力理解当前仓库

只安装不初始化，Agent 虽然“会干活”，却不知道团队的活应该按什么规矩干。

安装前，先准备好这三样东西

第一，机器上要有 Node.js 和 npm，因为通用安装方式会通过 npx 启动。可以先在终端检查：

 复制代码node --version
npm --version

第二，进入你真正准备使用这套 skill 的项目根目录。不要在下载目录里随便跑一次就算完成，因为后面的初始化需要读取当前仓库的 Git 远端、项目文档和目录结构。

 复制代码cd /path/to/your-project

第三，最好让项目已经是一个 Git 仓库，并配置好远端。没有远端也能使用本地 Markdown tracker，但如果团队本来就在 GitHub 或 GitLab 上协作，远端地址能帮助 setup 给出更准确的推荐。

安装方式一：通过 skills.sh 安装，适合 Codex 和多数 Agent

在项目根目录的

里执行：

 复制代码npx skills@latest add mattpocock/skills

安装器会让你选择要安装的 skill，以及要安装到哪个 Coding Agent。这里至少要勾选：

 复制代码setup-matt-pocock-skills

如果后面要完整读完这套学习套装，可以一起选择 grill-with-docs、to-spec、to-tickets、implement、tdd 和 code-review。使用 Codex 或其他支持 Agent Skills 标准的工具时，优先走这一条安装路径。

这条路径的特点是直接把选中的 skill 安装到目标 Agent 可读取的位置，适合想查看和按团队需要调整 skill 内容的人。

安装结束后，重新打开或刷新 Agent 会话。接下来要执行的 /setup-matt-pocock-skills 是发给 Agent 的指令，

。

安装方式二：作为 Claude Code 插件安装

如果团队统一走 Claude Code 路线，也可以把整套 skill 作为托管插件安装。在 Claude Code 的命令输入框中依次执行：

 复制代码/plugin marketplace add mattpocock/skills
/plugin install mattpocock-skills@mattpocock

也可以在终端使用 Claude CLI：

 复制代码claude plugin marketplace add mattpocock/skills
claude plugin install mattpocock-skills@mattpocock

插件方式更像订阅：技能包由插件管理，发布新版本后可以统一更新。skills.sh 方式更适合需要把 skill 落到本地、自己维护和修改的团队。两种方式任选其一，不需要重复安装。

真正的初始化，从这条命令开始

确认 Agent 已经进入目标项目后，在

输入：

 复制代码/setup-matt-pocock-skills

这个 skill 不是固定模板生成器。它会先读仓库，再根据实际情况向你确认。它通常会检查：

• git remote -v 和 .git/config，判断仓库来自 GitHub、GitLab，还是没有远端；
• 根目录的 CLAUDE.md、AGENTS.md，确认项目已经使用哪份 Agent 说明；
• CONTEXT.md、CONTEXT-MAP.md 和 docs/adr/，判断领域文档是否已经存在；
• docs/agents/ 和 .scratch/，判断是否初始化过或采用本地工单；
• 是否安装了 triage skill；
• pnpm-workspace.yaml、package.json 的 workspaces、packages/* 等 monorepo 信号。

所以，第一次看到 Agent 花时间扫描仓库，不要急着打断。它正在避免用一套默认答案覆盖项目已经存在的规则。

初始化时，你需要确认三个决定

1. Issue tracker 放在哪里

Agent 会根据 Git 远端先给出建议。GitHub 仓库通常建议 GitHub Issues，GitLab 仓库通常建议 GitLab Issues。没有远端的个人项目，可以选择把工单写到 .scratch// 下的 Markdown 文件。

Jira、Linear 或公司内部平台也可以使用，但需要用一段话讲清楚创建、读取、更新工单的方式。最终约定会写入：

 复制代码docs/agents/issue-tracker.md

这份文件会直接影响 /to-spec 和 /to-tickets 把产物发到哪里，也会影响 /triage、/qa 如何找到待处理工作。

2. Triage 标签叫什么

只有安装了 triage skill，setup 才会问这一项。默认的五个角色标签是：

 复制代码needs-triage
needs-info
ready-for-agent
ready-for-human
wontfix

如果团队已经有 status:triage、ai-ready 之类的标签，不要为了迁就 skill 再造一套。把现有标签映射给它即可。映射结果会写入：

 复制代码docs/agents/triage-labels.md

这一步解决的不是“标签长什么样”，而是让所有 skill 对工单状态说同一种语言。

3. 领域文档放在哪里

普通项目默认使用单上下文：根目录一份 CONTEXT.md，架构决策放在 docs/adr/。这已经能覆盖大多数仓库。

只有检测到大型 monorepo 信号时，setup 才会建议多上下文：用根目录的 CONTEXT-MAP.md 指向各业务域自己的 CONTEXT.md。最终的读取和写入规则会放在：

 复制代码docs/agents/domain.md

后面的 /grill-with-docs 会根据这里的规则读取术语、补充上下文，并把重要技术决定写回正确位置。

写入前别急着点头，先看草稿

三个决定确认后，setup 会先展示准备写入的内容，包括 docs/agents/*.md 和一段 ## Agent skills 配置。这一步建议项目负责人认真看一遍，尤其检查 tracker 地址、标签拼写和文档路径。

确认后，它会按以下规则写入：项目已有 CLAUDE.md，就更新 CLAUDE.md；没有 CLAUDE.md 但有 AGENTS.md，就更新 AGENTS.md；两者都没有时，它应该询问你要创建哪一个，不会擅自替团队决定。

一个启用了 triage 的普通项目，初始化后大致会得到：

 复制代码your-project/
├── CLAUDE.md 或 AGENTS.md
└── docs/
    └── agents/
        ├── issue-tracker.md
        ├── triage-labels.md
        └── domain.md

没有安装 triage 时，不生成 triage-labels.md，说明流程判断正确，不是漏文件。

一段真实的操作思路

假设项目远端是 GitHub，团队使用默认标签，仓库也不是大型 monorepo。一次典型对话会接近这样：

 复制代码你：/setup-matt-pocock-skillsAgent：检测到 GitHub 远端，建议使用 GitHub Issues，是否确认？
你：确认。Agent：检测到已安装 triage，建议保留默认的五个标签，是否确认？
你：确认。Agent：当前项目适合 single-context，将使用根目录 CONTEXT.md 和 docs/adr/。
      下面是准备写入的配置草稿……
你：路径没问题，写入。

如果 Agent 一上来不扫描仓库、不给草稿、直接覆盖文件，这次初始化就不合格。这个 skill 的关键不是多问几句，而是“先发现现状，再确认决定，最后写入”。

怎么判断这一课真的完成了

不要用“命令没报错”作为验收标准。至少检查下面五件事：

1. 在 Agent 对话中可以调用 /setup-matt-pocock-skills；
2. docs/agents/issue-tracker.md 指向团队真正使用的工单系统；
3. 安装了 triage 时，triage-labels.md 中的字符串与 tracker 里的真实标签一致；
4. domain.md 写清了 CONTEXT.md、ADR 或多上下文文档的读取规则；
5. CLAUDE.md 或 AGENTS.md 中只有一段 ## Agent skills，并正确引用上述文件。

最后做一个小型冒烟验证：让 Agent 说明“如果现在运行 /to-tickets，工单会写到哪里；如果遇到领域术语，它会先读哪份文件”。它能从配置中给出准确答案，才算初始化真正生效。

常见问题，提前避开

因为它不是 shell 命令，要在 Agent 对话框里运行。

先确认安装时是否勾选了 setup-matt-pocock-skills 和当前使用的 Agent；然后重开会话，让 Agent 重新加载 skill。

不影响初始化。个人项目可以选本地 Markdown，企业项目可以描述 Jira、Linear 或内部系统的工作流。

按 skill 的规则，优先更新已有的 CLAUDE.md，不要再复制一份相同配置，避免两个入口以后互相冲突。

会。团队更换 tracker、调整标签或拆分领域边界时，直接修改 docs/agents/*.md 即可；只有切换整个工作方式或想重新探测仓库时，才需要再次运行 setup。

第一课真正交付的，不是“装好了”

这节课结束时，每个人应该交付的是一套能被团队读懂、也能被后续 skill 读取的项目约定。

安装让命令出现，初始化让命令不再猜。等 issue tracker、标签和领域文档都对齐之后，第二课的 /grill-with-docs 才有可靠的上下文去追问真实需求。