AI coding assistants and skill.md

Use GitBook’s official skill.md file to give your AI coding assistants knowledge of GitBook’s features and blocks

GitBook provides a skill.md file that teaches AI coding assistants how to properly edit GitBook documentation. Use it as “project rules” when editing GitBook docs locally.

This fits well with Git Sync workflows where you edit your docs locally and then commit your changes to update your docs site. The reference file covers GitBook's markdown extensions, custom blocks, configuration files, and best practices.

Download

27KB

skill.md

Open

Prefer writing with AI in the GitBook editor?

GitBook also offers GitBook Agent for AI-assisted documentation right from your editor. This guide is for teams who prefer to use external coding assistants like Claude Code or Cursor.

What skill.md contains

• Complete syntax reference for all custom blocks

• Configuration file formats (.gitbook.yaml, SUMMARY.md, .gitbook/vars.yaml)

• Frontmatter options and layout controls

• Variables and expressions syntax

• Decision tables for choosing the right block type

• Common pitfalls and best practices

Adding this file to your AI coding assistant provides the information it needs about creating, editing and formatting content for your GitBook docs. This means that the assistant will follow established frameworks and best practices for GitBook's features.

Using skill.md via URL

Most AI coding assistants support project-specific instructions. You can reference the skill file in your project configuration by providing the URL for the skill file so the assistant knows how to work with GitBook syntax.

Using skill.md locally

You can also download the skill file and include it in your repository. First, download the skill.md to your repository root, and then reference it in the rules file for your coding assistant: "Read skill.md in the repo root for GitBook syntax and best practices" .

This approach works offline and allows team-specific modifications.

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

Testing AI-generated content

It’s important that you always review and test content generated by AI assistants — both for technical accuracy and proper formatting.

When working with AI assistants trained on the skill file, you should:

• Verify that any custom blocks render correctly in GitBook

• Check that all the internal links work

• Confirm that the frontmatter is valid YAML

• Test that variables reference the correct scope

Note: AI assistants may occasionally generate incorrect syntax or forget to close custom blocks. Always review changes before committing.

GitBook Agent

Prefer working directly in GitBook? GitBook Agent gives you an AI-assisted workflow in the GitBook editor — regardless of whether you use Git Sync.

The Agent has the full context of your docs, and is already trained on how to use GitBook’s blocks and features in the best possible ways. The Agent helps you draft content, make updates, and optimize your docs for different use-cases all from within the GitBook app.

Discover GitBook Agent