Skills For Real Engineers 系列之一：先配好项目，再让 ask-matt 帮我选技能

前言

接上篇文章，我说如果有兴趣聊这个SKill的话 Skills For Real Engineers，我会考虑另外开一篇讲解。

额，反馈结果有点超乎预期，谢谢大家厚爱了，作为一个AI菜鸡接线员，我也只能把自己用过的给大家分享一下。

这篇就拿我自己的开源项目 RxStudy 来聊，大家可以直接对照配置和源码阅读。

RxStudy 是基于 WanAndroid API 的 iOS 学习项目，包含 UIKit／RxSwift 与独立 SwiftUI 两种实现，也保留了日志、组件化和构建方式方面的实践。

聊到给 AI 编程助手装技能，我们经常会先看它能做什么：分析需求、排查问题、拆任务、写测试......看着都挺实用，先装上再说。

但是！技能装好了，回到项目里，还是有两个问题：

它怎么知道这个项目在哪里管理任务，文档应该放在哪里？
我现在遇到的事情，到底应该用哪个技能？

尤其是同时维护几个项目时，一个项目用 GitLab，另一个可能只想在本地记录任务。总不能每次开新对话，都重新解释一遍。

所以，这个系列的第一篇，我想先聊两个入口：setup-matt-pocock-skills 和 ask-matt。前者把项目约定配置好，后者帮我们找到合适的技能和流程。

1. 上下文已经很长了，为什么还需要这些技能？

模型的上下文越来越长，我也会想：以前放不下，现在代码和聊天都能读这么多了，还需要 Skill 吗？

我觉得可以分两种情况看：上下文紧张时，怎样少丢信息；上下文充足时，怎样把开发推进得更好。它们不是两个互相替代的年代，同一个项目里也可能同时遇到。

1.1 上下文更紧张时，先减少信息丢失

上下文容量受限时，长任务往往更依赖摘要和交接。换个会话，或者压缩历史内容后，需求可能还在，限制和决定的理由却遗漏了，实现也可能跟着走偏。

拿日志改造做个假设：我们聊的是"保留旧实现，新日志独立接入，可以切回旧体系"。摘要如果只留下"升级日志系统"，接手的人就可能直接替换旧实现。看起来还在完成任务，做的却不是原先商量的事情。

这时，这套技能有用的一点，是让重要信息有地方保存、可以重新读取：项目配置说明协作约定，GLOSSARY.md 统一术语，ADR 记录重要取舍，规格和任务保存交付要求与验收条件。

这些记录由不同流程逐步形成，不是初始化一次就全部生成。后续会话按入口读取，能减少只靠聊天摘要接续的负担；前提是记录准确、及时更新，也确实被读取。

1.2 上下文更充足时，让开发更有章法

现在能放下更多内容，许多讨论可以在同一会话继续，不必急着压缩。但读得到更多材料，还需要分清材料的性质。

聊天里既有事实，也有猜测；既有确认的决定，也有讨论过但否定的方案。代码能回答"现在怎么做"，却未必说明"这次希望改成什么"。

比如 RxStudy 的日志改造，即使旧代码和讨论都在眼前，"保留旧实现"究竟包含哪些行为、怎么回退、验证到什么程度，仍然需要说清楚。

技能在这里提供的是做事的方法：先追问目标与取舍，再整理规格和可验收任务；遇到异常进入诊断，完成实现后检查证据，按当前进度选择下一步。这样就有了判断"该继续写，还是先讨论、先验证"的依据。

我也更容易检查它有没有理解错：这次改动对应哪个需求，完成的依据是什么，哪些问题还没有验证。

所以我觉得，上下文紧张时，技能帮助我们少丢信息；上下文充足时，技能帮助我们更好地使用信息、推进开发。

1.3 长任务仍然要考虑怎么接续

更大的上下文仍有边界。ask-matt 在阶段边界给出一套选择思路：

下一阶段需要原始讨论，空间也够，就继续当前会话。
旧内容与下一项工作无关，可以清空。
换工具、目录或交给别人时，用 handoff 交接。
范围明确、可独立完成的工作，可以交给子代理。
仍需相关内容又要腾出空间时，再在阶段边界压缩。

具体会话能力取决于所用助手。阶段边界说明

Skill 不会扩大模型窗口，也不能保证开发永不偏移。它的价值，是把约定、决定和验证组织起来，让每一步有依据可查。

2. 先把技能装进来

这里采用官方 README 提供的可编辑文件安装方式。在目标项目目录打开终端，执行：

sql 复制代码

npx skills@latest add mattpocock/skills

省流版本：不会，找个AI帮你安装。不知道选啥Skill？都安装就是了。

安装完成后，查看助手的技能列表，确认能找到这两个名字。如果当前会话还没识别到，按所用助手的机制刷新或重新打开会话。

不同助手的入口可能是斜杠命令、技能选择器，或者显式指定技能。本文统一用 /技能名 展示，实际以你的工具为准。

这里还有一个容易混在一起的概念：安装让助手能够使用技能，仓库配置让技能知道这个项目的协作约定。

下面才进入第二步。

3. setup-matt-pocock-skills：给项目做一次 AI 协作初始化

如果用程序员熟悉的方式来理解，我觉得它有点像 git init。

新项目用 git init 建立版本管理的基础；这套工程技能第一次进入仓库，也需要先建立项目级的协作约定。

熟悉的操作	技能体系中的对应意义
安装 Git	安装技能，让工具可用
初始化仓库	配置当前项目的任务系统、标签与文档布局
日常提交和协作	后续技能按照项目约定开展工作

有了这个类比，就比较容易理解"为什么装完还要配置"：安装解决工具有没有，初始化解决当前项目如何使用。

不过，类比到这里就够了。这个技能通过探索和确认写入文档，不会执行 Git 初始化，也不会修改模型或让它自动获得永久记忆。已有项目同样可以补上这些协作约定，不需要新建仓库。

先进入准备工作的仓库，再调用：

arduino 复制代码

/setup-matt-pocock-skills

它是一套由提示词驱动的配置流程。按照技能说明，它会先探索仓库，再展示发现、确认选择、提供草稿，最后写入配置。

探索内容包括远程仓库、已有的 AGENTS.md 或 CLAUDE.md、领域文档，以及之前是否已经配置过这些技能。

项目已有的信息先读，需要我决定的事情再问。

3.1 任务到底放在哪里？

省流版本：一开始不太会，选择本地 Markdown。

这里的 Issue Tracker，可以理解为任务和规格的存放位置。后续技能需要根据它决定如何读取、发布任务。

选择	使用场景
GitHub Issues	项目已经在 GitHub 管理任务，使用 `gh` CLI
GitLab Issues	项目在 GitLab 管理任务，使用 `glab` CLI
本地 Markdown	个人项目，或者暂时不接外部任务系统
其他系统	描述现有流程，由技能记录项目约定

这里先区分一下"本地"和"远端"。本地任务是 Markdown 文件 ，例如 .scratch/logging/issues/01-export.md。只要没有被 .gitignore 忽略，就可以提交、推送到 GitHub，让其他人通过 Git 拉取。但它仍然是仓库文件，不会自动变成 Issue。

远端任务则是 GitHub Issues 页面里的记录 ，通过网页或 gh 管理。创建后直接保存在 GitHub，无需 git push；执行 git pull 也不会把 Issue 下载成 Markdown。

所以，"本地"不等于不能共享；区别是用仓库文件还是任务系统管理。任务跟踪方式也不是由 Git remote 自动决定的，需要按项目实际情况选择。

RxStudy 的 docs/agents/任务与规格管理.md 已明确配置 GitHub Issues，下面是原文节选：

bash 复制代码

# 任务跟踪：GitHub

本仓库的任务与规格存放于 seasonZhu/RxStudy 的 GitHub Issues。
使用 gh CLI 操作，显式指定 --repo seasonZhu/RxStudy。

完整文件还约定了读取、评论、标签和任务依赖的处理方式，可以查看任务与规格管理。初始化技能保存约定，后续技能据此操作；CLI 安装、认证和项目权限仍需具备。

纸上得来终觉浅，我们看一组 gh 示例。以下为演示，写作时没有执行登录或创建任务。创建命令会向真实的 RxStudy 仓库发布 Issue，请在自己的仓库练习，并替换 --repo：

css 复制代码

# 安装 gh 后，登录 GitHub
gh auth login --hostname github.com

# 在当前目录准备演示任务正文
cat > issue-body.md <<'EOF'
## 目标
明确日志导出的失败反馈。

## 验收条件
无日志可导出时，调用方能够收到明确错误。
EOF

# 发布任务；--repo 指定目标仓库
gh issue create --repo seasonZhu/RxStudy \
  --title "演示：梳理日志导出失败反馈" \
  --body-file issue-body.md

# 将 42 替换为实际任务编号，再读取正文与评论
gh issue view 42 --repo seasonZhu/RxStudy \
  --json number,title,body,labels,comments

这里用 --body-file 传入多行正文，也符合项目配置。Git 能推送代码，不代表 gh 已经完成 API 认证。创建任务参数、读取任务参数

如果项目使用 GitLab，对应工具是 glab，例如 glab auth login --hostname gitlab.example.com 和 glab issue create -R <项目地址>。任务保存在 GitLab Issues，同样不通过 Git 推送。GitLab CLI 说明

3.2 分流标签不是每个项目都要配置

RxStudy 的 docs/agents/分诊标签.md 配置了五个默认角色与 GitHub 标签的映射：

标签	含义
`needs-triage`	等待评估
`needs-info`	等待补充信息
`ready-for-agent`	信息充分，可交给代理处理
`ready-for-human`	需要人工处理
`wontfix`	不予处理

这张映射表可在分诊标签文件中核对；它说明项目采用的名称，不表示本文逐一查询了远端标签状态。

这里有一个条件：只有安装了 triage，初始化流程才会进入标签配置环节。 没装就跳过，不会要求每个项目都补齐这一套。

备注：triage是啥流程，我自己目前还没有摸清楚，有会的老铁请指导。

如果项目已有自己的标签名称，也可以映射到对应角色。对于 GitHub 或 GitLab，技能还会创建缺失的已配置标签，因此确认草稿时，也要看清这部分改动。

3.3 文档放在哪里，之后又该怎么读？

RxStudy 的领域文档约定采用单一上下文布局：

复制代码

RxStudy 仓库根目录/
├── AGENTS.md
├── GLOSSARY.md
└── docs/
    ├── agents/
    │   ├── 任务与规格管理.md
    │   ├── 分诊标签.md
    │   └── 领域文档约定.md
    └── adr/

这是约定布局，图里不代表所有文件都已生成。

GLOSSARY.md 记录领域术语；docs/adr/ 保存架构决策记录，也就是 ADR；docs/agents/领域文档约定.md 则说明它们在哪里，以及助手何时阅读、如何使用。

比如现有配置要求：探索代码前阅读已有术语表和相关 ADR；任务、方案和测试名称使用项目术语；新方案与已有决策冲突时，明确指出冲突。

配置文档位置，不等于已经梳理完业务术语和架构决策。 这些内容要随着后续讨论逐步建立。

大多数仓库采用这个布局即可。技能发现大型多包仓库的信号时，才会进一步确认是否采用多个上下文的文档布局。

3.4 查看草稿，再确认写入

省流版本：一般会有一个全局的AGENTS.md，然后每个项目也可以有一个自己的AGENTS.md，其实就是说明书，如果你使用Claude Code，名称略有不同（叫作CLAUDE.md）

项目规则文件承担入口作用。RxStudy 已有的 AGENTS.md 内容如下：

markdown 复制代码

## Agent skills

### Issue tracker

任务与规格使用 GitHub Issues（seasonZhu/RxStudy）管理。详见 `docs/agents/任务与规格管理.md`。

### Triage labels

使用五个默认分诊标签。详见 `docs/agents/分诊标签.md`。

### Domain docs

采用单上下文布局：根目录 `GLOSSARY.md` 与 `docs/adr/`。详见 `docs/agents/领域文档约定.md`。

可以直接查看仓库中的 AGENTS.md。这里展示的是已存在的配置，不据此推断当时具体如何调用初始化技能。上游模板默认使用英文文件名，RxStudy 已采用中文名称并同步修改入口引用，阅读时以项目配置为准。

至于写进哪个文件，当前技能有明确顺序：已有 CLAUDE.md 就编辑它，否则编辑已有的 AGENTS.md；两者都没有，再询问创建哪个。

已有 Agent skills 区块时就原地更新，其他项目规则继续保留。确认前，重点检查任务系统、文档位置和标签是否符合现有习惯。

初始化完成后，日常可以直接维护 docs/agents/*.md，不必每次开会话都重新配置。初始化技能说明

4. ask-matt：整个技能体系的"路由器"

项目约定有了，接下来面对一长串技能名，还是可能不知道选哪个。

做客户端开发时，我们习惯把一个页面地址交给路由，由路由找到对应入口。ask-matt 也可以这样理解：我们描述当前处境，它推荐合适的技能，或者由多个技能组成的流程。

区别在于，它要理解问题所处的阶段：需求还没明确？已经有可复现的异常？还是目标清楚、需要分批交付？同样一句"帮我优化"，背后的入口可能完全不同。

我不需要先背下所有技能名，但需要说清楚目标、证据、限制和当前进度。它还要求，在解释技能行为或建议跳过步骤之前，先阅读对应的 SKILL.md。导航介绍帮助定位，实际规则以技能说明为准。

下面用 RxStudy 的三个场景说明。项目背景有真实文档和代码支撑，提示词与技能推荐则是为文章提炼的示例，不是原始 ask-matt 调用记录。 推荐方向取决于上下文、已安装技能和版本。

4.1 日志系统想升级，旧实现要不要直接替换？

RxStudy 已有新旧日志体系：默认使用 .legacy，也可以在编译前选择 .modern；每次启动只启用一套，新日志提供独立导出接口。

看最终代码容易觉得"加个开关就行"，但设计前需要回答：旧日志保留到什么程度？控制台、文件和系统日志各输出什么？切回旧实现怎么做？

根据这个场景，可以这样提问：

bash 复制代码

/ask-matt

我想改进 RxStudy 的日志输出和导出能力。
希望保留旧实现，并能在需要时切回旧体系。
请先阅读现有代码，选择澄清方案的流程。
先明确输出、切换、回退和验证边界，不要直接写代码。

在有工作目录、又需要明确方案时，适合从 grill-with-docs 开始：先了解现有实现，再追问需要我们决定的行为，并结合领域建模记录术语和决策。

下一步是把"改进日志"变成具体行为，例如编译时切换还是运行时切换、导出失败如何反馈。否则"能回退"这三个字，双方可能理解得完全不同。

最终设计可以对照新旧日志体系说明和配置入口阅读。文档分别记录了定点检查、构建限制和待设备验证事项，不能把局部检查当作整工程与真机验证完成。技能说明

4.2 缺少 RxStudyKeys.h，是不是应该先清缓存？

项目排错指南记录过一条实际错误：CocoaPods 工作区编译时，Keys-framework 在复制头文件阶段报 RxStudyKeys.h 不存在。

如果只丢一句"编译失败了"，很容易得到清缓存、重装依赖等建议。更有价值的提问，是把失败阶段与实际错误带上：

yaml 复制代码

/ask-matt

RxStudy 的 CocoaPods 工作区编译失败。
Keys-framework 复制头文件时报错：
Pods/CocoaPodsKeys/RxStudyKeys.h: No such file or directory
请推荐诊断流程，先确认生成链路和最小验证方式。
不要直接改业务代码或删除全局缓存。

这类有具体异常的问题，适合进入 diagnosing-bugs：先建立能捕获该错误的反馈循环，再推进复现、缩小范围和验证假设。

下一步应确认文件是否存在、由哪个工具生成、哪条检查能复现缺失。指南中的排查结果是：.h/.m 为 cocoapods-keys 的生成文件，并被 Git 忽略；本机插件提供独立生成命令，可以定点补齐。

ini 复制代码

# 历史修复命令：在已具备正确插件及本机配置的项目中执行
pod keys generate RxStudy --keys=TEST_KEY

TEST_KEY 是键名，不是密钥值。这个结果不能解释文件最初为何消失，也不意味着所有构建错误都适用同一修复。

排错指南第 8 节记录了生成文件恢复、Keys-framework 编译通过，以及验证范围。它不等于两个 App 整工程和设备运行都已通过；本次写作也没有重跑修复或构建。技能说明

4.3 CocoaPods 与 Tuist 两套构建方式，怎么拆任务？

RxStudy 的文档提供了 develop-pods 和 develop-tuist 两条构建分支，保留一致的业务源码相对路径与双 Target 结构，还提供构建方式切换脚本。

这里涉及依赖安装、SwiftGen 资源生成、工程准备和验证。若跨几个会话推进，每次只说"继续迁移"，接手时就得重新确定完成到哪一步。

根据这个场景，可以这样提问，其中"已确认"是进入规格阶段的前提：

bash 复制代码

/ask-matt

我想分多个会话整理 RxStudy 的 CocoaPods／Tuist 双构建流程。
假设目标、分支约定与验收要求已在当前讨论中确认。
请推荐保存规格、拆分任务和安排依赖关系的流程。
覆盖资源生成、工程准备和双 Target 验证；缺信息先指出。

目标清楚后，典型方向是：

css 复制代码

已确认的讨论 → to-spec → to-tickets → 按依赖推进实现

to-spec 综合已有讨论形成规格；to-tickets 拆分可验证任务，记录阻塞关系，并在确认拆分后发布。它们会按项目配置操作 GitHub Issues，因此发布前要确认范围和目标仓库。

下一步是让每个任务带上交付物与验收条件，例如某一构建方式可以从资源生成走到工程准备，并明确后续验证依赖什么，而不是只按文件数量分组。

读者可以对照构建方式切换速查理解最终流程。文档明确：切换脚本准备构建环境，不同步业务提交。这个边界很适合写进规格，避免后续会话把"切换成功"理解成"业务同步完成"。规格说明、任务拆分说明

这三个例子分别对应：先想清楚、先查明白、把已明确的工作组织起来。ask-matt 根据处境帮助选路，后续技能负责各自阶段的工作，并不意味着提问一次就会自动跑完整条流程。

4.4 不知道下一步怎么说？让 AI 帮你整理

前面几段示例比较完整，但平时讨论，不一定要一上来就写这么多。我在另一个项目里，实际用过这样的问法。下面两条来自不同对话，调用入口统一写成斜杠形式，提问原话保留：

bash 复制代码

/ask-matt 下一步我们做什么？

还有一次是：

bash 复制代码

/ask-matt 这些迁移完成之后，下一步我们做什么？

当时助手先检查项目进度、迁移收口记录与验收材料，建议补运行／真机验收，发现具体问题再进入诊断流程，没有直接建议继续拆代码。这里说的是当时的处理，不代表项目现在仍停在这个阶段。

有上下文和项目记录可读，一句"下一步做什么"也能成为讨论入口。如果准备换个对话继续，还可以让它帮忙整理下一步的提示词。

我在项目里会这样让 AI 帮我写下一步怎么说。下面是按这种使用习惯整理的例子，不是历史对话原文：

复制代码

好，那下一步我该怎么跟你说？
你把刚才聊清楚的事情整理成一段提示词，
我准备开个新对话接着做。

带上现在做到哪了、下一步做什么、先看哪些文件，
还有哪些地方先别动。
没验证的也写清楚，别当成已经做完了。
如果该换个技能，就告诉我用哪个。

这个技巧省下的，是重新组织背景的功夫。知道上下文的助手，可以把进度、资料入口、目标和限制串起来；我再检查有没有理解错、漏掉约束，或者擅自扩大范围。

不过，两件事要分清：ask-matt 帮我们选流程；整理提示词是通用的协作技巧，不是它独有的能力。好用的提示词也不用什么"AI 才懂"的特殊措辞，把事情说清楚就行。

复制到新会话后，仍应要求重新核对代码、分支和验证状态。提示词是交接信息，不能完整恢复所有历史，也不能把上一轮的建议自动变成执行授权。

5. 把两个入口串起来

回到 RxStudy，一次完整的入口使用顺序是：

arduino 复制代码

确认技能可用
    ↓
在当前仓库运行 setup-matt-pocock-skills
    ↓
检查并确认项目配置
    ↓
向 ask-matt 描述当前问题
    ↓
进入推荐技能，推进具体任务

前面的配置来自公开仓库，下面的任务描述仍是演示。

第一次配置后，检查入口文件是否重复、任务系统是否正确，以及标签配置是否需要。

有了配置，再描述任务时就可以更聚焦：

bash 复制代码

/ask-matt

请先阅读当前项目的技能配置。
我想梳理 RxStudy 日志导出的失败反馈，还没有确定验收条件。
请推荐下一步流程，先不要修改业务代码。

信息	保存在哪里
任务系统、操作约定	仓库配置
术语与决策文档的位置、阅读规则	仓库配置
本次要解决什么问题、有什么证据	当前任务描述
本次允许修改什么、怎样算完成	当前任务描述与后续澄清

这个思路之所以有用，根本原因在于：相对稳定的项目约定有了固定位置，每次对话就能集中讨论当前问题。

换到另一个仓库，仍然应该按那个项目的实际情况配置。技能可以共用，任务系统和文档约定要分别核对。

6. 最后聊两句

其实就我个人的理解，这套技能吸引我的地方，是它把日常开发中的约定、记录和阶段划分组织起来，让我们和 AI 有一套可以共同遵循的工作方式。

setup-matt-pocock-skills 帮我们建立项目约定；ask-matt 帮我们判断当前问题适合从哪里开始。关键结论通过文档和任务承接，给后续会话提供依据。后续能否推进好，还要看需求信息、实际证据、记录维护和具体技能的执行过程。

然后虽然它的技能也给了不少，但是遇事不决，ask-matt。

推荐刚开始使用这套技能的同学，先选一个项目，把配置跑通，再拿一个边界明确的小任务试试。

至于需求澄清时应该问到什么程度、什么时候可以进入实现，后面考虑聊聊这套Skill核心技能Grill与主流程。

参考资料

说明

文章图片是AI生成的，部分段落也是AI生成了，大分部思路与资料都是实际开发过程中遇到的。