# AI 编码助手与 skill.md GitBook 提供了一个 [skill.md](https://gitbook.com/docs/skill.md) 文件，用于教会 AI 编码助手如何正确编辑 GitBook 文档。在本地编辑 GitBook 文档时，可将其用作“项目规则”。 这与 [Git 同步 ](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/getting-started/git-sync)在本地编辑文档，然后提交更改以更新文档站点的工作流程非常契合。该参考文件涵盖了 GitBook 的 Markdown 扩展、自定义区块、配置文件以及最佳实践。 #### 下载 {% file src="" %} {% hint style="info" %} #### 更喜欢在 GitBook 编辑器中使用 AI 写作？ GitBook 还提供 [GitBook Agent](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/gitbook-agent) 用于直接从编辑器进行 AI 辅助文档编写的功能。本指南适用于更偏好使用 Claude Code 或 Cursor 等外部编码助手的团队。 {% endhint %} ### skill.md 包含什么 * 所有自定义区块的完整语法参考 * 配置文件格式（`.gitbook.yaml`, `SUMMARY.md`, `.gitbook/vars.yaml`) * Frontmatter 选项和布局控制 * 变量和表达式语法 * 用于选择合适区块类型的决策表 * 常见陷阱和最佳实践 将此文件添加到你的 AI 编码助手后，它就能获得关于为 GitBook 文档创建、编辑和格式化内容所需的信息。这意味着该助手将遵循 GitBook 功能的既定框架和最佳实践。 ### 通过 URL 使用 skill.md 大多数 AI 编码助手都支持项目特定说明。你可以在项目配置中引用该技能文件，只需提供 skill 文件的 URL，这样助手就能知道如何使用 GitBook 语法。 ### 在本地使用 skill.md 你也可以下载该技能文件并将其包含在仓库中。首先，将 skill.md 下载到仓库根目录，然后在编码助手的规则文件中引用它： `"请阅读仓库根目录中的 skill.md，以了解 GitBook 语法和最佳实践"` . 这种方法可离线使用，并允许进行团队特定的修改。 {% hint style="warning" %} 请记得随着 GitBook 添加新功能，及时用最新的 skill.md 文件更新你的本地仓库。 {% endhint %} ### 测试 AI 生成的内容 重要的是，你要始终审查并测试由 AI 助手生成的内容——包括技术准确性和正确格式。 当你使用基于该技能文件训练的 AI 助手时，应当： * 确认任何自定义区块在 GitBook 中都能正确渲染 * 检查所有内部链接是否可用 * 确认 frontmatter 是有效的 YAML * 测试变量是否引用了正确的作用域 {% hint style="warning" %} **注意：** AI 助手有时可能会生成错误的语法，或忘记关闭自定义区块。提交之前务必审查更改。 {% endhint %} ### GitBook Agent 更喜欢直接在 GitBook 中工作？ [GitBook Agent](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/gitbook-agent/what-is-gitbook-agent) 为你提供 GitBook 编辑器中的 AI 辅助工作流——无论你是否使用 Git Sync。 Agent 拥有你文档的完整上下文，并且已经接受过如何以最佳方式使用 GitBook 的区块和功能的训练。Agent 可帮助你起草内容、进行更新，并从 GitBook 应用内为不同使用场景优化你的文档。 了解 GitBook Agent