Claude Code 火起来之后我身边几乎所有人都在折腾 Agent——让模型自己规划、自己调工具、自己跑完整个流程。Anthropic 放出官方 Skills 仓库那会儿我一开始也没太当回事一堆 Markdown 指令文件而已能有多厉害直到我把 document-skills 目录里的 coauthoring 技能翻完并且老老实实用它跑了一篇两万字左右的技术方案之后我的看法彻底变了。这个 skill 解决的不是写什么而是怎么写才能不翻车——它把长文档写作这个看似靠灵感的活儿拆成了可恢复、可审校、可迭代的工程流程。这篇就围绕 doc-coauthoring 这个官方技能聊聊它的核心原理、接入方式以及我实测下来的体会和踩过的坑。适合正在用 Claude Code、经常写长文档、或者想搞明白官方 Skill 到底怎么用的人。1. 为什么官方技能仓库里我先盯上的是 coauthoring1.1 Skills 到底是什么先和 Agent 划清界限很多人把 Skill 和 Agent 混为一谈。搜索热词里常年挂着skill和agent的区别这里我先给出一个尽量简单的说法Agent 是一个拥有工具、可以自主循环执行任务的执行体它会自己拆解目标、调用工具、检查结果Skill 是一份操作手册或专业打法它不会自动跑起来而是被 Claude 在合适的时机加载用来规范某类任务该怎么做。一句话Agent 负责自己去干Skill 负责教它怎么干得专业。两者不冲突。Claude Code 里跑着的 Agent 骨架加上 coauthoring 这份 skill就等于一个懂长文档写作规范的 Agent。Claude Code 加载 skill 的路径一般是自动发现把 skill 目录放进~/.claude/skills个人全局或.claude/skills当前项目描述信息匹配到用户请求时就会触发。doc-coauthoring 在官方仓库里对应document-skills/coauthoring是官方文档类技能中的一员。1.2 它解决的问题长文档不是长提示词我见过太多人让 Claude 写长文的方式把需求一股脑塞进一条提示词然后期待模型吐出一篇完整的万字文档。结果往往分成三种写到一半开始车轱辘话来回说前后章节口径不一致或者被上下文窗口掐断后半段完全是空壳。doc-coauthoring 的全部设计都在对抗同一个物理现实上下文窗口是有限的而长文档的信息量超过了窗口容量。一次性写太长注定失败那就把它切成恰好能装进上下文的块一块一块写再靠外部状态把块与块之间衔接起来。这就是它最核心的工程思想。2. 拆解核心机制把文档本身变成记忆体2.1 分块生成chunk 不是简单分段官方这套分块流程第一步不是开始写而是理解文档结构。Claude 会先摸清目标文档的标题层级、已有段落、缺失部分然后给出分块计划。每个块有独立编号和语义目标例如块1问题背景与术语定义块2架构总览。分块的标准有几个关键约束单个块的字数要控制在当前上下文能从容处理的范围。官方参考文档里强调的是一个块 已产出的摘要 工作指令三者的总和不能撑爆窗口块之间要有清晰的边界锚点最常见的做法是围绕标题Heading切分让每一块对应一个可独立审校的单元每个块被标记为pending待写、in_progress写作中、complete完成三种状态。块状态不是写完之后就扔掉。每块完成后Claude 会生成一段摘要写进一个清单里。后面任何一个块开写之前Claude 都先读这份清单保证后写的部分知道前面定过的口径、术语和结论。2.2 用 XML 上下文块做状态管理这个设计是整份 skill 里最巧妙的地方。为了让状态可以跨会话存活coauthoring 把一份结构化的流程状态直接嵌进文档自身通常是文档末尾的一个 XML 区域我把它称为上下文块。它的样子大致如下ctx phasewriting/phase plan item idp1梳理大纲确定六个主要章节/item item idp2为每章建立 chunk 注册信息/item item idp3逐块写作并同步审校/item /plan manifest chunk id1 title概述与背景 statuscomplete summary定义问题为X约束条件为Y-Z术语表第一版包含WN等三条 / chunk id2 title架构总览 statuscomplete summary采用三层架构模块A与模块B通过接口C通信边界在D处 / chunk id3 title核心实现 statusin_progress summary / /manifest active_doc idlocal:/docs/guide.md / /ctx为什么要用 XML 而不是普通文字原因很实际Claude 生成 XML 这类严格语法的格式远比生成自由文本可靠解析也明确XML 区块可以整个覆盖更新不容易把前面的正文搅乱而且文档保存一次状态就保存一次不需要额外的数据库或记忆文件。这对写长文写一半断掉的场景非常友好就算会话上下文耗尽重新开一个新会话Claude 读一遍文档尾部的 ctx 区块就能准确知道写到哪里、哪些块完成了、哪些没写然后接着干。这种文档即状态的思路比任何外置记忆方案都简单直接也更容易被用户检查和干预。2.3 渐进式摘要让后面的块永远知道前面写了什么分块之后最大的敌人是断裂感每个块都是独立生成的如果不做衔接合出来的文档完全不像一个人写的。coauthoring 的做法是渐进式摘要。每个块完成后Claude 用两三句话概括这一块的实质内容摘要必须包含具体锚点——人名、名词、决策、数字、术语定义而不是本章介绍了相关背景这种废话。我自己的体验是摘要的质量直接决定后半程文档的质量。摘要具体后面的块才能引用前面块里定义过的概念不会出现前面叫订单模块、后面写成销售模块这类尴尬摘要抽象后面基本就是各写各的。这也是我后面要专门讲的一条经验。3. 两种写作模式Google Docs 与本地文件3.1 Google Docs 模式为协作场景设计据官方仓库的说明coauthoring 在设计上考虑了对 Google Docs 的对接。比较典型的场景是文档本身托管在 Google Docs 上Claude 借助 Google Docs 的接口能力读取正文结构、按计划分块、再把写好的内容同步回去。因为分块流程天然支持一次只提交一个块的改动多人协作时其他人能实时看到文档推进Claude 的修改也有清晰的块边界可追踪。搭这种模式需要把 Google Docs 的访问权限配好OAuth 或者对应的集成工具。就我了解不少人是在自己的自动化环境中封了一层 Google Docs API 调用然后把 coauthoring 的分块清单当成中间数据来驱动。这个方向适合文档需要在线上协作、最终交付物就是 Google Docs 本身的团队。具体接口细节不同版本可能会有调整建议以官方仓库当前代码为准。3.2 本地文件模式Claude Code 场景下的主战场对我来说用得最多的反而是本地文件模式。文档就是一个 markdown 文件直接放在项目目录里Claude Code 读文件、写文件、更新文件尾部 ctx 区块全都在本地完成。好处是零额外配置而且一切变更都能用 git 追踪。本地模式下整个流程非常顺滑给 Claude 一份大纲或半成品文档Claude 读取结构输出分块计划并写入 ctx逐块写作每完成一块就更新 manifest 摘要你随时可以打断说块 3 重写或块 5 再补一段它只动对应块不碰其他内容。这种本地文件 尾部状态区的组合实际上是把复杂的文档协同变成了版本控制里的常规操作diff、review、合入主干。我很推荐团队内部做技术方案、产品需求、甚至知识库长文时用这套组合。4. 和一次性丢给 Claude相比实测差距在哪4.1 三个维度上的直观对比我自己做过的对照实验不算太严谨但结论足够有说服力。同一份两万字左右的技术方案分成一次性生成和coauthoring 分块两种方式差距集中在几个维度维度一次性生成doc-coauthoring可写长度上下文一满就断通常 3000 字往上质量明显下滑单个块 500-1500 字块数不限靠摘要串起来前后一致性前两章说的术语第四章可能就换说法每块开写前先读 manifest 摘要口径被锚定中断恢复断一次基本从头再来或者只能继续写碰运气读 ctx 状态即可定位断点精确续写局部修改想改第二章得把整篇重新吐一遍只重写对应块其余不动还有一个容易被忽略的点成本。一次性生成长文时模型为了保持记得前面写了什么会在上下文里反复回看全文token 消耗指数级上升分块后每块的上下文只有摘要 当前块 指令token 消耗线性可控。写两万字的时候这个差异能明显体现在账单上。4.2 什么时候不该用它任何工具都有边界coauthoring 也不是万能的。我自己的判断标准如下文档小于三四页分块的上下文维护开销反而大于收益直接写更干净需要极度口语化、私人化的内容比如一封短信、一条朋友圈文案不需要工程化流程处于头脑风暴阶段思路可能随时推翻硬套 chunk 清单只会拖慢节奏你本身没有审校的意愿coauthoring 强调 co协作者它默认你会逐块参与修改而不是交出去就完事。换句话说这是一把给认真写长东西的人准备的螺丝刀不是给所有写作场景准备的万能锤子。5. 接入实操从拉仓库到跑通一次长文协作5.1 获取技能并装进 Claude Code第一步还是去官方仓库拿代码命令很直接git clone https://github.com/anthropics/skills.git mkdir -p .claude/skills cp -r skills/document-skills/coauthoring .claude/skills/如果你的项目已经初始化过也可以放在用户级目录让所有项目都能用mkdir -p ~/.claude/skills cp -r skills/document-skills/coauthoring ~/.claude/skills/Claude Code 会自动发现项目目录.claude/skills和用户目录~/.claude/skills下的技能。装好后开一个新会话直接说用 coauthoring 技能帮我把这份大纲扩写成完整文档目标两万字只要请求内容和技能描述匹配它就会进入分块协作流程。如果你发现没有自动触发别慌。一个很实用的兜底办法是在提示里点名技能名称例如请加载 coauthoring 技能进入长文档协作模式。5.2 一次典型会话的完整流程我拿最近一次写技术方案的经历为例把整个流程还原一下我丢了一份只有三级标题的空大纲给 Claude要求最终产出约 15000 字Claude 先回传文档结构分析把大纲里的章节数量、每章预计体量、需要补充的缺失小节列出来并给出分块计划约 12 个块我确认计划后它把 ctx 区块写进文档尾部开始写块 1每写完一块它会短暂停下把摘要更新进 manifest然后继续写下一块写到第 5 块时我觉得某处口径不对直接说块 3 里的术语定义要改它定位到块 3 重写随后把块 4 以后涉及的引用顺带更新。整个流程最舒服的一点是可打断。以前我让模型写长文最怕中途改需求一改就是全文重来分块之后改动被限制在一个块内部成本肉眼可见地小。5.3 顺带学会照着官方 skill 自己写一个如果你在搜索skill 怎么编写那 coauthoring 本身就是一份很值得仿写的范例。一个标准 skill 的三要素SKILL.md 的 YAML 头部name给技能起名description是触发判断的依据要写清楚何时该用、用在什么任务上太含糊会导致该触发时不触发正文指令按步骤描述工作流比如先分析结构→再生成计划→再分块写作参考文件把细节较多的规则比如分块大小的判断标准、摘要写法规范放进 reference 目录按需加载避免占用主指令的篇幅。我自己后来给团队写过内部写作规范 skill骨架完全是从 coauthoring 学来的。有一点特别值得说description 写得越具体触发越准确。别写帮助写文档这种话要写用于超过 5000 字的长文档协作写作支持分块、审校、断点续写这种带条件、带能力边界的描述。6. 我踩过的坑和几条使起来才懂的规矩6.1 摘要写得太抽象等于白写第一次用的时候我发现块 3 写完后 manifest 里只有一句话本章介绍了系统设计。结果块 7 开写时它完全不知道前面定了什么表名、什么接口名直接造了一套新名词。后来我强制要求摘要里必须包含三类信息关键实体名字/编号、关键决策选了 A 没选 B 的原因、关键口径术语定义和边界。好的摘要长这样块3 定义订单状态机包含 pending/paid/cancelled 三态取消订单不触发退款流程退款仅通过 refund API 处理术语订单模块统称 order-service。 坏摘要就是那句本章介绍了系统设计。这条经验同样适用于你自己写任何 skill 或长流程 Agent 的中间状态设计。6.2 块大小、计划粒度、审校节奏三个参数我实测下来的推荐值块大小技术文档 500-1200 字/块比较稳叙事类或偏总结的内容可以放到 1500 字左右。太大了上下文压力重新出现太小了清单本身喧宾夺主计划粒度不要一次性规划 30 个块。先规划 5-8 个块产出部分内容后让模型基于新情况重新拆后续。文档是生长的不是浇筑的审校节奏不要攒到全部写完再慢慢看。每 2-3 个块就把当前文档拉出来通读一遍有问题立刻改。这个节奏下 ctx 区块里的状态永远和你的意图保持同步。顺带一提如果你和我一样用 git 管理文档可以留意一下块 3 完成后的那份提交信息直接写chunk3: 订单状态机 术语表比update doc好一百倍。这是流程带来的额外好处。6.3 几个使起来才懂的通用技巧最后分享几条零散的实操技巧都是我反复用之后沉淀下来的术语表可以放进 manifest 前面的固定位置每写一个块顺带更新长文档的一致性会非常扎实文档尾部的 ctx 区块是命根子任何自动化工具都不要去动它如果你自己写脚本合并文档务必备份好 ctx 再操作如果文档本身非常长比如几万字可以把 manifest 里已完成块的 summary 再做一个总摘要压缩到极简防止 ctx 区块自身越来越臃肿在 Claude Code 里如果技能没有自动触发除了点名之外还可以检查一下当前目录的权限设置——有时候是权限拦住了技能目录的读取。按我个人的经验真正要评估一个技能值不值得用就看它能不能让你写到一半敢停下来。coauthoring 做到了。我不太确定它对所有人都是最优解但对经常和长文档、大方案打交道的人来说这个官方技能至少提供了一条比硬背上下文可靠得多的路。如果你也正被长文写作的一致性问题折磨不妨照着上面的流程跑一遍再根据自己的节奏调整块的大小和摘要的写法。