> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/getting-started/ai-documentation/ai-coding-assistants-and-skillmd.md). # Agent 技能 GitBook 提供 [技能文件](https://github.com/GitbookIO/gitbook-skills/tree/main) 这些文件教 AI 编程助手如何正确编辑 GitBook 文档。如果你使用 Claude Code、Cursor、Codex 或其他外部编程助手，请添加 GitBook 技能，以便你的代理能够使用 GitBook 语法、块和配置文件。这与 [Git Sync](/docs/documentation/zh/getting-started/git-sync.md) 工作流非常契合——在你的仓库中进行更改，提交后，你的文档站点会自动更新。 {% hint style="info" %} 更喜欢在 GitBook 编辑器中写作？使用 [GitBook Agent](/docs/documentation/zh/gitbook-agent/what-is-gitbook-agent.md) 即可在不离开 GitBook 的情况下起草、改写、审阅和翻译内容。 {% endhint %} ## 将 GitBook 技能添加到你的 AI 代理当你的 AI 编程助手支持基于包的技能时，请使用此选项。 {% stepper %} {% step %} ### 创建访问令牌要让你的代理与 GitBook 交互，你需要 [创建访问令牌](https://app.gitbook.com/account/developer) ，通过 GitBook 开发者设置生成。GitBook 会使用此令牌在你的代理使用 GitBook 技能时进行身份验证。 {% endstep %} {% step %} ### 安装 GitBook 技能此技能是 [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) 仓库的一部分。运行以下命令可将 GitBook 技能直接安装到你的项目中： {% code expandable="true" %} ```bash npx skills add GitBookIO/gitbook-skills ``` {% endcode %} {% endstep %} {% endstepper %} ## 在本地添加 GitBook 技能如果你的助手不支持基于包的技能，请下载 GitBook 的技能。 {% stepper %} {% step %} ### 创建访问令牌要让你的代理与 GitBook 交互，你需要 [创建访问令牌](https://app.gitbook.com/account/developer) ，通过 GitBook 开发者设置生成。GitBook 会使用此令牌在你的代理使用 GitBook 技能时进行身份验证。 {% endstep %} {% step %} ### 下载 GitBook 技能使用以下方式安装 GitBook 技能 `npx skills add GitBookIO/gitbook-skills` ，当你的助手支持它时。要手动将文件复制到你的项目中，请从 [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) 仓库获取 GitBook 技能。

技能	描述	下载
`configure-site`	创建并维护整个 GitBook 文档站点。	GitHub
`write-docs`	编写、撰写、编辑并格式化 GitBook 文档页面。	GitHub
`write-openapi`	撰写、配置、组织并排查 OpenAPI/Swagger API 参考文档。	GitHub
`build-integration`	为 GitBook 构建自定义集成。	GitHub
`cr-create`	创建 GitBook 变更请求、推送内容、请求审阅并处理评论。	GitHub
`cr-review`	审阅 GitBook 变更请求，总结更改，评论、批准或请求修改。	GitHub

{% hint style="warning" %} 请记得在 GitBook 添加新功能时，更新你的本地仓库中的最新 `SKILL.md` 文件。 {% endhint %} {% endstep %} {% endstepper %} ## 使用 GitBook 技能 {% prompt description="Scaffold a Git-synced docs site from a folder of markdown" %} ```markdown 使用 GitBook 技能，将这个 markdown 文件夹转换为一个由 Git Sync 支持的 GitBook 文档站点。 1. 阅读我的 docs 文件夹并提出站点结构方案——空间、页面树和 SUMMARY.md 导航。在我写任何内容之前先展示给我。 2. 按照 GitBook 的单体仓库布局搭建仓库（每个 space 一个 README.md + SUMMARY.md），并提交它。 3. 创建站点和 space，然后给我精确、可直接复制粘贴的说明，告诉我在 GitBook 界面中需要做的唯一一步：把每个 space 与其目录通过 Git Sync 绑定。 4. 一旦我确认同步已设置完成，请验证站点结构与计划一致。 ``` {% endprompt %} {% prompt description="Upgrade a plain markdown page into a polished GitBook page" %} ```markdown 使用 GitBook 技能，借助 GitBook 的富文本块重写这个页面——它目前只是普通 markdown。 1. 阅读该页面并告诉我你会升级哪些内容：多语言代码示例 → 选项卡，按步骤的流程 → 步进器，提示框 → 提示，「选择你的路径」内容 → 卡片。 2. 使用正确的 GitBook 语法应用这些更改，包括 frontmatter（标题、描述、图标）。 3. 保持我的措辞——改进结构，而不是语气。 4. 列出在 GitBook 中渲染后我应该再检查的任何内容。 ``` {% endprompt %} {% prompt description="Generate an API reference from an OpenAPI spec" %} ```markdown 使用 GitBook 技能，根据我的 OpenAPI 规范在我的文档中设置一个 API 参考部分。 1. 找到我的规范（如果不存在，帮我从代码库生成一个）并验证它。 2. 在 SUMMARY.md 中使用 GitBook 的 OpenAPI 块设置自动生成的端点页面——不要手写端点页面；规范始终是唯一事实来源。 3. 为每个资源组添加一个简短的概述页面。 4. 标记规范中的缺口（缺少描述、示例、响应 schema），这些缺口会使渲染后的参考文档质量变差。 ``` {% endprompt %} ## 常见问题

SKILL.md 包含什么？

`SKILL.md` 为你的 AI 编程助手提供所需上下文，使其能够正确创建、编辑和格式化 GitBook 内容。它包括： * 自定义块的完整语法参考。 * 配置文件格式，包括 `.gitbook.yaml`, `SUMMARY.md`，以及 `.gitbook/vars.yaml`. * frontmatter 选项、布局控制、变量、表达式、决策表以及常见陷阱。

我该如何测试 AI 生成的内容？

始终审阅并测试 AI 助手生成的内容。在使用基于技能文件训练的助手时： * 验证自定义块是否在 GitBook 中正确渲染。 * 检查所有内部链接是否可用。 * 确认 frontmatter 是有效的 YAML。 * 测试变量是否引用了正确的作用域。

我怎么知道我的助手正在使用 SKILL.md？

让它解释它会如何格式化一个 GitBook 页面。如果它提到了 GitBook 块、frontmatter、变量，或者像 `SUMMARY.md`这样的文件，说明技能已加载。如果它只回答通用 Markdown，请检查你的项目规则并重新加载助手。

为什么助手忽略了 GitBook 特定语法？

这通常意味着技能文件未加载，或者规则不够具体。确保你的助手从 `SKILL.md` 仓库根目录读取，或者在项目说明中使用 GitHub URL。如果助手会缓存指令，在你添加或更新规则后重启会话。

如果助手生成了无效的 GitBook 内容怎么办？

先检查常见故障点： * 未闭合的自定义块 * frontmatter 中无效的 YAML * 损坏的变量引用 * 与页面结构不匹配的链接在提交之前，务必先在 GitBook 中审阅输出。

我还需要访问令牌吗？

当你的代理直接与 GitBook 交互时，你需要访问令牌。你可以在你的 [开发者设置](https://app.gitbook.com/account/developer). 如果你只是使用 `SKILL.md`在本地编辑文件，那么在你将助手连接到 GitBook 工作流或 API 之前，可能不需要访问令牌。

如果技能看起来过时了怎么办？

更新你的本地 `SKILL.md`，或者让你的助手重新指向 GitHub 源。如果你的团队把文件中的部分内容复制到了自定义规则中，也请一并更新这些规则。

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook.com/docs/documentation/zh/getting-started/ai-documentation/ai-coding-assistants-and-skillmd.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.