The best way to build a skill.md: start with AI, finish with humans

AI agents are only as useful as the context you give them — which is why skill.md files are quickly becoming a popular tool across the software industry.

A skill.md file gives tools like Cursor, Claude Code and OpenAI Codex structured instructions for how to work with your product, codebase or documentation. That’s why building a good one matters.

The question is, how you should create a skill.md? Can you let AI generate it automatically from your docs? Or should your team build and curate it manually?

Good news: there’s a middle ground, we have the tools you need to set it up, and it works great.

Auto-generated skill.md: pros and cons

Some tools now auto-generate a skill.md file from your existing documentation or codebase. I theory, this makes a lot of sense, because your docs already explain how your product works, so an AI system can scan them, extract the important parts and turn that into a skill file.

The biggest benefit is speed. You don’t start from a blank page, and the skill can update when your docs change. It’s a low barrier for entry if you’re just getting started with AI skills — but there are limits.

An automated skill is only as good as the content it learns from. If your docs are incomplete, outdated or missing important context, your skill.md will inherit those gaps. And more importantly, your docs may explain what your product does, but don’t always explain how agents should use it.

A useful skill file typically includes information that doesn’t always live in public docs: preferred workflows, naming conventions, tone rules, edge cases, product judgment and “don’t do this” guidance. If your docs aren’t written with agent workflows in mind — and many understandably aren’t — the auto-generated skill files won’t contain the information agents actually need to use your product effectively. And when those agents try to use your product, they’ll hit knowledge gaps that cause failures.

There’s also the question of control. In most cases, auto-generated skill files can’t be edited or fine-tuned, so your team can’t improve the skill.md structure over time, or fix those gaps mentioned above. So while you get convenience, you lose the chance to shape the instructions around real agent behavior.

Manually-generated skill.md: pros and cons

Another option is to write your skill.md manually.

This workflow gives you more control over the skill.md format, the skill.md YAML frontmatter, the instructions and the examples. You can decide exactly what the agent needs to know, how detailed the guidance should be, and where the file should live.

A human-curated skill is usually better because it includes a technical writer, PM or developer’s judgment. They can decide what should be included, and can explain why a workflow matters, rather than just describing the workflow itself.

The downside is time. Starting from scratch means you need to understand the right skill.md structure, write clear instructions, test the file in different tools and keep it updated as your product changes.

For most teams, that’s too much friction for a first draft, let alone a finished file you can share in your Git repository.

The best skill.md workflow: specialized AI draft + human review

You’ve probably worked out already that the strongest workflow sits between those two approaches.

Start with a dedicated AI tool, built specifically for skill creation, to generate a first draft, then have a human refine it.

AI is good at creating structure. It can produce the right frontmatter, organize sections clearly and turn rough product input into a usable skill.md template based on documentation input. But humans are better at adding the nuance that makes the skill stable, specific and useful.

That’s the workflow we recommend: generate the foundation, then have your product experts improve it.

GitBook’s skill file generator is built for exactly this. It gives you a structured first draft, but the final quality still comes from human review.

Create a skill.md for Cursor, Claude Code and Codex

GitBook’s skill.md generator lets you paste your product docs URL and generate a skill.md for Cursor, a skill.md for Claude Code or a skill.md for OpenAI Codex.

It’s a strong starting point because it’s designed around the right format. Instead of asking a general-purpose AI tool to guess the structure, the generator creates a first draft with the expected frontmatter, sections and formatting already in place.

From there, your team can review the output, add missing context and adapt the instructions to your product’s real workflows.

You can use the generated file as a skill.md file download, a starting skill.md template, or the foundation for a more detailed internal skill.

skill.md file example from our generator

Below is a raw skill.md example created directly from GitBook’s generator based only on our own documentation.

---
name: gitbook-docs
description: A skill explaining how to use the GitBook editor and API to create and edit content in the GitBook platform. Use this when updating documentation on a GitBook docs site, through either the API or via a synced GitHub or GitLab repository
metadata:
  author: GitBook
  version: "1.0"
  tags: [docs, knowledge-base, api, documentation, docs-tool, editor]
---
 
## Interaction Model
 
Use the GitBook MCP server for direct interaction with published docs. For editing and publishing, use the GitBook CLI.
 
## Core Workflows
 
### 1. Accessing Published Documentation
 
To access published documentation, use the MCP server:
 
```plaintext
use_mcp_tool("gitbook-server", "read-doc", { url: "https://your-site.gitbook.io/~gitbook" })
```
 
### 2. Creating and Editing Content
 
Use the GitBook CLI to create and edit content:
 
1. **Install the CLI:**
 
   ```bash
   npm install @gitbook/cli -g
   ```
 
2. **Authenticate:**
 
   ```bash
   gitbook auth --token=YOUR_API_TOKEN
   ```
 
3. **Create a New Document:**
 
   ```bash
   gitbook new "Document Title"
   ```
 
4. **Edit a Document:**
 
   Use your preferred text editor to modify the files in your local GitBook repository.
 
5. **Publish Changes:**
 
   ```bash
   gitbook publish
   ```
 
### 3. Syncing with GitHub or GitLab
 
1. **Link Repository:**
 
   Use the GitBook web interface to link your GitHub or GitLab repository.
 
2. **Push Changes:**
 
   Commit and push changes to your repository. GitBook will automatically sync.
 
⚠️ **API gap**: No direct API endpoint for syncing repositories. This requires manual setup in the GitBook UI.
 
## Authentication
 
Store your API token in an environment variable `GITBOOK_API_TOKEN` and use it for CLI authentication.
 
## Gotchas
 
- The CLI requires Node v18 or later.
- Ensure your API token has the correct permissions for the operations you intend to perform.
- Publishing changes via the CLI requires a valid `gitbook-manifest.yaml`.
 
## Error Handling
 
- **Authentication Errors**: Ensure your token is correct and has not expired.
- **Publishing Errors**: Check for syntax errors in your `gitbook-manifest.yaml`.
- For the full error reference, read `references/errors.md`.
 
## Reference Loading Instructions
 
- For complete CLI commands, read `references/cli-reference.md`.
- For MCP server configuration, read `references/mcp-servers.md`.
- For error codes and troubleshooting, read `references/errors.md`.

This output shows what the generator does well: it creates clean frontmatter, follows the right structure and gives you a formatted first draft quickly.

But it still needs to be reviewed. There are bound to be pieces missing from the output, and the best skills include product judgment, workflow nuance and examples that only product experts can flag or catch.

One other thing to consider: in many cases, it’s a good idea to create different skills for different specific workflows — each with contained references that dive deep into the best way agents can accomplish a task. Compare the skill generated above to our own official GitBook skills for writing docs, configuring change requests, and more and you’ll see how this is a good starting point that requires further work.

For more practical guidance, read our full guide to skill.md, which explains how skills work, where skill.md goes in your project and how to build a stable skill that agents can use reliably.

Better skills start with better knowledge

Automated skills are fast, and manual skills are precise. But the best workflow uses both: AI to create the first draft, and humans to make it complete.

As AI agents become a bigger part of how people discover, understand and use products, your documentation becomes a foundational part of your knowledge infrastructure. Your docs, API reference and skill files all work together to help agents understand your product accurately.

A good skill.md doesn’t replace high-quality documentation — in fact, the two work hand in hand to give agents clearer instructions for how to use your product effectively and efficiently.

→ Create a draft skill.md file with our skill generator

→ MCP vs skill.md — what’s the difference and why you need both

→ What we learned building a complete docs site using Claude, MCP and skill.md