Agent skills

Use GitBook’s official SKILL.md file to give AI coding assistants like Claude Code, Cursor or Codex knowledge of GitBook’s features and blocks

GitBook provides skill files that teach AI coding assistants how to edit GitBook documentation correctly. If you use Claude Code, Cursor, Codex, or another external coding assistant, add GitBook skills so your agent can work with GitBook syntax, blocks, and configuration files.

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

Create an access token

To let your agent interact with GitBook, you need to create an access token from your GitBook developer settings. GitBook uses this token to authenticate your agent when working with GitBook skills.

2

Install GitBook skills

This skill is part of the gitbook-skills repository. Run the following command to install GitBook skills directly to your project:

npx skills add GitBookIO/gitbook-skills

Add GitBook skills locally

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

1

Create an access token

To let your agent interact with GitBook, you need to create an access token from your GitBook developer settings. GitBook uses this token to authenticate your agent when working with GitBook skills.

2

Download GitBook skills

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

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

Skill	Description	Download
configure-site	Create and maintain entire GitBook documentation sites.	GitHub
write-docs	Write, author, edit, and format GitBook documentation pages.	GitHub
write-openapi	Author, configure, structure, and troubleshoot OpenAPI/Swagger API reference docs.	GitHub
build-integration	Build custom integrations for GitBook.	GitHub
cr-create	Create GitBook change requests, push content, request reviews, and address comments.	GitHub
cr-review	Review GitBook change requests, summarize changes, comment, approve, or request changes.	GitHub

Remember to update your local repository with the latest SKILL.md file as GitBook adds new features.

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 does SKILL.md contain?

SKILL.md gives your AI coding assistant the context it needs to create, edit, and format GitBook content correctly.

It 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.

How do I test AI-generated content?

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

• 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 SKILL.md?

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

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

If it answers with generic Markdown only, check your project rules and reload the assistant.

Why is the assistant ignoring GitBook-specific syntax?

This usually means the skill file isn’t loaded, or the rules aren’t specific enough.

Make sure your assistant reads SKILL.md from the repo root, or uses the GitHub URL in its project instructions.

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

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?

You need an access token when your agent interacts with GitBook directly. You can create a personal access token in your developer settings.

If you’re only editing files locally with SKILL.md, you might not need one until you connect the assistant to GitBook workflows or APIs.

What if the skill seems outdated?

Update your local SKILL.md, or point your assistant back to the GitHub source.

If your team copied parts of the file into custom rules, update those too.