我的 Agent Skills 工作流：决策、证据、项目记忆与交付

一个 Agent 能写代码，还需要知道当前的问题有没有说清、关键假设有没有验证、测试究竟证明了什么，以及下一次会话该从哪里接着做。这套 Skill 围绕这些具体问题分工：让决策有记录，让实现有证据，让交付物能被核对。

截至 2026 年 10 月 11 日，我维护的 Agent Skills Index 收录了 10 个 Skill，来自 8 个独立仓库。索引保存入口、用途、安装命令和核对过的提交；每个 Skill 的规则、脚本与参考资料仍留在来源仓库里。另有一个来自他人仓库、尚未收入索引的 asd-ste100，放在写作部分单独说明。

下面按一次任务的先后顺序介绍：动手之前、实现时、完成时，最后是交付物。文中的版本指文末列出的 Git 提交，不代表统一的发布版本，也不意味着每个任务都要把十个 Skill 跑一遍。

总览：按问题找 Skill

图 1：一条需要决策、事实核验和实现的工作路径。小任务可以省去不适用的环节；长期项目的状态由 project-map 持续维护。Mermaid 源文件。

一、动手之前：先分清缺的是什么

同样一句“还没想清楚”，可能对应三种不同的缺口。

缺人的取舍。 例如，第一版要覆盖多少用户、是否接受某项成本、两种交互方案选哪一个。这类问题由人决定，grilling 帮助把选择和代价摆到桌面上。

缺事实依据。 例如，目标 API 是否提供所需字段、某种格式能否保留批注、现有环境能否满足延迟要求。这类问题需要查证或实验，由 reality-first-engineering 组织最小探针。

缺持续记录。 方向已经确定，但决定散落在聊天里，任务之间的依赖不明确，README 也逐渐落后于代码。这是 project-map 管的事。

这几个 Skill 的边界很重要。查资料不能替用户做取舍；用户接受了一项建议，也不能反过来证明建议所依赖的假设已经成立。

grilling：把问题问到可以交接为止

grilling 只在用户明确点名时使用。它先确定讨论的终点，再把问题分成当前可讨论的问题、被前置条件阻塞的问题、还无法具体表述的模糊区域，以及范围之外的工作。

它会区分“用户自己提出的决定”和“用户接受了 Agent 的推荐”。最新版要求记录推荐背后的假设，并把新决定与已有约束逐项对照。有冲突就重新明确优先级，不能让两个互相矛盾的答案同时留在基线里。

推荐一旦被采纳，它依赖的假设就会成为下一轮的前提，讨论也就在不知不觉中偏离。为此，grilling 设有漂移检查（drift check）：用户询问进度或要求检查时，以及交接之前，它会原样引用用户对目的地和目标的描述，把“用户自己做的决定”与“只采纳了推荐的决定”分开列出，并写明后者携带的假设，请用户重点核对。它不会自行定期触发。

它的结束条件是人确认了可交接的结果。讨论结束后交接并停下，进入实现需要用户另行授权。 如果问题本来就能在一次会话内说清，也没有必要先创建一套庞大的问题账本。

reality-first-engineering：先验证会改变方向的事实

reality-first-engineering 用在错误假设可能带来明显返工、数据损失或错误验收的地方。

它要求区分已经观察到的事实、测量结果、推断和未知项，然后优先验证影响最大的未知项。一个探针要写清输入、方法、通过条件、失败条件、停止条件，以及证据保存在哪里。

例如，要基于某个外部服务做文档导出，可以先拿一份包含表格、图片和批注的样本验证格式保真。这个探针的结果可能直接改变方案。在本地模拟一个“导出成功”的返回值，无法回答外部服务是否真的保留了批注。

它也有明确的成本边界：普通文案修改、输入和契约都清楚的小改动，不需要额外经过这道流程。

project-map：让下一次会话能接上当前状态

project-map 用本地 Markdown 保存长期项目的目的地、决策索引、待办和关键文档。项目已有 .project-map/ 时继续使用；新建则由用户提出。

.project-map/
  MAP.md                  # 目的地、决策索引、未明确事项、活文档
  tickets/                # 决策、研究、前置任务和实现任务
  specs/                  # 从已确认决策整理出的规格
  archive/                # 已退出当前工作的记录
CONTEXT.md                # 项目术语表

MAP.md 是索引，有 150 行预算。细节放进对应 ticket 或文档，同一事实只在一个地方维护。开始会话和准备结束时都运行 status，检查结构问题和可能过期的活文档。

从决策走向实现时，它先整理规格，再切出接下来两三个纵向实现任务，让用户调整后写入；每次会话推进一个实现任务。这里的 Tracer bullet（曳光弹） 指一条穿过必要层次、能从真实入口运行的最薄路径。例如，一条任务同时打通输入、处理、存储和结果展示，再逐步扩大覆盖面。

CONTEXT.md 则维持 Ubiquitous language（统一领域语言）：同一个业务概念在讨论、代码、测试和文档中使用同一个名字，避免一次会话叫“任务”，下一次又在没有说明的情况下把它写成“作业”。

architecture-flow-map：接手已有代码时，先还原它怎么运行

architecture-flow-map 面向已经存在的代码库。它把主要模块、业务对象和 3—5 个关键场景整理成可逐步回放的交互地图。

它有两个主要产物：作为事实来源的 map.json，以及由固定查看器和构建脚本生成的 HTML。代码引用包含路径、行号和该行的字面符号；构建时会检查文件是否存在、行号是否越界、符号是否仍在对应位置。之后还要在浏览器运行自检并检查实际呈现。

地图中的结论分为 confirmed、inferred 和 unknown。前两者要有引用或运行依据，未知项则写明需要什么证据才能解决。文档说有登录校验、代码却没有时，地图画出代码实际行为，并记录这处文档偏差。

因此，它适合回答“点这个按钮之后，数据到底经过哪里”。如果要讨论一个尚未实现的新架构，就应回到设计和决策工作，不能把设想画成项目现状。

二、实现时：先有能拒绝错误行为的证据

evidence-first-testing 处理实现过程中的证据。它要求先保存能暴露问题的信号，再改行为，然后用同一个信号确认修复。

假设导出流程在遇到空单元格时错移了后续列。预期列位置应来自输入文件和格式约定。若直接把当前程序的输出抄成预期值，测试即使全绿，也没有证明列位置是对的。

图 2：预期值来自独立契约；失败与通过必须对应同一个行为信号。Mermaid 源文件。

如果代码已经先改好了，就补做反事实验证：在父版本、临时撤掉相关修复的版本，或重现缺陷的定向变异上运行测试。无法安全恢复错误行为时，保留修复后通过的事实，同时说明回归证明还不完整。

这套要求也区分三种红灯：已有缺陷的复现、新需求尚未实现的预期失败，以及偶发或环境相关的失败。环境没装好导致的报错，不能算作成功复现了业务缺陷。

三、完成时：按改动类型选择审查

完成检查按候选改动的类型选择审查方式：

结构审查看新增的异常边界、吞错、重试、回退、兼容分支和并行 API。扫描脚本只负责定位候选问题；没扫描到结果，不等于审查通过。这里的 Deep modules（深模块） 是一个判断标准：小接口应隐藏足够多的实现复杂度，只有一层转发的包装也会增加设计成本。

如果改动涉及 eval、benchmark、grader 或其他明确的验收表面，结构审查会转交行为验收审查。两者都针对冻结的候选，在新的只读上下文中工作，不沿用实现会话的解释作为结论。

对于模型驱动的 Agent 产品，行为验收还要检查生成结果是否依赖真实输入。例如，换掉一个关键字段后，输出应在相应位置改变；永远返回同一段“成功”文本的实现，不能通过验收。纯本地 mock 能证明的范围，也不能被扩大成真实服务边界已经验证。

四、交付物：文字与界面

写作和前端的四个 Skill 处理不同的问题，可以按产物单独使用。

document-writing 覆盖起草、润色、翻译和编码保护。自然表达必须服从语义保真：“小样本下可能有效”不能被润色成“已经证明有效”；数量、否定、例外和不确定程度都要留下。保存文件后还要回读，检查实际文字、BOM 和换行方式。

asd-ste100 的读者是模型或程序：工具描述、系统提示词、子 Agent 指令，以及供机器解析的错误和状态字符串。它按 ASD-STE100（简化技术英语）的结构规则改写英文：主动语态、一句一个指令、限制句长、不用分号和短语动词，并保留“可能”这类不确定程度。它只覆盖英文，也不内置 ASD 的核准词典，所以词汇规则只能作为方向，不能当作合规证明；仓库附有 scripts/ste-lint.py 检查脚本。给人读的 README、邮件和报告不在默认范围，除非用户明确点名 STE。它是第三方 Skill，我只在本机安装使用，没有收入索引。

frontend-less-ai-tone 负责前端的内容和视觉方向。先明确读者、主行动和一个视觉记忆点，再写结构与样式。事实来自已有材料，不能靠虚构客户、评价和数字填满页面。在不允许自由编写 CSS 的生成器中，则遵循项目已有约束。

same-visual-family 负责已经选定方向之后的组合一致性。引入外部组件时，保留有用的结构，把仍然生效的字体、颜色、圆角和阴影调整到当前视觉系统。如果没有成文规范，就先从已有界面提取背景、文字、强调色、边线、字体栈和圆角的具体值。

前一个 Skill 决定“这个产品应该怎么说、怎么看起来”，后一个决定“这些模块能不能放在同一页”。组件来自同一个库，并不能自动保证一致；来自不同的库，也不必一概否决。

五、放进一次具体任务里

假设要给一个已有知识库工具增加“上传文档并返回可定位的引用”功能。下面是使用方式示例，不是这些 Skill 已经完成过的项目实测。

1. 先看现有实现。 如果入口、存储和检索关系已经难以追踪，用 architecture-flow-map 还原上传与查询路径。
2. 把产品取舍说清。 如果用户点名 grilling，就讨论首版支持的格式、引用粒度和失败时的用户体验，确认结果后交接并停下。
3. 验证关键事实。 用带跨页段落、表格和扫描图片的样本，检查解析能力以及引用定位能否保留。结果不足以支持方向时，先解决未知项。
4. 获得实现授权后打通薄路径。 已有项目地图负责记录任务。先完成一种格式从上传到显示引用的完整路径，再增加格式和边界场景。
5. 保存能拒绝错误行为的证据。 预期引用来自人工核对的样本位置，测试要能发现错页、错段和固定返回同一引用的实现。
6. 按候选改动验收。 涉及生成结果及引用正确性时，使用行为验收审查；说明文档交给写作规则，界面按需要使用两个前端 Skill。

在这个例子中，项目地图贯穿多次会话，其他 Skill 在对应问题出现时进入。任务大小决定需要多少环节；结束条件由要交付的行为和证据决定。

六、来源仓库、索引与本地安装

这套目录采用“独立来源仓库 + 一个索引”的组织方式。修改规则时回到来源仓库；索引只记录去哪里找、何时使用，以及安装哪个 Skill。

图 3：索引仓库与本地链接的职责。工具目录的处理方式由同步脚本中的配置决定。Mermaid 源文件。

只安装需要的 Skill 即可。例如下面两个命令分别安装写作和回归证据相关的 Skill；-g 表示全局安装，-y 跳过交互确认，参数含义见 Skills CLI 文档。

npx skills add a1024053774/document-writing-skill --skill document-writing -g -y
npx skills add a1024053774/reality-evidence-engineering --skill evidence-first-testing -g -y

完整安装列表在 索引 README。这些命令跟随来源仓库的默认分支，不会锁定到本文核对的提交。

如果需要维护源码，可以把每个来源仓库放到 ~/Documents/SKILLS/<repository>，再在索引仓库里查看链接计划：

python3 scripts/sync_skills.py

确认计划后，添加 --apply 才会实际调整链接。脚本把目录中收录的 Skill 链接到 ~/.agents/skills，并按 MIRRORS 与 HUB_READERS 配置处理其他工具目录。真实目录只报告，不会自动搬走。换机器或更换工具时，应先检查这份配置与本机布局是否一致。

维护正文时还可以运行：

python3 scripts/check_skill_budget.py

它检查 SKILL.md 的字节预算、frontmatter、相对链接、锚点和未从入口链接的参考文件。2026 年 10 月 11 日，本次整理中的 10 个 Skill 全部通过了这些静态检查。这只说明目录和文件满足这些检查项，不能代替 Skill 的实际行为验证。

这也解释了为什么核心规则放在 SKILL.md 前部，阶段性细节放进 references/：进入任务时先能看见不能违反的边界，到具体阶段再读取所需说明。预算需要服务使用方式；例如 grilling 每轮都要用到的问题类型和提问规则保留在入口，因此索引给它单独设置了 11264 字节预算。

本文核对的版本

以下 8 个本地来源仓库的 HEAD，在 2026 年 10 月 11 日核对时均与 GitHub main 一致。_archive 中的历史副本未纳入索引。提交链接固定本文所依据的内容；之后的更新以来源仓库为准。

外部 Skill asd-ste100 不在上表和索引之内。我本机的副本基于上游 7d4a135，另有一处未提交的本地修改：把 SKILL.md 的触发描述收窄到“用户点名 STE，或文本供机器解析”。上游 HEAD 此后已经更新到 32511c6，我没有对照这两个版本之间的差异，所以文中对它的描述以本地副本为准。

• Previous
  解密 Anthropic 的 AI 原生 SDLC 安全体系：当 80% 的代码由 AI 编写时，安全如何重构？
• Next
  a2a 设计思路：让多个 Coding Agent 协作，不靠模型记住操作手册