Agent skills

Add GitBook skills to AI coding assistants like Claude Code, Cursor, or Codex so they can work with GitBook pages, sites, and workflows

Setting up GitBook for the first time? Point your agent to Set up GitBook instead.

GitBook publishes a set of skills in the gitbook-skills repository. They teach AI coding assistants how to work with GitBook documentation: writing pages, configuring sites, OpenAPI references, change requests, and integrations. If you use Claude Code, Cursor, Codex, or another coding assistant, add the skills so your agent can use GitBook syntax, blocks, and configuration files correctly.

This fits well with Git Sync workflows — make changes in your repo, commit them, and your docs site updates automatically.

Prefer writing in the GitBook editor? Use GitBook Agent to draft, rewrite, review, and translate content without leaving GitBook.

Add GitBook skills to your AI agent

Use this option when your AI coding assistant supports package-based skills.

1

Connect GitBook MCP

Skills that only edit files, such as write-docs, don’t need GitBook authentication. Skills that talk to GitBook — including configure-site, write-openapi, cr-create, and cr-review — should use the GitBook MCP connection, which signs in with OAuth in the browser.

A personal access token from your developer settings is only needed if you’re calling the REST API directly. cr-create and cr-review use the REST API, so they need a token. configure-site and write-openapi prefer MCP first, and fall back to a token when MCP isn’t connected.

2

Install GitBook skills

The skills live in the gitbook-skills repository. Run the following command to install them in your project:

Without both -y flags, the installer waits for input.

Add GitBook skills locally

Download GitBook’s skills if your assistant doesn’t support package-based skills.

1

Download GitBook skills

Install GitBook skills with npx -y skills add GitbookIO/gitbook-skills -y when your assistant supports it.

To copy the files to your project manually, get them from the gitbook-skills repository.

Skill
Description
Download

write-docs

Author and edit GitBook-flavored Markdown pages.

configure-site

Create and configure GitBook sites end-to-end via the REST API.

write-openapi

Author and publish OpenAPI reference docs in GitBook.

cr-create

Drive a GitBook docs review flow via the REST API — create a change request, push content, request review, and fix comments.

cr-review

Review GitBook change requests via the REST API — discover CRs, summarize changes, comment, approve, or request changes.

build-integration

Build, develop, and publish GitBook integrations — custom blocks, ContentKit UI, events, and OAuth.

Using GitBook skills

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

FAQ

What do the GitBook skills contain?

The skills in the gitbook-skills repository give your AI coding assistant the context it needs to create, edit, and format GitBook content correctly.

write-docs includes:

  • A complete syntax reference for custom blocks.

  • Configuration file formats, including .gitbook.yaml, SUMMARY.md, and .gitbook/vars.yaml.

  • Frontmatter options, layout controls, variables, expressions, decision tables, and common pitfalls.

The other skills cover site setup, OpenAPI references, change requests, and integrations.

How do I test AI-generated content?

Always review and test content generated by AI assistants. When working with an assistant trained on the GitBook skills:

  • Verify that custom blocks render correctly in GitBook.

  • Check that all internal links work.

  • Confirm that the frontmatter is valid YAML.

  • Test that variables reference the correct scope.

How do I know my assistant is using the GitBook skills?

Ask it to explain how it would format a GitBook page.

If it references GitBook blocks, frontmatter, variables, or files like SUMMARY.md, the skills are loaded.

If it answers with generic Markdown only, check that the skills are installed and reload the assistant.

Why is the assistant ignoring GitBook-specific syntax?

This usually means the skills aren’t loaded, or the rules aren’t specific enough.

Make sure the GitBook skills are installed, and that your assistant can read them.

If the assistant caches instructions, restart the session after you add or update a skill.

What if the assistant generates invalid GitBook content?

Check the common failure points first:

  • Unclosed custom blocks

  • Invalid YAML in frontmatter

  • Broken variable references

  • Links that don't match your page structure

Always review the output in GitBook before you commit it.

Do I still need an access token?

Connect GitBook MCP and sign in with OAuth when a skill needs to talk to GitBook. That covers most of configure-site and write-openapi.

You need a personal access token when a skill calls the REST API directly, including cr-create and cr-review, or when MCP isn’t connected. You can create one in your developer settings.

If you’re only editing files locally with write-docs, you don’t need a token or an MCP connection.

What if the skill seems outdated?

Update the installed skills, or point your assistant back to the GitHub source.

If your team copied parts of a skill into custom rules, update those too.

Last updated

Was this helpful?

Powered by GitBook