GitBook

View saved version →

---
name: build-integration
metadata:
  version: "1.0"
description: "Build, develop, and publish GitBook integrations — apps that run inside GitBook to add custom blocks, react to events, connect external services via OAuth, and extend the editor. Use this skill whenever a task involves the GitBook integrations platform: scaffolding an integration with the GitBook CLI (`gitbook new`), writing or editing an integration's code (`createIntegration`, `createComponent`, ContentKit TSX), configuring `gitbook-manifest.yaml` (scopes, blocks, configurations, secrets), building custom editor blocks or link unfurlers, handling GitBook events like `space_content_updated`, setting up an integration's OAuth flow, running `gitbook dev`, or publishing an integration (private/unlisted/public, marketplace submission). Trigger this even if the user just says they want to 'build an app for GitBook', 'add a custom block', or 'connect <some tool> to GitBook' without saying the word 'integration'."
---

# Build a GitBook Integration

A skill for building integrations on GitBook's developer platform: apps that run inside GitBook itself. An integration can render custom blocks in the editor, show configuration UI, listen to events (content updated, Git sync completed, space viewed), authenticate against external services with OAuth, and talk to anything over HTTP.

This skill covers the integration lifecycle — scaffold, code, develop, publish. For creating or restructuring the docs *site* an integration might be installed into, defer to `configure-site`; for authoring page content, defer to `write-docs`.

## What an integration is (mental model)

An integration is a small TypeScript app executed by GitBook's runtime — not a script injected into pages, and not code running on the user's server. Three consequences shape everything else:

1. **Rendering happens on GitBook's backend.** Your component's `render` function runs server-side on every interaction and returns ContentKit markup (a JSX-like UI description). There is no client-side React tree you control, no DOM access, and UI updates flow through the action → new state → re-render loop.
2. **You cannot inject JavaScript into a site.** The `site:script:inject` and `site:script:cookies` scopes you'll see in GitBook-owned integrations are internal-only. If the user's plan amounts to "add a script tag to their docs", stop and say so early — the supported paths are custom blocks, webframes, and events.
3. **Local development is a proxy, not a server you visit.** `gitbook dev` routes the *installed* integration's traffic to your machine. You never open the dev server's port in a browser; you interact with the integration inside app.gitbook.com.

## The project

`gitbook new` scaffolds this shape:

```
my-integration/
├── gitbook-manifest.yaml   # identity, scopes, blocks, configuration schema
├── .gitbook-dev.yaml       # local dev config (generated by `gitbook dev`)
├── package.json
└── src/
    └── index.tsx           # entry file — default-exports createIntegration()
```

The entry file (whatever `script:` in the manifest points to) default-exports `createIntegration({ fetch, components, events })`:

```tsx
import { createIntegration, createComponent } from '@gitbook/runtime';

const helloBlock = createComponent({
    componentId: 'hello-world',            // must match a block id in the manifest
    initialState: { message: 'Say hello!' },
    action: async (element, action, context) => {
        switch (action.action) {
            case 'say':
                return { state: { message: 'Hello world' } };
            default:
                return {};
        }
    },
    render: async (element, context) => (
        <block>
            <button label={element.state.message} onPress={{ action: 'say' }} />
        </block>
    ),
});

export default createIntegration({
    components: [helloBlock],
    events: {
        space_content_updated: async (event, context) => {
            // react to conten

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: configure-site
metadata:
  version: "1.0"
description: "Create and maintain entire GitBook documentation sites end-to-end — design the site structure from source content, scaffold a Git repository in monorepo layout, set up the GitHub/GitLab remote, drive the GitBook API (via its REST API or MCP server) to create the site/sections/spaces, apply branded customization, and hand the user clean instructions for the one UI step (Git Sync wiring) that GitBook does not expose programmatically. Trigger this skill whenever the user wants to spin up a new GitBook docs site, restructure or extend an existing one, link spaces to a Git repo for sync, change a site's branding (logo, colors, fonts, header/footer), or programmatically manage spaces, sections, or site-spaces. This skill is the orchestration layer; for authoring the markdown content of any individual page it defers to the companion `write-docs` skill."
---

# Configure GitBook Site

A skill for creating and maintaining entire GitBook documentation sites. Where `write-docs` covers what goes inside a single page, this skill covers everything around the pages: structure design, repo scaffolding, the GitBook API, and branding. Use the two skills together — this one calls into `write-docs` whenever it needs to generate or edit page content.

## How you can talk to GitBook

There's more than one way to drive GitBook — GitBook's MCP server and the REST API. Check what's actually available in the current session and prefer **MCP first**: if GitBook MCP tools are already connected, use them for anything they cover (creating/configuring sites, opening change requests, drafting and editing content, restructuring docs) instead of making direct API calls. Don't run a detection script for this — you already know your own available tools/MCP connections; just use that awareness.

**"MCP first" is about transport, not about bypassing Git Sync for content.** MCP exposes a change-request content-push tool (`updateChangeRequestContent`) that's tempting to reach for anytime it's connected — but for spaces that already have Git Sync configured, pushing content by editing files in the local repo and letting Git Sync carry it to GitBook is still the preferred path for anything beyond a small, targeted edit. Use the change-request push (MCP or REST) instead when the space isn't Git-synced, there's no local checkout available in the environment, or the edit is small enough that opening a CR is proportionate. See `write-docs`'s "Choosing Git Sync vs. a change-request content push" for the full rule — it applies here too.

The steps in this skill are described as outcomes ("list the orgs", "create the site", "add a section") rather than tied to one transport, so they apply whichever you use. If GitBook MCP tools are connected, call those directly — their own schemas describe their parameters. If you're on the REST API path instead, the exact endpoints, request bodies, and expected responses for each step are in `references/api-cheatsheet.md`.

- **GitBook MCP** — a full read/write surface over the same capabilities described below, not a narrower view. If it isn't connected yet and the task is substantial enough to benefit (a full site build, ongoing restructuring — not a one-off tweak), offer to set it up: `claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp` (then `/mcp` to complete OAuth sign-in — or append `--header "Authorization: Bearer $GITBOOK_TOKEN"` to skip the browser flow). Codex equivalent: `codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp`. Note: this is a different server from GitBook's separate, read-only "published docs" MCP, which only exposes already-published content.
- **REST API** (`https://api.gitbook.com/v1`) — the fallback when MCP isn't connected, or for anything MCP doesn't cover. Needs `GITBOOK_TOKEN` as a bearer header on every request.

The same personal access token (from https://app.gitbook.com/account/developer) works as the bearer

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 161 — file references are metadata, not package contents.

View saved version →

---
name: cr-create
metadata:
  version: "1.0"
description: Drive an end-to-end GitBook docs review flow from Claude Code by calling the GitBook REST API directly with curl (no CLI) — create a change request, push content (update an existing page AND create a new page), request reviewers, notify Slack, then pull review comments back in, fix them, re-push, and resolve. This is the authoring-side companion to cr-review (the reviewer side over the same API). Use this whenever someone wants to run a "docs review in GitBook" loop from the terminal/agent against the raw API (curl/HTTP), mentions creating a change request via the API, pushing content into a CR, "pull in the latest comments and fix them," requesting review on docs, or showing engineers how to collaborate on GitBook docs from Claude + Slack without a CLI.
---

# GitBook Review Flow (direct API)

Run a documentation review loop against a GitBook space entirely through the
**GitBook REST API** (`https://api.gitbook.com/v1`, hit with `curl`), so an engineer
never has to leave Claude Code (plus Slack) to propose docs changes and get them
reviewed. This is the authoring-side companion to `cr-review` (the reviewer side over the
same API). Every action here is a plain HTTP call — there is no CLI and no helper script.

The same actions serve three purposes with no separate code paths:
- **CR-creation demo** — create a change request and push content (one existing page updated, one new page created).
- **Notify/review demo** — request reviewers, drop a Slack link, pull comments, fix, re-push, resolve.
- **Real use** — the identical actions against the user's own content.

Because the demo is just a scripted sequence of the real actions, it cannot show
something that doesn't actually work. Keep it that way: never fake an output.

## Auth and the `gbapi` helper

Every call is a Bearer-authenticated request to `https://api.gitbook.com/v1`. The token
lives in **`GITBOOK_TOKEN`** in the repo-root `.env` (create one at
https://app.gitbook.com/account/developer).
**Never print the token; never write it to a tracked file.** If it's missing, prompt the
user for it and write it to `.env`; don't invent one.

Define this shell helper once per session and use it for every call below. It loads the
token from `.env`, sets the base URL and headers, and — critically for the "never fake
output" rule — **fails loudly on any non-2xx, printing the API's error body** (`curl
--fail-with-body`, curl ≥ 7.76 / stock on current macOS):

```bash
set -a; [ -f .env ] && . ./.env; set +a          # load GITBOOK_TOKEN (and SLACK_WEBHOOK_URL)
gbapi() {                                          # gbapi METHOD /path [extra curl args…]
  local method="$1" path="$2"; shift 2
  curl -sS --fail-with-body -X "$method" \
    "https://api.gitbook.com/v1${path}" \
    -H "Authorization: Bearer ${GITBOOK_TOKEN}" \
    -H "Content-Type: application/json" "$@"
}
```

Every response is **JSON** — pipe it through `jq` and read whole objects. **Never hand-parse
by grepping/line-pairing fields** (bind the wrong title↔id and you act on the wrong
space/CR). If `gbapi` exits non-zero, surface the printed error — do not report success.

## Endpoint map (verified against api.gitbook.com/openapi.json)

`<space>`, `<cr>`, `<pageId>`, `<commentId>` are the relevant IDs. Base URL is
`https://api.gitbook.com/v1`; all paths below are relative to it.

| Step | Method + path | Notes |
|------|---------------|-------|
| Who am I | `GET /user` | returns `{id, displayName, email}` — your own user ID is `.id` |
| List pages | `GET /spaces/<space>/content/pages` | flat-ish tree with `id`, `title`, `type` |
| Get a page (base) | `GET /spaces/<space>/content/page/<pageId>?format=markdown` | current markdown of a page on the live space |
| Create CR *(GATE)* | `POST /spaces/<space>/change-requests` body `{"subject":"…"}` | returns the CR object with `id` and `urls.app` (also a `Location` header) — **`urls.app` is only the editor/diff link, not a re

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: cr-review
metadata:
  version: "1.0"
description: Review GitBook change requests from Claude Code by calling the GitBook REST API directly with curl (no CLI) — the reviewer-side companion to cr-create (the authoring side over the same API). Discover the change requests that need review (filter by who opened them, by space, or across a whole org), get the GitBook app link to review the diff, summarize what actually changed in a CR, then leave comments and optionally submit a review verdict (approve / request changes). Use this whenever someone wants to review docs change requests over the raw API (curl/HTTP), asks "what CRs are open / waiting on me / opened by <person>", "show me the change requests in <space>/<org>", "summarize what changed in this CR", "review this change request", "leave a comment on a CR", or "approve / request changes on a CR". For the authoring side (create a CR, push content, request reviewers, fix comments) over the API, use cr-create instead.
---

# GitBook CR Review (direct API)

Review documentation change requests against a GitBook space or org entirely through the
**GitBook REST API** (`https://api.gitbook.com/v1`, hit with `curl`), so a reviewer never has
to leave Claude Code to find what needs review, understand what changed, and respond. This is
the **reviewer-side companion** to `cr-create` (the authoring side over the same API). The
reviewer flow is: **discover → understand → comment → decide**.

Because every step is a real HTTP call, never fake an output: if a call returns nothing, says
nothing changed, or errors, report exactly that.

## Auth and the `gbapi` helper

Every call is a Bearer-authenticated request to `https://api.gitbook.com/v1`. The token lives
in **`GITBOOK_TOKEN`** in the repo-root `.env` (create one at
https://app.gitbook.com/account/developer). **Never print the token; never write it to a
tracked file.** Define this helper once per session and use it for every call below — it fails
loudly on any non-2xx and prints the API's error body (`curl --fail-with-body`, curl ≥ 7.76 /
stock on current macOS):

```bash
set -a; [ -f .env ] && . ./.env; set +a          # load GITBOOK_TOKEN
gbapi() {                                          # gbapi METHOD /path [extra curl args…]
  local method="$1" path="$2"; shift 2
  curl -sS --fail-with-body -X "$method" \
    "https://api.gitbook.com/v1${path}" \
    -H "Authorization: Bearer ${GITBOOK_TOKEN}" \
    -H "Content-Type: application/json" "$@"
}
```

Every response is **JSON** — pipe it through `jq` and read whole objects. **Never hand-parse by
grepping/line-pairing fields** — bind the wrong title↔id and every downstream call runs against
the wrong space/CR (a confident "0 comments" from a space that isn't the one you meant). If
`gbapi` exits non-zero, surface the printed error — do not report success.

## Endpoint map (verified against api.gitbook.com/openapi.json)

`<org>`, `<space>`, `<cr>`, `<pageId>` are the relevant IDs. Base URL is
`https://api.gitbook.com/v1`; paths are relative to it.

| Step | Method + path | Notes |
|------|---------------|-------|
| Who am I | `GET /user` | your own user ID is `.id` (for `requestedReviewer=me`) |
| Resolve a person → user ID | `GET /orgs/<org>/members?search=<name\|email>` | match on `user.displayName`/`user.email`; the user ID is `id` (= `user.id`) |
| List orgs (to get IDs) | `GET /orgs?limit=100` | `.items[]` → `id`, `title` |
| List spaces in an org | `GET /orgs/<org>/spaces?limit=100` | `.items[]` → `id`, `title` |
| Discover CRs across an **org** | `GET /orgs/<org>/change-requests?[status=][&creator=][&space=][&site=][&requestedReviewer=][&contributor=][&orderBy=]` | |
| Discover CRs in a **single space** | `GET /spaces/<space>/change-requests?[status=][&creator=][&requestedReviewer=]` | |
| CR detail | `GET /spaces/<space>/change-requests/<cr>` | `subject`, `status`, `createdBy`, `comments`, `urls.app` |
| Link to review the diff | use `.urls.app` straight from the list/get 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: write-docs
metadata:
  version: "1.0"
description: "Write, author, edit, and format GitBook documentation pages in Git-synced repos, IDEs, or any text editor. Use whenever a task involves creating or editing a GitBook markdown page, writing or updating a README.md or SUMMARY.md, inserting a hint, tab, stepper, card, or other GitBook block, configuring page frontmatter or layout options, setting up variables or expressions, or formatting content for GitBook outside the GitBook UI."
---

### When to Use This Skill

Use this skill when working with GitBook documentation through:

* Git-synced repositories (GitHub, GitLab)
* Local markdown editors
* IDE integrations
* Any environment where you're editing GitBook content as files rather than through the GitBook UI

### Quick Reference

#### GitBook Content Structure

GitBook organizes content through pages, spaces, and collections:

* **Pages** are individual markdown files that make up your documentation
* **Spaces** are collections of pages organized into a documentation site
* **Collections** are groups of spaces

**File structure:**

```
/
  .gitbook/
    assets/              # GitBook-managed images and files
    includes/            # Reusable content blocks
    vars.yaml            # Space-level variables
  .gitbook.yaml          # Configuration
  README.md              # Homepage
  SUMMARY.md             # Table of contents
  getting-started/
    installation.md
    quickstart.md
  api-reference/
    authentication.md
    endpoints.md
```

**Frontmatter fields (quick form):**

```markdown
---
description: "Page description for SEO"
icon: book-open
hidden: true
vars:
  page_variable: value
layout:
  width: default  # or 'wide'
  tableOfContents:
    visible: true
  pagination:
    visible: true
---
```

**Variables and expressions:**

* Space variables: `/.gitbook/vars.yaml`
* Page variables: Frontmatter `vars:`
* Expression syntax: `<code class="expression">space.vars.variableName</code>`

**Most common custom blocks:**

* `{% tabs %}...{% endtabs %}` — for alternatives
* `{% hint style="..." %}...{% endhint %}` — callouts (info/warning/danger/success)
* `{% stepper %}...{% endstepper %}` — sequential steps
* `<details>...<summary>...</details>` — expandable content

**Links:**

* External: `[text](https://example.com)`
* Relative (same space): `[text](page.md)`, `[text](../folder/page.md)`
* Cross-space (different space): `[text](https://app.gitbook.com/s/<spaceId>/<path>)` — relative paths never cross space boundaries, and this is the only correct URL form (not `/spaces/<id>/pages/<id>`). Get `<spaceId>` from `GET /orgs/{orgId}/spaces` and `<path>` from a page's `path` field in `GET /spaces/{spaceId}/content/pages`. Scaffolding a new site where the target space doesn't exist yet? Use `XSPACE_<KEY>` sentinels; `configure-site` resolves them after creation. Full examples: `references/markdown.md`.
* Moved/renamed pages keep working — GitBook auto-creates a redirect from the old path.

**Key reminders:**

* Read SUMMARY.md first when working with existing content
* Test in GitBook after editing locally
* Keep SUMMARY.md synchronized with your file structure
* OpenAPI specs must be uploaded via the UI, API, MCP, or CLI, not embedded in markdown

### When to Use Which Block

| Need | Use | Why |
|---|---|---|
| Sequential, ordered instructions | `{% stepper %}` | Clear step progression |
| Alternative options (languages, platforms) | `{% tabs %}` | User chooses without page clutter |
| Optional or detailed information | `<details>` | Keeps page scannable |
| Important warnings or tips | `{% hint %}` | Colored callout (info/warning/danger/success) |
| Side-by-side comparisons | `{% columns %}` | Parallel layout (max 2 columns) |
| Timeline or changelog | `{% updates %}` | Dated entries with tag filtering |
| Visual navigation cards | `<table data-view="cards">` | Clickable card grid |
| Downloadable files | `{% file %}` | File with caption |
| Call-to-action links | `

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: write-openapi
metadata:
  version: "1.0"
description: >-
  Author, configure, structure, and troubleshoot OpenAPI/Swagger API reference
  documentation in GitBook. Use this whenever a task involves a GitBook OpenAPI
  block or `{% openapi %}` block, adding or updating an OpenAPI/Swagger spec in
  GitBook (by file or URL, via the API, MCP, CLI, or app UI), generating API
  reference pages from a spec, configuring the interactive "Test it" runner
  (auth, servers, CORS, proxy), customizing pages with GitBook `x-*` extensions
  (icons, titles, navigation hierarchy, code samples, enum descriptions),
  marking operations experimental/deprecated/hidden, or automating spec updates
  in CI/CD. Trigger even when the user only mentions GitBook plus OpenAPI, puts
  an `x-` extension on a spec destined for GitBook, or asks "why isn't my spec
  loading" or "why doesn't Test it work", without naming this skill.
---

# GitBook OpenAPI

GitBook turns an OpenAPI document into interactive, testable API reference blocks. You give it a spec (as JSON or YAML), and it renders endpoints, parameters, schemas, auth, and an in-page request runner. Most of the customization happens inside the spec itself through `x-*` extensions, not in the GitBook UI, so the bulk of any task here is editing OpenAPI YAML correctly.

This skill covers the full surface: getting a spec into GitBook, generating reference pages, structuring navigation, making the "Test it" runner work, controlling how operations and schemas display, and automating updates from CI/CD.

## How you can talk to GitBook

Most of this skill — editing the OpenAPI YAML/JSON itself — is transport-agnostic. But getting a spec *into* GitBook, or generating/inserting reference pages, does touch GitBook, and there's more than one way to do that: GitBook's MCP server and the REST API. Check what's actually available in the current session and prefer **MCP first**: if GitBook MCP tools are already connected, use them for anything they cover (publishing/updating a spec, generating reference pages) instead of making direct API calls. Don't run a detection script for this — you already know your own available tools/MCP connections; just use that awareness.

The steps below are described as outcomes ("add the spec", "generate the reference pages") rather than tied to one transport, so they apply whichever you use. If GitBook MCP tools are connected, call those directly — their own schemas describe their parameters. If you're on the REST API path instead, the exact endpoints and request bodies are in "Add or update a specification" below.

- **GitBook MCP** — a full read/write surface over the same capabilities described below, not a narrower view. If it isn't connected yet and the task is substantial enough to benefit (publishing a new spec, generating a full reference — not a one-off tweak), offer to set it up: `claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp` (then `/mcp` to complete OAuth sign-in — or append `--header "Authorization: Bearer $GITBOOK_TOKEN"` to skip the browser flow). Codex equivalent: `codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp`. Note: this is a different server from GitBook's separate, read-only "published docs" MCP, which only exposes already-published content.
- **REST API** (`https://api.gitbook.com/v1`) — the fallback when MCP isn't connected, or for anything MCP doesn't cover. Needs `GITBOOK_TOKEN` as a bearer header on every request.

The same personal access token (from https://app.gitbook.com/account/developer) works as the bearer token for both. MCP additionally supports OAuth as a friendlier alternative to pasting a token.

**If you end up needing a token** (REST API path, or MCP without OAuth), check for it at the start of the session:

```bash
[ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set"
```

If `GITBOOK_TOKEN` is not set, ask the user directly:
1. Tell them they need a GitBook personal acces

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.