## Overview

When you scaffold a project with `create-zudo-doc`, two independent options ship curated `zudo-doc-*` [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) into your project's `.claude/skills/` directory:

- **Claude skills (user-facing)** — authoring/maintenance skills: edit the design system, translate docs, and cut releases following zudo-doc's own conventions.
- **Claude skills (writing)** — a single writing-guide skill that teaches AI agents how to write docs and structure navigation correctly.

These are working skills — not generated documentation. Each is a self-contained `SKILL.md` maintained as a scaffold-ready variant inside the `create-zudo-doc` package itself (rewritten for a generated project's layout, not copied verbatim from the zudo-doc repository), and becomes available as a slash command in Claude Code sessions opened inside your project.

Both features are **off by default** and can be enabled independently — pick either, both, or neither when scaffolding.

[Dynamic content unavailable in text export]

This is distinct from [Claude Code Resources](https://zudo-doc.takazudomodular.com/docs/guides/claude-resources) (and its Codex counterpart, [Codex Resources](https://zudo-doc.takazudomodular.com/docs/guides/codex-resources)), which auto-generates documentation **pages** from your resource directories, and from the [Documentation Skill Symlinker](https://zudo-doc.takazudomodular.com/docs/guides/doc-skill-symlinker), which turns your docs into a lookup skill. The Claude skills features instead **ship ready-made skills** into your project.



## Claude Skills (User-Facing)

Enabling **Claude skills (user-facing)** copies three skills into your scaffolded project's `.claude/skills/`:

| Skill | Purpose |
|-------|---------|
| `zudo-doc-design-system` | Project-specific CSS and component rules — design tokens, the three-tier color architecture, and the component-first strategy. Consult it before editing CSS, zudo-wind classes, color tokens, or component markup. |
| `zudo-doc-translate` | Translate documentation between the locales configured in `zfb.config.ts`, applying zudo-doc's Japanese conventions only to `ja`. |
| `zudo-doc-version-bump` | Bump the package version, generate changelog docs, commit, tag, and create a GitHub release. |

Select **Claude skills (user-facing)** in the interactive `create-zudo-doc` prompts, or pass the CLI flag:

```bash
pnpm create zudo-doc my-docs --claude-skills
```

### What Else It Wires Up

Because `zudo-doc-version-bump` runs `<package-manager> b4push` as part of its release flow, enabling this feature also adds a minimal `b4push` script to your generated `package.json` so the skill does not fail with a missing-script error on a fresh project:

```jsonc
{
  "scripts": {
    "b4push": "pnpm check && pnpm build"
  }
}
```

This is a deliberately small stub — type-check then build. You are free to expand it into a richer pre-push pipeline later.

## Claude Skills (Writing)

Enabling **Claude skills (writing)** copies one skill into your scaffolded project's `.claude/skills/`:

| Skill | Purpose |
|-------|---------|
| `zudo-doc-writing` | Doc-writing and navigation-structure guide — the plan-the-nav-tree-first workflow, the 3-level navigation hierarchy, file-structure-is-navigation, category index pages, `sidebar_position` discipline, frontmatter schema, the no-h1 rule, relative `.mdx` links, and admonition syntax. |

This skill exists because AI agents asked to "fill in the docs" without guidance almost always produce a chaotic navigation structure — pages dumped wherever seemed closest, no category landing pages, alphabetical sidebar ordering. The skill condenses the [Writing Docs](https://zudo-doc.takazudomodular.com/docs/getting-started/writing-docs) and [How to Structure Navigations](https://zudo-doc.takazudomodular.com/docs/getting-started/structuring-navigations) guides into rules an agent consults before creating or editing any page, which reliably keeps generated doc sites in good shape.

Select **Claude skills (writing)** in the interactive prompts, or pass the CLI flag:

```bash
pnpm create zudo-doc my-docs --claude-skills-writing
```

[Dynamic content unavailable in text export]

If you plan to let an AI agent write most of your documentation, enable this feature — then tell the agent to invoke `/zudo-doc-writing` before it creates pages. The nav-planning step is the part agents skip most often, and the one that matters most.



## Using the Skills

Once scaffolded, open your project in Claude Code and invoke a skill as a slash command. For example, before touching styles:

```
/zudo-doc-design-system colors
```

Or before writing documentation:

```
/zudo-doc-writing
```

Claude reads the rules and applies them to your change. The other skills work the same way — invoke them by name when you need them.

[Dynamic content unavailable in text export]

The shipped skills live in your project's `.claude/skills/` and are yours to edit. Treat them as a starting point — adjust the conventions to fit how your team works.