> 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/skill.md). # 技能 端到端使用 GitBook：编写并格式化 GitBook 风格的 Markdown 页面和区块（提示、选项卡、步骤器）；通过 GitBook REST API 和 Git 设计、搭建并配置文档站点 {% hint style="info" %} 此页面自动生成自 [GitbookIO/gitbook-skills](https://github.com/GitbookIO/gitbook-skills)。不要直接编辑它——而是编辑那里的源技能。 {% endhint %} ## GitBook GitBook 面向 AI 编码代理的技能，涵盖 GitBook 工作的六个领域。下面的每个部分都是 [gitbook-skills](https://github.com/GitbookIO/gitbook-skills) 中的六项技能之一——阅读其描述以判断是否与你的任务匹配，然后在执行前获取其链接页面以查看完整说明。每项技能的说明都会链接到进一步的参考资料（完整块语法、API 负载、故障排查），位于 [gitbook-skills](https://github.com/GitbookIO/gitbook-skills) 在 `skills//references/` 下，当你需要比顶层说明更深入的信息时。 #### 编写与编辑文档 在 Git 同步仓库、IDE 或任何文本编辑器中编写、撰写、编辑和格式化 GitBook 文档页面。当任务涉及创建或编辑 GitBook markdown 页面、编写或更新 README.md 或 SUMMARY.md、插入提示、选项卡、步骤器、卡片或其他 GitBook 块、配置页面 frontmatter 或布局选项、设置变量或表达式，或在 GitBook UI 之外为 GitBook 格式化内容时，请使用此技能。 完整说明： #### 配置站点 端到端创建并维护完整的 GitBook 文档站点——从源内容设计站点结构，以 monorepo 布局搭建 Git 仓库，设置 GitHub/GitLab 远程仓库，调用 GitBook API（通过其 REST API 或 MCP 服务器）创建站点/章节/空间，应用品牌定制，并为用户提供 GitBook 无法通过程序暴露的那一步 UI 操作（Git Sync 连接）的清晰说明。始终先在站点级别设置 Git Sync——通过 gitbook-docs.yaml 将每个空间映射到同一仓库/分支中的一个目录——只有当某个空间确实需要独立的仓库或分支时，才回退到按空间设置 Git Sync。当用户想要启动一个新的 GitBook 文档站点、重组或扩展现有站点、将站点或空间链接到 Git 仓库进行同步、更改站点品牌（Logo、颜色、字体、页眉/页脚），或以程序化方式管理空间、章节或站点-空间时，触发此技能。此技能是编排层；对于任何单独页面的 markdown 内容编写，它会委托给配套的 `write-docs` 技能。 完整说明： #### 编写 OpenAPI 参考文档 在 GitBook 中撰写、配置、组织和排查 OpenAPI/Swagger API 参考文档。当任务涉及 GitBook OpenAPI 块或 `{% openapi %}` 块、在 GitBook 中添加或更新 OpenAPI/Swagger 规范（通过文件或 URL，经由 API、MCP、CLI 或应用 UI）、从规范生成 API 参考页面、配置交互式“Test it”运行器（身份验证、服务器、CORS、代理），使用 GitBook `x-*` 扩展（图标、标题、导航层级、代码示例、枚举描述）、将操作标记为实验性/已弃用/隐藏，或在 CI/CD 中自动更新规范时，请使用此技能。即使用户只是提到 GitBook 加 OpenAPI、在面向 GitBook 的规范上放了一个 `x-` 扩展，或者问“为什么我的规范没有加载”或“为什么 Test it 不起作用”，而没有提到此技能，也要触发。 完整说明： #### 创建与管理变更请求 通过 Claude Code 直接调用 GitBook REST API，并使用 curl（不使用 CLI）端到端驱动 GitBook 文档审阅流程——创建变更请求、推送内容（更新现有页面并创建新页面）、请求审阅者、通知 Slack，然后将审阅评论拉回、修复它们、重新推送并解决。 这是 cr-review（在同一 API 上的审阅者端）的编写侧配套技能。当有人想在终端/代理中针对原始 API（curl/HTTP）运行“GitBook 中的文档审阅”循环、提到通过 API 创建变更请求、将内容推送到 CR、“拉取最新评论并修复它们”、请求审阅文档，或向工程师展示如何在没有 CLI 的情况下通过 Claude + Slack 协作处理 GitBook 文档时，请使用此技能。 完整说明： #### 审阅变更请求 通过 Claude Code 直接调用 GitBook REST API，并使用 curl（不使用 CLI）审阅 GitBook 变更请求——这是 cr-create（在同一 API 上的编写侧）的审阅者端配套技能。发现需要审阅的变更请求（按创建者、空间或整个组织筛选），获取用于审阅差异的 GitBook 应用链接，总结 CR 中实际发生了什么变化，然后留下评论，并可选择提交审阅结论（批准 / 请求更改）。当有人想通过原始 API（curl/HTTP）审阅文档变更请求、问“有哪些 CR 处于打开状态 / 等我处理 / 由谁创建”、“显示 / 中的变更请求”、“总结这个 CR 中变更了什么”、“审阅这个变更请求”、“在 CR 上留言”，或“批准 / 请求这个 CR 的更改”时，请使用此技能。对于通过 API 进行的编写侧操作（创建 CR、推送内容、请求审阅者、修复评论），请改用 cr-create。 完整说明： #### 构建集成 构建、开发并发布 GitBook 集成——这些应用运行在 GitBook 内部，可添加自定义块、响应事件、通过 OAuth 连接外部服务并扩展编辑器。当任务涉及 GitBook 集成平台时使用此技能：使用 GitBook CLI 搭建集成（`gitbook new`）、编写或编辑集成代码（`createIntegration`, `createComponent`、ContentKit TSX）、配置 `gitbook-manifest.yaml` （作用域、块、配置、密钥）、构建自定义编辑器块或链接展开器、处理诸如 `space_content_updated`之类的 GitBook 事件、设置集成的 OAuth 流程、运行 `gitbook dev`，或发布一个集成（私有/未列出/公开，提交市场）。即使用户只是说他们想“为 GitBook 构建一个应用”“添加一个自定义块”或“连接到 GitBook”，而没有说出“集成”这个词，也要触发此技能。 完整说明： --- # 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/skill.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.