Agent experience starts on your homepage

More people start a task by asking an agent: "Set up GitBook for me," or "Move our docs over from ReadMe." Whatever the agent finds first decides how the next ten minutes go. That's agent experience (AX): how well AI agents can find, read, and act on your website and docs.

Over the last few weeks we looked closely at that first contact. We wanted to know how much of our traffic comes from agents, what they’re trying to do, and how well we help them do it. For context, AI agents now account for 51.8% of intentional reads across GitBook-hosted documentation, ahead of humans at 48.2%, according to our research on a week of traffic in spring 2026. This post covers what we changed and what we learned. Three choices shaped most of it: we plan for the steps only a person can do, we treat migration as a first-class path, and we went beyond the docs to our website.

What agents come to do

When we looked at what agents were asking for, two jobs stood out:

• Set up GitBook and publish a docs site.

• Move existing docs into GitBook from another tool.

Both jobs span several surfaces: the GitBook MCP server, the CLI, the API, Git Sync, and the Import panel. Each docs page assumed the reader knew which one to use. An agent knows only the request it was given and the last page it fetched.

One page written for agents

We wrote Set up GitBook, a single page addressed to agents. Step 1 of our Quickstart points agents there, and people get a prompt they can paste into their own agent.

The page starts by asking the agent who it is. A coding agent that can run commands connects the GitBook MCP server and does the work. A hosted assistant such as Claude or ChatGPT can’t install anything, so it relays a short set of steps for adding the official GitBook connector. If GitBook tools are already in the session, the agent confirms they work with one read-only call and skips ahead.

Then the agent asks the person one question: are you starting new docs, or moving docs you already have? Everything after that branches from the answer.

The MCP server is the primary route. The GitBook CLI is the fallback when the MCP tools can’t load in a session, and the API covers anything neither reaches.

A person stays in the loop, by design

GitBook needs an account, and only a person can create one and approve a sign-in. So setup.md plans around it.

The agent does all its prep first: it reads the codebase or the existing docs, drafts a short plan, and saves it to a file, because restarting the client to load the MCP tools ends the agent’s session. Then it sends one “your turn” message that covers every human step at once: create an account, restart, sign in, and say “done.” When the person comes back, the agent picks up from the plan and publishes.

A few rules make this trustworthy:

• The agent reads a config file before it changes it, says which file it’s about to change, and touches only the GitBook entry.

• If a client’s safety mode blocks a command, the agent doesn’t retry it or route around it. It tells the person what the command does and lets them run it.

• Every message to the person is two or three sentences: what’s done, and the one thing to do next.

That way the agent knows where its job ends and doesn’t have to guess.

Migration is a first-class path

Many teams that come to GitBook already have docs somewhere else, so migration gets its own section in setup.md. The agent works out where the docs live and picks a route:

• Mintlify and Docusaurus: the docs are Markdown or MDX in a Git repository, so the agent prepares the repo, converting Mintlify-specific MDX components to GitBook blocks, and the person connects Git Sync.

• ReadMe: the agent uses ReadMe’s Git Connection, or an export with rdme docs export, then Git Sync. The Import panel is the fallback.

• Confluence, Notion, and other published sites: the person uses the Import panel in the app.

• A few local Markdown files: the agent adds them as pages in a change request.

Each route names who does what, so the human step joins the single hand-off.

Your website is part of your agent experience

This was our biggest lesson. Agents rarely start at llms.txt. They fetch the page they were sent to, or the first one a search returns, and very often that’s the marketing site, not the docs.

Our website runs on Framer, which serves a Markdown version of each optimized page when an agent asks for it with ?md or an Accept: text/markdown header. So we started reading our homepage the way an agent sees it and made two kinds of changes:

• A line written for agents. The homepage Markdown opens by pointing agents to llms.txt for an overview and to setup.md for setup or migration.

• Prompts people can hand off. The homepage has “Set up GitBook with your agent” links that open Claude Code, Codex, or Cursor with the setup prompt filled in, a Copy prompt button, and links to the official Claude and ChatGPT connectors. Each of our eight comparison pages, such as GitBook vs Mintlify, has a “Migrating from Mintlify to GitBook?” section that offers to book a call or suggests you “ask your agent to migrate your docs,” with the same agent links and prompt. One prompt covers both jobs, because the first thing setup.md has the agent ask is whether you’re starting new docs or moving existing ones.

When the agent gets stuck

setup.md ends with two ways out. The agent can add ask and goal parameters to any docs page’s .md URL and get a Markdown answer. With the MCP connected, it can report what went wrong with report_tool_feedback.

Every GitBook site gets the same surfaces

None of this is special to our own docs. Every published GitBook site includes:

• Markdown pages at any page URL plus .md, and llms.txt and llms-full.txt at the site root.

• An MCP server for your docs at /~gitbook/mcp, which agents can use to search and read your content. With AI enabled, it also has an askQuestion tool for grounded answers. Browser agents can use its search and page tools through WebMCP.

• A sendFeedback tool on that MCP server, so agents can report content that’s unclear, outdated, or missing, and your team can act on it.

• An Agents & MCP report in site analytics, which shows the LLMs, coding agents, and crawlers that read your site and which pages they use.

Together they close a loop: agents read your docs and tell you where they fall short.

How to improve agent experience for your own docs

Here’s what we’d suggest to any docs team:

1. Find out what agents come for. Look at agent traffic and the questions agents ask. Pick the two or three jobs that matter most.

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

3. Name the human steps. Say plainly what only a person can do, and group those steps into one hand-off.

4. Make migration a route, not a footnote. If people switch to you from other tools, tell the agent how to bring their content along.

5. Read your website as an agent. Fetch your key pages as Markdown and look for missing content and missing pointers.

6. Give agents a way to ask and to report. A question endpoint and a feedback channel turn dead ends into fixes.

7. Measure it. Track agent traffic over time so you know whether the changes help.

Try it

Paste this into your coding agent or AI assistant to set up GitBook:

To move your existing docs instead:

If something doesn’t work the way the page says, your agent can tell us, and we’ll fix it.

→ Read the setup page agents follow

→ Introducing WebMCP support: your docs’ MCP server, now in the browser

→ Check how agent-ready your docs are with Agent score