Docs Changelog Writing Guide

Scope Boundary (Important)

This skill is only for changelog pages in:

• docs/changelog/*.mdx

This skill is not for GitHub Releases.
If the user asks for release PR body / GitHub Release notes, load ../version-release/SKILL.md.

Mandatory Companion Skills

For every docs changelog task, you MUST load:

• ../../../DESIGN.md (Voice & Content)
• ../i18n/SKILL.md (when EN/ZH pair is involved)

File and Naming Convention

Use date-based file names:

• English: docs/changelog/YYYY-MM-DD-topic.mdx
• Chinese: docs/changelog/YYYY-MM-DD-topic.zh-CN.mdx

EN and ZH files must exist as a pair and describe the same release facts.

Frontmatter Requirements

Each file should include:

---
title: <Title>
description: <1 sentence summary>
tags:
  - <Tag 1>
  - <Tag 2>
---

Rules:

1. title should match the H1 title in meaning.
2. description should be concise and user-facing.
3. tags should be feature-oriented, not internal-team labels.

Content Structure (Recommended)

Use this shape unless the user requests otherwise:

1. # <Title>
2. Opening paragraph (2-4 sentences): user-visible impact
3. 1-3 capability sections (optional ## headings)
4. ## Improvements and fixes / ## 体验优化与修复 with concise bullets

Keep heading count low and avoid heading-per-bullet structure.

Writing Rules

1. Keep all claims factual and tied to actual shipped changes.
2. Explain user value first, implementation second.
3. Prefer natural narrative paragraphs over pure bullet dumps.
4. Avoid marketing exaggeration and vague adjectives.
5. Keep internal terms consistent across EN/ZH files.
6. Keep EN/ZH section order aligned and scope-aligned.

EN/ZH Synchronization Rules

When generating bilingual changelogs: