用 doc-author Skill 为 AI 驱动文档写作立规矩：InsForge 开源仓库的文档维护实战指南-创锋一号

用 doc-author Skill 为 AI 驱动文档写作立规矩：InsForge 开源仓库的文档维护实战指南

【免费下载链接】InsForgeThe all-in-one, open-source backend platform for agentic coding. InsForge gives your coding agent database, auth, storage, compute, hosting, and AI gateway to ship full-stack apps end-to-end.项目地址: https://gitcode.com/GitHub_Trending/in/InsForge

本篇技术指南围绕 InsForge 开源仓库中的doc-author技能定义文件展开，讲解一套可供 Claude Code 等 Agent 直接加载执行的文档写作规范：从操作模式、核心原则、写作标准到 Mintlify 组件约定与验证护栏，全流程可落地。读完本文，你将理解如何借助SKILL.md这类"技能即规范"的机制，让 AI 与人类协作出产事实准确、风格统一、可直接发布的技术文档，并掌握 InsForge 仓库中该技能的本地化覆盖（INSFORGE.md）与上游同步脚本的运作方式。

技能从哪来：一份 460 行 SKILL.md 的构成

.claude/skills/doc-author/SKILL.md是 InsForge 仓库.claude/skills/目录下的一个技能（Skill）入口文件，由 Mintlify 官方文档技能逐字拷贝（vendored）而来，头部注释明确标注了上游来源、提交 SHA（commit 877f90193ea1）与 MIT 许可证。它在仓库中的角色，是指导贡献者"写、编辑和维护文档"，覆盖从与人类协作起草，到自主写作并走 PR 评审的全流程。

一个 Skill 文件的标准骨架由两部分组成：

YAML frontmatter（元数据区），见 SKILL.md 第 1-10 行：

字段	取值	含义
`name`	`doc-author`	技能唯一名称，Agent 据此识别与加载
`description`	一段英文描述	说明技能用途，并声明默认协作模式、由 Mintlify 构建
`license`	`MIT`	许可证声明，决定能否被第三方仓库引入
`compatibility`	需要 git 访问与创建 PR 的能力	声明运行前提：支持任何 Markdown/MDX 文档，针对 Mintlify 文档站优化
`metadata`	author、url、version`"0.2"`	归属与版本号

正文（Markdown 指令区），从第 24 行# Write and maintain documentation开始，包含操作模式、核心原则、写作标准、Mintlify 约定、验证护栏、工作流、常见任务与正反示例。这部分才是 Agent 实际执行的"行为规范"。

仓库的.claude/skills/README.md说明了技能目录的组织方式：Claude Code（及兼容 Agent）会自动发现该目录下的技能，每个子目录一个技能，入口统一为SKILL.md。同时 README 特别区分了两种身份：.claude/skills/是仓库内部贡献者技能，与 CLAUDE_PLUGIN.md 描述的公开发布插件（存放于独立仓库）不是一回事，不应混用。

两种操作模式：默认协作，授权才自主

原文档开篇定义的第一个概念就是操作模式，它决定了 Agent 在整个写作过程中的行为边界。

协作模式（默认）

不主动请求自主权时，Agent 以协作者身份工作，人类主导决策，Agent 负责辅助：

起草内容供人类精修
给出带有清晰理由的改进建议
在假设前先提出澄清问题
存在权衡时提供备选方案
指出风险但不阻塞进度

自主模式

只有满足以下条件之一才启用自主模式：

任务被显式委托（例如指派给你的 Linear issue）
人类明确说"直接写"或"放手去写"
你拿到一份无歧义的清晰简报

自主模式下，Agent 需要写出完整文档并提交 PR、为无法验证的内容添加 TODO 注释、在 PR 描述中标注不确定性，且绝不直接提交到主干，永远走 PR 评审。

当两种模式都说得通时，规则是"默认协作"。这一设计在 InsForge 这类多人开源仓库中的价值很明显：文档修改往往牵涉多语言页面、导航结构和产品语义，先与人对齐再动手，能避免大量返工。

六条核心原则：只写能验证的内容

Core principles一节给出了 Agent 写文档时必须遵守的底线，这也是全文最重要的判断标准：

只记录你能验证的内容。无法从代码库或用户明确输入确认的东西不写，留 TODO。
写得刚刚好。帮助用户成功并回到正事，更多文档不等于更好文档。
匹配既有模式。动笔前先读周边内容，一致性优先于个人偏好。
标注不确定性。不确定时，协作模式提问，自主模式加 TODO。
先问再假设。不清楚就问，不要猜产品行为、用户需求或组织偏好。
解释你的理由。提出修改时说明为什么，帮助他人学习并做出更好的决定。

在 InsForge 仓库中，这条原则被进一步强化。.claude/skills/doc-author/SKILL.md是上游的逐字拷贝，头部注释明确写着"Do not edit the prose below — local conventions go in ./INSFORGE.md"（不要编辑下面的正文，本地约定放在./INSFORGE.md），也就是说：全局规范与本地约定分层存放，上游正文不可手改，InsForge 特有的约定统一收在.claude/skills/doc-author/INSFORGE.md，两者冲突时本地覆盖仅在冲突处生效。

写作前的准备：先回答三个问题，再读两三个页面

原文档强调"Before you write"阶段要做三件事：

确认上下文足够。动笔前必须能回答：这个功能或概念是什么？谁需要这份文档？读者读完应能做什么？答不上来时，协作模式问人类，自主模式停下升级。

检查存量内容。创建新页面前先搜索现有文档，可能需要：更新已有页面而不是新建、给已有页面加一节、链接到已有内容而不是重复造轮子。

阅读周边内容。写作前读 2-3 个相似页面，理解语气与语调模式、结构与格式约定、提供的细节深度、组件用法模式。

这三条在 InsForge 的文档树里都有活样本。例如 docs/sdks/typescript/auth.mdx 是 SDK 参考风格的代表（frontmatter 只有title和description，参数用### Parameters下的无序列表）；docs/quickstart.mdx 是命令式第二人称语气的范例；docs/core-concepts/storage/s3-compatibility.mdx 展示了"概念 + 使用 + 限制"的结构编排。新写一页 Storage 或 Payments 文档前，读这几个页面就足以对齐仓库风格。

写作标准：第二人称、主动语态、禁用词清单

原文档对文字本身有明确的硬性要求：

语气与结构：使用第二人称（"you"）、主动语态、直白语言；标题用句首大写（sentence case，例如 "Getting started" 而非 "Getting Started"）；有益时先给上下文，先讲"是什么"再讲"怎么做"；过程性内容开头列前置条件。

禁用清单（Never use）：

营销语言（powerful、seamless、robust、cutting-edge）
填充短语（"it's important to note"、"in order to"）
过多连接词（moreover、furthermore、additionally）
主观评论词（obviously、simply、just、easily）
文档中的 Emoji

警惕 AI 典型模式：过度正式或生硬的措辞、不必要的概念重复、不提供价值的泛泛开头、复述前文的总结段落。

代码示例：保持简单实用；使用真实但通用的值（不要 "foo"、"bar"）；示例必须经过实际验证再写进文档；一个清晰的示例好过多个变体。

InsForge 的本地覆盖层 INSFORGE.md 在此基础上加了一条更细的"反 AI 味"要求：不用破折号做插叙或强调、不自动凑三连（"fast, reliable, and scalable"这类三词排比）、不做否定式平行结构、不夸大重要性、不使用"delve / leverage / utilize / seamless / robust"等 AI 高频词汇。它还明确要求"读一遍，如果像新闻稿或学期论文，就把它压平"（flatten it）。这些规则直接服务于"公开文档不能读起来像机器写的"这一目标。

Mintlify 文档站约定：MDX、组件与根相对链接

For Mintlify-powered docs一节是技能中可操作性最强的部分，因为 InsForge 的文档正是运行在 Mintlify 之上的（docs/docs.json 配置了"theme": "mint"、深色默认主题与多语言导航）。

文件格式

MDX 文件带 YAML frontmatter，每个页面必须包含title、description、keywords三个字段：

--- title: "Clear, descriptive title" description: "Concise summary for SEO and navigation." keywords: ["relevant", "search", "terms"] --- Content starts here.

而 InsForge 的本地约定做了收敛：docs 下的.mdx文件只用title和description，除非邻近页面已有其他键，否则不添加icon、sidebarTitle等 Mintlify 支持键。对照 docs/sdks/typescript/auth.mdx 第 1-4 行可以确认这一写法。

文件命名

使用 kebab-case：getting-started.mdx、api-reference.mdx；描述性强但简洁；与目录中既有命名模式保持一致。InsForge 的 docs 树（如docs/core-concepts/database/migrations.mdx、docs/sdks/typescript/realtime.mdx）全部遵循该约定。

组件

Mintlify 组件要按用途使用：

Callouts：<Note>补充上下文、<Warning>提示潜在破坏性操作、<Tip>给建议或最佳实践、<Info>说明与任务相关的信息
Steps：顺序流程用<Steps>包裹<Step title="...">
代码块必须带语言标签：

const example = "always specify language";

内部链接

使用根相对路径：/content/components/accordions，而不是../components/accordions或完整 URL。这在 InsForge 的实际文档中有多处体现，例如 docs/core-concepts/storage/s3-compatibility.mdx 中指向/deployment/self-host-storage和/core-concepts/storage/overview的链接。

InsForge 的三条本地硬性约定

INSFORGE.md 针对组件与代码插入给出了三条覆盖规则：

不用<ParamField>，参数一律写成普通 Markdown 无序列表，放在### Parameters标题下。仓库中<ParamField>的使用数为零，docs/sdks/typescript/auth.mdx 第 17-22 行是标准范式。
SDK 安装一律导入共享 snippet，绝不内联。写法固定为：

import Installation from '/snippets/sdk-installation.mdx'; <Installation />

snippet 本体在 docs/snippets/sdk-installation.mdx，涵盖 npm / yarn / pnpm 三种安装方式与createClient初始化示例。这意味着所有 SDK 页面共享同一份安装说明，改一处全站生效。

语气采用第二人称祈使句，以 docs/quickstart.mdx 为基准。

多语言导航由 docs.json 驱动

InsForge 文档支持 en、zh、zh-Hant、es 四种语言（.claude/skills/insforge-dev/docs/DOCS_I18N.md）。按该说明，导航由docs.json的navigation.languages数组驱动而非文件夹本身：每个语言一个条目，英文页用裸路径（introduction），其他语言页用带前缀路径（zh/introduction）。翻译时要保留 MDX 结构、代码块与import引用原样不动，只改自然语言文本；snippet 不做本地化（/snippets/x.mdx始终解析到英文）。这些多语言约定与 doc-author 技能"匹配既有模式"的原则一脉相承。

验证护栏：什么能写、什么留 TODO、什么必须升级

原文档用一整节建立"事实边界"，这是防止 Agent 编造内容的关键机制。

可以记录（What you can document）：能在代码库验证的行为；用户明确提供的信息；与既有文档一致的模式；基于已文档化 API 的标准用法。

需要 TODO（What requires a TODO）：无法验证的实现细节、未测试过的边界情况、不确定的配置项、可能随环境变化的行为。TODO 要写得清晰可查：

{/* TODO: Verify the default timeout value - couldn't find in codebase */}

必须升级（What requires escalation），遇到以下情况停下并上报：

内容不确定性：对功能理解不足以准确记录、现有文档与代码库矛盾、功能看起来不完整或已损坏
范围问题：改动波及多页面或导航结构、需要产品或设计输入、涉及安全敏感信息、涉及定价/计费/法律条款、需要废弃或大改现有内容
技术阻塞：找不到所记录功能的源码、API 或接口变化巨大、需要访问你无权访问的系统或环境

这条护栏在 InsForge 仓库中有直接呼应：技能头部的 vendored 注释本身就是"可验证信息"的体现，它记录了上游提交 SHA 与许可证状态；而scripts/update-mintlify-skill.sh里的许可证校验逻辑（用gh api查询上游license.spdx_id，不是 MIT 就报错退出）正是把"许可证可变"这一不确定性变成了可执行的升级门禁。

六步工作流与自审清单

原文档将写作过程固化为六步：

理解任务：细读 issue 或请求，明确要记录什么、影响哪些页面、读者读后应能做什么
研究：搜索现有文档、阅读相关源码、查看相似文档的模式
规划变更：列出要修改/新建的文件、要新增的章节、需要更新的既有内容；协作模式下先与人分享计划再动笔
写作：最重要的信息放最前、章节聚焦可扫读、恰当使用组件、不确定处加 TODO
自审：逐项核对清单
提交：协作模式把草稿当起点；自主模式永远开 PR、不直接提交

第 5 步自审清单值得逐条对照执行：

所有代码块都有语言标签
frontmatter 包含 title、description、keywords（若用 MDX）
内部链接正确
无营销语言或填充短语
内容与周边页面风格一致
TODO 对不确定内容标注清晰
新页面已加入导航（如适用）
已标注任何不确定区域

常见任务的操作模板

原文档为三类高频场景提供了可直接套用的流程。

起草新内容：范围不清先提问；读相关现有页面匹配风格；写草稿并标注假设；标出不确定区域。

编辑现有内容：通读整页获取上下文；指出具体问题（而不是泛泛的"改得更好"）；说明改什么、为什么改；协作模式下可提议修改或交由人类决定。原文档给出的反馈示例值得学习：

"我建议三处修改：1. 把前置条件移到顶部，现在用户进行到一半才看到；2. 缩短开头段落，它重复了 description 里的信息；3. 在第 3 步后加一个代码示例，目前没有实际语法支撑显得抽象。"

审查文档：对照代码库核对准确性；找出用户需要但缺失的信息；指出与其他文档的矛盾；标出含糊或歧义段落。反馈按"准确性 / 缺失信息 / 风格建议"分类给出，每条标注行号与具体问题。

帮助组织结构：先理解内容覆盖范围，识别读者目标，给出带理由的结构建议并开放备选方案。

好示例与差示例：一眼可辨的写作质量

原文档用一组正反对照给出了可量化的标准。

好的页面开头：frontmatter 齐全（title + description + keywords），description 一句话说清用途；正文第一段直接给出定义与触发场景：

--- title: "Webhooks" description: "Receive real-time notifications when events occur in your account." keywords: ["webhooks", "events", "notifications"] --- Webhooks let your application receive automatic notifications when specific events happen, like when a user signs up or a payment succeeds. Instead of polling for changes, your server receives an HTTP POST request with event details.

差的页面开头：description 用营销词（"powerful webhook system"），正文以空洞的欢迎语和排比开场（"incredibly powerful feature that seamlessly integrates"），没有任何事实信息。两者对比，好例子的每句话都在交付信息，差例子每句话都在填充篇幅。

好的过程性内容：用<Steps>分步，每一步有明确的动作、代码与完成标志（如创建 endpoint → 使其公网可达 → 注册），代码带语言标签。这一模式在 InsForge 的 docs/quickstart.mdx 中已经落地：创建项目 → 等待后端就绪 → 复制 Project ID →npx @insforge/cli link --project-id <your-project-id>，步骤与验证方式环环相扣。

技能的版本化与上游同步：InsForge 是怎么维护这份 SKILL.md 的

最后回到仓库工程层面：一份 vendored 技能文件如何保持可维护。doc-author/SKILL.md是 Mintlify 上游的逐字拷贝，因此仓库提供了专门的同步脚本scripts/update-mintlify-skill.sh，其工作流程是：

许可证校验：用gh api /repos/mintlify/docs --jq '.license.spdx_id'查询上游许可证，不是 MIT 就输出警告并退出（退出码 3），防止在许可条件变化时盲目更新
获取上游 SHA：查询mintlify/docs主干最新提交，截取 12 位短 SHA
幂等短路：若本地头部已引用该 SHA 且未加--force，直接输出 up-to-date 并退出
重新组装：用curl拉取上游正文，校验以 YAML frontmatter 开头，然后按"上游 frontmatter + 本地 attribution 块 + 上游正文"的顺序重组文件

脚本还声明了对curl、gh（需已认证）、jq三个工具的依赖，并提供了--force参数跳过短路检查强制重写。这一机制与.claude/skills/README.md的说明完全对应：SKILL.md 头部注释里的提交 SHA 与 vendored 日期由脚本维护，不要手改 SKILL.md，本地约定一律进INSFORGE.md。

同类模式还延伸到了.claude/skills/insforge-dev/：它与其他两个 Agent 目录（.codex/、.agents/）下的副本互为镜像，以.agents/skills/insforge-dev/为唯一真源，通过scripts/sync-skills.sh重新生成，CI 用--check模式防止三份拷贝漂移（见.claude/skills/README.md）。这构成了一套完整的"技能治理"体系：上游变更可追溯、许可证变更会阻断、本地约定与上游正文分层、多 Agent 目录副本自动同步。

结语：把写作规范变成可执行的技能

回看整个 doc-author 技能，它的核心贡献是把"好的文档写作"从模糊的经验变成了 Agent 可逐条执行的规范：先确认能否验证，再决定协作还是自主；动笔前研究上下文与周边风格；写作时守住语气、结构与组件约定；完成后对照自审清单；最后走 PR 而非直接提交。InsForge 仓库在引入这份技能的同时，用INSFORGE.md沉淀本地约定、用同步脚本固化上游版本、用多语言与导航约定约束落地，展示了一个开源项目如何系统性地让 AI 参与文档生产而不失质量与一致性。对于任何正在建设 Agent 协作式文档流程的团队，这份SKILL.md连同它的仓库配套，本身就是一份可复制的范本。

企业官网建设流程全解析