configure-site — an agent skill by gitbookio

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 c

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 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: If GITBOOK TOKEN is not set, ask the user directly: 1. Tell them they need a GitBook personal access token. Direct them to https://app.gitbook.com/account/developer to create one. 2. Ask them to paste the token into the conversation. Immediately export it as an environment variable ( export GITBOOK TOKEN=<pasted value ) and don't repeat it back in your response. 3. Do not proceed with any API calls until the token is confirmed present in the environment. Never write the token to a file, never echo it back in a response, never commit it. The fundamental constraint The most important thing to internalize before doing anything: GitBook can do almost everything except set up Git Sync, regardless of transport . Authorizing GitHub/GitLab, picking the repository, choosing the branch, and choosing the initial sync direction are all UI only operations — both the REST API and MCP (which wraps it) only let you read the resulting Git Sync state, never set it up. There's an API operation, installGitSyncProviderOnTarget , that targets either a site or a space, but the account connection (OAuth) step still has to happen in the app, and it isn't yet exposed through GitBook's MCP server — treat it as not yet usable rather than building a flow around it. Git Sync now configures at the site level, and that's the default to reach for. One connection (one repo, one branch) covers the whole site; gitbook docs.yaml maps each space to its own directory, which is the same shape this skill already scaffolds a monorepo into. Per space Git Sync still exists, but it's now the exception — reach for it only when a specific space needs an independent repo or branch (e.g. a private space that can't live in the public docs repo). That means the cleanest end to end flow is always: 1. Claude scaffolds a Git repo locally as a monorepo (one directory per space), ideally with gitbook docs.yaml pre authored mapping each space to its directory, and pushes the remote when tooling permits 2. Claude creates the site, sections, and any empty spaces it can 3. The user does one short, well scripted UI step in GitBook: connect the site to the repo/branch and confirm the space to directory mapping — not one step per space 4. Claude applies branding/customization The user's role in step 3 is unavoidable but should never be a surprise — generate clear, copy paste ready instructions for them. Reference: references/git sync handoff.md . If the user explicitly does not want Git Sync, fall back to the content import path (content import and template application) — covered briefly below and in references/api cheatsheet.md . Inputs you should gather up front Don't start scaffolding until these are known. If something is missing, ask once with a focused question rather than guessing. (Auth is handled separately — see "How you can talk to GitBook" above.) Organization — list the user's orgs and show the list to the user, then ask them to confirm which one is the target by name . Do this even if they have only one org — confirming once up front is cheap insurance against creating sites in the wrong place. Save the chosen organizationId for the rest of the session and refer to the org by its title (not its UUID) when narrating subsequent steps. Site plan and visibility — default to type: site on the Ultimate plan , public visibility, unless the user explicitly says otherwise. Most real customers want the Ultimate feature set (custom domain, AI Assistant, advanced customization, hidden GitBook trademark, custom fonts, custom logos). The free tier ( type: basic ) is appropriate only for clearly low stakes use cases like solo open source side projects. If you're unsure, ask: "I'll set this up on the Ultimate plan unless you'd prefer the free tier — should I downgrade?" — Ultimate features that are silently absent on basic (no AI assistant, no custom fonts, no custom domain) are a much bigger user surprise than briefly confirming the plan. The content seed — what's the site being built from? Common shapes: A folder of existing markdown — the cleanest starting point A handful of notes plus a competitor's site as a reference Just a description of what they want to document An existing site they want to restructure (in which case fetch the site's current structure first) A migration from another docs platform (Mintlify, Docusaurus, ReadTheDocs, GitBook v1) — see references/migration from other platforms.md for the workflow. Migration is its own discipline; don't treat it as a glorified file copy. OpenAPI spec for the API reference — if the site has any API reference content, ask up front whether they have an OpenAPI spec (or whether one can be generated from their codebase). If yes, the API reference space is one builtin:openapi SUMMARY entry plus a one paragraph overview README per resource — dramatically less work than hand authored endpoint pages, and never drifts. See references/block ecosystem.md and references/api cheatsheet.md for the workflow. Don't default to hand authored endpoint pages — they're almost always the wrong call. Branding — at minimum, primary color (hex). Optionally: logo URLs (light + dark), favicon, font choice (or one of GitBook's defaults), header links, footer text/links, theme preset ( clean , muted , bold , gradient ). For Ultimate sites, also consider AI assistant starter prompts (3 5 short questions visitors are likely to ask). Site structure — sections, not site spaces. If the site has more than one space, plan the section list with the user explicitly: each section has a title, a Font Awesome icon name, and a description. Section icons and descriptions are first class navigation furniture — visitors see them — and gathering them up front saves a follow up update per section later. Example: [{title: "Guides", icon: "book open", description: "Concepts and tutorials"}, {title: "API Reference", icon: "code", description: "REST API and SDKs"}, {title: "Changelog", icon: "clock rotate left", description: "Updates and release notes"}] . Git remote preference — GitHub, GitLab, or local only. Check whether gh or glab are installed before asking. If neither tool is available, say so explicitly and offer two paths: (1) commit locally and put the "create the remote and push" step at the top of the user's handoff, or (2) ask the user to install the tool. Don't quietly default to local only without telling them — they'll have a repo with no remote and no instructions. Site shape — single space or multi space. Multi space sites use sections to group spaces in the navigation; this is the right choice when content has clearly distinct audiences (e.g. user docs + API reference + changelog). Use site spaces directly only for translation variants — see references/api cheatsheet.md . Verify the content source before building Once the user names a content seed — a repo, folder, or docs site URL — verify you can actually read it before designing structure or scaffolding anything: 1. Resolve and echo the source. State exactly what you're about to read (repo URL and branch, folder path, or site URL) and show the user its top level contents — a short file or page list — so they can confirm it's the right one. 2. If you can't access it, stop and say so. Git hosts return 404 for private repositories — indistinguishable from "repository doesn't exist." Treat any 404 or clone failure on a user named repo as possibly private : tell the user what failed, and ask them to either make the content reachable (local clone, archive, authenticated gh / glab , public mirror) or correct the URL. Check whether an authenticated gh / glab CLI is available before declaring the repo unreachable. 3. Never substitute a source. Do not search for, guess, or fall back to a similarly named repository or site — even one that looks identical. Building a docs site from the wrong source is far worse than pausing to ask. Any change of source requires the user's explicit sign off. Confirmation gates for state changing operations Site creation, space creation, adding sections, attaching site spaces, and customization changes all create or modify objects that are immediately visible to everyone in the org and that take real effort to clean up. Treat them as heavy operations. The rule: never make a state changing change without first showing the user a one screen preview of exactly what's about to happen and getting an explicit "yes". A good preview is short and concrete: About to run, in org Acme Inc ( org abc123 ): Create site "Acme Platform Docs" (type: site, plan: ultimate, visibility: p