对我们，直奔主题；对智能体，事无巨细。

现在，我的拉取请求描述、代码评审回复和 issue，大部分都由智能体来写。它们写得不错，就是写得太多。

很长的拉取请求描述没人读。评审者扫一眼开头几行，往下一滚，就批准了，或者问一个正文里早已回答过的问题。可是下一个接手这个讨论的智能体，需要的恰恰是全部内容：改了什么、为什么改、测了什么、没测什么。

所以，每篇帖子都有两类读者。我不再试图用同一段文字同时照顾他们。

开头两句话，其余折叠

现在，我让智能体发布的每篇帖子都是同一个结构：

1. 一到两句话的开头，写给人看。技能里把它叫作 lead。
2. 一条分隔线。
3. 折叠起来的完整正文，写给智能体，也写给想看全部内容的人。
4. 一行页脚，写明是哪个技能写的。

在 GitHub 上，这个块是 <details> 元素；在 Linear（很多软件团队使用的任务管理工具）上，是 >>> 块。无论哪种，评审者看到的都只是两句话和一个合上的盒子。

下面是一个真实的例子：我给 Raycast 的 Homebrew 扩展提的拉取请求。开头说明改了什么、需要评审什么。前后对比图就放在开头下面，其余内容全部折叠起来。

有一点要注意：GitHub 的命令行工具只能替对仓库有写权限的人上传图片。从自己的 fork 给别人的项目提拉取请求时，通常没有这个权限。所以技能会先发出表格，在每个图片格里放一个占位提示，告诉你哪个文件放哪里。然后你在浏览器里粘贴图片，在那里任何贡献者都能添加图片。

之前	之后
📎 在这里粘贴 dia-before.png	📎 在这里粘贴 dia-after.png
输入 dia 时 AirMedia 排第一，Dia 在大约三页之后。	输入 dia 时 Dia 排第一，后面是以“dia”开头的名字。

有些帖子很短，加上折叠块也只是重复同样的话。回复一条评审意见，一行就够了：“已在 b72e019 中修复，请再评审一次。“这时智能体只发这一行，不加分隔线、折叠块和页脚。

开头说清要做什么

开头说两件事：改了什么，以及读者需要做什么。“请检查重试的等待时间。""请检查深色模式下错误提示的颜色。“如果没有需要做的事，就写清楚改了什么。

智能体最后才写开头，等细节都写完以后。先写的话，开头容易变成开场白：“这个 PR 添加了……”。最后写，它就是对已有内容的总结，要做的事也一眼就能看到。

“先写下一步行动”这个想法来自 i-have-adhd 这个技能。不管有没有 ADHD，它都管用，因为忙碌的评审者也有同样的问题。

细节一个不少

折叠块不是摘要。如果仓库有拉取请求模板，折叠块就按模板的标题逐一来写。模板是维护者为认真评审准备的，所以它会保留下来，只是挪到不碍事的地方。没有模板时，技能用自己的标题：概要、原因、改动、测试方法，以及未测试的内容和原因。

所以，评审者有两条路。想快速看一眼，开头和截图就够了：改了什么、看起来怎样、要检查什么。想认真评审，就打开代码和折叠块，里面是他们自己要求的模板，已经填好了。

最重要的是”未测试的内容”。CI 通过，只能证明 CI 跑过的部分没问题。一个会说明自己没检查什么的智能体，能让评审者知道该具体看哪里。即使模板里没有这一项，技能也会加上。

因为人默认不会打开这个块，它想写多长都可以。没有人需要在”简短”和”完整”之间二选一。

打开 Homebrew 拉取请求的折叠块，可以看到它按 Raycast 的模板来写：Description 和 Screencast，最后是检查清单。在它们之间，技能加上了 How it was tested（实际运行的命令和结果）和 Not tested (and why)。

你的语言，你的顺序

不是团队里的每个人都能轻松读英语，也不是每个人都用英语写作。所以这些技能用你的语言来写：一种放在最前面的语言，以及放在下面的其他语言。

第一次使用时，技能会用你和智能体对话的语言问两个问题，并把答案保存为默认设置：

你的帖子用哪种语言开头？

英语

要在下面加上其他语言吗？

是：日语

之后，每篇帖子都可以用普通的话来改：“只用英语""日语在前""只用葡萄牙语”。日语在前时，英语原文放在 原文: 后面，读者就知道哪一份是原文。

我在前面那个 Homebrew 修复上试了一下。真正的拉取请求保持英文，以免打扰我参与的开源项目。在我自己的 fork 上，我用英语和日语提了同样的改动，也用同样的方式建了一个 Linear issue。

用我自己的语言写的部分总是先写，其他语言都从定稿翻译。从草稿翻译，译文会和最终版本越走越远。

发布之前，一个小脚本会检查文本。它在每种语言里都限制句子长度：30 个词；像日语这样词与词之间不加空格的语言，则是 80 个字。它还会在英语里找出长破折号、缩写形式，以及 “should” 这类含糊的词，并检查格式的各个部分：开头、分隔线、折叠块和页脚。它检查不了意思，所以技能还会要求智能体单独把开头再读一遍。英语规则以 simple-english 和 unslop 为基础。

一个技能，一项职责

一共有四个技能，每个只负责一件事：

• post 负责文本：格式、语言、风格和检查。
• github 和 linear 负责平台：语法和命令。
• create-pr 负责拉取请求的流程：准确的提交范围、各项检查、标题，以及紧跟在开头下面的前后对比图。文本部分交给 post。

GitHub 改了显示方式，只需要改 github。想把开头写得更好，只需要改 post。以后在 github 旁边加一个 gitlab 技能，在 linear 旁边加一个 jira 技能，也不用动其他技能。

页脚会写明运行的是哪个技能，比如 clins:create-pr。喜欢这个结果的读者，就知道该运行什么来得到同样的东西。

试一试

演示页面展示了每个技能写出的内容，用的是 GitHub 和 Linear 上的虚构例子，其中有一个拉取请求，可以在四种语言组合之间切换。

这些技能是开源的。用下面的命令，就能装到任何编程智能体里：

npx skills add clins1994/skills

欢迎提 issue 和拉取请求。贡献指南里列了几个上手的方向。