Product updates
Published:
13 Nov, 2026
How we made GitBook easier for AI agents to use

AI summary
GitBook improved its agent experience with website entry points that direct agents to task-oriented setup and migration instructions. The workflows explain tool selection, fallback routes, and human handoffs. Published docs also provide machine-readable content, MCP tools, feedback, and analytics to help teams support agents and improve their experience.
Ask a coding agent to set up a documentation site, and it may find several guides explaining different ways to get started. Before it can begin, it has to work out which instructions apply and which tools to use.
We’ve been working on that problem at GitBook. We call it agent experience (AX): how easily agents can find information and use it to complete tasks. In our research from spring 2026, AI agents accounted for 51.8% of intentional reads across GitBook-hosted documentation, compared with 48.2% from humans.
Those agents need readable documentation, guidance on using tools, and instructions for involving people. So recently, we focused on improving how they interact with GitBook, particularly when setting up a site or migrating existing docs.
Your website is part of your agent experience
Our first instinct was to focus on documentation. GitBook already provides Markdown, llms.txt, and MCP servers to make docs accessible to agents. But we quickly realized that an agent might encounter our homepage or a comparison page first and need directions from there.
Our marketing website runs on Framer, which can serve optimized pages as Markdown when requested with ?md or an Accept: text/markdown header. So we started reading our homepage as an agent would.
The homepage Markdown now points agents to llms.txt for an overview of GitBook and to setup.md for setup and migration instructions. Visitors can also open Claude Code, Codex, or Cursor with a setup prompt already filled in, copy the prompt themselves, or connect GitBook to Claude and ChatGPT.
We extended this approach to other pages, too. For example, comparison pages now offer visitors the option to book a migration call or ask their agent to migrate their docs for them.
One setup page, with different paths for different agents
Publishing a new GitBook site and migrating existing documentation can involve GitBook’s MCP server, CLI, API, Git Sync, and Import panel. We’d documented each tool individually, but agents still had to work out which to use.
To help guide them, we created Set up GitBook, a page written for agents, and linked to it from our Quickstart.
It starts by asking the agent who it is to establish what it can do. A coding agent that can run commands will connect to the GitBook MCP server. A hosted assistant such as Claude or ChatGPT that can’t configure tools itself guides the person through adding the official GitBook connector. if GitBook tools are already in the session, the agent verifies them with a read-only call and jumps ahead.
Next, the agent asks the user one question: “Are you starting new docs, or moving docs you already have?” The answer determines the workflow.
MCP is the primary route, with the GitBook CLI as a fallback when MCP tools can’t load, and the API for operations neither supports.
A person stays in the loop, by design
Someone needs to create a GitBook account and approve agent authentication. We designed the workflow around those requirements, including the interruption they can cause.
The agent does all its prep first, reading the codebase or existing docs, preparing a plan, and saving it to a file. Restarting a client to load newly connected MCP tools can end the active session, so saving the plan gives the agent somewhere to resume.
It then gives the person one handoff message covering the required steps: create an account, restart if necessary, sign in, and confirm when finished.
We also established rules for how agents should behave:
Inspect configuration files before editing them, explain the change, and modify only the GitBook entry.
If a command is blocked, respect the restriction. Explain it and let the person decide whether to run it.
Keep handoffs to two or three sentences explaining what’s complete and what happens next.
Migration gets its own, dedicated workflow
Many teams that come to GitBook already have docs somewhere else, so migration gets its own section in setup.md.
The agent needs to understand where content lives, how it’s structured, and how to move it. The routes in setup.md depend on the source:
Mintlify and Docusaurus: the agent prepares the Markdown or MDX repository, converting Mintlify-specific components where necessary. The person then connects Git Sync.
ReadMe: the agent uses ReadMe’s Git Connection or an export with
rdme docs export, followed by Git Sync. The Import panel is a fallback.Confluence, Notion, and other published sites: the agent guides the person through the Import panel.
Local Markdown files: the agent adds a small collection of files through a change request.
Each route explains what the agent can handle and where it needs human input.
When an agent gets stuck
We added two ways for agents to get help with unexpected problems. They can append ask and goal parameters to a docs page’s .md URL to request a Markdown answer. With GitBook’s MCP server connected, they can also use report_tool_feedback to report tool problems. These reports help us identify what needs improving.
What this means for your own docs
The setup workflow is specific to GitBook, but every published GitBook site includes features that help support a good agent experience:
Markdown pages,
llms.txt, andllms-full.txtmake content machine-readable.MCP for published docs provides search and read tools at
/~gitbook/mcp, plusaskQuestionwhen AI is enabled. Browser agents can also access search and page tools through WebMCP.The
sendFeedbacktool lets agents flag unclear, outdated, or missing content.Agents & MCP analytics shows which agents access your docs and which pages they use.
Task-oriented instructions build on these capabilities by explaining how agents can use the information and tools to complete a workflow.
How to improve your own agent experience
Here are the things we suggest docs teams focus on to improve AX for your own product:
Find out what agents come for. Look at agent traffic and the questions agents ask, then pick the two or three jobs that matter most.
Write one page per job, addressed to the agent. Branch on what the agent can do, ask the person one clarifying question, and keep messages short.
Name the human steps. Say plainly what only a person can do, and group those steps into a single hand-off.
Make migration a first-class route, not a footnote. If people switch to you from other tools, tell the agent how to bring their content along.
Read your website as an agent. Fetch your key pages as Markdown and look for missing content and missing pointers.
Give agents a way to ask and to report. A question endpoint and a feedback channel turn dead ends into fixes.
Measure it. Track agent traffic over time so you know whether the changes help.
Try it yourself
Want to test out how GitBook’s AX stacks up? Paste either of these prompts into your coding agent or AI assistant.
To set up GitBook:
Set up GitBook for me by following https://gitbook.com/docs/setup.md
To migrate existing docs:
Migrate my docs to GitBook by following https://gitbook.com/docs/setup.md
→ Read the setup page agents follow
→ Research: What documentation defects cost AI coding agents
→ How to optimize your documentation for AI (without breaking it for humans)
Share
Read more
Product updates
Get the GitBook newsletter
Get the latest product news, useful resources and more in your inbox. 130k+ people read it every month.
Accurate docs. Better answers.
Your docs are already feeding AI. Are users getting the right answers or the wrong ones?
Accurate docs. Better answers.
Your docs are already feeding AI. Are users getting the right answers or the wrong ones?
Accurate docs. Better answers.
Your docs are already feeding AI. Are users getting the right answers or the wrong ones?
Product
Create & Publish
Solutions
Resources
© 2026 Copyright GitBook INC.
440 N Barranca Ave #7171, Covina, CA 91723, USA. EIN: 320502699
Get an AI summary

The State of Docs Report 2026
State of Docs brings together insights from documentation experts from across the industry

Product
Create & Publish
Solutions
Resources
© 2026 Copyright GitBook INC.
440 N Barranca Ave #7171, Covina, CA 91723, USA. EIN: 320502699
Get an AI summary
The State of Docs Report 2026
State of Docs brings together insights from documentation experts from across the industry

Product
Create & Publish
Solutions
Resources
© 2026 Copyright GitBook INC.
440 N Barranca Ave #7171, Covina, CA 91723, USA. EIN: 320502699
Get an AI summary
The State of Docs Report 2026
State of Docs brings together insights from documentation experts from across the industry









