write-docs
创建或更新算盘文档网站的文档页面。用于添加新文档、更新现有页面或确保文档与代码变更同步。确保页面遵循星光模式并正确构建。
📖 中文导读:创建或更新算盘文档网站的文档页面。用于添加新文档、更新现有页面或确保文档与代码变更同步。确保页面遵循星光模式并正确构建。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: write-docs description: Create or update documentation pages for the Abacus docs site. Use when adding new documentation, updating existing pages, or ensuring docs stay in sync with code changes. Ensures pages follow Starlight patterns and build correctly. allowed-tools: Read, Grep, Glob, Edit, Write, Bash
Write Docs Skill
Create and maintain documentation for the Abacus docs site (Astro Starlight).
Before Starting
- Read existing pages in
docs/src/content/docs/to understand patterns - Check
docs/astro.config.mjsfor sidebar structure - Understand the section you're adding to (getting-started, providers, cli, deployment, development)
Workflow
Adding a New Page
- Create
.mdxfile in the appropriate directory - Add required frontmatter (see below)
- Use existing pages as reference for component usage
- Run
cd docs && pnpm buildto verify
Updating an Existing Page
- Read the current page first
- Make changes, preserving existing patterns
- Run
cd docs && pnpm buildto 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)