Agent 技能

使用 GitBook 官方的 SKILL.md 文件，让 Claude Code、Cursor 或 Codex 等 AI 编码助手了解 GitBook 的功能和块

GitBook 提供 技能文件 教 AI 编码助手如何正确编辑 GitBook 文档。如果你使用 Claude Code、Cursor、Codex 或其他外部编码助手，请添加 GitBook 技能，以便你的代理能够处理 GitBook 语法、区块和配置文件。

这与……非常契合 Git Sync 工作流——在你的仓库中进行更改，提交后，你的文档站点会自动更新。

更喜欢在 GitBook 编辑器中编写？使用 GitBook Agent 来起草、改写、审阅和翻译内容，而无需离开 GitBook。

将 GitBook 技能添加到你的 AI 代理

当你的 AI 编码助手支持基于包的技能时，请使用此选项。

1

创建访问令牌

要让你的代理与 GitBook 交互，你需要 创建一个访问令牌 在你的 GitBook 开发者设置中。GitBook 使用此令牌在你的代理使用 GitBook 技能时进行身份验证。

2

安装 GitBook 技能

该技能属于 gitbook-skills 仓库。运行以下命令直接将 GitBook 技能安装到你的项目中：

npx skills add GitBookIO/gitbook-skills

在本地添加 GitBook 技能

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

1

创建访问令牌

要让你的代理与 GitBook 交互，你需要 创建一个访问令牌 在你的 GitBook 开发者设置中。GitBook 使用此令牌在你的代理使用 GitBook 技能时进行身份验证。

2

下载 GitBook 技能

使用 npx skills add GitBookIO/gitbook-skills 安装 GitBook 技能，当你的助手支持时。

若要手动将文件复制到你的项目中，请从 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

记得将你的本地仓库更新为最新的 SKILL.md 文件，因为 GitBook 会不断添加新功能。

使用 GitBook 技能

Scaffold a Git-synced docs site from a folder of markdown

Upgrade a plain markdown page into a polished GitBook page

Generate an API reference from an OpenAPI spec

常见问题

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这样的文件

，则说明技能已加载。

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

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

确保你的助手读取 SKILL.md 仓库根目录中的文件，或在其项目说明中使用 GitHub URL。

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

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

先检查常见的失败点：

• 未闭合的自定义区块
• frontmatter 中无效的 YAML
• 损坏的变量引用
• 与页面结构不匹配的链接

在提交之前，始终先在 GitBook 中审阅输出。

我还需要访问令牌吗？

当你的代理直接与 GitBook 交互时，你需要访问令牌。你可以在你的 开发者设置.

如果你只是使用 SKILL.md在本地编辑文件，在将助手连接到 GitBook 工作流或 API 之前，可能不需要令牌。

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

更新你的本地 SKILL.md，或者让你的助手重新指向 GitHub 源。

如果你的团队将文件的部分内容复制到了自定义规则中，也请一并更新那些内容。