Industry
Published:
13 Nov, 2026
What we learned running a hands-on AI workshop at Write the Docs 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.
Open Claude Code in the docs repo. This puts the agent in the files it needs to edit.
Connect the published site’s MCP server. The live docs give it context for the update and help it avoid duplicating existing content.
Install GitBook skills for writing and formatting guidance (optional). It’s worth checking whether the other tools you use publish their own skills, too.
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.
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.
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.
Check links across the whole site. The review should include pages outside the files changed in the PR.
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.
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.
Connect the GitBook MCP so the agent can retrieve those gaps.
Ask it to draft a PR addressing the gap, following the update workflow.
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
Read more
Industry
Get the GitBook newsletter
Get the latest product news, useful resources and more in your inbox. 130k+ people read it every month.

25 Aug, 2026
The writing was never the hard part: notes from the State of Docs panel with WTD NYC

Tal Gluck
DevRel

3 Aug, 2026
Improving your docs and advocating for them are two different jobs

Tal Gluck
DevRel

22 Jun, 2026
Supporting AI standards at GitBook: What OKF, MCP and llms.txt tell us about the future of docs

Steven Hall
Head of Engineering
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



