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

On October 6 we were in San Francisco with Write the Docs Bay Area for an evening called Practical AI for Documentation, at Mindspace on Market Street. Ian Alton, Head of Technical Writing at Airbyte, opened with a production talk on AutoDoc, the system Airbyte uses to keep docs for 600+ open source connectors up to date. After that, our DevRel Lead Addison Schultz and our Docs Lead Sarah Dugan ran a hands-on workshop for the room.

Most technical writers already use AI. Fewer have a repeatable way to use it on real docs work without losing quality. So we skipped the theory and worked through three jobs every docs team does each week: updating content, reviewing it, and fixing drift.

Why AI fluency matters for tech writers

In the State of Docs Report 2026, 76% of respondents said they use AI regularly for documentation creation, up from 60% in 2025, and 64% said AI will be “extremely impactful” for documentation, up from 49%.

So the useful question isn’t whether writers will use AI. It’s how to keep docs accurate, consistent, and readable when an agent is doing part of the work.

Three building blocks

Before building anything, we covered three concepts:

• Client: the app you talk to the AI in. Claude on the web or desktop is good for writing, research, and quick reviews. Claude Code works directly in your repo, which makes it a good fit for docs-as-code, PRs, and bulk changes.

• Skills: instructions the AI loads when it needs them. A skill is just a folder with a SKILL.md file, plus optional examples, templates, or scripts. The description decides when the skill is used, and the body decides how the work gets done. If you can write docs, you can write a skill.

• MCP (Model Context Protocol): an open standard for connecting AI to outside tools and data. Every published GitBook site has an MCP server at {docs-site-url}/~gitbook/mcp.

In short, skills tell the AI how to do something, and MCP gives it access to something. The workshop used both.

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

The scenario: “An engineer just handed me a PRD for a new feature. Let’s get it into the docs.”

1. Open Claude Code in the docs repo. It does the work there and opens the PR.

2. Connect your published site’s MCP server. This gives the AI your live docs as context, so new content fits with what already exists rather than repeating it.

3. Add GitBook skills (optional). These give the agent GitBook know-how for writing and formatting. Whatever tools you use, it’s worth checking whether they already publish skills.

4. Hand over the PRD and ask for a draft PR. The new content lands as a PR, ready for review.

Workflow 2: Reviewing content in the PR

The scenario: “I’m a different tech writer, and I’m reviewing that same PR.”

1. Connect the agent to GitHub so it leaves every change as a suggestion on the PR. The author keeps control and reviewers can see exactly what changed.

2. Turn your style guide into a skill. Sarah created a style-guide skill live, installed it, and used it to check the PR against house rules. You only write the rules once, and you don’t have to paste the style guide into every prompt.

3. Check for broken links across the whole site, not just the files the PR changed.

4. Run the AI readability check skill so pages are easier for AI assistants to read and answer from.

Skills are worth the setup because they give you the same rules on every run, can be checked into the repo and shared with the whole team, and can be stacked for a single task.

Workflow 3: Fixing content drift

The scenario: “Our docs have drifted out of sync. Let’s find where, and fix it.”

1. Find what your docs don’t answer. In GitBook, Content gaps compares visitor questions, support tickets, forum posts, and other records from your connected sources with your published content. It ranks each gap by severity and describes the problem, the evidence, and a recommendation.

2. Connect the GitBook MCP so the AI can pull those gaps directly.

3. Fix them with the update flow, drafting the changes as a PR.

4. Check them with the review flow, against the same style guide skill.

This last workflow is the one that ties the evening together. Drift is caught with the same update and review steps the room had just practiced.

What attendees asked, and what we learned

The questions we got during and after the session were specific. People asked for the skills we demoed and built live, so they could run them on their own docs. They also asked for best practices: how to use AI effectively in their docs work without losing accuracy or control.

Those requests came back to three practical themes:

• Where to start: which skills are worth installing first, and which docs tasks to hand to AI first.

• How to share it: how to get skills into a team’s setup, so everyone works from the same rules rather than one person’s laptop.

• How to know it’s working: how to check whether docs are actually ready for AI agents.

What we took away is that writers don’t need more AI theory. They want the skills themselves, and a clear way to use them in the workflow they already have. The building blocks from the workshop (a client, a few skills, an MCP connection) already exist.

What was missing was a ready-made set of skills anyone could start using straight away.

What we did next

So we built one. The Docs AI Toolkit brings free documentation skills, a Skill generator and Agent score together in one place. They work with any docs site, and you don’t need an account. Find it at gitbook.com/ai-toolkit.

Our next stop is the Write the Docs London meetup on Thursday 19 November at Wallacespace Spitalfields, where Addison is speaking on “How GitBook runs its own docs.” See all our upcoming events at gitbook.com/events.

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