用 Markdown 固化编程智能体工作流
Yonto Player 将提单、修复问题、提交 PR 和质量检查等七类流程写成 SKILL.md,供不同编程智能体和开发者共同执行。文件通过元数据描述适用场景,再按顺序组织操作说明与命令。
AI 深度解读
让 AI 按团队流程做事,不一定要先搭一套复杂的编排系统。Yonto Player 把仓库里的七类工作流写成 Markdown:人能照着执行,不同 AI 编程助手也能读取同一份规则。
这篇值得借鉴的地方,是作者把「什么时候用、先做什么、怎样算完成、工具不支持时怎么办」写进了文件。它展示了一种容易复制的仓库实践,但没有提供效率或缺陷率的对照数据。我们可以拿走组织方法,不必连效果承诺一起接受。
一份 Markdown,怎样变成可执行的流程
Yonto Player 是面向 Android TV、手机和平板的个人媒体库播放器。它的 skills/ 目录包含七个文件夹,分别处理质量巡检、提交 issue、清理 issue 队列、修复单个 issue、创建 pull request、从观众视角走查应用,以及编写源插件。
每个文件夹都有一个 SKILL.md,其中两个另带 references/。主文件顶部只有 name 和 description 两个元数据字段,下面按执行顺序写说明和 shell 命令。作者没有为这套格式增加其他 schema、实现代码或注册表。
下面是原文的简化示意,用来说明如何把一次提交流程写成技能;它并非仓库里的真实文件:
---
name: ship-a-change
description: ">"
Use when a change is ready to propose: "open a PR", "put this up",
"/ship-a-change". Produces a PR whose body says why, what and how to test.
---
## Ship a change
One sentence on what a good result looks like.
## Before you write anything
(commands to run, in order, each with the reason it is there)
## The body
(what the three sections hold, and the test of a good one)
## Then
(what comes next, and which other skill covers it)
重点看 description 所在段落:它同时描述触发场景、调用名称和交付结果。这个代码块只是格式草图,括号中的内容也只是占位说明,使用前仍需补成实际步骤,并确认目标工具能正确解析 front matter。
作者认为,描述比看起来更关键。用户可能说「open a PR」,也可能直接输入 /ship-a-change,技能应让助手把这些表达对应到同一项工作。
边界也要写清。提交 issue 与修复 issue 是两种工作,但修复流程可能包含提交 issue。作者的做法是在修复技能中引用提交技能的名称,让规则只维护一份。否则,同一条规则复制到几个文件后,很容易各自变化。
真正有用的是顺序、证据和停止条件
文件能读懂,还不等于流程可靠。作者展示的几类工作流,都把完成条件写得相当具体。
修复技能包含七个有序步骤:复现、调查、计划、提交 issue、修复、评审、合并。不能复现就说明情况并停止,避免仅凭推测修改代码。
顺序和停止条件,也是工作流需要交付的内容。
创建 PR 的技能先定义什么叫好描述:评审者读完正文,再看 diff,不应遇到意料之外的变化。这个标准能迫使提交者解释改动动机、范围与验证方式,而不是只填几个模板标题。
质量巡检要求每一步之后截图,并在提交问题前验证发现。清理队列则先读 PR 列表,再读 issue 列表,直到队列为空才结束,不以「已经扫过一遍」作为完成条件。
这些都是仓库已经采用的规则,但原文没有给出执行成功率,也没解释遇到外部依赖阻塞、暂时无法处理的 issue 时怎样结束队列清理。一般团队照搬时,需要把这类边界补上。
工具方面,流程使用 git、gh、shell,以及应用开发所需的模拟器。修复和队列清理最终都要求由没有参与编写改动的新工作者评审:助手支持 helper 就用 helper,否则开启独立会话。
这里要保留的是评审者的独立性。至于第二次评审究竟能发现多少额外问题,作者没有提供测量结果。
流程短不短,取决于细节放在哪里
质量巡检和队列清理的细节较多,作者把只在某一步需要的信息移到 references/。
质量巡检的参考目录有两个文件:一个列出巡检覆盖范围,另一个提供进入异常状态的方法,例如离线、媒体流始终无法启动。队列清理则把多个工作副本的协作规则放进 coordination.md:通过评论认领 issue,各自选择下一项任务,不给其他工作者派活。
这样,单独修复 bug 的助手通常不必读取整套巡检技巧,也就不用为无关细节消耗上下文。它类似 AGENTS.md 中按任务提示「什么时候读哪个文件」的做法:入口负责指路,细节按需展开。
为了适配不同助手的目录约定,仓库还维护了相对符号链接。某个工具需要专属目录,就增加一个链接,技能正文始终只有一份。
不过,单一副本只能减少重复维护,不能保证内容一直正确。作者还规定:文档、AGENTS.md 和技能的更新,必须与对应代码进入同一个 PR。
PR 技能会追问「这次改动让哪些描述失效」,再要求按主题搜索并阅读每个命中结果。比如命令或文件路径变了,只搜索旧句子未必够,相关操作说明也可能需要一起改。
我的判断
我赞成先把重复工作写成短流程,再考虑更复杂的自动化。对已有 git、gh 和 shell 工具链的团队,这种方式容易审查,也方便新人和 AI 共用。
但「任何 agent 都能运行」要结合文章语境理解:流程尽量不依赖某个产品的专有能力,并且提供替代路径。它不保证所有助手都会自动发现技能、准确触发,或者严格遵守每一步。
Markdown 能表达约束,执行约束仍要靠工具和检查。
与 CI 相比,它适合承载调查、判断、异常处理等需要解释的步骤;类型检查、测试和构建这类明确可执行的检查,仍适合交给 CI。原文没有比较两者成本,也没有证明技能能替代既有检查。
独立评审、每步截图、清空队列也都有成本。作者展示的是他们团队的流程选择,没有给出通用收益数据。借鉴时应保留这些规则背后的目的,再根据项目规模决定执行强度。
能拿来做什么
- 从一个反复执行的任务开始,例如修复前端 bug 或创建 PR,把前置检查、执行顺序、完成标准和停止条件写进一份
SKILL.md,不要一开始就复制七套目录。 - 给 AI 修复任务明确复现要求,记录操作步骤、预期与实际表现;无法复现时先交代证据缺口,再决定是否继续调查。
- 把 PR 描述、issue 提交等共用规则分别维护,通过技能名称互相引用,并将异常场景操作移入
references/。 - 在代码评审中检查命令、路径和操作说明是否仍然成立;需要独立复核时,明确使用新工作者或独立会话,避免默认当前助手已经完成第二次评审。