doc-coauthoring 是”工作流即代码”型的纯指令 Skill——375 行 SKILL.md 编码了完整的文档协作方法论：从上下文收集到逐节精炼再到读者测试，Claude 作为主动引导者而非被动工具陪伴用户完成文档创作全过程。
- 🧭 三阶段工作流：上下文收集（Context Gathering）→ 精炼与结构（Refinement & Structure）→ 读者测试（Reader Testing）
- 🧩 逐节构建：每节 6 步流程——澄清问题 → 头脑风暴 → 筛选 → 差距检查 → 起草 → 迭代精炼
- 🧪 读者测试：用全新的 Claude 测试文档是否真正可读——发现创作者盲区
- 🔄 自适应流程：用户可随时跳过、调整或退出——始终保持用户主导权
- 📎 Artifact 集成：支持
create_file创建脚手架、str_replace精确编辑、Artifact 链接导航
当用户提到”写文档”、“起草提案”、“创建设计文档”、“编写 PRD”、“写 RFC”、“写技术规格”等文档协作任务时触发。
One-Line Summary
Section titled “One-Line Summary”doc-coauthoring is a “workflow as code” pure-instruction Skill — 375 lines of SKILL.md encoding a complete documentation co-authoring methodology: from context gathering to section-by-section refinement to reader testing, with Claude acting as an active guide rather than a passive tool throughout the entire document creation process.
Core Capabilities
Section titled “Core Capabilities”- 🧭 Three-Stage Workflow: Context Gathering → Refinement & Structure → Reader Testing
- 🧩 Section-by-Section Building: 6-step process per section — clarifying questions → brainstorming → curation → gap check → drafting → iterative refinement
- 🧪 Reader Testing: Testing documents with a fresh Claude instance to catch creator blind spots
- 🔄 Adaptive Flow: Users can skip, adjust, or exit at any point — user agency is always maintained
- 📎 Artifact Integration: Supports
create_filefor scaffolding,str_replacefor surgical edits, Artifact link navigation
Trigger Scenarios
Section titled “Trigger Scenarios”Triggers when users mention “write a doc”, “draft a proposal”, “create a design doc”, “write a PRD”, “write an RFC”, “write a technical spec” or similar document collaboration tasks.
File Inventory
Section titled “File Inventory”- doc-coauthoring
目录结构分析
Section titled “目录结构分析”doc-coauthoring 是单体”工作流即代码”型 Skill——全部 375 行逻辑都集中在 SKILL.md 中，没有任何脚本、模板或外部文件。
这在所有技能中是独一无二的：它既没有脚本，也不是简单的”纯指令”。它是一个完整的方法论编码——将一个人工引导的文档协作流程精确地编码为 Markdown 指令。
SKILL.md 结构解析
Section titled “SKILL.md 结构解析”375 行的 SKILL.md 是当前学习中心中最长的单文件 skill。其结构呈现清晰的三阶段+辅助章节的布局：
Stage 1：上下文收集（Context Gathering）——约 97 行
Section titled “Stage 1：上下文收集（Context Gathering）——约 97 行”SKILL.md 最详细的阶段，指导 Claude 首先缩小”信息差”：
- 初始问题（5 个）：文档类型、受众、期望影响力、模板、约束——系统性地收集元上下文
- 信息倾泻（Info Dumping）：鼓励用户自由输出所有背景信息，无需关注组织方式
- 澄清问题：基于收集的上下文生成 5-10 个针对性问题
- 退出条件：当 Claude 能问出”边缘案例和权衡”级别的问题时，信息收集完成
这一阶段的精细度（占全文约 26%）反映了该 skill 的核心理念：好的文档始于彻底的理解。
Stage 2：精炼与结构（Refinement & Structure）——约 138 行
Section titled “Stage 2：精炼与结构（Refinement & Structure）——约 138 行”这是最长且最详细的阶段，定义了逐节构建文档的 6 步循环：
- 澄清问题：每节开始前问 5-10 个针对性问题
- 头脑风暴：生成 5-20 个可能的要点
- 筛选：用户选择保留/删除/合并
- 差距检查：问是否有遗漏的重要内容
- 起草：使用
str_replace替换占位文本 - 迭代精炼：用户反馈 → 精确编辑 → 直到满意
再加上质量检查（3 轮无实质修改后问”能否删减”）和最终通读审查。
Stage 3：读者测试（Reader Testing）——约 90 行
Section titled “Stage 3：读者测试（Reader Testing）——约 90 行”最有创意的阶段——用无上下文的”新鲜 Claude”测试文档的可读性：
- 预测读者问题：生成 5-10 个读者可能问的问题
- 子代理测试（Claude Code）：直接用新子代理测试每个问题
- 手动测试（claude.ai）：给用户测试指引自行操作
- 报告与修复：汇总问题，返回 Stage 2 修复
- Final Review：最终建议（事实核实、读者测试通过后的收尾步骤）
- Tips（约 25 行）：语气指导、异常处理、上下文管理、Artifact 操作提示
三阶段工作流示意图
Section titled “三阶段工作流示意图”Directory Structure Analysis
Section titled “Directory Structure Analysis”doc-coauthoring is a monolithic “workflow as code” Skill — all 375 lines of logic concentrated in a single SKILL.md, with no scripts, templates, or external files.
This is unique among all skills: it has neither scripts nor simple “pure instructions”. It is a complete methodology encoding — precisely encoding a human-guided document collaboration workflow into Markdown instructions.
SKILL.md Structure Analysis
Section titled “SKILL.md Structure Analysis”375 lines of SKILL.md make it the longest single-file skill in the learning center. Its structure follows a clear three-stage + supplementary layout:
Stage 1: Context Gathering (~97 lines)
Section titled “Stage 1: Context Gathering (~97 lines)”The most detailed stage in SKILL.md, guiding Claude to first close the “knowledge gap”:
- Initial Questions (5): document type, audience, desired impact, template, constraints — systematically gathering meta-context
- Info Dumping: encouraging users to freely output all background information without worrying about organization
- Clarifying Questions: generating 5-10 targeted questions based on gathered context
- Exit Condition: information gathering complete when Claude can ask about “edge cases and trade-offs”
The depth of this stage (~26% of the full text) reflects the core philosophy: good documents start with thorough understanding.
Stage 2: Refinement & Structure (~138 lines)
Section titled “Stage 2: Refinement & Structure (~138 lines)”The longest and most detailed stage, defining a 6-step loop for section-by-section document construction:
- Clarifying Questions: 5-10 targeted questions before each section
- Brainstorming: 5-20 possible points
- Curation: User selects keep/remove/combine
- Gap Check: Ask if anything important is missing
- Drafting: Using
str_replaceto replace placeholder text - Iterative Refinement: User feedback → surgical edits → until satisfied
Plus quality checks (ask “can anything be removed” after 3 rounds with no substantial changes) and final full-read review.
Stage 3: Reader Testing (~90 lines)
Section titled “Stage 3: Reader Testing (~90 lines)”The most innovative stage — testing document readability with a “fresh” Claude that has no context:
- Predict Reader Questions: generate 5-10 questions readers might ask
- Sub-agent Testing (Claude Code): directly test each question with a new sub-agent
- Manual Testing (claude.ai): provide testing instructions for users to do it themselves
- Report and Fix: aggregate issues, return to Stage 2 to fix
Supplementary Sections
Section titled “Supplementary Sections”- Final Review: final recommendations (fact-checking, closing steps after reader testing passes)
- Tips (~25 lines): tone guidance, deviation handling, context management, Artifact operation tips
Three-Stage Workflow Diagram
Section titled “Three-Stage Workflow Diagram”| 阶段 | 目标 | 关键活动 | 大约行数 |
|---|---|---|---|
| Stage 1: Context Gathering | 缩小信息差 | 初始问题 → 信息倾泻 → 澄清问题 | ~97 行 |
| Stage 2: Refinement & Structure | 逐节构建完成文档 | 6 步循环 × 每节 → 质量检查 → 通读 | ~138 行 |
| Stage 3: Reader Testing | 找到创作者盲区 | 预测问题 → 测试 → 报告 → 修复 | ~90 行 |
| Final Review + Tips | 收尾与持续改进 | 最终建议 + 异常处理提示 | ~50 行 |
| Stage | Goal | Key Activities | Approx. Lines |
|---|---|---|---|
| Stage 1: Context Gathering | Close the knowledge gap | Initial questions → Info dump → Clarifying questions | ~97 lines |
| Stage 2: Refinement & Structure | Complete document section by section | 6-step loop × each section → QC → Full read | ~138 lines |
| Stage 3: Reader Testing | Find creator blind spots | Predict questions → Test → Report → Fix | ~90 lines |
| Final Review + Tips | Closing and continuous improvement | Final recommendations + exception handling tips | ~50 lines |
doc-coauthoring 不包含任何脚本、模板或资产文件。
“工作流即代码”模式深度分析
Section titled ““工作流即代码”模式深度分析”这是唯一采用**“工作流即代码”**模式的技能——375 行 SKILL.md 编码的不是”如何做某件事”的操作指南，而是”如何引导用户完成复杂创作过程”的方法论。
它与”纯指令”的关系
Section titled “它与”纯指令”的关系”虽然 doc-coauthoring 没有脚本，但它与 brand-guidelines 那样的纯指令有本质区别：
- 纯指令型（如 brand-guidelines）：告诉 Claude “做什么”（应用这些品牌规则）
- 工作流即代码型（如 doc-coauthoring）：告诉 Claude “怎么引导”（按这个流程串起对话）
doc-coauthoring 的 SKILL.md 是元指令——它不直接生成内容，而是定义 Claude 与用户的交互协议。
没有脚本的原因
Section titled “没有脚本的原因”- 工作流是对话性的：文档协作的本质是对话和迭代，不是数据处理——不需要脚本
- 输出由用户上下文决定：每份文档的内容完全取决于用户提供的上下文，无法预编码
- 引导比执行为重：skill 的核心价值在于”如何引导用户思考”，而非”如何自动生成”
- 复杂性在流程而非计算：375 行的复杂在于工作流细节（退出条件、异常处理、质量判断），而非算法逻辑
关于 375 行的设计决策
Section titled “关于 375 行的设计决策”这是 SKILL.md 中最长的单文件。为什么这么长？
- 每个阶段都有精确的退出条件：不是简单的”做完就继续”，而是有可判断的标准（“当 Claude 能问边缘案例问题”）
- 两套执行路径：子代理可用和不可用的完整分支——覆盖 Claude Code 和 claude.ai 两种环境
- 深度嵌入”如何指导”的细节：语气、异常处理、示例对话——让 Claude 的行为像有经验的导师而非机器
- Artifact 操作的精确规范：何时用
create_file、何时用str_replace、何时提供链接
Script Inventory
Section titled “Script Inventory”doc-coauthoring contains no scripts, templates, or asset files.
Deep Analysis of the “Workflow as Code” Pattern
Section titled “Deep Analysis of the “Workflow as Code” Pattern”This is the only skill adopting the “Workflow as Code” pattern — 375 lines of SKILL.md encoding not “how to do something” operational guidelines, but “how to guide users through a complex creative process” methodology.
Relationship with “Pure Instruction”
Section titled “Relationship with “Pure Instruction””Although doc-coauthoring has no scripts, it differs fundamentally from skills like brand-guidelines:
- Pure Instruction (e.g., brand-guidelines): tells Claude “what to do” (apply these brand rules)
- Workflow as Code (e.g., doc-coauthoring): tells Claude “how to guide” (orchestrate conversation flow)
doc-coauthoring’s SKILL.md is meta-instruction — it doesn’t directly generate content, but defines Claude’s interaction protocol with the user.
Why No Scripts
Section titled “Why No Scripts”- Workflow is conversational: Document collaboration is inherently about conversation and iteration, not data processing — no scripts needed
- Output is user-context-dependent: Every document’s content depends entirely on user-provided context, cannot be pre-encoded
- Guidance over execution: The skill’s core value lies in “how to guide user thinking”, not “how to auto-generate”
- Complexity in process, not computation: The 375 lines’ complexity lies in workflow details (exit conditions, exception handling, quality judgment), not algorithmic logic
The Design Decision Behind 375 Lines
Section titled “The Design Decision Behind 375 Lines”This is the longest single file SKILL.md in the collection. Why so long?
- Precise exit conditions for each stage: Not simple “continue when done”, but judgeable criteria (“when Claude can ask about edge cases”)
- Two execution paths: Complete branches for sub-agent available and unavailable — covering both Claude Code and claude.ai environments
- Deeply embedded “how to guide” details: Tone, exception handling, example conversations — making Claude behave like an experienced mentor rather than a machine
- Precise Artifact operation specifications: When to use
create_file, when to usestr_replace, when to provide links
| 对比维度 | 纯指令型 | 工作流即代码型 |
|---|---|---|
| 指令焦点 | Claude 输出什么（What） | Claude 如何引导（How to guide） |
| SKILL.md 长度 | 通常 < 100 行 | 375 行（最长的单文件） |
| 用户交互 | 一次性输出结果 | 多轮迭代对话 |
| 核心价值 | 规则和约束的精确性 | 引导和流程的完整性 |
| 复杂度来源 | 参数和规则的数量 | 分支、退出条件和异常处理 |
| 最佳场景 | 品牌规则、格式转换 | 文档协作、创意引导 |
| Dimension | Pure Instruction | Workflow as Code |
|---|---|---|
| Instruction Focus | What Claude outputs | How Claude guides |
| SKILL.md Length | Typically < 100 lines | 375 lines (longest single file) |
| User Interaction | One-shot output | Multi-turn iterative conversation |
| Core Value | Precision of rules and constraints | Completeness of guidance and flow |
| Complexity Source | Number of parameters and rules | Branches, exit conditions, exception handling |
| Best For | Brand rules, format conversion | Document collaboration, creative guidance |
- “工作流即代码”模式：375 行 Markdown 编码了一个完整的文档协作方法论——将人类”最佳实践”转化为 AI 可执行的交互协议
- 三阶段递进设计：Context → Refinement → Testing，每个阶段的输出是下一个阶段的输入——逻辑严密且不可逆
- 读者测试的创新：用”新鲜 Claude”测试文档可读性——这是人类协作中”找同事帮忙看看”的 AI 版本，极具创意
- 6 步精炼循环：每节 6 步（澄清→头脑风暴→筛选→差距→起草→迭代）——结构固定但内容可适应任何文档类型
- 双路径执行：子代理可用（Claude Code 自动测试）和不可用（claude.ai 指导用户手动测试）——覆盖所有使用场景
- 用户始终主导：可随时跳过阶段、自由选择节顺序、用简答回答复杂问题——不让方法论变成束缚
“如果你想创建类似的引导式工作流 Skill…”
- 识别可方法论的流程：寻找可重复的”最佳实践”流程——不仅仅是”做什么”，还包括”如何做决策”和”何时退出”
- 定义阶段和退出条件：将流程分解为 3-5 个阶段，每个阶段有明确的进入条件和退出判断标准
- 编写分支执行路径：考虑工具可用和不可用两种场景——确保在任何环境中都能工作
- 嵌入引导细节：语气、提示示例、异常处理——让 AI 的行为像有经验的人类引导者
- 保持用户自主权：任何时候都要提供”跳过”或”自由创作”的选项——不能让方法论变成负担
⚠️ 指令过长可能导致 Claude 选择性忽略： 375 行的 SKILL.md 包含大量细节，Claude 可能在执行中简化——需要考虑分阶段加载或更清晰的层级
⚠️ 读者测试依赖子代理可用性： Claude Code 有子代理支持，claude.ai 只能依赖用户手动测试——后者体验和可靠性都大打折扣
⚠️ 逐节循环可能显得冗长： 6 步 × 5+ 节 = 30+ 次交互——文档协作本身是耗时的，但用户可能对流程满意度下降
⚠️ 退出条件判断主观： “能问边缘案例问题”是主观标准——不同 Claude 实例可能有不同的”足够好”判断
⚠️ 模板处理较弱： 模板处理部分相对简单（只是读取文件），但对”有格式要求”的文档协作来说，模板集成可能是用户的关键需求
Design Highlights
Section titled “Design Highlights”- “Workflow as Code” Pattern: 375 lines of Markdown encoding a complete document collaboration methodology — transforming human “best practices” into AI-executable interaction protocols
- Three-Stage Progressive Design: Context → Refinement → Testing, each stage’s output is the next stage’s input — logically tight and irreversible
- Reader Testing Innovation: Testing document readability with a “fresh Claude” — it’s the AI version of “ask a colleague to look this over” from human collaboration, extremely creative
- 6-Step Refinement Loop: 6 steps per section (clarify → brainstorm → curate → gap check → draft → iterate) — fixed structure but adaptable content for any document type
- Dual Execution Paths: Sub-agent available (Claude Code auto-test) and unavailable (claude.ai manual test guidance) — covering all usage scenarios
- User Always in Control: Skip stages freely, choose section order, answer complex questions with shorthand — methodology never becomes a constraint
Reusable Patterns
Section titled “Reusable Patterns”Porting Guide
Section titled “Porting Guide”“If you want to create a similar guided workflow Skill…”
- Identify methodizable processes: Look for repeatable “best practice” workflows — not just “what to do”, but “how to make decisions” and “when to exit”
- Define stages and exit conditions: Break flow into 3-5 stages, each with clear entry conditions and exit judgment criteria
- Write branched execution paths: Consider tool-available and tool-unavailable scenarios — ensure it works in any environment
- Embed guidance details: Tone, prompt examples, exception handling — make AI behave like an experienced human facilitator
- Maintain user agency: Always provide “skip” or “freeform” options — methodology should never become a burden
Common Pitfalls
Section titled “Common Pitfalls”⚠️ Long instructions may lead to selective ignoring by Claude: 375-line SKILL.md contains many details, Claude may simplify during execution — consider staged loading or clearer hierarchy
⚠️ Reader testing depends on sub-agent availability: Claude Code has sub-agent support, claude.ai relies on manual user testing — experience and reliability suffer in the latter
⚠️ Section-by-section loops can feel lengthy: 6 steps × 5+ sections = 30+ interactions — document collaboration is inherently time-consuming, but users may grow less satisfied with the process
⚠️ Exit condition judgment is subjective: “Can ask about edge cases” is a subjective standard — different Claude instances may have different “good enough” judgments
⚠️ Template handling is weak: The template handling section is relatively simple (just reading files), but for “format-constrained” document collaboration, template integration may be a key user need
| 模式 | 说明 | 适用于... |
|---|---|---|
| 工作流即代码 | 将完整引导方法论编码为 Markdown 指令 | 需要多轮交互的引导型技能（文档协作、设计评审） |
| 三阶段递进 | 输入→处理→验证的严格递进结构 | 产出质量关键且需要验证的场景 |
| 6 步精炼循环 | 标准化但内容可适应的逐节构建循环 | 需逐部分构建复杂产出的场景 |
| 读者测试 | 用"新鲜 AI"测试输出的可理解性 | 文档、教程、说明类产出的质量保障 |
| 双路径执行 | 工具可用和不可用两套执行方案 | 需同时支持 CLI 和 Web 使用场景的 skill |
| Pattern | Description | Applies to... |
|---|---|---|
| Workflow as Code | Encode complete guidance methodology into Markdown instructions | Guidance skills needing multi-turn interaction (doc collaboration, design review) |
| Three-Stage Progressive | Strict progressive structure: input → process → verify | Scenarios where output quality is critical and needs validation |
| 6-Step Refinement Loop | Standardized but content-adaptable section-by-section build cycle | Scenarios requiring complex, section-by-section output construction |
| Reader Testing | Test output comprehensibility with a "fresh AI" | Quality assurance for documentation, tutorials, instructional content |
| Dual Execution Path | Two execution plans: tool available vs unavailable | Skills needing to support both CLI and web usage scenarios |