Show and Tell: We started using GitBook as a skill manager for AI agents

[YuyangXueEd]

We Started Using GitBook as a Skill Manager

We did not start this project trying to invent a new use case for GitBook.

We were trying to solve a practical problem in our group: as we started using AI agents for real research work, our useful instructions were ending up everywhere: Some lived in chat history, some in personal prompt snippets, some in Markdown notes, and some only in one person's head.

That felt wrong. A good workflow for reading a paper, writing a rebuttal, designing experiments, or checking a medical imaging fairness claim should be something the whole team can reuse and improve.

So we built Vios Research Skills: a shared library of SKILL.md files for contemporary AI research workflows.

At first, we thought of it as a skills repository. Then something clicked:

GitBook can be the visual management layer for team-built AI agent skills, while GitHub remains the distribution layer agents install from.

That is the pattern we are excited to share. 😸

The Pattern

GitBook has already explored skill.md as a way to help AI coding assistants edit GitBook documentation. Our use case is the inverse: we are using GitBook to help humans create, browse, improve, and manage the skills that agents use.

In our setup, each skill is one plain Markdown file:

skills/<skill-name>/SKILL.md

That same file has two readers:

• A human reads it in GitBook as a browsable workflow.
• An LLM agent reads it as procedural guidance when the skill is installed.

This matters because skills are not just prompts. They are shared practice. They need to be written, reviewed, versioned, and kept readable by the people who are responsible for the work.

Why GitBook + GitHub Sync Works

GitBook gives us the human-facing layer: visual navigation, search, categories, readable pages, and low-friction editing.

GitHub gives us the distribution and governance layer: source control, pull requests, CI checks, generated navigation, and a stable place for agents to install from.

Git Sync connects the two. A researcher can improve a skill in GitBook, the change lands in GitHub, and the same updated Markdown becomes available to agent clients such as Claude Code.

How We Made It Work

The setup is intentionally small. Our .gitbook.yaml points GitBook directly at the skills directory:

root: ./skills/
structure:
  readme: SKILL.md
  summary: SUMMARY.md

The GitBook homepage is skills/SKILL.md. The sidebar is skills/SUMMARY.md. Every skill page is the actual SKILL.md file an agent will later read. What you see in GitBook is what the agent sees.

We added a few guardrails:

• Existing skills can be edited in GitBook.
• New skills go through GitHub pull requests.
• Skills stay in plain Markdown, without GitBook-only blocks.
• SUMMARY.md is generated from skill frontmatter.
• CI checks names, categories, descriptions, and sidebar consistency.

We also added a small auto-update path. In our setup, the installer can register a Claude Code startup hook that quietly runs npx skills update --yes at the beginning of a session. The broader point is simple: once a skill is improved in GitBook and synced to GitHub, agents can pull the updated workflow without anyone copying prompts by hand.

What Feels New

We are not claiming to have invented SKILL.md, Git Sync, or skill managers. The interesting part is the combination:

GitBook + GitHub Sync + SKILL.md can become a team skill manager for AI-native work.

Most skill managers focus on installation and local agent environments. That matters, but it is only half the problem. Before a skill can be installed, a team has to write it, read it, agree on it, improve it, and keep it from drifting.

That is the management layer. GitBook is very good at it. For us, this turns GitBook from a place where knowledge is documented into a place where agent behavior is shaped.

Why We Are Sharing This

We think this pattern could help many teams, not just research labs. It could apply to code review practices, incident response playbooks, support workflows, design system rules, release processes, internal engineering conventions, or any team knowledge that should become reusable AI agent behavior. It also feels aligned with GitBook's AI direction: skill.md, MCP, Git Sync, and documentation that serves both humans and agents.

We would love to see GitBook promote this pattern as a tutorial, starter template, case study, or eventually first-class support for SKILL.md libraries.

The basic version already works today, and that is why we are excited. We built Vios Research Skills because we needed a better way to share research workflows with AI agents. Along the way, we found something broader: GitBook can work beautifully as the visual management layer for shared agent skills.

We are also grateful that GitBook supports our lab through the Community plan. Sharing this pattern is one small way we hope to give back to the GitBook community. 🤗

[addisonschultz]

This is awesome!