---

The Problem

"I asked Claude Code to audit my docs. It hallucinated 3 non-existent sections, missed broken links, and produced a report I couldn't act on."

AI agents are powerful — but they have no shared standard for what good documentation looks like, how to audit it, or how to publish it. Every project reinvents the wheel.

---

The Solution

29 reusable skills (Workflow + Guardrails + Acceptance Criteria) that teach your AI agent to handle any documentation task correctly — from audit to publish.

Before	After
Agent hallucinates doc structure	Agent works from your real docs — files, sitemap, or doc graph
One-off prompts per project	Reusable skill catalog, works everywhere
No acceptance criteria	Every skill ships with pass/fail checklist
Hours of prompting per audit	/docs-analyze → unified report in minutes

Skills describe what the agent needs and how to think — not which tool to call. They run on a bare agent (grep/find over a docs folder) and get faster and cheaper when an optional graph/semantic search tool is connected. See Optional acceleration.

---

What Is a Skill?

A skill is a reusable regulation (like a QA checklist) — not a one-time task.

Concept	Analogy	Lives in
Skill	QA Checklist — describes Workflow, Guardrails, Acceptance Criteria	this repo
Subagent	Jira ticket — specific model, tools, event trigger	docs-subagents

Skills are agent-agnostic: the same SKILL.md works in Claude Code, Cursor, Copilot, and Codex.

---

Quickstart

Install the whole catalog (or one skill) into your AI agent — Claude Code, Cursor, Codex, Copilot:

# everything
npx skills add Docsbook-io/docs-skills --skill '*'

# or just one
npx skills add Docsbook-io/docs-skills --skill docs-analyze

Then just ask your agent in plain language:

"Audit my docs and give me one prioritized report" "Turn this GitHub repo into a live docs site" "Which pages are users searching for but not finding?" "Translate my docs into 15 languages"

No flags, no config — the skill fires from your request. Browse the full catalog below.

---

Skills Catalog

39 skills across 7 categories. Browse live: docsbook.io/skills.

Analysis — audit existing documentation

Run when your docs exist but you're not sure they're correct, readable, or complete.

npx skills add Docsbook-io/docs-skills --skill docs-analyze
// Prompts:
// Audit my docs and give me one prioritized report
// Run a full health check before our release
// What's wrong with my documentation?
// Do a complete review of the docs/ folder

npx skills add Docsbook-io/docs-skills --skill docs-content-types
// Prompts:
// Users say they can't find answers — are my page types mixed up?
// Check my docs against Diátaxis
// Which pages mix tutorials with reference material?
// Are my how-to guides actually how-to guides?

npx skills add Docsbook-io/docs-skills --skill docs-structure-templates
// Prompts:
// Check these new pages for missing frontmatter before I merge
// Are my headings nested correctly?
// Which code blocks are missing a language tag?
// Validate the structure of every page in docs/

npx skills add Docsbook-io/docs-skills --skill docs-style-tone
// Prompts:
// My docs feel corporate — flag the marketing fluff
// Find passive voice and filler words in my docs
// Tighten the prose without rewriting it for me
// Where am I using 'simply' and 'just' and 'powerful'?

npx skills add Docsbook-io/docs-skills --skill docs-audience
// Prompts:
// Junior devs keep bouncing off this page — why?
// Which pages talk over the reader's head?
// Find undefined jargon and missing prerequisites
// Is this page trying to serve beginners and experts at once?

npx skills add Docsbook-io/docs-skills --skill docs-navigation-linking
// Prompts:
// Find the broken internal links in my docs
// Which pages are orphans with nothing linking to them?
// Hunt down the dead ends and 'click here' anchors
// Check my doc graph after this restructure

npx skills add Docsbook-io/docs-skills --skill docs-seo
// Prompts:
// Make my docs rank in Google and AI Overviews
// Find missing or duplicate titles and descriptions
// Run an SEO audit on my documentation
// Why isn't this docs section getting organic traffic?

npx skills add Docsbook-io/docs-skills --skill docs-accessibility
// Prompts:
// Check my docs for WCAG 2.1 AA violations
// Find images missing alt text
// Are my docs usable with a screen reader?
// Run an a11y audit before we launch publicly

npx skills add Docsbook-io/docs-skills --skill docs-i18n
// Prompts:
// Are my translations lagging behind the English source?
// Check content parity across all my languages
// Find stale translations and broken hreflang tags
// Which pages aren't translated yet?

npx skills add Docsbook-io/docs-skills --skill docs-media
// Prompts:
// Find the bloated images slowing my docs down
// Which screenshots are out of date after the UI redesign?
// Flag images with no alt text or generic filenames
// Audit every image and video in my docs

npx skills add Docsbook-io/docs-skills --skill docs-maintenance
// Prompts:
// Find docs that reference features or prices that no longer exist
// Run a quarterly maintenance audit on the whole tree
// Which pages still have TODO/FIXME left in them?
// Find deprecated pages with no migration path

Creation — generate new documentation

Use when you need to produce docs from scratch or migrate from another platform.

npx skills add Docsbook-io/docs-skills --skill docs-create
// Prompts:
// Turn this GitHub repo into a live docs site
// Create documentation from my product website
// Build me a docs site from scratch and publish it
// I have a Mintlify site — make it a Docsbook site

npx skills add Docsbook-io/docs-skills --skill docs-create-interactive
// Prompts:
// Create my docs but let me approve each step
// Build a docs site — pause before publishing so I can review
// I want to pick the structure and branding myself
// Walk me through creating docs with checkpoints

npx skills add Docsbook-io/docs-skills --skill docs-detect-source
// Prompts:
// Is this a website, a repo, or an existing docs platform?
// Figure out what kind of docs source I have
// What should I run to build docs from this URL?
// Detect whether this is Mintlify or GitBook

npx skills add Docsbook-io/docs-skills --skill docs-from-site
// Prompts:
// Make docs from my product website
// Crawl this site and turn it into Markdown docs
// Import my marketing site as documentation
// Generate docs from this URL

npx skills add Docsbook-io/docs-skills --skill docs-from-code
// Prompts:
// Build docs from my GitHub repo
// Generate API docs from this codebase
// Import the repo's README and exported API as docs
// Make documentation from this code — the marketing site doesn't exist yet

npx skills add Docsbook-io/docs-skills --skill docs-from-docs
// Prompts:
// Migrate my docs off Mintlify
// Import my GitBook into a clean Markdown folder
// Move my Docusaurus site to Docsbook
// Convert my Nextra docs to plain Markdown, structure intact

npx skills add Docsbook-io/docs-skills --skill docs-branding
// Prompts:
// Set up the branding for my docs workspace
// Pull brand colors from my website and apply them
// Pick an accent color and font that match my product
// Brand my docs from my logo and README

npx skills add Docsbook-io/docs-skills --skill docs-first-run-enrichment
// Prompts:
// Make my freshly generated docs rich instead of a bare skeleton
// Auto-brand and flesh out this new docs site before I publish
// Turn this skeleton into a real multi-section site
// Enrich the docs with a proper getting-started and landing page

npx skills add Docsbook-io/docs-skills --skill docs-imagine
// Prompts:
// Imagine docs for my product — I only have a name
// Invent documentation for X, no URL or repo
// Make up a marketing-grade docs site from scratch
// придумай документацию for better selling

Publishing — ship docs to Docsbook

Use after generating docs locally to push them live and configure the workspace.

npx skills add Docsbook-io/docs-skills --skill docs-publish
// Prompts:
// Push my local docs folder to GitHub
// Publish these docs to a new repo
// Commit and push my docs and give me the Docsbook URL
// Ship the docs I just generated

npx skills add Docsbook-io/docs-skills --skill docs-setup-workspace
// Prompts:
// Configure my Docsbook workspace from one command
// Wire up branding, SEO, languages and AI chat
// Set up my workspace without clicking through the UI
// Apply my branding and turn on the right features

npx skills add Docsbook-io/docs-skills --skill docs-generate-agents-md
// Prompts:
// Generate an AGENTS.md so every AI agent knows about my docs
// Give Cursor and Claude Code context about my documentation
// Write the AGENTS.md file at repo root
// Make sure my agents start each session knowing the docs URL

Observability — turn analytics into actions

Use when you want to act on real user signal rather than guesswork.

npx skills add Docsbook-io/docs-skills --skill docs-gap-finder
// Prompts:
// Which docs page should I write next?
// What are users searching for but not finding?
// Find the top missing pages from real user signal
// Open GitHub issues for the biggest content gaps

npx skills add Docsbook-io/docs-skills --skill docs-question-clusterer
// Prompts:
// Group every question users ask the AI chat into topics
// Which questions are content gaps vs the chat just missing the page?
// Cluster my AI chat questions and tell me what's missing
// Did my new docs actually reduce AI chat failures?

npx skills add Docsbook-io/docs-skills --skill docs-engagement-analyzer
// Prompts:
// Which long-read pages are loved vs which are confusing?
// Split my high-dwell pages into deep interest vs stuck users
// Find pages where people spend ages but leave unhappy
// Did my rewrite actually improve engagement?

npx skills add Docsbook-io/docs-skills --skill docs-funnel-mapper
// Prompts:
// Map the most common journeys through my docs
// Where are users dropping before they reach a conversion page?
// Find the high-volume paths with low completion rates
// Which links does the doc graph imply that users never actually take?

npx skills add Docsbook-io/docs-skills --skill docs-link-click-analyzer
// Prompts:
// Which CTA buttons are underperforming on my docs?
// Measure click-through on every internal link
// Is my Upgrade button buried where nobody clicks it?
// Find pages with pageviews but zero outgoing clicks

npx skills add Docsbook-io/docs-skills --skill docs-utm-analyzer
// Prompts:
// Which campaigns send traffic that bounces on the docs?
// Match my UTM traffic against the pages people land on
// Where does the ad promise not match the doc reality?
// We got a referrer surge but no signups — find the mismatch

npx skills add Docsbook-io/docs-skills --skill docs-visitor-cohort
// Prompts:
// Who are my most active visitors and what are they doing?
// Cluster my top visitors by behavior pattern
// Find the buyer-blockers — people who hit pricing then leave unhappy
// What's the current profile of my power users before a pricing change?

Growth — understand who buys, how they enter, and who you compete with

Use when you want your docs to grow the product, not just document it — and to keep your private product knowledge base honest about your buyers and your market.

npx skills add Docsbook-io/docs-skills --skill docs-audience-enricher
// Prompts:
// Figure out who actually buys my product and how they enter
// Enrich my product knowledge base with buyer segments and competitors
// What's changed in my competitive landscape since I last wrote?
// Fill the blind spots in my product source-of-truth before a growth pass

Planning — design the structure before writing

Use when starting from scratch or when the existing docs need a strategic rethink.

npx skills add Docsbook-io/docs-skills --skill docs-strategy-plan
// Prompts:
// I have no docs and don't know where to start
// What should I document, for whom, and in what order?
// Help me build a documentation roadmap
// Give me a prioritized content backlog before I start writing

Automation — wire docs maintenance into your CI/CD pipeline

Install once, run forever.

npx skills add Docsbook-io/docs-skills --skill docs-sync
// Prompts:
// Stop my docs from drifting out of sync with the code
// Install a pre-push hook that fixes drifted docs automatically
// Detect and fix code↔docs drift before this push
// Which docs sections did my last code change make stale?

npx skills add Docsbook-io/docs-skills --skill docs-pr-check
// Prompts:
// Add a CI gate that flags code changes shipped without docs
// Generate a GitHub Action to check docs on every PR
// Catch missing frontmatter and broken links in pull requests
// Make sure no PR merges with stale documentation

npx skills add Docsbook-io/docs-skills --skill docs-enable-translation
// Prompts:
// Translate my docs into 15 languages
// Turn on AI auto-translation for my workspace
// Enable Spanish, French and German and notify Slack when each batch finishes
// We're launching in a new market — switch on translations

npx skills add Docsbook-io/docs-skills --skill docs-tune-ai-chat
// Prompts:
// Users keep thumbs-downing the AI chat — fix the prompt
// Improve my AI chat using last month's negative feedback
// The chatbot says 'I don't know' too often — tune it
// Cluster chat failures and propose a prompt update I can approve

npx skills add Docsbook-io/docs-skills --skill docs-release-announce
// Prompts:
// Announce every release to Slack automatically
// Send an email when a new release is published
// Wire up release notifications so I stop posting them by hand
// Set up a GitHub Action that fires on release: published

npx skills add Docsbook-io/docs-skills --skill docs-stale-watcher
// Prompts:
// Turn stale-content alerts into GitHub Issues automatically
// Surface outdated docs in our normal issue triage
// Watch for stale pages and file an issue for each one
// Stop relying on manual quarterly audits for outdated docs

npx skills add Docsbook-io/docs-skills --skill docs-translate-webhook
// Prompts:
// Route translation to my own DeepL pipeline instead of the built-in one
// Bypass the built-in translator and use my TMS over webhooks
// Scaffold a webhook handler for custom translation
// Switch my workspace to external translation mode

How It Works

Each skill states a need ("get the list of pages in scope and read their content") and how to reason about it — never a hardcoded tool call. The agent satisfies the need with whatever it has connected:

AI Tool (Claude Code / Cursor / Codex / Copilot)
        │
        ▼
  docs-skill runs  ──▶  states the need + how to think
        │
        ├─ nothing connected ──▶  grep / find over the docs folder
        ├─ markdown-lsp       ──▶  semantic / graph search, self-hosted
        └─ Docsbook MCP       ──▶  same capability in the cloud + workspace settings
        │
        ▼
  Audit report / generated files / configured workspace

The skill never names the tool. The agent sees what's available and picks the cheapest path that satisfies the need.

Optional acceleration

Most analysis skills need to list the pages in scope and read their content. That works on a bare agent with grep/find. It gets faster and cheaper when graph/semantic search over the docs is available — two interchangeable transports for the same capability:

Path	What you get	Cost
Nothing (default)	grep/find over the docs folder	free, works everywhere
markdown-lsp (self-hosted)	semantic + graph search, runs locally — repo	free, you host it
Docsbook MCP (cloud)	the same search in the cloud, plus workspace settings (branding, languages, analytics)	optional account

# Optional cloud transport
mcp add --transport http https://docsbook.io/api/mcp/server

The cloud transport runs markdown-lsp for you — so self-hosted and cloud are the same capability, your choice of where it runs. The cloud path is still maturing; the self-hosted path and the bare grep/find fallback always work. A handful of skills are intentionally about a hosted platform (/docs-setup-workspace, /docs-branding, the webhook-based automation skills) and genuinely need it — they say so and fall back to printed instructions when it's absent.

---

---

Features

✅ 39 reusable skills — analysis, creation, publishing, observability, growth, planning, automation
✅ One command, plain-language trigger — npx skills add then just ask your agent
✅ Acceptance Criteria — every skill ships with a pass/fail checklist
✅ Agent-agnostic — Claude Code, Cursor, Copilot, Codex
✅ Tool-agnostic — describes the need, not the tool; runs on bare grep/find, accelerates with markdown-lsp or Docsbook MCP
✅ Open source — fork, extend, contribute back

---

CLI Reference

Powered by the skills CLI:

npx skills add Docsbook-io/docs-skills --skill '*'        # install the whole catalog
npx skills add Docsbook-io/docs-skills --skill docs-seo   # install one skill
npx skills add Docsbook-io/docs-skills -a claude-code -a cursor --skill '*'   # target specific agents
npx skills list                                           # list installed skills
npx skills find <keyword>                                 # search for a skill
npx skills update                                          # update installed skills

---

Contributing

Skills are plain Markdown files in skills/<name>/SKILL.md. To add a skill:

1. Create skills/your-skill/SKILL.md following the schema in schema/
2. Run pnpm build-index to regenerate index.json
3. Open a PR

The catalog is intentionally minimal — one file per skill, no runtime dependencies.

---

License

MIT © 2024 Dan Bondarev / docsbook.io