Markbook
View as Markdown

Agent skills

Markbook is agent-first by default. The markbook npm package ships six procedural skills designed for AI coding agents — Claude Code, Codex, OpenCode, Cursor, Copilot CLI, and anything else that auto-discovers skills from .claude/, .codex/, .opencode/, or .agents/.

These aren't an afterthought. They're how we expect most Markbook setups to happen:

You:    "Set up Markbook in this project."
Agent:  *runs /markbook-init*    → markbook.config.ts + first page
You:    "Generate docs for every component under src/components."
Agent:  *runs /markbook-bulk-generate --from src/components*
You:    "Apply the github preset, accent #0969da."
Agent:  *runs /markbook-style github --accent '#0969da'*
You:    "Embed the Button story on our marketing page."
Agent:  *runs /markbook-bundle-story button-primary*

No markbook.config.ts to hand-edit. No directives to memorise. The agent already knows.

Install#

After installing the markbook package, drop the shipped skills into your project's agent vendor surfaces:

npx markbook skills install

Markbook detects which surfaces exist (.claude/, .codex/, .opencode/, .agents/) and copies skill content into each. Each skill lands at <surface>/skills/markbook-<name>/SKILL.md (flat namespace, cross-vendor portable).

npx markbook skills install --surface .codex   # limit to one surface
npx markbook skills install --update           # refresh after upgrading markbook
npx markbook skills list                       # see installed + drift state

The six skills at a glance#

Skill What it does
markbook-init 🆕 Scaffold a new site (markbook.config.ts, sample page, example story, suggested package scripts). Refuses to clobber.
markbook-add-component-page 📄 Generate one docs page (frontmatter + :::props + :::stories) for a single component file.
markbook-bulk-generate 📦 Scan a directory, dry-run by default, generate pages for every component-like file. --write actually writes.
markbook-style 🎨 Apply a visual preset (minimal / vibrant / corporate / github / nord). Optional --accent / --font overrides.
markbook-layout 🏗️ Scaffold a custom HTML layout (docs / marketing / blog / minimal) with required placeholders pre-wired.
markbook-bundle-story 📤 Walk through markbook bundle for embedding a story externally. Picks embed or package mode and prints the snippet.

For every flag of every skill, see the skills reference →.

Why agent-first?#

Three reasons we made skills a first-class output of the build, not a docs page somewhere:

  1. Docs sites are forgettable infra. Most teams set one up once and never touch it again. That setup-once cost — config file, sample page, story scaffold, theming — is exactly what agents are best at.
  2. Discoverability beats documentation. /markbook-style github is less friction than "edit markbook.config.ts's css: field, write a CSS file with token overrides like --mb-accent…" The agent shouldn't need to read a guide — the procedure is the guide.
  3. Conventions, encoded. Every skill has "prevention tests" that catch common mistakes. The agent doesn't have to guess that :::story{src=./X.stories.tsx} is the right shape vs <Story src=...>. The skill knows.

Markbook still works perfectly as a hand-edit-the-config tool — every skill is a wrapper around the same markbook.config.ts and pages/ you'd write by hand.

Customizing the shipped skills#

When markbook skills install copies a skill, it copies the entire skill directory — SKILL.md plus any presets/, templates/, or other resource files. Edit your local copy freely; markbook skills install --update will flag drift and ask before overwriting. To upstream a change, PR against packages/cli/skills/.

What's next#