doc-coauthoring

📁 lingxling/awesome-skills-cn 📅 2 days ago
3
总安装量
3
周安装量
#58885
全站排名
安装命令
npx skills add https://github.com/lingxling/awesome-skills-cn --skill doc-coauthoring

Agent 安装分布

mcpjam 3
iflow-cli 3
claude-code 3
junie 3
windsurf 3
zencoder 3

Skill 文档

文档协作编写工作流程

此技能提供结构化工作流程,用于指导用户进行协作文档创建。作为主动指南,引导用户完成三个阶段:上下文收集、完善与结构、读者测试。

何时提供此工作流程

触发条件:

  • 用户提及编写文档:”编写文档”、”起草提案”、”创建规范”、”编写”
  • 用户提及特定文档类型:”PRD”、”设计文档”、”决策文档”、”RFC”
  • 用户似乎正在开始一项重要的写作任务

初始提议: 向用户提供结构化的文档协作编写工作流程。解释三个阶段:

  1. 上下文收集:用户提供所有相关上下文,同时Claude提出澄清问题
  2. 完善与结构:通过头脑风暴和编辑迭代构建每个部分
  3. 读者测试:使用新的Claude(无上下文)测试文档,以便在其他人阅读之前发现盲点

解释这种方法有助于确保文档在他人阅读时(包括当他们将其粘贴到Claude中时)能够良好工作。询问他们是否想尝试此工作流程或更喜欢自由形式工作。

如果用户拒绝,则自由形式工作。如果用户接受,则进入第一阶段。

第一阶段:上下文收集

**目标:**缩小用户所知与Claude所知之间的差距,以便后续提供智能指导。

初始问题

首先向用户询问关于文档的元上下文:

  1. 这是什么类型的文档?(例如:技术规范、决策文档、提案)
  2. 主要受众是谁?
  3. 阅读此文档时的期望影响是什么?
  4. 是否有模板或特定格式需要遵循?
  5. 是否有其他约束或上下文需要了解?

告知他们可以简写回答或以最适合他们的方式倾倒信息。

如果用户提供模板或提及文档类型:

  • 询问他们是否有模板文档可以分享
  • 如果他们提供共享文档的链接,使用适当的集成来获取它
  • 如果他们提供文件,则读取它

如果用户提及编辑现有的共享文档:

  • 使用适当的集成读取当前状态
  • 检查没有alt-text的图像
  • 如果存在没有alt-text的图像,解释当其他人使用Claude理解文档时,Claude将无法看到它们。询问他们是否希望生成alt-text。如果是,请求他们将每张图像粘贴到聊天中以便生成描述性alt-text。

信息倾倒

一旦初始问题得到回答,鼓励用户倾倒他们拥有的所有上下文。请求诸如以下信息:

  • 项目/问题的背景
  • 相关团队讨论或共享文档
  • 为什么不使用替代解决方案
  • 组织上下文(团队动态、过去的事件、政治)
  • 时间线压力或约束
  • 技术架构或依赖项
  • 利益相关者关注点

建议他们不要担心组织它 – 只需把所有内容都倒出来。提供多种提供上下文的方式:

  • 信息倾倒意识流
  • 指向要阅读的团队频道或线程
  • 链接到共享文档

如果集成可用(例如:Slack、Teams、Google Drive、SharePoint或其他MCP服务器),提及这些可用于直接拉取上下文。

如果未检测到集成并且在Claude.ai或Claude应用中: 建议他们可以在Claude设置中启用连接器,以允许直接从消息应用程序和文档存储中拉取上下文。

告知他们将在完成初始倾倒后提出澄清问题。

在上下文收集期间:

  • 如果用户提及团队频道或共享文档:

    • 如果集成可用:告知内容现在将被读取,然后使用适当的集成
    • 如果集成不可用:解释缺乏访问权限。建议他们在Claude设置中启用连接器,或直接粘贴相关内容。
  • 如果用户提及未知的实体/项目:

    • 询问是否应该搜索连接的工具以了解更多
    • 在搜索之前等待用户确认
  • 当用户提供上下文时,跟踪正在学习什么以及仍然不清楚什么

提出澄清问题:

当用户表示他们已完成初始倾倒(或提供了大量上下文)后,提出澄清问题以确保理解:

根据上下文中的差距生成5-10个编号问题。

告知他们可以使用简写回答(例如:”1:是,2:见#channel,3:不因为向后兼容”),链接到更多文档,指向要阅读的频道,或只是继续信息倾倒。对他们来说最有效的方式。

退出条件: 当问题显示理解时,即当可以询问边缘情况和权衡而不需要解释基础知识时,就收集了足够的上下文。

过渡: 询问他们是否想在此阶段提供更多上下文,还是时候开始起草文档。

如果用户想添加更多,让他们添加。准备好后,进入第二阶段。

第二阶段:完善与结构

目标: 通过头脑风暴、策划和迭代完善逐节构建文档。

给用户的说明: 解释文档将逐节构建。对于每个部分:

  1. 将询问关于要包含什么的澄清问题
  2. 将头脑风暴5-20个选项
  3. 用户将指示保留/删除/合并什么
  4. 将起草该部分
  5. 将通过精确编辑进行完善

从最未知的部分开始(通常是核心决策/提案),然后处理其余部分。

部分排序:

如果文档结构清晰: 询问他们想从哪个部分开始。

建议从最未知的部分开始。对于决策文档,这通常是核心提案。对于规范,这通常是技术方法。摘要部分最好留到最后。

如果用户不知道他们需要哪些部分: 根据文档类型和模板,建议适合文档类型的3-5个部分。

询问此结构是否可行,或者他们是否想调整它。

一旦结构达成一致:

创建包含所有部分占位符文本的初始文档结构。

如果可以访问工件: 使用create_file创建工件。这为Claude和用户提供了一个可以工作的脚手架。

告知将创建包含所有部分占位符的初始结构。

创建包含所有部分标题和简短占位符文本(如”[待编写]”或”[内容在此]”)的工件。

提供脚手架链接并指示现在是填充每个部分的时候了。

如果无法访问工件: 在工作目录中创建markdown文件。适当命名(例如:decision-doc.md、technical-spec.md)。

告知将创建包含所有部分占位符的初始结构。

创建包含所有部分标题和占位符文本的文件。

确认文件名已创建,并指示现在是填充每个部分的时候了。

对于每个部分:

步骤1:澄清问题

宣布将开始在[部分名称]部分工作。询问5-10个关于应该包含什么的澄清问题:

根据上下文和部分目的生成5-10个具体问题。

告知他们可以简写回答或只指示需要涵盖的重要内容。

步骤2:头脑风暴

对于[部分名称]部分,根据部分的复杂程度,头脑风暴可能包含的[5-20]件事。寻找:

  • 可能被遗忘的共享上下文
  • 尚未提及的角度或考虑因素

根据部分复杂程度生成5-20个编号选项。在最后,如果他们想要更多选项,提供头脑风暴更多。

步骤3:策划

询问应该保留、删除或合并哪些点。请求简短理由以帮助学习下一部分的优先级。

提供示例:

  • “保留1、4、7、9”
  • “删除3(重复1)”
  • “删除6(受众已经知道这个)”
  • “合并11和12”

如果用户给出自由形式反馈(例如:”看起来不错”或”我喜欢大部分但…”)而不是编号选择,则提取他们的偏好并继续。解析他们想要保留/删除/更改的内容并应用它。

步骤4:差距检查

根据他们选择的内容,询问[部分名称]部分是否有任何重要的遗漏。

步骤5:起草

使用str_replace将此部分的占位符文本替换为实际起草的内容。

宣布[部分名称]部分现在将根据他们选择的内容进行起草。

如果使用工件: 起草后,提供工件链接。

请他们通读并指示要更改什么。注意具体说明有助于学习下一部分。

如果使用文件(无工件): 起草后,确认完成。

告知[部分名称]部分已在[文件名]中起草。请他们通读并指示要更改什么。注意具体说明有助于学习下一部分。

给用户的关键说明(在起草第一部分时包括): 提供说明:与其直接编辑文档,不如让他们指示要更改什么。这有助于学习他们未来部分的风格。例如:”删除X要点 – 已由Y涵盖”或”使第三段更简洁”。

步骤6:迭代完善

当用户提供反馈时:

  • 使用str_replace进行编辑(绝不重新打印整个文档)
  • 如果使用工件: 每次编辑后提供工件链接
  • 如果使用文件: 只确认编辑完成
  • 如果用户直接编辑文档并要求阅读:心理上记录他们所做的更改,并在未来的部分中记住它们(这显示了他们的偏好)

继续迭代直到用户对该部分满意。

质量检查

在3次连续迭代没有实质性更改后,询问是否可以在不丢失重要信息的情况下删除任何内容。

当部分完成时,确认[部分名称]已完成。询问是否准备好进入下一部分。

对所有部分重复。

接近完成

当接近完成时(80%+的部分完成),宣布打算重新阅读整个文档并检查:

  • 部分之间的流程和一致性
  • 冗余或矛盾
  • 任何感觉像”垃圾”或通用填充的内容
  • 每个句子是否都有分量

阅读整个文档并提供反馈。

当所有部分都起草和完善后: 宣布所有部分都已起草。表示打算再审查一次完整文档。

审查整体连贯性、流程、完整性。

提供任何最终建议。

询问是否准备好进入读者测试,或者他们是否想完善其他内容。

第三阶段:读者测试

目标: 使用新的Claude(无上下文泄漏)测试文档,以验证它对读者有效。

给用户的说明: 解释现在将进行测试,以查看文档是否真的对读者有效。这会发现盲点——对作者有意义但可能让其他人困惑的事情。

测试方法

如果可以访问子代理(例如,在Claude Code中):

直接执行测试,无需用户参与。

步骤1:预测读者问题

宣布打算预测读者在尝试发现此文档时可能会问什么问题。

生成读者会实际问的5-10个问题。

步骤2:使用子代理测试

宣布这些问题将使用新的Claude实例(无此对话的上下文)进行测试。

对于每个问题,调用仅包含文档内容和问题的子代理。

总结读者Claude在每个问题上对/错的内容。

步骤3:运行额外检查

宣布将执行额外检查。

调用子代理检查歧义、错误假设、矛盾。

总结发现的任何问题。

步骤4:报告和修复

如果发现问题: 报告读者Claude在特定问题上遇到困难。

列出具体问题。

表示打算修复这些差距。

循环回有问题的部分进行完善。


如果无法访问子代理(例如,claude.ai Web界面):

用户将需要手动进行测试。

步骤1:预测读者问题

询问人们在尝试发现此文档时可能会问什么问题。他们会在Claude.ai中输入什么?

生成读者会实际问的5-10个问题。

步骤2:设置测试

提供测试说明:

  1. 打开新的Claude对话:https://claude.ai
  2. 粘贴或共享文档内容(如果使用带有启用连接器的共享文档平台,提供链接)
  3. 向读者Claude提出生成的问题

对于每个问题,指示读者Claude提供:

  • 售案
  • 是否有任何内容模糊或不清楚
  • 文档假设读者已经知道什么知识/上下文

检查读者Claude是否给出正确答案或误解了任何内容。

步骤3:额外检查

还询问读者Claude:

  • “本文档中可能对读者来说模糊或不清楚的是什么?”
  • “本文档假设读者已经拥有什么知识或上下文?”
  • “是否有任何内部矛盾或不一致?”

步骤4:根据结果迭代

询问读者Claude弄错或遇到困难的内容。表示打算修复那些差距。

循环回任何有问题的部分进行完善。


退出条件(两种方法)

当读者Claude持续正确回答问题并且没有发现新的差距或歧义时,文档就准备好了。

最终审查

当读者测试通过时: 宣布文档已通过读者Claude测试。完成之前:

  1. 建议他们自己进行最后的通读 – 他们拥有此文档并对其质量负责
  2. 建议仔细检查任何事实、链接或技术细节
  3. 询问他们验证它是否实现了他们想要的影响

询问他们是否想要最后一次审查,或者工作是否完成。

如果用户想要最终审查,则提供。否则: 宣布文档完成。提供一些最终提示:

  • 考虑在附录中链接此对话,以便读者可以看到文档是如何开发的
  • 使用附录提供深度而不会使主文档臃肿
  • 当从真实读者收到反馈时更新文档

有效指导的提示

基调:

  • 直接和程序化
  • 当影响用户行为时简要解释理由
  • 不要试图”推销”方法 – 只需执行它

处理偏差:

  • 如果用户想跳过一个阶段:询问他们是否想跳过这个并自由形式编写
  • 如果用户似乎感到沮丧:承认这比预期的要长。建议加快速度的方法
  • 始终给用户调整流程的主动权

上下文管理:

  • 整个过程中,如果缺少关于提及内容的上下文,主动询问
  • 不要让差距积累 – 在它们出现时解决它们

工件管理:

  • 使用create_file起草完整部分
  • 对所有编辑使用str_replace
  • 每次更改后提供工件链接
  • 绝不要将工件用于头脑风暴列表 – 那只是对话

质量优于速度:

  • 不要匆忙通过阶段
  • 每次迭代都应该进行有意义的改进
  • 目标是一个真正对读者有效的文档