Write Docs Skill

Create and maintain documentation for the Abacus docs site (Astro Starlight).

Before Starting

1. •Read existing pages in docs/src/content/docs/ to understand patterns
2. •Check docs/astro.config.mjs for sidebar structure
3. •Understand the section you're adding to (getting-started, providers, cli, deployment, development)

Workflow

Adding a New Page

1. •Create .mdx file in the appropriate directory
2. •Add required frontmatter (see below)
3. •Use existing pages as reference for component usage
4. •Run cd docs && pnpm build to verify

Updating an Existing Page

1. •Read the current page first
2. •Make changes, preserving existing patterns
3. •Run cd docs && pnpm build to verify

Frontmatter

Every page requires:

---
title: Page Title
description: One-line description for SEO
sidebar:
  order: 1  # Position within section
---

Key Rules

Links Must Include Base Path

Internal links need /abacus/ prefix (GitHub Pages requirement):

[Quick Start](/abacus/getting-started/quick-start/)  ✓
[Quick Start](/getting-started/quick-start/)          ✗

Import Components Before Use

import { Steps, Aside } from '@astrojs/starlight/components';

<Steps>
1. First step
2. Second step
</Steps>

<Aside type="tip">Helpful note</Aside>

Code Blocks Need Language Tags

```bash
pnpm cli sync

## Build Verification

**Always verify before committing:**

```bash
cd docs && pnpm build

Common errors:

• •Missing imports
• •Invalid frontmatter
• •Broken links (wrong path or missing /abacus/)

Style Guidelines

• •Imperative mood ("Run this" not "You should run")
• •Code examples over abstract descriptions
• •Keep paragraphs short - users skim
• •Tables for reference data (env vars, options)