Communitygithub.com

Flagrare/agent-skills 编辑风格审校

像人类编辑那样从头到尾审阅一份完成或接近完成的文档,构建其试图传达的内容模型,然后诊断整体的一致性、连贯性、叙事主线、节奏、一致性、阅读流畅度、上下文关联性和清晰度,而不仅仅是逐行检查。同时清除代理常遗留的四类噪声。

agent-skills 编辑风格审校 是什么?

该技能模拟人类编辑的审阅方式,而非像代码检查工具那样只做局部检查。它适用于任何长篇文档(技术文档或非技术文档),例如 TDD、RCA、设计文档、调查报告、README、提案和长 PR 描述。其核心方法包括:先完整通读文档两次,第一次感受阅读体验,第二次进行诊断;然后从大到小(结构、流程、段落、行)诊断问题;并特别针对四类代理常遗留的噪声(来源叙述、排除假设残留、自指脚手架和戏剧化背景)进行清除。技能输出一份编辑备忘录,包含文档核心主张、总体诊断、按重要性排序的发现、待修复/待确认/待作者决定的分类以及优点总结,待作者批准后才进行修改。它强调在应用修改后需验证准确性,并避免仅做局部审查、重写为自身风格或从细节问题开始的备忘录等反模式。该技能支持 Claude Code、Cursor、Codex 等平台,旨在减少读者理解文档所需的心智负担,确保文档清晰、连贯且易于理解。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Flagrare/agent-skills/tree/HEAD/plugins/flagrare/skills/editorial-pass

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

编辑风格审校

代理审查文档的方式就像 linter 审查代码:一次一个局部发现,每个发现都对照规则进行判断,但没有任何一个发现是根据整体来判断的。人类编辑的做法则不同。他们从头到尾通读文档,建立一个关于文档试图传达什么的运行模型,注意该模型在何处变得困惑、无聊或迷失方向,然后才深入到行级。导致文档失败的大部分问题在行级是不可见的:一个回答了无人提出的问题的章节,一个在文档中途改变含义的术语,一个因三个段落重复一个想法而变得拖沓的中间部分,一个兑现了开头从未做出的承诺的结尾。

该技能就是这样的编辑。它适用于任何长篇文档,无论是技术性的还是非技术性的。不要将 TDD 和散文视为不同的类型:人类处理两者都需要循序渐进、有利益攸关和得到回报的步骤。这全都是讲故事,编辑的工作在任何地方都是一样的:最小化读者在理解文档试图传达的内容时的风险和心智负担。对于技术文档,这意味着读者无需重读就能回答“我们正在解决什么、为什么以及如何解决”。

在开始之前先划清一条边界:这是一个散文编辑,而不是技术审查者。你审查的是写作,而不是写作所描述的工作。模式是否正确、设计是否合理或数字是否成立是其他人的审查范围;你的权限是读者能否接收到文档所说的内容。唯一的例外是内部矛盾:当文档自相矛盾时,这属于写作缺陷,应由你指出。

何时调用

每当一份文档存在且有人将要阅读它时:用户要求对你自己或他人撰写的草稿进行审阅、编辑、润色、“确保其通顺”检查或清理。在你写完任何长篇文档后应主动调用,因为以下提到的失败模式正是起草代理会引入的。对于从头开始撰写文档,/flagrare:write-docs 负责写作技巧,/flagrare:tdd-writer 负责 TDD;此技能是对应的阅读和修复工具,并假定草稿已存在。

约定:先生成编辑备忘录(步骤 5),获得作者的同意,然后再应用更改。不要将默默重写他人的文档作为第一步。

流程

1. 通读整个文档。两遍。

在撰写任何笔记之前,先完整阅读整个文档。第一遍阅读是作为目标读者的感受体验,而不是作为审阅者:你在哪里投入了,注意力在哪里分散了,在哪里不得不回溯重读,有什么信息是你需要一直记在心里未解决以及持续了多久。克制在第一遍阅读时做注释的冲动。很多看似的问题会在文档后面得到解决,而很多真正的问题只有在回顾时才变得可见。

第一遍阅读结束后,写一句话:这份文档试图传达什么? 这句话就是主干。审阅中的一切都围绕它展开。如果你写不出这句话,那么这个无能本身就是主要发现,行级的任何问题都还不重要。

第二遍阅读是诊断性的。现在你知道文档想做什么,那么问题就变成了:它在哪些方面成功了,哪些方面做得不够?

2. 从大到小进行诊断

先结构,后流程,再段落,最后行。一份以逗号拼接句作为开头而文档本身叙事主线断裂的编辑备忘录是在浪费作者的时间。从四个层次自上而下分析:

叙事主线。 每个章节是否都服务于主干,还是某些章节属于另一份不同的文档?开头是否做出了一个承诺(一个问题、一个利益攸关点、一个钩子),且文档的其余部分兑现了这个承诺?两个简单的整文档代理:仅按顺序阅读标题,检查一个略读者是否能仅凭它们重构出论证;然后仅阅读每个段落的第一句话,检查它们自己是否能形成一个连贯的链条。如果任何一个链条断裂,那么无论句子写得如何,结构就在那里断裂了。

排序和上下文关联。 读者只能根据之前句子提供的信息来理解当前句子。通读文档时,在每个新概念、主张或术语出现时问自己:读者是否已经获得了在此处理解它所需的一切?上下文必须在需要时提供,而不是放在词汇表中或晚了三个章节。最常见的失败是知识诅咒式的排序:作者按照他们自己学习事物的顺序,或系统执行事物的顺序来安排内容,而不是按照一个陌生人能够吸收的顺序。

节奏和比例。 文档中的篇幅即强调。每个想法获得的文字量是否与其对主干的重要性相匹配?两个标准失败是相反的:一个承载风险的关键点被压缩进一个六个从句的句子,而一个次要机制因为作者觉得弄懂它很有趣而占据了三个段落。同时留意拖沓的中间部分,连续几个章节用不同的外衣重复同一个想法;以及重复信息(通常两次引入相同的事实意味着两个草稿被合并了,而没有人通读整个文档)。

一致性。 整个文档中每个概念使用一个名称;同义词循环在作者看来是优雅的变体,但在读者看来是第二个概念。检查数字、主张和术语在章节间是否一致,承诺过的内容(“下文讨论”)是否缺失,以及语气是否在文档中途发生突变。

3. 追查四类噪声

这些是删除性检查。代理(以及疲惫的人类)都会留下这三类噪声,每类都是写作过程的残余物,却出现在已发布的文档中。读者要买的是建筑,不是脚手架。

来源叙述。 作者如何得知某个事实是研究轨迹,而不是内容。“如 ia-logic.js 中验证的那样”、“X 与 Y 在该线程中确认”、“一份设计文档指向此处”、“在代码、Confluence 和 Slack 中检查:不存在这样的作业”。陈述事实,让它凭自身权威立足;验证确实发生了,只是不需要叙述出来。需要注意的词语:验证、确认、正如与…讨论过、根据该线程、根据该文档、检查后、我查看了。

之前: 根据 M1 决策文档(由 PM 在 2026-06-16 线程中确认),sold_out 必须在场地当地时间午夜重置。经在代码、Confluence 和 Slack 中验证:目前不存在这样的重置作业。

之后: sold_out 在场地当地时间午夜重置,且目前没有作业执行此操作,因此标记为“明天之前缺货”的商品永远不会被清除。

有两个例外,都非常狭窄。当某人的签核是待执行的操作(例如审批者、未决决策的负责人)时,才引用这个人,而绝不要作为归因于事实的依据。保留方法当方法本身即是主张时:基准测试结果与测量方式密不可分。

排除假设残留。 代理会保留它们所证明内容的负面空间记录:“我们确认 reconcile 不是原因”、“这原来是个假线索”、“服务路径无需更改(已验证)”。调查需要这些步骤;读者几乎从不需要。只有在未来的读者很有可能走入相同的死胡同并重复这项工作时,一个死胡同分支才值得一个句子,并且只占一行,精确地放在该读者可能开始挖掘的位置,而不是一个独立的章节。其他一切:保留正面结论,删除反面论点。“该功能是写路径;读取已正常工作”这一个句子就完成了一个完整的“无需更改的内容(已验证)”章节所做的全部工作。

自指脚手架。 文档谈论自身作为草稿:“这纠正了之前的注释”、关于已验证内容的陈旧的 [需要验证] 标记、作为已删除条目与“已解决:”注释一同保留的已解决问题、以及列出每个被检查的来源的结尾“验证摘要”。一个已确定的决策不是一个问题:一次性陈述选择,放在它所属的位置,并删除讨论过程。如果某个标题下的所有内容都已解决,则删除该标题,而不是写上“不适用”。该类噪声存在的迹象:在解决问题的过程中,文档变得更长了。后面的检查应该减少长度。

戏剧化背景。 为读者只需接受的内容进行论证的写作。三个特征:对读者已经理解的概念进行说明(“'汉堡' 是一个固定的东西,没有'选择酱料'”);一个说明工作为何重要的利益攸关句子(“定制化才是真正菜单的灵魂”),而文档的存在本身已确立了这一点;以及一步步推导因果链,而下游只使用其结论(“唯一的写入者是以太坊同步;手动合作伙伴没有以太多;因此他们无法创作”)。在读者的理解水平上直接断言事实,然后继续;在机制起到支撑作用的地方一次性陈述机制,而不是在引言中。让这一删除操作不损害真正上下文的边界是:上下文用于决策,断言用于背景。 任何读者需要判断的内容保留其完整成分(当前行为、分支、利益攸关点);任何读者只需接受以继续阅读的内容只用一个平实的句子。每个句子的测试:如果删除它,读者是否会做出错误的决策,或者只是感觉不那么受引导?错误决策,保留;感觉不那么受引导,删除。

4. 扫描清晰度

用另一套视角审视同一文本,寻找三件事:新读者无法解码的行话、过于压缩而无法一口气理解的句子、听起来专业但实际无意义的短语(“由构造保证”、“按设计”、“利用这一点”)。在首次使用时,内联地在同一个句子中定义内部行话;校准到一位熟悉该领域一般知识但不了解此特定角落的新员工。给最密集、最重要的段落留出最大的空间:将其分解成节拍,每个句子表达一个想法,先原因后结果。测试方法是出声朗读:任何无法一口气说完的从句,或新员工会停下来查阅的术语,都需要重写。

清晰度不是简化。当准确的解释需要实际的数据模型时,就使用实际的数据模型;罪过是让读者去做解包工作,而不是存在细节。在内容实质上是并行的参考资料(例如列列表、附录、错误表)时,密度是可以接受的。这些天生是可扫描的;不要将其散文化。

5. 提供编辑备忘录,然后等待

先报告,后重写。备忘录按以下顺序组织:

  1. 理解的主干。 一到两句话,说明你认为文档试图传达的内容。这既是以下所有内容的框架,也是一个测试:如果你的理解与作者的意图不同,那么这个差距就是最大的发现。
  2. 总体诊断。 一两个最主要的问题,直白地命名。不要用五十个行级注释来掩盖一个断裂的叙事弧线。
  3. 发现,从大到小。 对于重复出现的模式,命名该模式并给出两到三个代表性示例,而不是穷举所有实例。引用实际文本;至少为一个示例提出实际的替换方案,以便作者可以看到具体的修改方式,而不仅仅是规则。按对作者的重要程度组织发现,而不是按此技能的清单:上述的噪声类别和层级名称是用于发现问题的视角,而它们本身不适合作为目录。一个按类别分节的备忘录读起来像在填表格;一个按“什么对读者成本最高”排序的备忘录读起来像一位编辑。
  4. 分类。 分成:你将在批准后应用的修复(机制性的、已验证的);你将标记但不会捏造的空白(缺失的章节变成 [待定:...] 锚点,绝不发明内容);以及属于作者判断的决策(为节奏牺牲完整性的删除、语气选择)。
  5. 优点。 简要说明。作者需要知道在修订中不要改动什么。

备忘录本身也是一份供人阅读的文档,因此它遵循自身规则。不要描述你的流程(“根据技能要求,我读了两遍”),不要报告未发现问题的检查(“未发现长破折号”),不要用你查看的所有内容来填充它。陈述发现;对于所有通过检查的内容,沉默就是报告。

然后停下来,让作者回应。当他们同意后,再应用。对于结构性问题,优先选择从头重写文档,而不是在原地修补句子:结构决策已融入句子构造,润色无法修复一个本不应存在的段落。在磁盘上保留之前的版本以供差异比较。

6. 应用后验证

压缩和改写可能会无声地改变含义。重写后,逐一检查每个措辞发生变化的主张是否与其来源(代码、数据、引用的文档)一致,然后作为陌生读者从头到尾再通读一遍最终文档。对于高风险的文档,最有效的检查是请一位没有任何上下文的新读者:将文档单独交给一个子代理,询问文档中哪些内容含糊不清、假设了哪些知识、是否存在任何自相矛盾之处。让上下文无关的读者感到困惑的内容也会让真实读者感到困惑。

反模式

仅进行局部审查。 直接跳到行级编辑,而从未形成主干句子。如果你的审阅可以通过拼接每个段落级别的审阅来生成,那么你并没有阅读文档,你只是扫描了它。

重写为自身风格。 目标是这份文档、由这位作者创作的最佳版本。当一项更改会改变含义或意图时,请询问而不是覆盖:“你的意思是 X 吗?读者可能会将其理解为 Y。” 学会区分“这位作者总是做 X”(风格)和“这位作者在这里偶然做了 X”(错误)。

从细节问题开始的备忘录。 以错别字和逗号拼接句开头,而结构性问题却未被提及。零散的技术性错误在应用步骤中会默默修复;而重复出现的句子级别的问题应该在备忘录中作为模式指出。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能