Gen Docs

Overview

This repository maintains bilingual user documentation under docs/. docs/en/ and docs/zh/ are mirrored pairs for most pages; update both in the same change. Changelog is the exception — English is the source, and Chinese is translated from English.

Use this skill to update the corresponding documentation whenever the codebase has changes that affect product behavior or user experience.

For a full pre-release audit of all pages (detecting hallucinations and coverage gaps), use the audit-docs skill instead.

Prerequisites

This skill depends on the following being in place. If any are missing, stop and report to the user before continuing:

• docs/ directory with docs/zh/, docs/en/, and docs/.vitepress/config.ts set up (VitePress site).
• docs/AGENTS.md style guide — defines source-of-truth rules, terminology table, typography, and writing style.
• docs/scripts/sync-changelog.mjs — auto-syncs root CHANGELOG.md to docs/en/release-notes/changelog.md.
• translate-docs skill in .agents/skills/ — handles bilingual synchronization.

Workflow

1. Inspect changes

   • git log main..HEAD --oneline — commits on the current branch
   • git diff main..HEAD --stat — file-level scope
   • ls .changeset/*.md (excluding README.md) — pending changeset entries
   • Read CHANGELOG.md and any subpackage packages/*/CHANGELOG.md for already-recorded entries.

2. Understand user-facing impact

   For each change, read the actual implementation when needed; do not infer behavior from commit messages or PR titles alone. Skip:

   • Internal refactors with no externally visible behavior change
   • Tests, CI, type-only changes
   • Tooling / build-system changes that do not change how users invoke the CLI

   If after the scan you conclude there is no user-facing impact, say so and stop.

3. Sync English changelog

   Run:

   node docs/scripts/sync-changelog.mjs
   

   This updates docs/en/release-notes/changelog.md from the root CHANGELOG.md. Never edit the docs changelog by hand.

4. Update user docs

   Following the rules in docs/AGENTS.md, edit the affected pages in whichever locale you are working in, then sync the mirror. Match terminology with the term table in docs/AGENTS.md and the existing wording in surrounding pages.

   Cover all relevant sections:

   • Guides (getting-started, use cases, interaction, sessions, IDE integration)
   • Customization (skills, agents, MCP, hooks, plugins, etc.)
   • Configuration (config files, env vars, providers, data locations)
   • Reference (CLI subcommands, slash commands, keyboard shortcuts)
   • Release notes (docs/zh/release-notes/breaking-changes.md if a breaking change is involved)

5. Sync bilingual content

   Invoke the translate-docs skill. It will:

   • Sync updated non-changelog pages between docs/en/ and docs/zh/
   • Translate the English changelog → Chinese under docs/zh/release-notes/changelog.md

Rules and conventions

• Locale sync: Non-changelog pages stay mirrored between docs/en/ and docs/zh/. Changelog flows English → Chinese.
• Terminology: Use the term table in docs/AGENTS.md exactly. Do not invent new translations or use synonyms.
• Scope discipline: Only update sections affected by the recent changes. Do not opportunistically rewrite unrelated docs.
• Public examples: Never write real internal endpoints, key names, account names, or service names into docs. Use neutral placeholders such as https://api.example.com/v1, https://registry.example.com/v1/models/api.json, example.test, and YOUR_API_KEY.
• Breaking changes: If any change is breaking, also update docs/en/release-notes/breaking-changes.md (under ## Unreleased) with **Affected** + **Migration** subsections, and mirror it in docs/zh/release-notes/breaking-changes.md.
• Do not edit auto-synced files: docs/en/release-notes/changelog.md is regenerated by the sync script; any manual edit will be overwritten.

Common mistakes

• Describing what code changed instead of what the user can now do (or can no longer do).
• Adding a new section heading per feature instead of weaving the change into existing prose.
• Updating only one locale and leaving its mirror stale.
• Editing only the mirror to fix wording that should be corrected in the locale you changed first.
• Inventing new terminology that drifts from the docs/AGENTS.md term table.
• Using real internal values in examples instead of neutral example placeholders.