Industry

Published:

13 Nov, 2026

What we learned running a hands-on AI workshop at Write the Docs San Francisco

GitBook and Write the Docs logos side by side above a label reading Practical AI for Documentation · San Francisco.

AI summary

At Write the Docs Bay Area, GitBook ran a hands-on workshop covering three AI-assisted documentation workflows: turning a PRD into a draft PR, reviewing the changes, and addressing gaps in published docs. The session showed how clients, reusable skills, and MCP connections support those tasks. Attendee requests for the demonstrated skills and guidance on using them informed the Docs AI Toolkit.

On October 6, Sarah Dugan, our Docs Lead, and I (Addison Schultz) ran a hands-on workshop at Write the Docs Bay Area in San Francisco. The evening, Practical AI for Documentation, took place at Mindspace on Market Street. Ian Alton, Head of Technical Writing at Airbyte, opened with a look at AutoDoc, the production system Airbyte uses to keep documentation for 600+ open source connectors up to date.

Our session focused on the work of a technical writer: taking a feature brief, getting a draft into review, and dealing with gaps in published docs. We chose three scenarios so we could work through those tasks with the room and show where AI clients, skills, and MCP connections fit into the process.

Here’s how we approached each one, with the steps you can use to try them on your own docs.

Why AI fluency matters for tech writers

AI is already part of many writers’ working day. In the State of Docs Report 2026, 76% of respondents said they regularly use AI for documentation creation, compared with 60% in 2025. Meanwhile, 64% expected AI to be “extremely impactful” for documentation, up from 49%.

Regular use doesn’t necessarily give you a repeatable process, though. When an agent drafts or reviews content, you still need to check its accuracy and make sure it follows the conventions your team has agreed on. That’s what we wanted attendees to practice.

Three building blocks

We started by explaining the tools we’d use throughout the workshop.

  • The client: The app where you work with the AI. Claude on the web or desktop suits writing, research, and quick reviews. For the repository work in our scenarios, we used Claude Code, which can work directly on docs files, handle bulk changes, and open PRs.

  • Skills: instructions the AI can reuse. Each skill is a folder containing a SKILL.md file, with optional examples, templates, or scripts alongside it. The description tells the agent when to use the skill; the body explains how to carry out the task. Writing those instructions uses many of the same skills as writing docs.

  • MCP (Model Context Protocol): This connects the agent to outside tools and data. Every published GitBook site has an MCP server at {docs-site-url}/~gitbook/mcp, giving the agent access to the live documentation.

In the workshop, we used MCP to supply context and connect tools, then skills to guide how the agent worked with them.

Workflow 1: Updating content, from a PRD to a draft PR

For the first scenario, an engineer had handed over a PRD for a new feature. Our job was to turn it into a documentation PR that another writer could review.

The PRD supplied the feature details. We also gave the agent access to the published docs so it could see what was already covered and where the new material belonged.

  1. Open Claude Code in the docs repo. This puts the agent in the files it needs to edit.

  2. Connect the published site’s MCP server. The live docs give it context for the update and help it avoid duplicating existing content.

  3. Install GitBook skills for writing and formatting guidance (optional). It’s worth checking whether the other tools you use publish their own skills, too.

  4. Give the agent the PRD and ask it to draft the documentation and open a PR. This gave us a version that was ready for review

Workflow 2: Reviewing content in the PR

Next, we took on the role of a second technical writer reviewing that PR. Sarah created and installed a style-guide skill live, turning house rules into instructions the agent could apply to the draft.

  1. Connect the agent to GitHub and ask it to leave proposed edits as suggestions on the PR. That keeps the changes visible and leaves the author in control of what gets accepted.

  2. Use a style-guide skill to check the draft against your team’s rules. Once those instructions are in a skill, you can reuse them without pasting the guide into every prompt.

  3. Check links across the whole site. The review should include pages outside the files changed in the PR.

  4. Run the AI readability check skill to help make the content easier for AI assistants to read and answer from.

The style-guide skill was something the team could keep in the repo and share. Everyone could use the same instructions on subsequent reviews, alongside any other skills the task needed.

Workflow 3: Fixing content drift

The final scenario began with published docs that had gaps or had fallen out of date. This time, we needed to identify what required attention before drafting a change.

We used GitBook’s Content gaps to find that starting point, then returned to the update and review process attendees had just practiced.

  1. Find unanswered questions with Content gaps. It compares your published content with visitor questions, support tickets, forum posts, and other records from connected sources. Each gap has a severity ranking, an explanation of the problem, supporting evidence, and a recommendation.

  2. Connect the GitBook MCP so the agent can retrieve those gaps.

  3. Ask it to draft a PR addressing the gap, following the update workflow.

  4. Review the PR with the same style-guide skill and checks used earlier.

This last workflow was the one that tied the evening together. It helps teams catch documentation drift with the same update and review steps the room had just practiced, closing the loop on docs quality.

What attendees asked, and what we learned

During and after the workshop, people asked for the skills we’d demonstrated and built live so they could use them on their own docs. They also wanted help choosing which skills to install and which tasks to hand over first.

Some questions were about working as a team: how do you share skills so everyone uses the same rules? Others were focused on the results, including how to check whether documentation is ready for AI agents. The common theme across all the discussions, though, was that attendees wanted practical guidance on using AI without losing accuracy or control.

The client, skills, and MCP connections we’d used were already available. But the requests suggested that gathering documentation skills in one place, with guidance on using them, would make it easier for attendees to try these workflows themselves.

What we did next

To make useful skills easier to find, we built the Docs AI Toolkit. It includes free documentation skills, a skill generator, and Agent score to help you understand how well your docs are set up for agent consumption. You can use them with any docs site, without creating an account.

We’ll next be at the Write the Docs London meetup on Thursday, November 19 at Wallacespace Spitalfields. I’m speaking about how we run our own docs at GitBook, and how we’re improving them for agent consumption. You can find that meetup and our other upcoming events on our events page.

Thanks to Write the Docs Bay Area and organizer Doug Purcell for hosting, and to Ian Alton and Airbyte for the opening talk.

→ How to create and publish documentation with AI and MCP

→ Free documentation skills in the Docs AI Toolkit

→ By the numbers: Where documentation quality breaks down in 2026


Share
Get the GitBook newsletter

Get the latest product news, useful resources and more in your inbox. 130k+ people read it every month.

Email

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?

Enterprise

Intelligent documentation that’s built to scale




FreedomPay thumbnail
FreedomPay logo - white
FreedomPay

How FreedomPay is rebuilding its integration experience with GitBook

The State of Docs Report 2026

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

FreedomPay thumbnail
FreedomPay logo - white
FreedomPay

How FreedomPay is rebuilding its integration experience with GitBook

The State of Docs Report 2026

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

FreedomPay thumbnail
FreedomPay logo - white
FreedomPay

How FreedomPay is rebuilding its integration experience with GitBook

The State of Docs Report 2026

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