> 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/wen-dang-ji-dai-ma/ai-coding-assistants-and-skillmd.md). # Agent 技能 GitBook 提供 [技能文件](https://github.com/GitbookIO/gitbook-skills/tree/main) 这些文件教会 AI 编码助手如何正确编辑 GitBook 文档。如果你使用 Claude Code、Cursor、Codex 或其他外部编码助手，请添加 GitBook skills，以便你的代理能够使用 GitBook 语法、区块和配置文件。这与……非常契合 [Git Sync](/docs/documentation/zh/wen-dang-ji-dai-ma/git-sync.md) 工作流——在你的仓库中进行更改、提交，然后文档站点会自动更新。 {% hint style="info" %} 更喜欢在 GitBook 编辑器中编写？使用 [GitBook 代理](/docs/documentation/zh/gitbook-agent/overview.md) 即可在不离开 GitBook 的情况下起草、重写、审阅和翻译内容。 {% endhint %} ## 将 GitBook skills 添加到你的 AI 代理当你的 AI 编码助手支持基于包的 skills 时，使用此选项。 {% stepper %} {% step %} ### 创建访问令牌要让你的代理与 GitBook 交互，你需要 [创建访问令牌](https://app.gitbook.com/account/developer) 在 GitBook 开发者设置中创建。GitBook 会使用此令牌在你的代理使用 GitBook skills 时对其进行身份验证。 {% endstep %} {% step %} ### 安装 GitBook skills 此 skill 属于 [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) 仓库。运行以下命令可将 GitBook skills 直接安装到你的项目中： {% code expandable="true" %} ```bash npx skills add GitBookIO/gitbook-skills ``` {% endcode %} {% endstep %} {% endstepper %} ## 在本地添加 GitBook skills 如果你的助手不支持基于包的 skills，请下载 GitBook 的 skills。 {% stepper %} {% step %} ### 创建访问令牌要让你的代理与 GitBook 交互，你需要 [创建访问令牌](https://app.gitbook.com/account/developer) 在 GitBook 开发者设置中创建。GitBook 会使用此令牌在你的代理使用 GitBook skills 时对其进行身份验证。 {% endstep %} {% step %} ### 下载 GitBook skills 使用以下方式安装 GitBook skills `npx skills add GitBookIO/gitbook-skills` 当你的助手支持时。要手动将这些文件复制到你的项目中，请从 [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) 仓库中获取 GitBook skills。

技能	说明	下载
`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 skills {% prompt description="Scaffold a Git-synced docs site from a folder of markdown" %} ```markdown 使用 GitBook skills，将这个 markdown 文件夹转换为由 Git Sync 支持的 GitBook 文档站点。 1. 先阅读我的文档文件夹并建议站点结构——空间、页面树和 SUMMARY.md 导航。在写任何内容之前先展示给我。 2. 按照 GitBook 的 monorepo 布局（每个空间一个 README.md + SUMMARY.md）搭建仓库并提交。 3. 创建站点和空间，然后给我关于我在 GitBook UI 中要做的唯一一步的准确、可复制粘贴的说明：把每个空间通过 Git Sync 连接到其目录。 4. 一旦我确认同步已设置好，验证站点结构是否与计划一致。 ``` {% endprompt %} {% prompt description="Upgrade a plain markdown page into a polished GitBook page" %} ```markdown 使用 GitBook skills，用 GitBook 的富文本区块重写此页面——它目前只是普通 markdown。 1. 阅读该页面并告诉我你会升级什么：多语言代码示例 → 选项卡，顺序式操作流程 → 步进器，提示框 → 提示，“选择你的路径”内容 → 卡片。 2. 使用正确的 GitBook 语法应用更改，包括 frontmatter（标题、描述、图标）。 3. 保持我的措辞不变——改进结构，而不是语气。 4. 列出在 GitBook 中渲染后我应该再次检查的内容。 ``` {% endprompt %} {% prompt description="Generate an API reference from an OpenAPI spec" %} ```markdown 使用 GitBook skills，根据我的 OpenAPI 规范在文档中设置 API 参考部分。 1. 找到我的规范（如果不存在，帮助我从代码库生成一个）并验证它。 2. 使用 SUMMARY.md 中 GitBook 的 OpenAPI 区块设置自动生成的端点页面——不要手写端点页面；规范始终是唯一事实来源。 3. 为每个资源组添加一个简短的概览页面。 4. 标记规范中的缺口（缺少的描述、示例、响应架构），这些会让渲染后的参考文档质量变差。 ``` {% endprompt %} ## 常见问题

SKILL.md 包含什么？

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

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

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

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

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

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

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

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

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

我还需要访问令牌吗？

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

如果 skill 看起来已经过时了怎么办？

更新你的本地 `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/wen-dang-ji-dai-ma/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.