> 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/docs-as-code/ai-coding-assistants-and-skillmd.md).

# Agent 技能

将 GitBook 技能添加到 Claude Code、Cursor 或 Codex 等 AI 编码助手中，让它们能够处理 GitBook 页面、站点和工作流。

第一次设置 GitBook？请改为让你的智能体访问 [设置 GitBook](https://gitbook.com/docs/documentation/zh/setup.md) 。

GitBook 在 [gitbook-skills](https://github.com/GitbookIO/gitbook-skills) 仓库中发布了一组技能。这些技能帮助 AI 编程助手处理 GitBook 文档，包括编写页面、配置站点、编写 OpenAPI 参考文档、处理变更请求以及构建集成。如果你使用 Claude Code、Cursor、Codex 或其他编程助手，请添加这些技能，以便你的智能体正确使用 GitBook 语法、块和配置文件。

这与 [Git Sync](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync.md) 工作流很契合：在代码仓库中进行更改并提交后，文档站点就会自动更新。

{% hint style="info" %}
更喜欢在 GitBook 编辑器中写作？使用 [GitBook Agent](https://gitbook.com/docs/documentation/zh/gitbook-dai-li/overview.md) ，无需离开 GitBook，即可起草、改写、审阅和翻译内容。
{% endhint %}

## 将 GitBook 技能添加到你的 AI 智能体

如果你的 AI 编程助手支持基于软件包的技能，请使用此选项。

{% stepper %}
{% step %}

### 连接 GitBook MCP

仅编辑文件的技能（例如 `write-docs`）不需要 GitBook 身份验证。与 GitBook 通信的技能（包括 `configure-site`, `write-openapi`, `cr-create`和 `cr-review` ）应使用 [GitBook MCP](https://gitbook.com/docs/documentation/zh/docs-as-code/gitbook-mcp.md) 连接，该连接通过浏览器中的 OAuth 登录。

只有在直接调用 REST API 时，才需要从 [开发者设置](https://app.gitbook.com/account/developer) 中获取个人访问令牌。 `cr-create` 和 `cr-review` 使用 REST API，因此需要令牌。 `configure-site` 和 `write-openapi` 优先使用 MCP；如果未连接 MCP，则使用令牌。
{% endstep %}

{% step %}

### 安装 GitBook 技能

这些技能位于 [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) 仓库中。运行以下命令，将它们安装到你的项目中：

{% code expandable="true" %}

```bash
npx -y skills add GitbookIO/gitbook-skills -y
```

{% endcode %}

如果没有同时使用两个 `-y` 标志，安装程序会等待输入。
{% endstep %}
{% endstepper %}

## 在本地添加 GitBook 技能

如果你的助手不支持基于软件包的技能，请下载 GitBook 技能。

{% stepper %}
{% step %}

### 下载 GitBook 技能

如果你的助手支持，请使用 `npx -y skills add GitbookIO/gitbook-skills -y` 安装 GitBook 技能。

如需手动将文件复制到项目中，请从 [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) 仓库获取这些文件。

<table><thead><tr><th width="156.67578125" valign="top">技能</th><th width="455.33203125" valign="top">说明</th><th valign="top">下载</th></tr></thead><tbody><tr><td valign="top"><code>write-docs</code></td><td valign="top">编写和编辑 GitBook 风格的 Markdown 页面。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/write-docs">GitHub</a><br></td></tr><tr><td valign="top"><code>configure-site</code></td><td valign="top">通过 REST API 端到端地创建和配置 GitBook 站点。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/configure-site">GitHub</a><br></td></tr><tr><td valign="top"><code>write-openapi</code></td><td valign="top">在 GitBook 中编写和发布 OpenAPI 参考文档。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/write-openapi">GitHub</a></td></tr><tr><td valign="top"><code>cr-create</code></td><td valign="top">通过 REST API 执行 GitBook 文档审查流程：创建变更请求、推送内容、请求审查并处理评论。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/cr-create">GitHub</a></td></tr><tr><td valign="top"><code>cr-review</code></td><td valign="top">通过 REST API 审查 GitBook 变更请求：查找变更请求、总结更改、发表评论、批准或请求修改。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/cr-review">GitHub</a></td></tr><tr><td valign="top"><code>build-integration</code></td><td valign="top">构建、开发和发布 GitBook 集成，包括自定义块、ContentKit UI、事件和 OAuth。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/build-integration">GitHub</a></td></tr></tbody></table>

{% hint style="warning" %}
请记得在 GitBook 添加新功能时更新本地技能。
{% endhint %}
{% endstep %}
{% endstepper %}

## 使用 GitBook 技能

{% prompt description="Scaffold a Git-synced docs site from a folder of markdown" %}

```markdown
使用 GitBook 技能，将这个 Markdown 文件夹转换为由 Git Sync 支持的 GitBook 文档站点。

1. 阅读我的文档文件夹，并提出站点结构方案——包括空间、页面树和 SUMMARY.md 导航。开始写入任何内容之前，先给我查看。
2. 按照 GitBook 的单体仓库布局搭建代码仓库（每个空间包含 README.md 和 SUMMARY.md），并提交。
3. 创建站点和空间，然后提供准确、可直接复制粘贴的操作说明，告诉我如何在 GitBook 界面中完成唯一需要手动执行的步骤：使用 Git Sync 将每个空间关联到对应目录。
4. 确认同步设置完成后，验证网站结构是否符合计划。
```

{% endprompt %}

{% prompt description="Upgrade a plain markdown page into a polished GitBook page" %}

```markdown
使用 GitBook 技能，借助 GitBook 的富文本块重写此页面——目前它只是纯 Markdown。

1. 阅读页面并告诉我可以改进哪些方面：多语言代码示例 → 选项卡，按顺序展开的操作指南 → 步骤器，提示框 → 提示块，“选择你的路径”内容 → 卡片。
2. 使用正确的 GitBook 语法应用这些更改，包括 frontmatter（title、description、icon）。
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. 指出规范中的不足（缺少描述、示例或响应架构），这些不足会削弱渲染后的参考文档。
```

{% endprompt %}

## 常见问题

<details>

<summary>GitBook 技能包含哪些内容？</summary>

在 [gitbook-skills](https://github.com/GitbookIO/gitbook-skills) 仓库中的技能为你的 AI 编程助手提供所需的上下文，帮助它正确创建、编辑和格式化 GitBook 内容。

`write-docs` 包括：

* 自定义块的完整语法参考。
* 配置文件格式，包括 `.gitbook.yaml`, `SUMMARY.md`和 `.gitbook/vars.yaml`.
* Frontmatter 选项、布局控制、变量、表达式、决策表以及常见问题。

其他技能涵盖站点设置、OpenAPI 参考、变更请求和集成。

</details>

<details>

<summary>如何测试 AI 生成的内容？</summary>

务必检查并测试 AI 助手生成的内容。使用基于 GitBook 技能训练的助手时：

* 验证自定义块能否在 GitBook 中正确渲染。
* 检查所有内部链接是否正常。
* 确认 frontmatter 是有效的 YAML。
* 测试变量是否引用了正确的作用域。

</details>

<details>

<summary>如何确认我的助手正在使用 GitBook 技能？</summary>

请它说明会如何格式化 GitBook 页面。

如果它提到了 GitBook 块、frontmatter、变量或类似 `SUMMARY.md`这样的文件，说明技能已加载。

如果它只提供通用 Markdown，请检查技能是否已安装，并重新加载助手。

</details>

<details>

<summary>为什么助手会忽略 GitBook 专用语法？</summary>

这通常意味着技能未加载，或者规则不够具体。

确保已安装 GitBook 技能，并且助手能够读取这些技能。

如果助手会缓存指令，请在添加或更新技能后重启会话。

</details>

<details>

<summary>如果助手生成的 GitBook 内容无效，该怎么办？</summary>

首先检查以下常见问题：

* 未闭合的自定义块
* frontmatter 中的 YAML 无效
* 变量引用错误
* 与页面结构不匹配的链接

提交前务必在 GitBook 中检查输出内容。

</details>

<details>

<summary>我还需要访问令牌吗？</summary>

连接 [GitBook MCP](https://gitbook.com/docs/documentation/zh/docs-as-code/gitbook-mcp.md) ，并在技能需要与 GitBook 通信时使用 OAuth 登录。这适用于大多数 `configure-site` 和 `write-openapi`.

如果技能会直接调用 REST API（包括 `cr-create` 和 `cr-review`），或者未连接 MCP，则需要个人访问令牌。你可以在 [开发者设置](https://app.gitbook.com/account/developer).

如果你只是使用 `write-docs`在本地编辑文件，则不需要令牌或 MCP 连接。

</details>

<details>

<summary>如果技能似乎已经过时，该怎么办？</summary>

更新已安装的技能，或让助手重新使用 GitHub 源。

如果团队将某个技能的部分内容复制到了自定义规则中，也请一并更新。

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/docs-as-code/ai-coding-assistants-and-skillmd.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
