documentation-writing

Files (3)

• SKILL.md
• astro.config.template.js
• content.config.template.js

SKILL.md (first lines)

# Documentation Writing

## When to Apply

Activate this skill when:

- Creating or editing documentation files in `docs/`
- Writing guides, explanations, or reference docs
- Setting up the documentation toolchain for the first time
- The user asks to "document", "write docs", or "add a guide" for a feature

---

## Toolchain Setup

Run this setup when `astro.config.js` does not yet exist at the project root.

### 1. Install packages

Install the current releases as dev dependencies — let npm resolve the versions instead of hand-writing them into `package.json`:

```bash
npm install --save-dev astro @astrojs/starlight astro-mermaid starlight-llms-txt
```

Respect the project's existing setup:

- If a `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb` is present, use that package manager's equivalent instead of npm.
- Leave `.npmrc` (registries, scopes, auth) untouched and never delete or regenerate the lockfile.
- Commit the resulting `package.json` and lockfile changes together.

If npm reports a peer dependency conflict, install the versions it names rather than forcing the install with `--legacy-peer-deps` — the Starlight and mermaid integrations are tied to the Astro major version.

Then add to the `scripts` block in `package.json`:

```json
"build:docs": "astro build",
"dev:docs": "astro dev --port 4322"
```

### 2. Create `astro.config.js`

Read `.claude/skills/documentation-writing/astro.config.template.js` and copy it to `astro.config.js` at the project root. Then fill in the `TODO` values:

| Placeholder | What to set |
|---|---|
| `YOUR-PROJECT.test/docs` | Actual site base URL |
| `PROJECT NAME` | Human-readable project name for the navbar |
| `short description` | One-sentence description for SEO |
| `ORG/REPO` | GitHub org and repo name |

### 3. Create content collection config

Read `.claude/skills/documentation-writing/content.config.template.js` and copy it to `docs/src/content.config.ts`. No changes needed — it can be used as-is.

### 4. Directory structure

```
docs/
├── api/
│   └── spec.yaml              # OpenAPI spec root file (input for Redocly)
├── public/                    # Static assets served at /docs/
│   └── api/
│       └── bundle.yml         # Generated — do not edit manually
└── src/
    └── content/
        └── docs/
            ├── guides/        # How-to guides (autogenerated sidebar)
            └── explanation/   # Conceptual explanations (autogenerated sidebar)
```

---

## Writing Documentation

### Style

Write concise, comprehensive, professional documentation aimed at technical readers:

- Get to the point and use the correct technical terms. Include every detail needed for a thorough understanding of the topic — and nothing more; cut anything verbose or redundant.
- Prefer high-level overviews over code snippets. Go into specifics only for interesting complexities or edge cases.
- When a topic is genuinely complex, explain it thoroughly: provide examples wherever they help, and anticipate and answer the questions a reader would ask at that point.
- Add an FAQ section only when it earns its place — for relevant questions that are neither obvious nor already covered by the page.

### File format

All documentation pages use `.mdx` (preferred — supports components) or `.md`. Place them under `docs/src/content/docs/`.

```mdx
---
title: Page Title
description: Short description for search engines and social previews.
---

Content here.
```

### Frontmatter fields

| Field | Type | Notes |
|---|---|---|
| `title` | `string` | **Required.** Shown at top of page, in `<title>`, and in sidebar |
| `description` | `string` | Used by search engines and social previews |
| `sidebar.order` | `number` | Sort position in autogenerated groups |
| `sidebar.label` | `string` | Override link text in the sidebar |
| `sidebar.hidden` | `boolean` | `true` removes page from autogenerated sidebars |
| `sidebar.badge` | `string \| { text, variant }` | Badge on the sidebar link. Variants: `note`, `tip`, `danger`, `caution`, `success` |
| `template` | `'doc' \| 'splash'` | `'splash'` gives a wide landing-page layout |
| `draft` | `boolean` | Hidden in production; visible in dev |
| `lastUpdated` | `Date \| boolean` | Override global setting for this page |
| `pagefind` | `boolean` | `false` excludes page from search index |

### Content types

**Guides** (`docs/src/content/docs/guides/`) — Step-by-step instructions for completing a task. Use imperative titles: "Configuring Authentication", "Setting Up SCORM".

**Explanations** (`docs/src/content/docs/explanation/`) — Conceptual background for understanding how and why. Use noun-phrase titles: "Authentication Architecture", "SCORM Data Flow".

### Callouts / Asides

From mindtwo/agent-tooling, MIT.

More from mindtwo/agent-tooling