尧图网站建设 
用 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而来头部注释明确标注了上游来源、提交 SHAcommit 877f90193ea1与 MIT 许可证。它在仓库中的角色是指导贡献者写、编辑和维护文档覆盖从与人类协作起草到自主写作并走 PR 评审的全流程。一个 Skill 文件的标准骨架由两部分组成YAML frontmatter元数据区见 SKILL.md 第 1-10 行字段取值含义namedoc-author技能唯一名称Agent 据此识别与加载description一段英文描述说明技能用途并声明默认协作模式、由 Mintlify 构建licenseMIT许可证声明决定能否被第三方仓库引入compatibility需要 git 访问与创建 PR 的能力声明运行前提支持任何 Markdown/MDX 文档针对 Mintlify 文档站优化metadataauthor、url、version0.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填充短语its 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-casegetting-started.mdx、api-reference.mdx描述性强但简洁与目录中既有命名模式保持一致。InsForge 的 docs 树如docs/core-concepts/database/migrations.mdx、docs/sdks/typescript/realtime.mdx全部遵循该约定。组件Mintlify 组件要按用途使用CalloutsNote补充上下文、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 的标准用法。需要 TODOWhat requires a TODO无法验证的实现细节、未测试过的边界情况、不确定的配置项、可能随环境变化的行为。TODO 要写得清晰可查{/* TODO: Verify the default timeout value - couldnt 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 keywordsdescription 一句话说清用途正文第一段直接给出定义与触发场景--- 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连同它的仓库配套本身就是一份可复制的范本。延伸阅读技能定义全文.claude/skills/doc-author/SKILL.md本地约定覆盖.claude/skills/doc-author/INSFORGE.md技能库总览与维护说明.claude/skills/README.md上游同步脚本scripts/update-mintlify-skill.sh技能镜像同步脚本scripts/sync-skills.shMintlify 站点配置docs/docs.json文档风格范例docs/quickstart.mdx、docs/sdks/typescript/auth.mdx、docs/core-concepts/storage/s3-compatibility.mdx共享安装 snippetdocs/snippets/sdk-installation.mdx多语言翻译约定.claude/skills/insforge-dev/docs/DOCS_I18N.md【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 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而来头部注释明确标注了上游来源、提交 SHAcommit 877f90193ea1与 MIT 许可证。它在仓库中的角色是指导贡献者写、编辑和维护文档覆盖从与人类协作起草到自主写作并走 PR 评审的全流程。一个 Skill 文件的标准骨架由两部分组成YAML frontmatter元数据区见 SKILL.md 第 1-10 行字段取值含义namedoc-author技能唯一名称Agent 据此识别与加载description一段英文描述说明技能用途并声明默认协作模式、由 Mintlify 构建licenseMIT许可证声明决定能否被第三方仓库引入compatibility需要 git 访问与创建 PR 的能力声明运行前提支持任何 Markdown/MDX 文档针对 Mintlify 文档站优化metadataauthor、url、version0.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填充短语its 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-casegetting-started.mdx、api-reference.mdx描述性强但简洁与目录中既有命名模式保持一致。InsForge 的 docs 树如docs/core-concepts/database/migrations.mdx、docs/sdks/typescript/realtime.mdx全部遵循该约定。组件Mintlify 组件要按用途使用CalloutsNote补充上下文、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 的标准用法。需要 TODOWhat requires a TODO无法验证的实现细节、未测试过的边界情况、不确定的配置项、可能随环境变化的行为。TODO 要写得清晰可查{/* TODO: Verify the default timeout value - couldnt 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 keywordsdescription 一句话说清用途正文第一段直接给出定义与触发场景--- 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连同它的仓库配套本身就是一份可复制的范本。延伸阅读技能定义全文.claude/skills/doc-author/SKILL.md本地约定覆盖.claude/skills/doc-author/INSFORGE.md技能库总览与维护说明.claude/skills/README.md上游同步脚本scripts/update-mintlify-skill.sh技能镜像同步脚本scripts/sync-skills.shMintlify 站点配置docs/docs.json文档风格范例docs/quickstart.mdx、docs/sdks/typescript/auth.mdx、docs/core-concepts/storage/s3-compatibility.mdx共享安装 snippetdocs/snippets/sdk-installation.mdx多语言翻译约定.claude/skills/insforge-dev/docs/DOCS_I18N.md【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考