From a7ba8d9c6a7c9d2ad24d9ca9b1885505238cf969 Mon Sep 17 00:00:00 2001
From: qiancai <qqzczy@126.com>
Date: Tue, 26 May 2026 18:14:21 +0800
Subject: [PATCH 1/6] Create SKILL.md

---
 .ai/skills/write-update-tidb-docs/SKILL.md | 310 +++++++++++++++++++++
 1 file changed, 310 insertions(+)
 create mode 100644 .ai/skills/write-update-tidb-docs/SKILL.md

diff --git a/.ai/skills/write-update-tidb-docs/SKILL.md b/.ai/skills/write-update-tidb-docs/SKILL.md
new file mode 100644
index 0000000000000..e11f75bd83ba7
--- /dev/null
+++ b/.ai/skills/write-update-tidb-docs/SKILL.md
@@ -0,0 +1,310 @@
+---
+name: write-update-tidb-docs
+description: Write new TiDB documentation or update existing TiDB documentation from code changes, engineering notes, PRs, issues, design docs, rough drafts, existing docs, or short feature descriptions. Use when R&D engineers need user-facing docs in pingcap/docs or pingcap/docs-cn.
+---
+
+# Write or Update TiDB Docs
+
+Use this skill to turn engineering context into user-facing TiDB documentation
+in `pingcap/docs` or `pingcap/docs-cn`. Inputs can be code diffs, PRs, issues,
+design notes, release notes, rough Markdown, existing docs, or a few sentences
+from an R&D engineer.
+
+## Defaults
+
+- Inspect first, confirm when uncertain, then edit.
+- Prefer updating existing docs. Write a new page only when the change introduces
+  a distinct user task, feature, reference area, integration, or troubleshooting
+  workflow that does not fit cleanly in an existing page.
+- Documentation must justify its maintenance cost. Not every code change needs a
+  doc update.
+- If the user asks about local changes without naming files, run `git status -u`.
+  If there are no uncommitted changes and the user clearly wants the latest local
+  change, inspect `git show --name-status` and targeted diffs.
+- For broad changes, group work by documentation area, such as guides, reference
+  docs, release notes, examples, overview pages, and TOC updates. Use subagents
+  or parallel analysis when available, but review the final result holistically.
+- For substantial new docs or vague inputs, switch to co-authoring mode: gather
+  context, agree on structure, draft section by section, and test whether the doc
+  answers likely reader questions.
+
+## Load context progressively
+
+Always read:
+
+- `.ai/shared/repo-conventions.md`
+- `.ai/shared/writing-style.md`
+
+Read only when relevant:
+
+- `.ai/shared/translation-rules.md` and `.ai/shared/translation-terms.md` when
+  the target is `docs-cn`, or the task involves English-to-Chinese translation
+  or Chinese documentation updates.
+- `resources/doc-templates/<template>.md` after choosing the doc type:
+    - `template-new-feature.md`
+    - `template-task.md`
+    - `template-concept.md`
+    - `template-reference.md`
+    - `template-troubleshooting.md`
+- `resources/terms.md` when terminology is uncertain.
+
+Before drafting, inspect nearby docs, related overview/reference pages, TOC
+entries, existing terminology, linked issues or PRs, and relevant code changes.
+Prefer existing structure and wording in the same documentation area.
+
+## Workflow
+
+### 1. Plan with 5W1H
+
+- **Who**: target readers, role, technical level, and prior knowledge.
+- **What**: primary information versus secondary details.
+- **Why**: user goal and product value, not only implementation change.
+- **When**: use cases, feature status, applicable versions, and scenarios.
+- **Where**: target repo, target file, TOC location, and whether to update or
+  write a page.
+- **How**: steps, SQL, commands, APIs, examples, expected output, limitations,
+  compatibility, validation, and follow-up docs.
+
+When facts are missing, derive what you can from code, tests, config names,
+release notes, nearby docs, and issue or PR context. Ask focused questions only
+for facts that cannot be verified locally and would change the documentation.
+
+For substantial docs, ask the user to dump context in any form that is efficient:
+notes, issue links, PR links, design docs, team decisions, rejected alternatives,
+timeline constraints, stakeholder concerns, or rough bullets. Track what is
+known, what is assumed, and what still needs confirmation.
+
+### 2. Triage documentation impact
+
+Prioritize tasks:
+
+- **Critical**: breaking changes, changed defaults, compatibility changes,
+  security-relevant behavior, user-facing errors, or new/changed public APIs.
+- **Important**: new features, configuration options, workflows, SQL behavior,
+  limitations, performance guidance, examples, or required TOC/index updates.
+- **Nice to have**: minor clarifications or comments for non-obvious logic that
+  users or contributors are likely to need.
+
+Skip or consolidate docs that only:
+
+- duplicate generated references, schemas, or existing docs without user context
+- describe obvious internal implementation details
+- document temporary workarounds or behavior expected to disappear soon
+- repeat the same information in multiple places
+
+### 3. Find the target doc and TOC placement
+
+Before deciding whether to update an existing doc or write a new page, inspect
+the relevant TOC file. TOC placement is often the fastest way to find the right
+existing page, neighboring docs, and navigation category.
+
+Use `rg` to search TOC files by feature name, command, component, or likely path:
+
+```bash
+rg -n "<keyword>|<path>" TOC*.md
+```
+
+TOC file purposes in `pingcap/docs`:
+
+| TOC file | Use for |
+| --- | --- |
+| `TOC.md` | Main TiDB Self-Managed docs |
+| `TOC-ai.md` | TiDB for AI, vector search, `pytidb`, MCP, AI integrations |
+| `TOC-develop.md` | Application development guides, quick starts, integrations, developer reference |
+| `TOC-best-practices.md` | Best practice pages for schema, deployment, operations, and performance |
+| `TOC-api.md` | API documentation navigation for TiDB Cloud and TiDB Self-Managed |
+| `TOC-tidb-releases.md` | TiDB Self-Managed release notes |
+| `TOC-tidb-cloud.md` | Main TiDB Cloud docs, especially Dedicated/general Cloud navigation |
+| `TOC-tidb-cloud-starter.md` | TiDB Cloud Starter docs |
+| `TOC-tidb-cloud-essential.md` | TiDB Cloud Essential docs |
+| `TOC-tidb-cloud-premium.md` | TiDB Cloud Premium docs |
+| `TOC-tidb-cloud-releases.md` | TiDB Cloud release notes and maintenance notifications |
+
+For `docs-cn`, check the corresponding TOC files in that repository, except for
+`/tidb-cloud/` and `/ai/` content. These two areas are maintained through English
+source updates only; do not manually update their Chinese translations.
+
+Common doc targets in `pingcap/docs`:
+
+| User request mentions | Start with |
+| --- | --- |
+| system variable | `system-variables.md` and `system-variable-reference.md` |
+| status variable | `status-variables.md` |
+| TiDB config parameter | `tidb-configuration-file.md` |
+| TiKV config parameter | `tikv-configuration-file.md` |
+| TiFlash config parameter | `tiflash/tiflash-configuration.md` |
+| PD config parameter | `pd-configuration-file.md` |
+| TSO or scheduling config | `tso-configuration-file.md` or `scheduling-configuration-file.md` |
+| TiDB/TiKV/PD/TiFlash command-line flag | `command-line-flags-for-*-configuration.md` or `tiflash/tiflash-command-line-flags.md` |
+| TiCDC server or changefeed config | `ticdc/ticdc-server-config.md` or `ticdc/ticdc-changefeed-config.md` |
+| TiProxy config | `tiproxy/tiproxy-configuration.md` |
+| SQL statement | `sql-statements/sql-statement-<statement>.md` and `sql-statements/sql-statement-overview.md` |
+| function or operator | `functions-and-operators/` and `functions-and-operators/functions-and-operators-overview.md` |
+| data type | `data-type-*.md` and `data-type-overview.md` |
+| vector type/function/index | `/ai/reference/` docs, English-only in `release-8.5` |
+| `INFORMATION_SCHEMA` table | `information-schema/` |
+| monitoring metric | `grafana-*.md`, `tiflash/monitor-tiflash.md`, or `ticdc/monitor-ticdc.md` |
+
+Treat these as starting points, not final answers. Confirm placement in the
+appropriate TOC and inspect nearby entries before editing.
+
+### 4. Choose the doc type
+
+- **New feature**: what it is, why it matters, when to use it, how to use it,
+  limitations, compatibility, and related resources.
+- **Task**: prerequisites, numbered steps, expected results, and troubleshooting
+  tips when useful.
+- **Concept**: ideas, architecture, terms, behavior, or tradeoffs users need
+  before tasks.
+- **Reference**: syntax, APIs, configuration, system variables, parameters,
+  functions, outputs, or limits.
+- **Troubleshooting**: symptoms, likely causes, checks, fixes, and prevention.
+- **Developer/API doc**: interfaces, parameters, examples, return values, errors,
+  compatibility, and migration impact.
+- **Architecture/design doc**: components, data flow, interfaces, tradeoffs,
+  scalability, security, and observability only when they affect users.
+- **Existing-doc update**: change only affected sections and preserve the
+  surrounding structure, tone, and technical scope.
+
+For any update, check whether overview pages, reference pages, examples,
+`TOC.md`, aliases, links, or release notes also need changes.
+
+### 5. Write
+
+For new feature docs, or substantial feature expansions, use this shape when
+applicable:
+
+```markdown
+---
+title: <same as H1>
+summary: <115-145 character reader-focused summary>
+---
+
+# <same as title>
+
+<Intro: what the feature does, why it matters, and when users should use it.>
+
+## Usage scenarios
+
+## Prerequisites
+
+## Usage or procedures
+
+### Method 1: <method name> (recommended)
+
+### Method 2: <method name>
+
+## Limitations
+
+## Compatibility
+
+## FAQ
+
+## More resources
+```
+
+Use only sections that help users complete tasks or make decisions. When updating
+an existing doc, fit new content into the existing structure unless the current
+structure blocks user understanding.
+
+For substantial new docs or major rewrites, draft section by section:
+
+1. Propose the 3-5 core sections based on the doc type or template.
+2. Start with the section that has the most unknowns; write summaries or
+   conclusions last.
+3. For each section, ask only the clarifying questions needed for that section,
+   draft the section, then revise surgically instead of reprinting the whole doc.
+4. After several small edits, ask whether anything can be removed without losing
+   important information.
+
+Writing rules that matter most:
+
+- Start with useful information directly. Avoid internal background unless users
+  need it.
+- Start task docs with the most common use case or shortest path to first
+  success.
+- Put conditions before instructions. Tell users where to perform each action.
+- Explain placeholders and include expected output for commands, SQL, or APIs
+  when useful.
+- Keep code examples realistic and runnable when possible. Use language IDs and
+  comments only for non-obvious logic.
+- Define jargon on first use.
+- Preserve commands, SQL, API names, UI strings, config names, JSON fields,
+  outputs, and technical meaning unless they are factually wrong or confirmed.
+
+## TiDB docs gotchas
+
+- Target `master` by default. Use release branches only for version-specific
+  behavior, compatibility changes, broken links in published docs, explicit user
+  requests, or the `/tidb-cloud/` and `/ai/` exceptions below.
+- The `/tidb-cloud/` and `/ai/` folders are currently maintained only in the
+  `pingcap/docs` `release-8.5` branch. For these folders, update English only.
+  Do not manually update Chinese content:
+    - `/tidb-cloud/` Chinese content is in `pingcap/docs`
+      `i18n-zh-release-8.5` and is AI-translated weekly.
+    - `/ai/` Chinese content is in `pingcap/docs-cn` and is also AI-translated
+      weekly.
+- New navigable pages usually require `TOC.md` updates. Renamed or replaced pages
+  might need `aliases`.
+- TiDB Cloud docs use special branch and rendering rules. Before changing shared
+  TiDB/TiDB Cloud content, check repo guidance and any `CustomContent` blocks.
+- Do not silently broaden scope from a local doc fix into cross-file rewrites.
+  Note possible related updates, and only edit them when needed for correctness
+  or navigation.
+- Preserve code samples, commands, SQL, config names, API fields, JSON, EBNF, and
+  UI strings unless the task requires changing them or they are clearly wrong.
+- Front matter `title` must match the H1. English titles use title case; headings
+  below H1 use sentence case.
+- Summaries should be reader-focused and usually 115-145 characters. Add
+  `aliases` only when replacing, renaming, or deleting an existing page.
+- For `docs-cn`, preserve source meaning, structure, links, and terminology. Use
+  repo translation guidance instead of free paraphrasing.
+
+## Validation loop
+
+1. Review against the plan: facts, user goal, doc type, scope, examples, links,
+   TOC impact, version scope, and maintainability.
+2. Run Markdown validation when practical:
+
+   ```bash
+   ./scripts/markdownlint <changed-files>
+   ```
+
+3. Run targeted link validation when adding or changing links, anchors, moved
+   files, renamed files, aliases, or TOC entries.
+4. For procedural docs, mentally or actually test the steps, sample code, SQL,
+   expected output, and placeholders.
+5. For substantial docs, run a reader test: predict 5-10 realistic reader
+   questions, verify the doc answers them without hidden context, and fix gaps,
+   ambiguities, contradictions, or unstated assumptions. Use a subagent for a
+   fresh-read review when available.
+6. If validation fails, fix the issue and repeat until checks pass or clearly
+   report why a check could not be run.
+
+## Output templates
+
+When proposing a plan before editing:
+
+```markdown
+Target: <repo/path>
+Change type: <update existing doc | write new page>
+Doc type: <task | concept | reference | new feature | troubleshooting | other>
+Outline: <short heading list>
+Related updates: <TOC, aliases, links, overview/reference/release notes>
+Validation: <checks to run>
+Reader test: <questions the doc should answer, for substantial docs>
+Open questions: <facts that need confirmation>
+```
+
+When reporting completed edits:
+
+```markdown
+Changed files:
+- <path>: <what changed>
+
+Checks:
+- <command>: <result>
+
+Notes:
+- <key decisions, maintenance triggers, or unresolved engineering questions>
+```

From d1b56c8c0a8516c1051de5b2510d5a664a8e0118 Mon Sep 17 00:00:00 2001
From: qiancai <qqzczy@126.com>
Date: Wed, 27 May 2026 10:50:09 +0800
Subject: [PATCH 2/6] add draft

---
 .ai/AI-README.md                           |   1 +
 .ai/skills/write-update-tidb-docs/SKILL.md | 139 +++++++++++++++------
 AGENTS.md                                  |   1 +
 3 files changed, 101 insertions(+), 40 deletions(-)

diff --git a/.ai/AI-README.md b/.ai/AI-README.md
index 45802a018e4f3..87bd5479a78e3 100644
--- a/.ai/AI-README.md
+++ b/.ai/AI-README.md
@@ -25,6 +25,7 @@ Use `resources/terms.md` when terminology is uncertain or not covered by the qui
 - `.ai/skills/create-or-update-zh-translation-pr/`: create a new docs translation PR or update an existing one by combining repo-local scripts with minimal-edit translation rules and incremental source-diff handling
 - `.ai/skills/writing-doc-summaries/`: write or update the `summary` front matter field in a document following the repo's 115-145 character SEO-friendly sentence rules
 - `.ai/skills/write-review-translate-release-notes/`: write, review, revise, and translate TiDB release note entries for the Compatibility changes, Improvements, and Bug fixes sections in English and Chinese
+- `.ai/skills/write-update-tidb-docs/`: write new TiDB documentation or update existing documentation based on code PRs, issues, design docs, or feature descriptions
 
 The related resources skill includes bundled scripts under `.ai/skills/add-related-resources/scripts/` for:
 
diff --git a/.ai/skills/write-update-tidb-docs/SKILL.md b/.ai/skills/write-update-tidb-docs/SKILL.md
index e11f75bd83ba7..0847c0384c4fc 100644
--- a/.ai/skills/write-update-tidb-docs/SKILL.md
+++ b/.ai/skills/write-update-tidb-docs/SKILL.md
@@ -1,12 +1,13 @@
 ---
 name: write-update-tidb-docs
-description: Write new TiDB documentation or update existing TiDB documentation from code changes, engineering notes, PRs, issues, design docs, rough drafts, existing docs, or short feature descriptions. Use when R&D engineers need user-facing docs in pingcap/docs or pingcap/docs-cn.
+description: Write new TiDB documentation or update existing TiDB documentation from code changes, PRs, issues, design docs, rough drafts, existing docs, or short feature descriptions. Use when R&D engineers need user-facing docs in pingcap/docs based on code PRs in pingcap/tidb or other TiDB ecosystem repositories.
 ---
 
 # Write or Update TiDB Docs
 
 Use this skill to turn engineering context into user-facing TiDB documentation
-in `pingcap/docs` or `pingcap/docs-cn`. Inputs can be code diffs, PRs, issues,
+in `pingcap/docs`. The most common input is a code PR from `pingcap/tidb` or
+other TiDB ecosystem repositories. Other inputs include code diffs, issues,
 design notes, release notes, rough Markdown, existing docs, or a few sentences
 from an R&D engineer.
 
@@ -27,6 +28,11 @@ from an R&D engineer.
 - For substantial new docs or vague inputs, switch to co-authoring mode: gather
   context, agree on structure, draft section by section, and test whether the doc
   answers likely reader questions.
+- English documentation in `pingcap/docs` is the primary output. Do not write
+  Chinese docs directly. If Chinese docs are also needed, finish the English doc
+  first, then use the `create-or-update-zh-translation-pr` skill.
+- If the code change also needs release notes, flag that and offer to use the
+  `write-review-translate-release-notes` skill after the doc work is done.
 
 ## Load context progressively
 
@@ -38,8 +44,7 @@ Always read:
 Read only when relevant:
 
 - `.ai/shared/translation-rules.md` and `.ai/shared/translation-terms.md` when
-  the target is `docs-cn`, or the task involves English-to-Chinese translation
-  or Chinese documentation updates.
+  the task involves English-to-Chinese translation or Chinese documentation.
 - `resources/doc-templates/<template>.md` after choosing the doc type:
     - `template-new-feature.md`
     - `template-task.md`
@@ -54,7 +59,59 @@ Prefer existing structure and wording in the same documentation area.
 
 ## Workflow
 
-### 1. Plan with 5W1H
+### 0. Analyze the code PR
+
+When the input is a code PR URL or reference:
+
+1. Fetch the PR metadata and diff:
+
+   ```bash
+   gh pr view <PR-URL> --json title,body,labels,baseRefName,headRefName,files
+   gh pr diff <PR-URL>
+   ```
+
+2. Read the PR description, linked issues, and any design doc references in the
+   PR body. These often contain the user-facing motivation and scope.
+
+3. Scan the diff for documentation-relevant changes. Look for:
+
+   | Code pattern | Likely doc impact |
+   | --- | --- |
+   | New or changed `SysVar` / `DefValue` in session/variable code | Update `system-variables.md` |
+   | New or changed config struct fields / `toml` tags | Update the corresponding `*-configuration-file.md` |
+   | New or changed command-line flags | Update `command-line-flags-for-*-configuration.md` |
+   | New SQL statement or grammar change (parser `.y` files) | New or updated `sql-statements/sql-statement-*.md` |
+   | New built-in function registration | Update `functions-and-operators/` docs |
+   | New `INFORMATION_SCHEMA` table | New doc under `information-schema/` |
+   | New metrics or changed alert rules | Update `grafana-*.md` or monitoring docs |
+   | New feature flag or experimental feature gate | New feature doc or update existing feature doc |
+   | Changed default behavior or compatibility | Critical: update relevant docs + possibly release notes |
+   | New API endpoint | Update or create API reference |
+
+4. Determine the documentation scope: is this a new page, an update to an
+   existing page, or both? Check whether release notes, overview pages, or TOC
+   also need updates.
+
+5. If the code diff is large, focus on user-facing changes (exported APIs,
+   config, SQL grammar, error messages, system variables) and skip internal
+   refactors that do not affect user behavior.
+
+### 1. Map code branches to docs branches
+
+Use the code PR's target branch to determine the docs branch:
+
+| Code repo target branch | Docs repo target branch | Notes |
+| --- | --- | --- |
+| `master` | `master` | Default for new development |
+| `release-X.Y` | `release-X.Y` (if it exists in docs) | Version-specific behavior or compatibility changes |
+| Any branch, but change is user-facing across versions | `master` + cherry-pick labels | Use `needs-cherry-pick-release-X.Y` labels |
+
+When in doubt, target `master` and let the user decide about cherry-picks.
+
+For TiDB Cloud content (`/tidb-cloud/` path), target the `release-8.5` branch.
+For AI content (`/ai/` path), target the `release-8.5` branch.
+
+### 2. Plan with 5W1H
 
 - **Who**: target readers, role, technical level, and prior knowledge.
 - **What**: primary information versus secondary details.
@@ -74,7 +131,7 @@ notes, issue links, PR links, design docs, team decisions, rejected alternatives
 timeline constraints, stakeholder concerns, or rough bullets. Track what is
 known, what is assumed, and what still needs confirmation.
 
-### 2. Triage documentation impact
+### 3. Triage documentation impact
 
 Prioritize tasks:
 
@@ -92,7 +149,7 @@ Skip or consolidate docs that only:
 - document temporary workarounds or behavior expected to disappear soon
 - repeat the same information in multiple places
 
-### 3. Find the target doc and TOC placement
+### 4. Find the target doc and TOC placement
 
 Before deciding whether to update an existing doc or write a new page, inspect
 the relevant TOC file. TOC placement is often the fastest way to find the right
@@ -120,11 +177,7 @@ TOC file purposes in `pingcap/docs`:
 | `TOC-tidb-cloud-premium.md` | TiDB Cloud Premium docs |
 | `TOC-tidb-cloud-releases.md` | TiDB Cloud release notes and maintenance notifications |
 
-For `docs-cn`, check the corresponding TOC files in that repository, except for
-`/tidb-cloud/` and `/ai/` content. These two areas are maintained through English
-source updates only; do not manually update their Chinese translations.
-
-Common doc targets in `pingcap/docs`:
+Common doc targets (from code change patterns):
 
 | User request mentions | Start with |
 | --- | --- |
@@ -148,7 +201,7 @@ Common doc targets in `pingcap/docs`:
 Treat these as starting points, not final answers. Confirm placement in the
 appropriate TOC and inspect nearby entries before editing.
 
-### 4. Choose the doc type
+### 5. Choose the doc type
 
 - **New feature**: what it is, why it matters, when to use it, how to use it,
   limitations, compatibility, and related resources.
@@ -159,17 +212,29 @@ appropriate TOC and inspect nearby entries before editing.
 - **Reference**: syntax, APIs, configuration, system variables, parameters,
   functions, outputs, or limits.
 - **Troubleshooting**: symptoms, likely causes, checks, fixes, and prevention.
-- **Developer/API doc**: interfaces, parameters, examples, return values, errors,
-  compatibility, and migration impact.
-- **Architecture/design doc**: components, data flow, interfaces, tradeoffs,
-  scalability, security, and observability only when they affect users.
 - **Existing-doc update**: change only affected sections and preserve the
   surrounding structure, tone, and technical scope.
 
 For any update, check whether overview pages, reference pages, examples,
 `TOC.md`, aliases, links, or release notes also need changes.
 
-### 5. Write
+### 6. Write
+
+Follow `.ai/shared/writing-style.md` for all writing conventions. Key points
+for this workflow:
+
+- Start with useful information directly. Avoid internal background unless users
+  need it.
+- Start task docs with the most common use case or shortest path to first
+  success.
+- Put conditions before instructions. Tell users where to perform each action.
+- Explain placeholders and include expected output for commands, SQL, or APIs
+  when useful.
+- Keep code examples realistic and runnable when possible.
+- Define jargon on first use.
+- Preserve commands, SQL, API names, UI strings, config names, JSON fields,
+  outputs, and technical meaning unless they are factually wrong or confirmed
+  changed.
 
 For new feature docs, or substantial feature expansions, use this shape when
 applicable:
@@ -217,21 +282,6 @@ For substantial new docs or major rewrites, draft section by section:
 4. After several small edits, ask whether anything can be removed without losing
    important information.
 
-Writing rules that matter most:
-
-- Start with useful information directly. Avoid internal background unless users
-  need it.
-- Start task docs with the most common use case or shortest path to first
-  success.
-- Put conditions before instructions. Tell users where to perform each action.
-- Explain placeholders and include expected output for commands, SQL, or APIs
-  when useful.
-- Keep code examples realistic and runnable when possible. Use language IDs and
-  comments only for non-obvious logic.
-- Define jargon on first use.
-- Preserve commands, SQL, API names, UI strings, config names, JSON fields,
-  outputs, and technical meaning unless they are factually wrong or confirmed.
-
 ## TiDB docs gotchas
 
 - Target `master` by default. Use release branches only for version-specific
@@ -253,12 +303,17 @@ Writing rules that matter most:
   or navigation.
 - Preserve code samples, commands, SQL, config names, API fields, JSON, EBNF, and
   UI strings unless the task requires changing them or they are clearly wrong.
-- Front matter `title` must match the H1. English titles use title case; headings
-  below H1 use sentence case.
-- Summaries should be reader-focused and usually 115-145 characters. Add
-  `aliases` only when replacing, renaming, or deleting an existing page.
-- For `docs-cn`, preserve source meaning, structure, links, and terminology. Use
-  repo translation guidance instead of free paraphrasing.
+
+## Coordinating with other skills
+
+| Scenario | Skill to use |
+| --- | --- |
+| Chinese translation needed after English doc is done | `create-or-update-zh-translation-pr` |
+| Code change also needs release notes | `write-review-translate-release-notes` |
+| English doc PR needs review | `review-doc-pr` |
+| Doc pages need `summary` front matter written | `writing-doc-summaries` |
+
+Flag these needs to the user instead of silently switching skills.
 
 ## Validation loop
 
@@ -286,7 +341,8 @@ Writing rules that matter most:
 When proposing a plan before editing:
 
 ```markdown
-Target: <repo/path>
+Target: <repo/branch/path>
+Source: <code PR URL or other input>
 Change type: <update existing doc | write new page>
 Doc type: <task | concept | reference | new feature | troubleshooting | other>
 Outline: <short heading list>
@@ -302,9 +358,12 @@ When reporting completed edits:
 Changed files:
 - <path>: <what changed>
 
+Source PR: <link to the code PR that motivated the change>
+
 Checks:
 - <command>: <result>
 
 Notes:
 - <key decisions, maintenance triggers, or unresolved engineering questions>
+- <whether Chinese translation or release notes are also needed>
 ```
diff --git a/AGENTS.md b/AGENTS.md
index 367525a713a95..d565416deeff8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -42,6 +42,7 @@ Use the workflow-specific skills in `.ai/skills/` when they match the task:
 
 - `review-doc-pr`: review Markdown diffs, doc PRs, wording, structure, factual accuracy, and possible cross-file impact
 - `create-or-update-zh-translation-pr`: create or update an EN -> ZH translation PR that maps an English docs change or incremental source update to `pingcap/docs-cn`, using the bundled scripts in `.ai/skills/create-or-update-zh-translation-pr/scripts/` when applicable
+- `write-update-tidb-docs`: write new TiDB documentation or update existing documentation based on code PRs from `pingcap/tidb` or other TiDB ecosystem repositories, issues, design docs, or feature descriptions
 
 If no existing skill matches the task, follow this file plus the shared guidance and keep the change narrowly scoped.
 

From a3124a0b9a941de0ceefe73f0856bfe60283c2d0 Mon Sep 17 00:00:00 2001
From: qiancai <qqzczy@126.com>
Date: Thu, 11 Jun 2026 17:25:04 +0800
Subject: [PATCH 3/6] optimize the workflow

---
 .ai/AI-README.md                              |   2 +-
 .ai/skills/write-update-tidb-docs/SKILL.md    | 378 +++++++-----------
 .../ref-create-new-doc.md                     | 273 +++++++++++++
 .../ref-update-existing-doc.md                | 315 +++++++++++++++
 4 files changed, 729 insertions(+), 239 deletions(-)
 create mode 100644 .ai/skills/write-update-tidb-docs/ref-create-new-doc.md
 create mode 100644 .ai/skills/write-update-tidb-docs/ref-update-existing-doc.md

diff --git a/.ai/AI-README.md b/.ai/AI-README.md
index 87bd5479a78e3..3b14dd460ea3a 100644
--- a/.ai/AI-README.md
+++ b/.ai/AI-README.md
@@ -25,7 +25,7 @@ Use `resources/terms.md` when terminology is uncertain or not covered by the qui
 - `.ai/skills/create-or-update-zh-translation-pr/`: create a new docs translation PR or update an existing one by combining repo-local scripts with minimal-edit translation rules and incremental source-diff handling
 - `.ai/skills/writing-doc-summaries/`: write or update the `summary` front matter field in a document following the repo's 115-145 character SEO-friendly sentence rules
 - `.ai/skills/write-review-translate-release-notes/`: write, review, revise, and translate TiDB release note entries for the Compatibility changes, Improvements, and Bug fixes sections in English and Chinese
-- `.ai/skills/write-update-tidb-docs/`: write new TiDB documentation or update existing documentation based on code PRs, issues, design docs, or feature descriptions
+- `.ai/skills/write-update-tidb-docs/`: write new TiDB documentation or update existing documentation based on code PRs, issues, design docs, product specs, or feature descriptions; includes separate reference files for creating new docs (`ref-create-new-doc.md`) and updating existing docs (`ref-update-existing-doc.md`)
 
 The related resources skill includes bundled scripts under `.ai/skills/add-related-resources/scripts/` for:
 
diff --git a/.ai/skills/write-update-tidb-docs/SKILL.md b/.ai/skills/write-update-tidb-docs/SKILL.md
index 0847c0384c4fc..630e1d44c2195 100644
--- a/.ai/skills/write-update-tidb-docs/SKILL.md
+++ b/.ai/skills/write-update-tidb-docs/SKILL.md
@@ -1,15 +1,33 @@
 ---
 name: write-update-tidb-docs
-description: Write new TiDB documentation or update existing TiDB documentation from code changes, PRs, issues, design docs, rough drafts, existing docs, or short feature descriptions. Use when R&D engineers need user-facing docs in pingcap/docs based on code PRs in pingcap/tidb or other TiDB ecosystem repositories.
+description: Write new TiDB documentation or update existing TiDB documentation from code changes, PRs, issues, design docs, product specs, rough drafts, existing docs, or short feature descriptions. Use when PM or R&D engineers need user-facing docs in pingcap/docs based on code PRs from pingcap/tidb or other TiDB ecosystem repositories, GitHub issues, product specifications, or external reference materials.
 ---
 
 # Write or Update TiDB Docs
 
-Use this skill to turn engineering context into user-facing TiDB documentation
-in `pingcap/docs`. The most common input is a code PR from `pingcap/tidb` or
-other TiDB ecosystem repositories. Other inputs include code diffs, issues,
-design notes, release notes, rough Markdown, existing docs, or a few sentences
-from an R&D engineer.
+Use this skill when PM or R&D engineers provide engineering or product context
+and need it turned into user-facing TiDB documentation in `pingcap/docs`.
+
+**Role**: Act as a senior documentation engineer who understands both the
+technical implementation and the user's information needs. Evaluate not just
+*what* to write, but *where* it belongs, *how* it connects to existing content,
+and *what style* fits the surrounding documentation.
+
+## Accepted inputs
+
+| Input type | Examples |
+| --- | --- |
+| Code PR | `pingcap/tidb` PR link, diff, or reference |
+| GitHub issue | Feature request, bug report, design discussion |
+| Product spec | Feature specification, product requirement document |
+| Design doc | Technical design, RFC, architecture proposal |
+| External reference | Blog post, conference talk notes, user feedback |
+| Rough notes | Bullets, chat messages, informal descriptions |
+| Existing docs | Current doc page that needs improvement |
+| Verbal description | Short sentences describing the feature or change |
+
+Multiple input types can be combined. The more context provided, the fewer
+questions needed.
 
 ## Defaults
 
@@ -19,49 +37,35 @@ from an R&D engineer.
   workflow that does not fit cleanly in an existing page.
 - Documentation must justify its maintenance cost. Not every code change needs a
   doc update.
-- If the user asks about local changes without naming files, run `git status -u`.
-  If there are no uncommitted changes and the user clearly wants the latest local
-  change, inspect `git show --name-status` and targeted diffs.
-- For broad changes, group work by documentation area, such as guides, reference
-  docs, release notes, examples, overview pages, and TOC updates. Use subagents
-  or parallel analysis when available, but review the final result holistically.
-- For substantial new docs or vague inputs, switch to co-authoring mode: gather
-  context, agree on structure, draft section by section, and test whether the doc
-  answers likely reader questions.
 - English documentation in `pingcap/docs` is the primary output. Do not write
   Chinese docs directly. If Chinese docs are also needed, finish the English doc
   first, then use the `create-or-update-zh-translation-pr` skill.
-- If the code change also needs release notes, flag that and offer to use the
-  `write-review-translate-release-notes` skill after the doc work is done.
+- If the user asks about local changes without naming files, run `git status -u`.
+  If there are no uncommitted changes and the user clearly wants the latest local
+  change, inspect `git show --name-status` and targeted diffs.
 
 ## Load context progressively
 
-Always read:
+Always read first:
 
 - `.ai/shared/repo-conventions.md`
 - `.ai/shared/writing-style.md`
 
-Read only when relevant:
+Read when relevant:
 
-- `.ai/shared/translation-rules.md` and `.ai/shared/translation-terms.md` when
-  the task involves English-to-Chinese translation or Chinese documentation.
-- `resources/doc-templates/<template>.md` after choosing the doc type:
-    - `template-new-feature.md`
-    - `template-task.md`
-    - `template-concept.md`
-    - `template-reference.md`
-    - `template-troubleshooting.md`
+- `.ai/shared/translation-rules.md` and `.ai/shared/translation-terms.md`when the task involves English-to-Chinese translation or Chinese documentation.
+- `resources/doc-templates/<template>.md` after choosing the doc type (see the create-new-doc reference).
 - `resources/terms.md` when terminology is uncertain.
 
 Before drafting, inspect nearby docs, related overview/reference pages, TOC
 entries, existing terminology, linked issues or PRs, and relevant code changes.
 Prefer existing structure and wording in the same documentation area.
 
-## Workflow
+## Workflow overview
 
-### 0. Analyze the code PR
+### Phase 1: Analyze the input
 
-When the input is a code PR URL or reference:
+**When the input is a code PR URL or reference:**
 
 1. Fetch the PR metadata and diff:
 
@@ -70,239 +74,158 @@ When the input is a code PR URL or reference:
    gh pr diff <PR-URL>
    ```
 
-2. Read the PR description, linked issues, and any design doc references in the
-   PR body. These often contain the user-facing motivation and scope.
+2. Read the PR description, linked issues, and any design doc references.
 
-3. Scan the diff for documentation-relevant changes. Look for:
+3. Scan the diff for documentation-relevant changes:
 
    | Code pattern | Likely doc impact |
    | --- | --- |
-   | New or changed `SysVar` / `DefValue` in session/variable code | Update `system-variables.md` |
-   | New or changed config struct fields / `toml` tags | Update the corresponding `*-configuration-file.md` |
-   | New or changed command-line flags | Update `command-line-flags-for-*-configuration.md` |
-   | New SQL statement or grammar change (parser `.y` files) | New or updated `sql-statements/sql-statement-*.md` |
-   | New built-in function registration | Update `functions-and-operators/` docs |
+   | New/changed `SysVar` / `DefValue` | Update `system-variables.md` |
+   | New/changed config struct / `toml` tag | Update `*-configuration-file.md` |
+   | New/changed command-line flag | Update `command-line-flags-for-*-configuration.md` |
+   | New SQL statement or grammar change | New or updated `sql-statements/sql-statement-*.md` |
+   | New built-in function | Update `functions-and-operators/` docs |
    | New `INFORMATION_SCHEMA` table | New doc under `information-schema/` |
-   | New metrics or changed alert rules | Update `grafana-*.md` or monitoring docs |
-   | New feature flag or experimental feature gate | New feature doc or update existing feature doc |
-   | Changed default behavior or compatibility | Critical: update relevant docs + possibly release notes |
+   | New metrics or alert rules | Update `grafana-*.md` or monitoring docs |
+   | New feature flag or experimental gate | New feature doc or update existing |
+   | Changed default or compatibility | Update relevant docs + possibly release notes |
    | New API endpoint | Update or create API reference |
 
-4. Determine the documentation scope: is this a new page, an update to an
-   existing page, or both? Check whether release notes, overview pages, or TOC
-   also need updates.
-
-5. If the code diff is large, focus on user-facing changes (exported APIs,
+4. If the code diff is large, focus on user-facing changes (exported APIs,
    config, SQL grammar, error messages, system variables) and skip internal
-   refactors that do not affect user behavior.
+   refactors.
+
+**When the input is a product spec, issue, or design doc:**
+
+1. Identify the user-facing changes: what can users now do, configure, or observe
+   that they could not before?
+2. Identify the affected components: which TiDB component(s) does this touch?
+3. Determine version scope: which versions will include this change?
+4. Note any constraints, limitations, or compatibility concerns mentioned.
+
+**When the input is rough notes or verbal description:**
 
-### 1. Map code branches to docs branches
+1. Extract the key user-facing facts.
+2. Identify what information is missing and ask focused questions.
+3. Derive what you can from code, tests, config names, existing docs, and
+   related issues/PRs.
 
-Use the code PR's target branch to determine the docs branch:
+### Phase 2: Map to docs branch
 
-| Code repo target branch | Docs repo target branch | Notes |
+| Source target branch | Docs target branch | Notes |
 | --- | --- | --- |
 | `master` | `master` | Default for new development |
-| `release-X.Y` | `release-X.Y` (if it exists in docs) | Version-specific behavior or compatibility changes |
-| Any branch, but change is user-facing across versions | `master` + cherry-pick labels | Use `needs-cherry-pick-release-X.Y` labels |
+| `release-X.Y` | `release-X.Y` (if it exists) | Version-specific behavior |
+| Any, but user-facing across versions | `master` + cherry-pick labels | Use `needs-cherry-pick-release-X.Y` |
+| TiDB Cloud content (`/tidb-cloud/`) | `release-8.5` | Cloud docs branch |
+| AI content (`/ai/`) | `release-8.5` | AI docs branch |
 
 When in doubt, target `master` and let the user decide about cherry-picks.
 
-For TiDB Cloud content (`/tidb-cloud/` path), target the `release-8.5` branch.
-For AI content (`/ai/` path), target the `release-8.5` branch.
+### Phase 3: Plan with 5W1H
 
-### 2. Plan with 5W1H
-
-- **Who**: target readers, role, technical level, and prior knowledge.
-- **What**: primary information versus secondary details.
+- **Who**: target readers, role, technical level, prior knowledge.
+- **What**: primary information vs. secondary details.
 - **Why**: user goal and product value, not only implementation change.
-- **When**: use cases, feature status, applicable versions, and scenarios.
-- **Where**: target repo, target file, TOC location, and whether to update or
-  write a page.
+- **When**: use cases, feature status, applicable versions, scenarios.
+- **Where**: target repo, target file(s), TOC location.
 - **How**: steps, SQL, commands, APIs, examples, expected output, limitations,
-  compatibility, validation, and follow-up docs.
-
-When facts are missing, derive what you can from code, tests, config names,
-release notes, nearby docs, and issue or PR context. Ask focused questions only
-for facts that cannot be verified locally and would change the documentation.
+  compatibility, validation.
 
-For substantial docs, ask the user to dump context in any form that is efficient:
-notes, issue links, PR links, design docs, team decisions, rejected alternatives,
-timeline constraints, stakeholder concerns, or rough bullets. Track what is
-known, what is assumed, and what still needs confirmation.
+### Phase 4: Decide — create new or update existing
 
-### 3. Triage documentation impact
+This is the key routing decision. Ask:
 
-Prioritize tasks:
+1. Does this feature/change have a natural home in an existing page?
+2. Is the existing page already covering this topic area?
+3. Would adding this content to an existing page make it unreasonably long or
+   confuse the page's current focus?
+4. Does this introduce a distinct user task or feature that deserves standalone
+   discoverability?
 
-- **Critical**: breaking changes, changed defaults, compatibility changes,
-  security-relevant behavior, user-facing errors, or new/changed public APIs.
-- **Important**: new features, configuration options, workflows, SQL behavior,
-  limitations, performance guidance, examples, or required TOC/index updates.
-- **Nice to have**: minor clarifications or comments for non-obvious logic that
-  users or contributors are likely to need.
-
-Skip or consolidate docs that only:
+| Decision | Action |
+| --- | --- |
+| Content fits in existing page(s) | → Read `ref-update-existing-doc.md` and follow its workflow |
+| Content needs a new standalone page | → Read `ref-create-new-doc.md` and follow its workflow |
+| Both (new page + updates to related pages) | → Read both references; start with the new page, then update related |
 
-- duplicate generated references, schemas, or existing docs without user context
-- describe obvious internal implementation details
-- document temporary workarounds or behavior expected to disappear soon
-- repeat the same information in multiple places
+### Phase 5: Triage priority
 
-### 4. Find the target doc and TOC placement
+When multiple docs need updating, prioritize:
 
-Before deciding whether to update an existing doc or write a new page, inspect
-the relevant TOC file. TOC placement is often the fastest way to find the right
-existing page, neighboring docs, and navigation category.
+- **Critical**: breaking changes, changed defaults, compatibility changes,
+  security-relevant behavior, user-facing errors, new/changed public APIs.
+- **Important**: new features, configuration options, workflows, SQL behavior,
+  limitations, performance guidance, examples, TOC updates.
+- **Nice to have**: minor clarifications, comments for non-obvious logic.
 
-Use `rg` to search TOC files by feature name, command, component, or likely path:
+Skip or consolidate docs that only duplicate generated references without user
+context, describe obvious internal implementation, or document temporary behavior.
 
-```bash
-rg -n "<keyword>|<path>" TOC*.md
-```
+### Phase 6: Write
 
-TOC file purposes in `pingcap/docs`:
+Follow `.ai/shared/writing-style.md` for all writing conventions. Key reminders:
 
-| TOC file | Use for |
-| --- | --- |
-| `TOC.md` | Main TiDB Self-Managed docs |
-| `TOC-ai.md` | TiDB for AI, vector search, `pytidb`, MCP, AI integrations |
-| `TOC-develop.md` | Application development guides, quick starts, integrations, developer reference |
-| `TOC-best-practices.md` | Best practice pages for schema, deployment, operations, and performance |
-| `TOC-api.md` | API documentation navigation for TiDB Cloud and TiDB Self-Managed |
-| `TOC-tidb-releases.md` | TiDB Self-Managed release notes |
-| `TOC-tidb-cloud.md` | Main TiDB Cloud docs, especially Dedicated/general Cloud navigation |
-| `TOC-tidb-cloud-starter.md` | TiDB Cloud Starter docs |
-| `TOC-tidb-cloud-essential.md` | TiDB Cloud Essential docs |
-| `TOC-tidb-cloud-premium.md` | TiDB Cloud Premium docs |
-| `TOC-tidb-cloud-releases.md` | TiDB Cloud release notes and maintenance notifications |
-
-Common doc targets (from code change patterns):
-
-| User request mentions | Start with |
-| --- | --- |
-| system variable | `system-variables.md` and `system-variable-reference.md` |
-| status variable | `status-variables.md` |
-| TiDB config parameter | `tidb-configuration-file.md` |
-| TiKV config parameter | `tikv-configuration-file.md` |
-| TiFlash config parameter | `tiflash/tiflash-configuration.md` |
-| PD config parameter | `pd-configuration-file.md` |
-| TSO or scheduling config | `tso-configuration-file.md` or `scheduling-configuration-file.md` |
-| TiDB/TiKV/PD/TiFlash command-line flag | `command-line-flags-for-*-configuration.md` or `tiflash/tiflash-command-line-flags.md` |
-| TiCDC server or changefeed config | `ticdc/ticdc-server-config.md` or `ticdc/ticdc-changefeed-config.md` |
-| TiProxy config | `tiproxy/tiproxy-configuration.md` |
-| SQL statement | `sql-statements/sql-statement-<statement>.md` and `sql-statements/sql-statement-overview.md` |
-| function or operator | `functions-and-operators/` and `functions-and-operators/functions-and-operators-overview.md` |
-| data type | `data-type-*.md` and `data-type-overview.md` |
-| vector type/function/index | `/ai/reference/` docs, English-only in `release-8.5` |
-| `INFORMATION_SCHEMA` table | `information-schema/` |
-| monitoring metric | `grafana-*.md`, `tiflash/monitor-tiflash.md`, or `ticdc/monitor-ticdc.md` |
-
-Treat these as starting points, not final answers. Confirm placement in the
-appropriate TOC and inspect nearby entries before editing.
-
-### 5. Choose the doc type
-
-- **New feature**: what it is, why it matters, when to use it, how to use it,
-  limitations, compatibility, and related resources.
-- **Task**: prerequisites, numbered steps, expected results, and troubleshooting
-  tips when useful.
-- **Concept**: ideas, architecture, terms, behavior, or tradeoffs users need
-  before tasks.
-- **Reference**: syntax, APIs, configuration, system variables, parameters,
-  functions, outputs, or limits.
-- **Troubleshooting**: symptoms, likely causes, checks, fixes, and prevention.
-- **Existing-doc update**: change only affected sections and preserve the
-  surrounding structure, tone, and technical scope.
-
-For any update, check whether overview pages, reference pages, examples,
-`TOC.md`, aliases, links, or release notes also need changes.
-
-### 6. Write
-
-Follow `.ai/shared/writing-style.md` for all writing conventions. Key points
-for this workflow:
-
-- Start with useful information directly. Avoid internal background unless users
-  need it.
+- Start with useful information directly. No preamble about what the doc will do.
 - Start task docs with the most common use case or shortest path to first
   success.
-- Put conditions before instructions. Tell users where to perform each action.
-- Explain placeholders and include expected output for commands, SQL, or APIs
-  when useful.
+- Put conditions before instructions.
+- Explain placeholders and include expected output for commands, SQL, or APIs.
 - Keep code examples realistic and runnable when possible.
 - Define jargon on first use.
 - Preserve commands, SQL, API names, UI strings, config names, JSON fields,
-  outputs, and technical meaning unless they are factually wrong or confirmed
-  changed.
-
-For new feature docs, or substantial feature expansions, use this shape when
-applicable:
-
-```markdown
----
-title: <same as H1>
-summary: <115-145 character reader-focused summary>
----
-
-# <same as title>
-
-<Intro: what the feature does, why it matters, and when users should use it.>
-
-## Usage scenarios
-
-## Prerequisites
+  outputs, and technical meaning unless factually wrong or confirmed changed.
 
-## Usage or procedures
+For doc-type-specific structure, see the appropriate reference file.
 
-### Method 1: <method name> (recommended)
+### Phase 7: Validate
 
-### Method 2: <method name>
-
-## Limitations
+1. Review against the plan: facts, user goal, doc type, scope, examples, links,
+   TOC impact, version scope, and maintainability.
+2. Run Markdown validation:
 
-## Compatibility
+   ```bash
+   ./scripts/markdownlint <changed-files>
+   ```
 
-## FAQ
+3. Run link validation when adding or changing links, anchors, moved or renamed
+   files, aliases, or TOC entries.
+4. For procedural docs, mentally or actually test the steps, sample code, SQL,
+   expected output, and placeholders.
+5. For substantial docs, run a reader test: predict 5–10 realistic reader
+   questions, verify the doc answers them without hidden context, and fix gaps.
+6. If validation fails, fix the issue and repeat.
 
-## More resources
-```
+## Reference files
 
-Use only sections that help users complete tasks or make decisions. When updating
-an existing doc, fit new content into the existing structure unless the current
-structure blocks user understanding.
+This skill includes two reference files for the detailed workflows:
 
-For substantial new docs or major rewrites, draft section by section:
+- `ref-create-new-doc.md` — complete guidance for creating new documentation
+  pages, including TOC placement, doc type selection, file naming, structure,
+  front matter, and co-authoring mode.
+- `ref-update-existing-doc.md` — complete guidance for updating existing pages,
+  including target identification, related doc assessment, style consistency,
+  cross-document impact, and common update patterns.
 
-1. Propose the 3-5 core sections based on the doc type or template.
-2. Start with the section that has the most unknowns; write summaries or
-   conclusions last.
-3. For each section, ask only the clarifying questions needed for that section,
-   draft the section, then revise surgically instead of reprinting the whole doc.
-4. After several small edits, ask whether anything can be removed without losing
-   important information.
+Load the relevant reference file after Phase 4 determines the action type.
 
 ## TiDB docs gotchas
 
 - Target `master` by default. Use release branches only for version-specific
   behavior, compatibility changes, broken links in published docs, explicit user
-  requests, or the `/tidb-cloud/` and `/ai/` exceptions below.
-- The `/tidb-cloud/` and `/ai/` folders are currently maintained only in the
-  `pingcap/docs` `release-8.5` branch. For these folders, update English only.
-  Do not manually update Chinese content:
-    - `/tidb-cloud/` Chinese content is in `pingcap/docs`
-      `i18n-zh-release-8.5` and is AI-translated weekly.
-    - `/ai/` Chinese content is in `pingcap/docs-cn` and is also AI-translated
-      weekly.
-- New navigable pages usually require `TOC.md` updates. Renamed or replaced pages
+  requests, or the `/tidb-cloud/` and `/ai/` exceptions.
+- The `/tidb-cloud/` and `/ai/` folders are maintained only in `release-8.5`.
+  Update English only. Chinese content is AI-translated weekly.
+- New navigable pages always require `TOC.md` updates. Renamed or replaced pages
   might need `aliases`.
-- TiDB Cloud docs use special branch and rendering rules. Before changing shared
-  TiDB/TiDB Cloud content, check repo guidance and any `CustomContent` blocks.
-- Do not silently broaden scope from a local doc fix into cross-file rewrites.
-  Note possible related updates, and only edit them when needed for correctness
-  or navigation.
+- TiDB Cloud docs use special branch and rendering rules. Check `CustomContent`
+  blocks before changing shared TiDB/TiDB Cloud content.
+- Do not silently broaden scope from a local fix into cross-file rewrites. Note
+  related updates and only make them when needed for correctness or navigation.
 - Preserve code samples, commands, SQL, config names, API fields, JSON, EBNF, and
   UI strings unless the task requires changing them or they are clearly wrong.
+- For broad changes, group work by documentation area and use subagents or
+  parallel analysis when available, but review the final result holistically.
 
 ## Coordinating with other skills
 
@@ -311,39 +234,18 @@ For substantial new docs or major rewrites, draft section by section:
 | Chinese translation needed after English doc is done | `create-or-update-zh-translation-pr` |
 | Code change also needs release notes | `write-review-translate-release-notes` |
 | English doc PR needs review | `review-doc-pr` |
-| Doc pages need `summary` front matter written | `writing-doc-summaries` |
+| Doc pages need `summary` front matter | `writing-doc-summaries` |
 
 Flag these needs to the user instead of silently switching skills.
 
-## Validation loop
-
-1. Review against the plan: facts, user goal, doc type, scope, examples, links,
-   TOC impact, version scope, and maintainability.
-2. Run Markdown validation when practical:
-
-   ```bash
-   ./scripts/markdownlint <changed-files>
-   ```
-
-3. Run targeted link validation when adding or changing links, anchors, moved
-   files, renamed files, aliases, or TOC entries.
-4. For procedural docs, mentally or actually test the steps, sample code, SQL,
-   expected output, and placeholders.
-5. For substantial docs, run a reader test: predict 5-10 realistic reader
-   questions, verify the doc answers them without hidden context, and fix gaps,
-   ambiguities, contradictions, or unstated assumptions. Use a subagent for a
-   fresh-read review when available.
-6. If validation fails, fix the issue and repeat until checks pass or clearly
-   report why a check could not be run.
-
 ## Output templates
 
-When proposing a plan before editing:
+**When proposing a plan before editing:**
 
 ```markdown
 Target: <repo/branch/path>
-Source: <code PR URL or other input>
-Change type: <update existing doc | write new page>
+Source: <code PR URL, issue, spec, or other input>
+Change type: <update existing doc | write new page | both>
 Doc type: <task | concept | reference | new feature | troubleshooting | other>
 Outline: <short heading list>
 Related updates: <TOC, aliases, links, overview/reference/release notes>
@@ -352,13 +254,13 @@ Reader test: <questions the doc should answer, for substantial docs>
 Open questions: <facts that need confirmation>
 ```
 
-When reporting completed edits:
+**When reporting completed edits:**
 
 ```markdown
 Changed files:
 - <path>: <what changed>
 
-Source PR: <link to the code PR that motivated the change>
+Source: <link to the code PR, issue, or spec that motivated the change>
 
 Checks:
 - <command>: <result>
diff --git a/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md b/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md
new file mode 100644
index 0000000000000..30e8e5f87f941
--- /dev/null
+++ b/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md
@@ -0,0 +1,273 @@
+# Reference: Create New TiDB Documentation
+
+This reference covers the full workflow for creating a new documentation page in
+`pingcap/docs`. Read this after the main SKILL.md has determined that a new page
+is needed.
+
+## When to create a new page
+
+Create a new page only when the change introduces content that does not fit
+cleanly in an existing page. Typical triggers:
+
+- A distinct user-facing feature with its own usage scenarios, configuration,
+  and limitations (for example, a new index type, a new SQL statement, a new
+  tool mode).
+- A new integration, connector, or ecosystem tool that needs a standalone guide.
+- A new reference entity that follows an established pattern (for example, a new
+  `INFORMATION_SCHEMA` table, a new TiCDC sink type).
+- A troubleshooting workflow that is complex enough to justify its own page
+  rather than a section in an existing troubleshooting doc.
+- A new concept or architecture topic that supports multiple task or reference
+  pages.
+
+Do **not** create a new page when:
+
+- The content can be added as a section or subsection of an existing page without
+  making that page unreasonably long.
+- The content duplicates information already available elsewhere.
+- The content is too thin to justify standalone maintenance (fewer than ~3
+  meaningful sections).
+
+## Step 1: Choose the doc type and template
+
+Match the user's information need to a doc type:
+
+| Doc type | User need | Template |
+| --- | --- | --- |
+| New feature | "What is this, why should I use it, how do I use it?" | `resources/doc-templates/template-new-feature.md` |
+| Task | "How do I do X step by step?" | `resources/doc-templates/template-task.md` |
+| Concept | "What is X and how does it work?" | `resources/doc-templates/template-concept.md` |
+| Reference | "What are the parameters, syntax, config options?" | `resources/doc-templates/template-reference.md` |
+| Troubleshooting | "Something is wrong, how do I fix it?" | `resources/doc-templates/template-troubleshooting.md` |
+
+Read the selected template before drafting. Use the template as the structural
+skeleton; skip sections that do not apply rather than filling them with thin
+content.
+
+For features that combine concept, usage, and reference (common in TiDB), prefer
+the **new feature** template and merge concept and reference into its sections.
+Split into multiple pages only when the content naturally exceeds ~1500 words per
+concern.
+
+## Step 2: Choose the file path and name
+
+Follow existing patterns in the same documentation area:
+
+- Check where similar docs live by inspecting the relevant TOC file and nearby
+  directory structure.
+- Use lowercase, hyphen-separated names: `feature-name.md`.
+- Keep names concise and stable. Avoid version numbers or overly specific wording
+  that would require renaming.
+- If the feature belongs to a component that has its own directory (for example,
+  `ticdc/`, `tiflash/`, `tiproxy/`, `dm/`), place the file in that directory.
+- If the feature is cross-component or general, place it at the repository root.
+
+Examples:
+
+| Feature | Good path | Why |
+| --- | --- | --- |
+| New TiCDC sink type | `ticdc/ticdc-sink-to-<target>.md` | Follows existing sink docs pattern |
+| New SQL statement | `sql-statements/sql-statement-<name>.md` | Follows SQL statement pattern |
+| New INFORMATION_SCHEMA table | `information-schema/information-schema-<name>.md` | Follows info schema pattern |
+| New general feature | `<feature-name>.md` at root | Matches other root-level features |
+| New TiFlash feature | `tiflash/<feature-name>.md` | Component directory |
+
+## Step 3: Determine TOC placement
+
+Every new navigable page requires an entry in the appropriate TOC file.
+
+### Identify the right TOC file
+
+| Content type | TOC file |
+| --- | --- |
+| TiDB Self-Managed (most common) | `TOC.md` |
+| AI, vector search, pytidb, MCP | `TOC-ai.md` |
+| Application development guides | `TOC-develop.md` |
+| Best practices | `TOC-best-practices.md` |
+| API documentation | `TOC-api.md` |
+| TiDB release notes | `TOC-tidb-releases.md` |
+| TiDB Cloud (Dedicated/general) | `TOC-tidb-cloud.md` |
+| TiDB Cloud Starter | `TOC-tidb-cloud-starter.md` |
+| TiDB Cloud Essential | `TOC-tidb-cloud-essential.md` |
+| TiDB Cloud Premium | `TOC-tidb-cloud-premium.md` |
+| TiDB Cloud release notes | `TOC-tidb-cloud-releases.md` |
+
+### Find the right position
+
+1. Search the TOC for the relevant section or category:
+
+   ```bash
+   rg -n "<keyword>|<component>" TOC.md
+   ```
+
+2. Look at the neighboring entries. TOC entries follow logical grouping:
+   - Features of the same component are grouped together.
+   - Related features are adjacent (for example, all sink types under
+     "Create Changefeeds").
+   - Difficulty generally progresses from overview → getting started → usage →
+     reference → troubleshooting within each group.
+
+3. Position the new entry:
+   - If there is a clear peer group, add the entry adjacent to similar items.
+   - If it is the first of a new category, create a new section heading.
+   - If it is a sub-feature, nest it under the parent feature entry.
+
+4. Use the correct indentation level (2 spaces per TOC level). The TOC format:
+
+   ```markdown
+   - Category Name
+     - [Page Title](/path/to/file.md)
+     - [Another Page](/path/to/another.md)
+       - [Sub Page](/path/to/sub.md)
+   ```
+
+### TOC title conventions
+
+- Use title case for TOC entries.
+- Keep TOC titles concise (typically 3–7 words).
+- Match the document H1 when possible, but shorten for TOC readability.
+- Do not include "TiDB" in the TOC title when the context already makes it
+  clear.
+
+## Step 4: Write front matter
+
+Every new page needs front matter:
+
+```yaml
+---
+title: <same as H1, title case, ≤59 characters>
+summary: <115–145 characters, starts with a verb, SEO-friendly, reader-focused>
+---
+```
+
+Rules:
+
+- The `title` must match the H1 heading exactly.
+- The `summary` must not start with special characters (`>`, `*`, `#`, `-`, `[`).
+- The `summary` should tell readers what they will learn or accomplish.
+- Do not add other metadata fields unless there is a specific reason (for
+  example, `aliases` for a page that replaces an older URL).
+
+## Step 5: Draft the document
+
+### General structure principles
+
+- Start with what users care about: what the feature does, why it matters, when
+  to use it.
+- Put conditions and prerequisites before instructions.
+- Include realistic, runnable examples where practical.
+- Define jargon on first use.
+- End with related resources or next steps.
+
+### Structure by doc type
+
+**New feature:**
+
+```
+H1: Feature Name
+  Intro paragraph (what, why, when)
+H2: Usage scenarios
+H2: Prerequisites (optional)
+H2: Usage / Procedures
+  H3: Method 1 (recommended)
+  H3: Method 2
+H2: Parameter reference (if applicable)
+H2: Limitations
+H2: Compatibility
+H2: FAQ (optional)
+H2: More resources
+```
+
+**Task:**
+
+```
+H1: Task Title
+  Intro paragraph (what this doc helps you do)
+H2: Prerequisites
+H2: Step 1. <action>
+H2: Step 2. <action>
+H2: Step 3. <action>
+H2: What's next
+```
+
+**Concept:**
+
+```
+H1: Concept Title
+  Intro paragraph (what the concept is)
+H2: Architecture / Key components
+H2: How it works
+H2: Key features / Limitations
+H2: What's next
+```
+
+**Reference:**
+
+```
+H1: Reference Title
+  Intro paragraph (what this reference covers)
+H2: Category 1
+  H3: Parameter/item
+H2: Category 2
+  H3: Parameter/item
+```
+
+**Troubleshooting:**
+
+```
+H1: Troubleshoot <Problem>
+  Intro paragraph (what problems this doc covers)
+H2: Common causes
+  H3: Cause 1 (Symptom + Solution)
+  H3: Cause 2
+H2: Other causes
+  H3: Cause 3
+```
+
+### Co-authoring mode for substantial docs
+
+For documents expected to exceed ~800 words or with unclear scope:
+
+1. Propose the 3–5 core sections first and get confirmation.
+2. Start with the section that has the most unknowns or highest user value.
+3. Draft section by section, asking focused questions only for facts that cannot
+   be derived from code, tests, or existing docs.
+4. After drafting, run a reader test: predict 5–10 realistic reader questions and
+   verify the doc answers them.
+5. Ask whether anything can be removed without losing important information.
+
+## Step 6: Handle associated updates
+
+Creating a new page often requires updates elsewhere:
+
+| Check | Action |
+| --- | --- |
+| TOC entry added? | Required for all navigable pages |
+| Overview page mentions new feature? | Add a brief entry or link if the area has an overview |
+| Related docs link to new page? | Add "See also" or inline links where users would benefit |
+| `sql-statement-overview.md` updated? | Required for new SQL statements |
+| `functions-and-operators-overview.md` updated? | Required for new functions |
+| Release notes mention the feature? | Flag for release notes skill if applicable |
+| `system-variables.md` references new page? | If the feature has system variables |
+
+## Step 7: Validate
+
+1. Run `./scripts/markdownlint <new-file>` to catch formatting issues.
+2. Run `./scripts/verify-links.sh` if the new page has links or is linked from
+   other pages.
+3. Verify the TOC renders correctly (correct indentation, no orphaned entries).
+4. Check front matter: title matches H1, summary is 115–145 characters.
+5. Mentally test: can a user who finds this page via search complete their task
+   without hidden context?
+
+## Common mistakes to avoid
+
+- Creating a page that is too thin (only 1–2 short sections). Consider whether
+  the content fits as a section in an existing page.
+- Placing the TOC entry in the wrong file or nesting level.
+- Using a file name that duplicates or conflicts with existing names.
+- Writing an intro that describes what the document will do instead of starting
+  with useful information directly.
+- Skipping the overview/reference page updates that help users discover the new
+  page.
+- Forgetting to handle `aliases` when a new page replaces an older page.
diff --git a/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md b/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md
new file mode 100644
index 0000000000000..65ff03628a4a4
--- /dev/null
+++ b/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md
@@ -0,0 +1,315 @@
+# Reference: Update Existing TiDB Documentation
+
+This reference covers the full workflow for updating existing documentation pages
+in `pingcap/docs`. Read this after the main SKILL.md has determined that one or
+more existing pages need updating.
+
+## When to update existing docs
+
+Update rather than create when:
+
+- A feature gains a new option, parameter, configuration item, or behavior mode
+  that fits in the existing page structure.
+- A default value, behavior, or limitation changes.
+- A system variable, config parameter, or command-line flag is added or modified.
+- A code change affects user-visible behavior documented on an existing page.
+- A compatibility or deprecation note needs to be added.
+- An existing page has outdated, incomplete, or incorrect information.
+
+Prefer targeted edits over broad rewrites. Change only the sections affected by
+the update unless the existing structure is clearly inadequate.
+
+## Step 1: Identify target docs from code changes
+
+Use the code change patterns to find which docs likely need updating:
+
+| Code pattern | Primary target doc(s) |
+| --- | --- |
+| New/changed `SysVar` / `DefValue` | `system-variables.md`, `system-variable-reference.md` |
+| New/changed config struct field / `toml` tag | `tidb-configuration-file.md`, `tikv-configuration-file.md`, `tiflash/tiflash-configuration.md`, `pd-configuration-file.md`, or equivalent |
+| New/changed command-line flag | `command-line-flags-for-*-configuration.md` |
+| Changed SQL grammar (parser `.y`) | `sql-statements/sql-statement-<name>.md` |
+| New/changed built-in function | `functions-and-operators/` relevant file |
+| New `INFORMATION_SCHEMA` table column | `information-schema/information-schema-<name>.md` |
+| Changed metric or alert rule | `grafana-*.md` or monitoring docs |
+| Changed default behavior | Feature doc + possibly release notes |
+| New error code or message | Error reference docs |
+| Changed API endpoint or response | API reference docs |
+
+### Search strategies
+
+Find existing docs by keyword, feature name, or path:
+
+```bash
+rg -l "<system-variable-name>|<config-name>|<feature-keyword>" --type md
+rg -n "<keyword>" TOC*.md
+```
+
+When the code change touches a specific component, also check the component's
+directory (`ticdc/`, `tiflash/`, `tiproxy/`, `dm/`, `br/`) for related docs.
+
+## Step 2: Assess related and associated docs
+
+A single code change often affects multiple documentation pages. Assess the full
+impact before editing:
+
+### Direct impact
+
+Pages that directly describe the changed behavior:
+
+- The primary reference page (config file, system variables, command flags)
+- The feature or task page that explains how to use the behavior
+- The SQL statement page if syntax changed
+
+### Indirect impact
+
+Pages that reference or summarize the changed behavior:
+
+- **Overview pages**: pages that list or summarize features in a category (for
+  example, `functions-and-operators-overview.md`, `sql-statement-overview.md`)
+- **Compatibility pages**: `mysql-compatibility.md`, feature compatibility tables
+- **Limitation pages**: `tidb-limitations.md`, feature-specific limitations
+- **Release notes**: if the change is user-facing in a specific version
+- **FAQ pages**: if the change affects commonly asked questions
+- **Best practice pages**: if the change affects recommended workflows
+- **Troubleshooting pages**: if the change resolves or introduces known issues
+
+### Discovering related pages
+
+```bash
+# Find pages that mention the feature or config item
+rg -l "<feature-name>|<config-name>" --type md
+
+# Find pages that link to the target page
+rg -l "/path-to-target-doc.md" --type md
+
+# Check if the feature appears in overview or summary docs
+rg -l "<feature-keyword>" *-overview.md basic-features.md
+```
+
+### Scope discipline
+
+- Update direct-impact pages in the same edit.
+- For indirect-impact pages, assess whether the update is **required for
+  correctness** or merely **nice to have**.
+- If an indirect page update is required (for example, a limitation was removed
+  and the limitations page still lists it), include it.
+- If an indirect page update is nice to have (for example, an overview page could
+  mention the enhancement), flag it in the output notes but do not expand scope
+  unless the user confirms.
+
+## Step 3: Understand the existing page before editing
+
+Before making changes, read the target page (or relevant sections) to understand:
+
+1. **Existing structure**: heading hierarchy, section order, and content flow.
+2. **Existing tone and voice**: formal vs. conversational, level of detail,
+   whether the page uses imperative ("Configure X") or descriptive ("X is
+   configured by") style.
+3. **Existing patterns**: how similar items are documented on the same page. For
+   example, if system variables use a specific description format, follow it.
+4. **Existing terminology**: which terms the page uses for concepts. Do not
+   introduce synonyms or alternate terms.
+5. **Existing scope**: what the page covers and what it explicitly excludes. Do
+   not expand scope without reason.
+
+Key principle: **the updated section should read as if it were written by the
+same author as the rest of the page**. Do not let new content stand out
+stylistically.
+
+## Step 4: Plan the edit
+
+For each target page, determine:
+
+- **Where** in the page the new content goes (which section, which position
+  within the section).
+- **What** to add, change, or remove.
+- **How much** surrounding context to preserve or adjust for flow.
+
+### Placement within a page
+
+Follow existing ordering conventions on the page:
+
+| Page type | Typical ordering |
+| --- | --- |
+| System variables | Alphabetical by variable name |
+| Config parameters | Grouped by section, then by related functionality |
+| SQL statement | Synopsis → Description → Examples → See also |
+| Function reference | Syntax → Parameters → Return type → Examples |
+| Feature page sections | Conceptual intro → Usage → Limitations → Compatibility |
+
+When adding a new item to a list or table:
+
+- Insert in the correct sort order (alphabetical, logical grouping, or as
+  established by neighbors).
+- Match the existing column structure and description style exactly.
+- Do not reorder existing items unless correcting a clear sorting error.
+
+### Handling additions vs. modifications
+
+**Adding new content** (new parameter, new section, new example):
+
+- Follow the format of adjacent entries.
+- If adding a new section, maintain heading level hierarchy—do not skip levels.
+- Add transitional context if needed so the addition flows with surroundings.
+
+**Modifying existing content** (changed default, updated behavior):
+
+- Change only the specific facts that are wrong or outdated.
+- Preserve the sentence structure and style when possible.
+- If the behavioral change is breaking, add a version note or warning.
+- Update any version-specific statements (for example, "Starting from v8.4" →
+  adjust the version scope).
+
+**Removing content** (deprecated feature, removed limitation):
+
+- Remove cleanly without leaving orphaned references or broken flow.
+- Check if other parts of the same page reference the removed content.
+- If the removal is for a deprecated feature, consider adding a deprecation note
+  instead of deleting entirely.
+
+## Step 5: Maintain style consistency
+
+### Match the existing description format
+
+For structured reference docs (system variables, config files), each entry
+typically follows a pattern. Examples:
+
+**System variable entry pattern:**
+
+```markdown
+### variable_name
+
+- Scope: SESSION | GLOBAL | SESSION | GLOBAL, SESSION
+- Persists to cluster: Yes | No
+- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): Yes | No
+- Type: Boolean | Integer | Enum | ...
+- Default value: `<value>`
+- Range: `[min, max]` (for numeric types)
+- This variable controls ...
+```
+
+**Config parameter entry pattern:**
+
+```markdown
+### `parameter-name`
+
+- Default value: `<value>`
+- Range: ... (if applicable)
+- Description text explaining what the parameter controls.
+```
+
+When adding new entries, replicate the exact format including field order,
+punctuation, backtick usage, and description style.
+
+### Preserve voice and level of detail
+
+- If the page uses terse descriptions, keep new content terse.
+- If the page uses full explanatory paragraphs, write comparably.
+- If the page includes examples for each item, add an example for new items.
+- If the page does not include examples, do not add one only for the new item
+  unless it significantly aids understanding.
+
+### Version annotations
+
+When a change is version-specific:
+
+- Use the established format: "Starting from vX.Y, ..." or "This variable was
+  introduced in vX.Y."
+- Place version notes consistently with how they appear elsewhere on the page.
+- For behavior changes, clearly state both the old and new behavior when helpful.
+
+## Step 6: Handle cross-document consistency
+
+After editing, verify that related docs remain consistent:
+
+1. **Same facts in multiple places**: if the same default value, limitation, or
+   behavior appears in multiple docs, update all of them.
+2. **Links still valid**: if you change a heading, check whether other docs link
+   to that anchor.
+3. **Feature lists and overviews**: if a feature gains new capabilities,
+   check whether summary pages need updating.
+4. **Compatibility tables**: if behavior changes for MySQL compatibility,
+   `mysql-compatibility.md` may need updating.
+5. **Code examples**: if a default changes, examples that rely on the old default
+   may produce different output.
+
+## Step 7: Handle version and branch scoping
+
+Decide which branches the update targets:
+
+| Change type | Target branch |
+| --- | --- |
+| New feature in development | `master` only |
+| Behavior change in released version | `master` + cherry-pick label for the release branch |
+| Bug fix in documentation (factual error) | `master` + cherry-pick label if error exists in release branch |
+| TiDB Cloud documentation | `release-8.5` |
+| AI / vector documentation | `release-8.5` |
+| Wording improvement not tied to a version | `master` only |
+
+When the update includes version-specific notes, ensure the phrasing is accurate
+for the target branch. A note saying "Starting from v8.5" makes sense in
+`master` and `release-8.5` but not in `release-8.4`.
+
+## Step 8: Validate
+
+1. Run `./scripts/markdownlint <changed-files>` to catch formatting issues.
+2. If headings changed, run `./scripts/verify-links.sh` to detect broken anchors.
+3. Re-read the changed section in context (at least 2–3 surrounding sections) to
+   verify it reads naturally and consistently.
+4. Verify facts against the source (code PR, issue, design doc).
+5. For procedural docs, mentally trace the steps with the new information.
+6. Check that no orphaned references remain if content was removed or moved.
+
+## Common update patterns
+
+### Adding a new system variable
+
+1. Add the entry in `system-variables.md` in alphabetical order following the
+   existing entry format.
+2. If the variable is referenced in `system-variable-reference.md`, add it there
+   too.
+3. Check if the feature page that uses this variable should mention it.
+4. If the variable controls a new feature, the feature doc takes priority; the
+   variable entry should link to it.
+
+### Adding a new config parameter
+
+1. Add the entry in the corresponding `*-configuration-file.md` under the
+   correct `[section]`.
+2. Follow the exact format of neighboring entries.
+3. If the parameter has a corresponding command-line flag, update the flag doc
+   too.
+
+### Updating default values or behavior
+
+1. Change the default value in the parameter/variable description.
+2. Add a version note if the change is version-specific.
+3. Check if examples elsewhere on the page (or in other docs) assume the old
+   default.
+4. If the change is breaking, add a compatibility or warning note.
+
+### Adding a limitation or removing a limitation
+
+1. Update the limitations section of the feature doc.
+2. If the limitation affects `tidb-limitations.md`, update that page too.
+3. If a limitation is removed, check whether workaround documentation should also
+   be removed or marked as no longer necessary.
+
+### Documenting a deprecation
+
+1. Add a deprecation notice in the relevant section with the version it was
+   deprecated and expected removal timeline.
+2. Update any "recommended" guidance that points users to the deprecated feature.
+3. Link to the replacement feature or migration path.
+4. Do not delete documentation for deprecated features that are still functional.
+
+## Common mistakes to avoid
+
+- Changing only one occurrence of a fact that appears in multiple places.
+- Breaking the style or format consistency with surrounding entries.
+- Expanding scope into unrelated improvements while making a targeted fix.
+- Adding version notes that are inaccurate for the target branch.
+- Leaving orphaned cross-references when removing or moving content.
+- Introducing different terminology for the same concept within one page.
+- Rewriting surrounding content unnecessarily while making a targeted edit.

From b5db02a3a6106f67ba4f2eaf896c6b42661e5474 Mon Sep 17 00:00:00 2001
From: qiancai <qqzczy@126.com>
Date: Thu, 11 Jun 2026 17:34:07 +0800
Subject: [PATCH 4/6] refine the skill

---
 .ai/skills/write-update-tidb-docs/SKILL.md    | 316 +++++---------
 .../ref-create-new-doc.md                     | 379 ++++++++--------
 .../ref-update-existing-doc.md                | 405 ++++++++----------
 3 files changed, 465 insertions(+), 635 deletions(-)

diff --git a/.ai/skills/write-update-tidb-docs/SKILL.md b/.ai/skills/write-update-tidb-docs/SKILL.md
index 630e1d44c2195..5516fd9023de7 100644
--- a/.ai/skills/write-update-tidb-docs/SKILL.md
+++ b/.ai/skills/write-update-tidb-docs/SKILL.md
@@ -5,13 +5,16 @@ description: Write new TiDB documentation or update existing TiDB documentation
 
 # Write or Update TiDB Docs
 
-Use this skill when PM or R&D engineers provide engineering or product context
-and need it turned into user-facing TiDB documentation in `pingcap/docs`.
+Act as a senior documentation engineer. Turn engineering or product context into
+user-facing TiDB documentation in `pingcap/docs`.
 
-**Role**: Act as a senior documentation engineer who understands both the
-technical implementation and the user's information needs. Evaluate not just
-*what* to write, but *where* it belongs, *how* it connects to existing content,
-and *what style* fits the surrounding documentation.
+## Quick start
+
+1. Read this file to analyze the input and decide the action type.
+2. Load one reference file based on your decision:
+   - **Creating** a new page → read `ref-create-new-doc.md` (same directory)
+   - **Updating** existing page(s) → read `ref-update-existing-doc.md` (same directory)
+3. Follow that reference file's workflow end-to-end.
 
 ## Accepted inputs
 
@@ -24,248 +27,149 @@ and *what style* fits the surrounding documentation.
 | External reference | Blog post, conference talk notes, user feedback |
 | Rough notes | Bullets, chat messages, informal descriptions |
 | Existing docs | Current doc page that needs improvement |
-| Verbal description | Short sentences describing the feature or change |
 
-Multiple input types can be combined. The more context provided, the fewer
-questions needed.
+Multiple inputs can be combined. More context = fewer questions needed.
 
 ## Defaults
 
 - Inspect first, confirm when uncertain, then edit.
-- Prefer updating existing docs. Write a new page only when the change introduces
-  a distinct user task, feature, reference area, integration, or troubleshooting
-  workflow that does not fit cleanly in an existing page.
-- Documentation must justify its maintenance cost. Not every code change needs a
-  doc update.
-- English documentation in `pingcap/docs` is the primary output. Do not write
-  Chinese docs directly. If Chinese docs are also needed, finish the English doc
-  first, then use the `create-or-update-zh-translation-pr` skill.
-- If the user asks about local changes without naming files, run `git status -u`.
-  If there are no uncommitted changes and the user clearly wants the latest local
-  change, inspect `git show --name-status` and targeted diffs.
-
-## Load context progressively
-
-Always read first:
+- Prefer updating existing docs over creating new pages.
+- Not every code change needs a doc update. Documentation must justify its
+  maintenance cost.
+- English in `pingcap/docs` is the primary output. For Chinese docs, finish
+  English first, then use the `create-or-update-zh-translation-pr` skill.
+- If the user asks about local changes without naming files, start with
+  `git status -u` or `git show --name-status`.
+
+## Step 1: Load shared context
+
+Always read before making any doc changes:
 
 - `.ai/shared/repo-conventions.md`
 - `.ai/shared/writing-style.md`
 
-Read when relevant:
+Read only when relevant:
 
-- `.ai/shared/translation-rules.md` and `.ai/shared/translation-terms.md`when the task involves English-to-Chinese translation or Chinese documentation.
-- `resources/doc-templates/<template>.md` after choosing the doc type (see the create-new-doc reference).
-- `resources/terms.md` when terminology is uncertain.
+- `.ai/shared/translation-rules.md` — when translation is involved
+- `resources/terms.md` — when terminology is uncertain
 
-Before drafting, inspect nearby docs, related overview/reference pages, TOC
-entries, existing terminology, linked issues or PRs, and relevant code changes.
-Prefer existing structure and wording in the same documentation area.
+## Step 2: Analyze the input
 
-## Workflow overview
+### From a code PR
 
-### Phase 1: Analyze the input
+```bash
+gh pr view <PR-URL> --json title,body,labels,baseRefName,headRefName,files
+gh pr diff <PR-URL>
+```
 
-**When the input is a code PR URL or reference:**
+Scan for documentation-relevant patterns:
 
-1. Fetch the PR metadata and diff:
+| Code pattern | Likely doc impact |
+| --- | --- |
+| New/changed `SysVar` / `DefValue` | `system-variables.md` |
+| New/changed config field / `toml` tag | `*-configuration-file.md` |
+| New/changed command-line flag | `command-line-flags-for-*-configuration.md` |
+| New SQL statement or grammar change | `sql-statements/sql-statement-*.md` |
+| New built-in function | `functions-and-operators/` |
+| New `INFORMATION_SCHEMA` table | `information-schema/` |
+| New feature flag or experimental gate | Feature doc (new or existing) |
+| Changed default or compatibility | Relevant docs + possibly release notes |
 
-   ```bash
-   gh pr view <PR-URL> --json title,body,labels,baseRefName,headRefName,files
-   gh pr diff <PR-URL>
-   ```
+Focus on user-facing changes. Skip internal refactors that do not affect behavior.
 
-2. Read the PR description, linked issues, and any design doc references.
+### From a product spec, issue, or design doc
 
-3. Scan the diff for documentation-relevant changes:
+Extract:
 
-   | Code pattern | Likely doc impact |
-   | --- | --- |
-   | New/changed `SysVar` / `DefValue` | Update `system-variables.md` |
-   | New/changed config struct / `toml` tag | Update `*-configuration-file.md` |
-   | New/changed command-line flag | Update `command-line-flags-for-*-configuration.md` |
-   | New SQL statement or grammar change | New or updated `sql-statements/sql-statement-*.md` |
-   | New built-in function | Update `functions-and-operators/` docs |
-   | New `INFORMATION_SCHEMA` table | New doc under `information-schema/` |
-   | New metrics or alert rules | Update `grafana-*.md` or monitoring docs |
-   | New feature flag or experimental gate | New feature doc or update existing |
-   | Changed default or compatibility | Update relevant docs + possibly release notes |
-   | New API endpoint | Update or create API reference |
+1. What can users now do, configure, or observe that they could not before?
+2. Which components are affected?
+3. Which versions will include this?
+4. Any constraints, limitations, or compatibility concerns?
 
-4. If the code diff is large, focus on user-facing changes (exported APIs,
-   config, SQL grammar, error messages, system variables) and skip internal
-   refactors.
+### From rough notes or verbal description
 
-**When the input is a product spec, issue, or design doc:**
+Extract key user-facing facts. Ask focused questions only for facts that cannot
+be derived from code, tests, or existing docs.
 
-1. Identify the user-facing changes: what can users now do, configure, or observe
-   that they could not before?
-2. Identify the affected components: which TiDB component(s) does this touch?
-3. Determine version scope: which versions will include this change?
-4. Note any constraints, limitations, or compatibility concerns mentioned.
+## Step 3: Determine the target branch
 
-**When the input is rough notes or verbal description:**
+| Source context | Docs target branch |
+| --- | --- |
+| New development (default) | `master` |
+| Version-specific behavior | `release-X.Y` + `master` |
+| Cross-version change | `master` + `needs-cherry-pick-release-X.Y` labels |
+| `/tidb-cloud/` content | `release-8.5` |
+| `/ai/` content | `release-8.5` |
 
-1. Extract the key user-facing facts.
-2. Identify what information is missing and ask focused questions.
-3. Derive what you can from code, tests, config names, existing docs, and
-   related issues/PRs.
+When in doubt, target `master`.
 
-### Phase 2: Map to docs branch
+## Step 4: Decide — create new page or update existing
 
-| Source target branch | Docs target branch | Notes |
-| --- | --- | --- |
-| `master` | `master` | Default for new development |
-| `release-X.Y` | `release-X.Y` (if it exists) | Version-specific behavior |
-| Any, but user-facing across versions | `master` + cherry-pick labels | Use `needs-cherry-pick-release-X.Y` |
-| TiDB Cloud content (`/tidb-cloud/`) | `release-8.5` | Cloud docs branch |
-| AI content (`/ai/`) | `release-8.5` | AI docs branch |
+Ask these questions:
 
-When in doubt, target `master` and let the user decide about cherry-picks.
+1. Does this change have a natural home in an existing page?
+2. Would adding it to an existing page make that page too long or dilute its
+   focus?
+3. Does it introduce a distinct user task or feature that needs standalone
+   discoverability?
+4. Is there enough substance for a standalone page (≥3 meaningful sections)?
 
-### Phase 3: Plan with 5W1H
+| Answer | Action |
+| --- | --- |
+| Fits in existing page(s) | → Load `ref-update-existing-doc.md` |
+| Needs a new standalone page | → Load `ref-create-new-doc.md` |
+| New page + related updates to existing pages | → Load both; start with `ref-create-new-doc.md` |
 
-- **Who**: target readers, role, technical level, prior knowledge.
-- **What**: primary information vs. secondary details.
-- **Why**: user goal and product value, not only implementation change.
-- **When**: use cases, feature status, applicable versions, scenarios.
-- **Where**: target repo, target file(s), TOC location.
-- **How**: steps, SQL, commands, APIs, examples, expected output, limitations,
-  compatibility, validation.
+Then follow the loaded reference file's workflow from start to finish.
 
-### Phase 4: Decide — create new or update existing
+## Shared gotchas
 
-This is the key routing decision. Ask:
+These apply to both creating and updating:
 
-1. Does this feature/change have a natural home in an existing page?
-2. Is the existing page already covering this topic area?
-3. Would adding this content to an existing page make it unreasonably long or
-   confuse the page's current focus?
-4. Does this introduce a distinct user task or feature that deserves standalone
-   discoverability?
-
-| Decision | Action |
-| --- | --- |
-| Content fits in existing page(s) | → Read `ref-update-existing-doc.md` and follow its workflow |
-| Content needs a new standalone page | → Read `ref-create-new-doc.md` and follow its workflow |
-| Both (new page + updates to related pages) | → Read both references; start with the new page, then update related |
-
-### Phase 5: Triage priority
-
-When multiple docs need updating, prioritize:
-
-- **Critical**: breaking changes, changed defaults, compatibility changes,
-  security-relevant behavior, user-facing errors, new/changed public APIs.
-- **Important**: new features, configuration options, workflows, SQL behavior,
-  limitations, performance guidance, examples, TOC updates.
-- **Nice to have**: minor clarifications, comments for non-obvious logic.
-
-Skip or consolidate docs that only duplicate generated references without user
-context, describe obvious internal implementation, or document temporary behavior.
-
-### Phase 6: Write
-
-Follow `.ai/shared/writing-style.md` for all writing conventions. Key reminders:
-
-- Start with useful information directly. No preamble about what the doc will do.
-- Start task docs with the most common use case or shortest path to first
-  success.
-- Put conditions before instructions.
-- Explain placeholders and include expected output for commands, SQL, or APIs.
-- Keep code examples realistic and runnable when possible.
-- Define jargon on first use.
-- Preserve commands, SQL, API names, UI strings, config names, JSON fields,
-  outputs, and technical meaning unless factually wrong or confirmed changed.
-
-For doc-type-specific structure, see the appropriate reference file.
-
-### Phase 7: Validate
-
-1. Review against the plan: facts, user goal, doc type, scope, examples, links,
-   TOC impact, version scope, and maintainability.
-2. Run Markdown validation:
-
-   ```bash
-   ./scripts/markdownlint <changed-files>
-   ```
-
-3. Run link validation when adding or changing links, anchors, moved or renamed
-   files, aliases, or TOC entries.
-4. For procedural docs, mentally or actually test the steps, sample code, SQL,
-   expected output, and placeholders.
-5. For substantial docs, run a reader test: predict 5–10 realistic reader
-   questions, verify the doc answers them without hidden context, and fix gaps.
-6. If validation fails, fix the issue and repeat.
-
-## Reference files
-
-This skill includes two reference files for the detailed workflows:
-
-- `ref-create-new-doc.md` — complete guidance for creating new documentation
-  pages, including TOC placement, doc type selection, file naming, structure,
-  front matter, and co-authoring mode.
-- `ref-update-existing-doc.md` — complete guidance for updating existing pages,
-  including target identification, related doc assessment, style consistency,
-  cross-document impact, and common update patterns.
-
-Load the relevant reference file after Phase 4 determines the action type.
-
-## TiDB docs gotchas
-
-- Target `master` by default. Use release branches only for version-specific
-  behavior, compatibility changes, broken links in published docs, explicit user
-  requests, or the `/tidb-cloud/` and `/ai/` exceptions.
-- The `/tidb-cloud/` and `/ai/` folders are maintained only in `release-8.5`.
-  Update English only. Chinese content is AI-translated weekly.
-- New navigable pages always require `TOC.md` updates. Renamed or replaced pages
-  might need `aliases`.
-- TiDB Cloud docs use special branch and rendering rules. Check `CustomContent`
-  blocks before changing shared TiDB/TiDB Cloud content.
-- Do not silently broaden scope from a local fix into cross-file rewrites. Note
-  related updates and only make them when needed for correctness or navigation.
-- Preserve code samples, commands, SQL, config names, API fields, JSON, EBNF, and
-  UI strings unless the task requires changing them or they are clearly wrong.
-- For broad changes, group work by documentation area and use subagents or
-  parallel analysis when available, but review the final result holistically.
+- The `/tidb-cloud/` and `/ai/` folders live only in `release-8.5`. Update
+  English only; Chinese is AI-translated weekly.
+- Do not change `CustomContent` blocks without understanding platform-specific
+  rendering.
+- Do not silently broaden scope from a targeted fix into cross-file rewrites.
+- Preserve code samples, commands, SQL, config names, API fields, JSON, EBNF,
+  and UI strings unless the task requires changing them or they are clearly wrong.
 
 ## Coordinating with other skills
 
-| Scenario | Skill to use |
+| Need | Skill |
 | --- | --- |
-| Chinese translation needed after English doc is done | `create-or-update-zh-translation-pr` |
-| Code change also needs release notes | `write-review-translate-release-notes` |
-| English doc PR needs review | `review-doc-pr` |
-| Doc pages need `summary` front matter | `writing-doc-summaries` |
-
-Flag these needs to the user instead of silently switching skills.
-
-## Output templates
-
-**When proposing a plan before editing:**
-
-```markdown
-Target: <repo/branch/path>
-Source: <code PR URL, issue, spec, or other input>
-Change type: <update existing doc | write new page | both>
-Doc type: <task | concept | reference | new feature | troubleshooting | other>
-Outline: <short heading list>
-Related updates: <TOC, aliases, links, overview/reference/release notes>
-Validation: <checks to run>
-Reader test: <questions the doc should answer, for substantial docs>
-Open questions: <facts that need confirmation>
+| Chinese translation | `create-or-update-zh-translation-pr` |
+| Release notes | `write-review-translate-release-notes` |
+| Doc PR review | `review-doc-pr` |
+| Front matter `summary` | `writing-doc-summaries` |
+
+Flag these to the user instead of silently switching.
+
+## Output format
+
+**Plan (before editing):**
+
+```
+Target: <branch/path>
+Source: <PR URL, issue, spec, or description>
+Action: <create new page | update existing | both>
+Doc type: <task | concept | reference | new feature | troubleshooting>
+Outline: <heading list>
+Related updates: <TOC, links, overview, release notes>
+Open questions: <facts needing confirmation>
 ```
 
-**When reporting completed edits:**
+**Completion report:**
 
-```markdown
+```
 Changed files:
 - <path>: <what changed>
 
-Source: <link to the code PR, issue, or spec that motivated the change>
+Source: <link or description>
 
-Checks:
-- <command>: <result>
+Validation:
+- <check>: <result>
 
-Notes:
-- <key decisions, maintenance triggers, or unresolved engineering questions>
-- <whether Chinese translation or release notes are also needed>
+Follow-up:
+- <translation, release notes, or other needs>
 ```
diff --git a/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md b/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md
index 30e8e5f87f941..39219cdc58296 100644
--- a/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md
+++ b/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md
@@ -1,162 +1,131 @@
-# Reference: Create New TiDB Documentation
+# Create New TiDB Documentation
 
-This reference covers the full workflow for creating a new documentation page in
-`pingcap/docs`. Read this after the main SKILL.md has determined that a new page
-is needed.
+Self-contained workflow for creating a new documentation page in `pingcap/docs`.
+Follow these steps sequentially after SKILL.md has determined that a new page is
+needed.
 
-## When to create a new page
+## Confirm the decision to create
 
-Create a new page only when the change introduces content that does not fit
-cleanly in an existing page. Typical triggers:
+A new page is justified when all of these are true:
 
-- A distinct user-facing feature with its own usage scenarios, configuration,
-  and limitations (for example, a new index type, a new SQL statement, a new
-  tool mode).
-- A new integration, connector, or ecosystem tool that needs a standalone guide.
-- A new reference entity that follows an established pattern (for example, a new
-  `INFORMATION_SCHEMA` table, a new TiCDC sink type).
-- A troubleshooting workflow that is complex enough to justify its own page
-  rather than a section in an existing troubleshooting doc.
-- A new concept or architecture topic that supports multiple task or reference
-  pages.
+- The content does not fit cleanly as a section of an existing page.
+- There is enough substance for ≥3 meaningful sections.
+- The content has standalone discoverability value (users might search for it
+  directly).
 
-Do **not** create a new page when:
+Typical triggers: new feature with its own scenarios/config/limitations, new SQL
+statement, new `INFORMATION_SCHEMA` table, new integration/tool, new
+troubleshooting workflow.
 
-- The content can be added as a section or subsection of an existing page without
-  making that page unreasonably long.
-- The content duplicates information already available elsewhere.
-- The content is too thin to justify standalone maintenance (fewer than ~3
-  meaningful sections).
+Do **not** create a new page if:
 
-## Step 1: Choose the doc type and template
+- The content can be a section in an existing page without making it too long.
+- The content would be too thin (fewer than ~3 sections).
+- Similar content already exists and could be expanded instead.
 
-Match the user's information need to a doc type:
+## 1. Choose doc type and template
 
-| Doc type | User need | Template |
+| Doc type | User question it answers | Template to read |
 | --- | --- | --- |
-| New feature | "What is this, why should I use it, how do I use it?" | `resources/doc-templates/template-new-feature.md` |
+| New feature | "What is this? Why use it? How?" | `resources/doc-templates/template-new-feature.md` |
 | Task | "How do I do X step by step?" | `resources/doc-templates/template-task.md` |
 | Concept | "What is X and how does it work?" | `resources/doc-templates/template-concept.md` |
-| Reference | "What are the parameters, syntax, config options?" | `resources/doc-templates/template-reference.md` |
-| Troubleshooting | "Something is wrong, how do I fix it?" | `resources/doc-templates/template-troubleshooting.md` |
+| Reference | "What are the params/syntax/options?" | `resources/doc-templates/template-reference.md` |
+| Troubleshooting | "Something is wrong, how to fix?" | `resources/doc-templates/template-troubleshooting.md` |
 
-Read the selected template before drafting. Use the template as the structural
-skeleton; skip sections that do not apply rather than filling them with thin
-content.
+Read the selected template before drafting. Use it as a structural skeleton; skip
+sections that do not apply.
 
-For features that combine concept, usage, and reference (common in TiDB), prefer
-the **new feature** template and merge concept and reference into its sections.
-Split into multiple pages only when the content naturally exceeds ~1500 words per
-concern.
+For features combining concept + usage + reference (common in TiDB), use the
+**new feature** template. Split into multiple pages only when content naturally
+exceeds ~1500 words per concern.
 
-## Step 2: Choose the file path and name
+## 2. Choose file path and name
 
-Follow existing patterns in the same documentation area:
+Look at where similar docs live:
 
-- Check where similar docs live by inspecting the relevant TOC file and nearby
-  directory structure.
-- Use lowercase, hyphen-separated names: `feature-name.md`.
-- Keep names concise and stable. Avoid version numbers or overly specific wording
-  that would require renaming.
-- If the feature belongs to a component that has its own directory (for example,
-  `ticdc/`, `tiflash/`, `tiproxy/`, `dm/`), place the file in that directory.
-- If the feature is cross-component or general, place it at the repository root.
+```bash
+# Find peers in the TOC
+rg -n "<component>|<feature-keyword>" TOC*.md
 
-Examples:
+# Check existing directory structure
+ls <component-dir>/
+```
 
-| Feature | Good path | Why |
-| --- | --- | --- |
-| New TiCDC sink type | `ticdc/ticdc-sink-to-<target>.md` | Follows existing sink docs pattern |
-| New SQL statement | `sql-statements/sql-statement-<name>.md` | Follows SQL statement pattern |
-| New INFORMATION_SCHEMA table | `information-schema/information-schema-<name>.md` | Follows info schema pattern |
-| New general feature | `<feature-name>.md` at root | Matches other root-level features |
-| New TiFlash feature | `tiflash/<feature-name>.md` | Component directory |
+**Naming rules:**
+
+- Lowercase, hyphen-separated: `feature-name.md`
+- Concise and stable — avoid version numbers or overly specific wording
+- Follow existing patterns in the same area
+
+**Placement rules:**
+
+| Feature scope | Path |
+| --- | --- |
+| Component-specific (TiCDC, TiFlash, TiProxy, DM, BR) | `<component>/feature-name.md` |
+| SQL statement | `sql-statements/sql-statement-<name>.md` |
+| INFORMATION_SCHEMA table | `information-schema/information-schema-<name>.md` |
+| Function/operator | `functions-and-operators/<category>.md` |
+| Cross-component or general | Root: `feature-name.md` |
 
-## Step 3: Determine TOC placement
+## 3. Determine TOC placement
 
-Every new navigable page requires an entry in the appropriate TOC file.
+Every navigable page needs a TOC entry.
 
-### Identify the right TOC file
+### Which TOC file?
 
-| Content type | TOC file |
+| Content area | TOC file |
 | --- | --- |
 | TiDB Self-Managed (most common) | `TOC.md` |
-| AI, vector search, pytidb, MCP | `TOC-ai.md` |
-| Application development guides | `TOC-develop.md` |
+| AI / vector search / pytidb / MCP | `TOC-ai.md` |
+| App development guides | `TOC-develop.md` |
 | Best practices | `TOC-best-practices.md` |
-| API documentation | `TOC-api.md` |
+| API docs | `TOC-api.md` |
 | TiDB release notes | `TOC-tidb-releases.md` |
-| TiDB Cloud (Dedicated/general) | `TOC-tidb-cloud.md` |
-| TiDB Cloud Starter | `TOC-tidb-cloud-starter.md` |
-| TiDB Cloud Essential | `TOC-tidb-cloud-essential.md` |
-| TiDB Cloud Premium | `TOC-tidb-cloud-premium.md` |
+| TiDB Cloud general | `TOC-tidb-cloud.md` |
+| TiDB Cloud tier-specific | `TOC-tidb-cloud-starter.md` / `essential` / `premium` |
 | TiDB Cloud release notes | `TOC-tidb-cloud-releases.md` |
 
-### Find the right position
-
-1. Search the TOC for the relevant section or category:
-
-   ```bash
-   rg -n "<keyword>|<component>" TOC.md
-   ```
-
-2. Look at the neighboring entries. TOC entries follow logical grouping:
-   - Features of the same component are grouped together.
-   - Related features are adjacent (for example, all sink types under
-     "Create Changefeeds").
-   - Difficulty generally progresses from overview → getting started → usage →
-     reference → troubleshooting within each group.
-
-3. Position the new entry:
-   - If there is a clear peer group, add the entry adjacent to similar items.
-   - If it is the first of a new category, create a new section heading.
-   - If it is a sub-feature, nest it under the parent feature entry.
+### Where in the TOC?
 
-4. Use the correct indentation level (2 spaces per TOC level). The TOC format:
+1. Find the relevant section: `rg -n "<keyword>" TOC.md`
+2. Look at neighbors — TOC groups by component, then by complexity (overview →
+   getting started → usage → reference → troubleshooting).
+3. Place the entry adjacent to similar items at the correct nesting level.
 
-   ```markdown
-   - Category Name
-     - [Page Title](/path/to/file.md)
-     - [Another Page](/path/to/another.md)
-       - [Sub Page](/path/to/sub.md)
-   ```
+**Format** (2-space indent per level):
 
-### TOC title conventions
-
-- Use title case for TOC entries.
-- Keep TOC titles concise (typically 3–7 words).
-- Match the document H1 when possible, but shorten for TOC readability.
-- Do not include "TiDB" in the TOC title when the context already makes it
-  clear.
+```markdown
+- Category Name
+  - [Page Title](/path/to/file.md)
+  - [New Page Title](/path/to/new-file.md)
+    - [Sub Page](/path/to/sub.md)
+```
 
-## Step 4: Write front matter
+**TOC title**: title case, concise (3–7 words), match the doc H1 when feasible.
 
-Every new page needs front matter:
+## 4. Write front matter
 
 ```yaml
 ---
 title: <same as H1, title case, ≤59 characters>
-summary: <115–145 characters, starts with a verb, SEO-friendly, reader-focused>
+summary: <115–145 characters, verb-led, SEO-friendly>
 ---
 ```
 
-Rules:
-
-- The `title` must match the H1 heading exactly.
-- The `summary` must not start with special characters (`>`, `*`, `#`, `-`, `[`).
-- The `summary` should tell readers what they will learn or accomplish.
-- Do not add other metadata fields unless there is a specific reason (for
-  example, `aliases` for a page that replaces an older URL).
+- `title` must match the H1 exactly.
+- `summary` must not start with `>`, `*`, `#`, `-`, or `[`.
+- `summary` tells readers what they will learn or accomplish.
+- Add `aliases` only if replacing an older page URL.
 
-## Step 5: Draft the document
+## 5. Draft the document
 
-### General structure principles
+### Writing principles
 
-- Start with what users care about: what the feature does, why it matters, when
-  to use it.
-- Put conditions and prerequisites before instructions.
-- Include realistic, runnable examples where practical.
+- Start with what users care about — not internal background.
+- Put conditions before instructions.
 - Define jargon on first use.
+- Include realistic, runnable examples.
 - End with related resources or next steps.
 
 ### Structure by doc type
@@ -164,110 +133,132 @@ Rules:
 **New feature:**
 
 ```
-H1: Feature Name
-  Intro paragraph (what, why, when)
-H2: Usage scenarios
-H2: Prerequisites (optional)
-H2: Usage / Procedures
-  H3: Method 1 (recommended)
-  H3: Method 2
-H2: Parameter reference (if applicable)
-H2: Limitations
-H2: Compatibility
-H2: FAQ (optional)
-H2: More resources
+# Feature Name
+  Intro: what it does, why it matters, when to use it.
+
+## Use cases
+
+## Prerequisites (if needed)
+
+## How to use <feature>
+### Method 1: <name> (recommended)
+### Method 2: <name>
+
+## Parameter reference (if applicable)
+
+## Limitations
+
+## Compatibility
+
+## FAQ (if needed)
+
+## See also
 ```
 
 **Task:**
 
 ```
-H1: Task Title
-  Intro paragraph (what this doc helps you do)
-H2: Prerequisites
-H2: Step 1. <action>
-H2: Step 2. <action>
-H2: Step 3. <action>
-H2: What's next
+# Task Title
+  Intro: what this helps you accomplish.
+
+## Prerequisites
+
+## Step 1. <verb phrase>
+
+## Step 2. <verb phrase>
+
+## Step 3. <verb phrase>
+
+## What's next
 ```
 
 **Concept:**
 
 ```
-H1: Concept Title
-  Intro paragraph (what the concept is)
-H2: Architecture / Key components
-H2: How it works
-H2: Key features / Limitations
-H2: What's next
+# Concept Title
+  Intro: what this concept is and why it matters.
+
+## Architecture / How it works
+
+## Key features
+
+## Limitations (if applicable)
+
+## What's next
 ```
 
 **Reference:**
 
 ```
-H1: Reference Title
-  Intro paragraph (what this reference covers)
-H2: Category 1
-  H3: Parameter/item
-H2: Category 2
-  H3: Parameter/item
+# Reference Title
+  Intro: what this reference covers.
+
+## Category 1
+### Item / parameter
+
+## Category 2
+### Item / parameter
 ```
 
 **Troubleshooting:**
 
 ```
-H1: Troubleshoot <Problem>
-  Intro paragraph (what problems this doc covers)
-H2: Common causes
-  H3: Cause 1 (Symptom + Solution)
-  H3: Cause 2
-H2: Other causes
-  H3: Cause 3
-```
+# Troubleshoot <Problem>
+  Intro: what problems this covers.
 
-### Co-authoring mode for substantial docs
+## Common causes
+### Cause 1
+  Symptom → Solution
+### Cause 2
+
+## Other causes
+### Cause 3
+```
 
-For documents expected to exceed ~800 words or with unclear scope:
+### Co-authoring mode (for substantial docs)
 
-1. Propose the 3–5 core sections first and get confirmation.
-2. Start with the section that has the most unknowns or highest user value.
-3. Draft section by section, asking focused questions only for facts that cannot
-   be derived from code, tests, or existing docs.
-4. After drafting, run a reader test: predict 5–10 realistic reader questions and
-   verify the doc answers them.
-5. Ask whether anything can be removed without losing important information.
+When the doc is expected to exceed ~800 words or has unclear scope:
 
-## Step 6: Handle associated updates
+1. Propose 3–5 core sections. Get confirmation.
+2. Start with the highest-value or most-uncertain section.
+3. Draft section by section. Ask questions only when facts cannot be derived
+   from available sources.
+4. After drafting, run a reader test: predict 5–10 questions a real user would
+   ask. Verify the doc answers them.
+5. Ask: can anything be removed without losing value?
 
-Creating a new page often requires updates elsewhere:
+## 6. Handle associated updates
 
-| Check | Action |
+| Check | Action when needed |
 | --- | --- |
-| TOC entry added? | Required for all navigable pages |
-| Overview page mentions new feature? | Add a brief entry or link if the area has an overview |
-| Related docs link to new page? | Add "See also" or inline links where users would benefit |
-| `sql-statement-overview.md` updated? | Required for new SQL statements |
-| `functions-and-operators-overview.md` updated? | Required for new functions |
-| Release notes mention the feature? | Flag for release notes skill if applicable |
-| `system-variables.md` references new page? | If the feature has system variables |
-
-## Step 7: Validate
-
-1. Run `./scripts/markdownlint <new-file>` to catch formatting issues.
-2. Run `./scripts/verify-links.sh` if the new page has links or is linked from
-   other pages.
-3. Verify the TOC renders correctly (correct indentation, no orphaned entries).
-4. Check front matter: title matches H1, summary is 115–145 characters.
-5. Mentally test: can a user who finds this page via search complete their task
-   without hidden context?
-
-## Common mistakes to avoid
-
-- Creating a page that is too thin (only 1–2 short sections). Consider whether
-  the content fits as a section in an existing page.
-- Placing the TOC entry in the wrong file or nesting level.
-- Using a file name that duplicates or conflicts with existing names.
-- Writing an intro that describes what the document will do instead of starting
-  with useful information directly.
-- Skipping the overview/reference page updates that help users discover the new
-  page.
-- Forgetting to handle `aliases` when a new page replaces an older page.
+| TOC entry | Always required |
+| Overview page | Add brief mention or link (e.g., `sql-statement-overview.md`) |
+| Related docs | Add "See also" links where users benefit |
+| Release notes | Flag for the release notes skill |
+| System variable page | Cross-link if the feature has variables |
+| Compatibility page | Update if MySQL compat is affected |
+
+## 7. Validate
+
+```bash
+./scripts/markdownlint <new-file> <changed-toc-file>
+./scripts/verify-links.sh  # if links were added
+```
+
+Also check:
+
+- [ ] Front matter: title matches H1, summary is 115–145 chars
+- [ ] TOC: correct file, correct level, correct indentation
+- [ ] Heading levels: no skipped levels, exactly one H1
+- [ ] File name: lowercase, hyphen-separated, `.md` extension
+- [ ] A user finding this via search can complete their task without hidden
+      context
+
+## Common mistakes
+
+- Page too thin — should have been a section in an existing page.
+- TOC entry in wrong file or wrong nesting level.
+- Intro describes what the doc will do instead of starting with useful info.
+- Missing overview/reference page updates that help users discover the new page.
+- Forgetting `aliases` when replacing an older page.
+- Writing content that duplicates an existing page without adding new user value.
diff --git a/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md b/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md
index 65ff03628a4a4..f5c14acb1649f 100644
--- a/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md
+++ b/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md
@@ -1,315 +1,250 @@
-# Reference: Update Existing TiDB Documentation
+# Update Existing TiDB Documentation
 
-This reference covers the full workflow for updating existing documentation pages
-in `pingcap/docs`. Read this after the main SKILL.md has determined that one or
-more existing pages need updating.
+Self-contained workflow for updating existing documentation pages in
+`pingcap/docs`. Follow these steps sequentially after SKILL.md has determined
+that existing pages need updating.
 
-## When to update existing docs
+## 1. Identify target docs
 
-Update rather than create when:
+### From code patterns
 
-- A feature gains a new option, parameter, configuration item, or behavior mode
-  that fits in the existing page structure.
-- A default value, behavior, or limitation changes.
-- A system variable, config parameter, or command-line flag is added or modified.
-- A code change affects user-visible behavior documented on an existing page.
-- A compatibility or deprecation note needs to be added.
-- An existing page has outdated, incomplete, or incorrect information.
-
-Prefer targeted edits over broad rewrites. Change only the sections affected by
-the update unless the existing structure is clearly inadequate.
-
-## Step 1: Identify target docs from code changes
-
-Use the code change patterns to find which docs likely need updating:
-
-| Code pattern | Primary target doc(s) |
+| Code pattern | Primary target |
 | --- | --- |
-| New/changed `SysVar` / `DefValue` | `system-variables.md`, `system-variable-reference.md` |
-| New/changed config struct field / `toml` tag | `tidb-configuration-file.md`, `tikv-configuration-file.md`, `tiflash/tiflash-configuration.md`, `pd-configuration-file.md`, or equivalent |
+| New/changed `SysVar` / `DefValue` | `system-variables.md` |
+| New/changed config field / `toml` tag | `tidb-configuration-file.md` / `tikv-configuration-file.md` / `pd-configuration-file.md` / `tiflash/tiflash-configuration.md` |
 | New/changed command-line flag | `command-line-flags-for-*-configuration.md` |
 | Changed SQL grammar (parser `.y`) | `sql-statements/sql-statement-<name>.md` |
-| New/changed built-in function | `functions-and-operators/` relevant file |
-| New `INFORMATION_SCHEMA` table column | `information-schema/information-schema-<name>.md` |
-| Changed metric or alert rule | `grafana-*.md` or monitoring docs |
-| Changed default behavior | Feature doc + possibly release notes |
-| New error code or message | Error reference docs |
-| Changed API endpoint or response | API reference docs |
+| New/changed function | `functions-and-operators/` |
+| New INFORMATION_SCHEMA column | `information-schema/information-schema-<name>.md` |
+| Changed metric or alert | `grafana-*.md` or component monitoring docs |
+| Changed default/behavior | Feature doc + compatibility notes |
+| New error code | Error reference docs |
+| Changed API | API reference docs |
 
 ### Search strategies
 
-Find existing docs by keyword, feature name, or path:
-
 ```bash
-rg -l "<system-variable-name>|<config-name>|<feature-keyword>" --type md
+# Find docs mentioning the feature/config/variable
+rg -l "<name-or-keyword>" --type md
+
+# Find where it appears in TOC
 rg -n "<keyword>" TOC*.md
-```
 
-When the code change touches a specific component, also check the component's
-directory (`ticdc/`, `tiflash/`, `tiproxy/`, `dm/`, `br/`) for related docs.
+# Find docs that link to the target page
+rg -l "/path-to-target.md" --type md
+```
 
-## Step 2: Assess related and associated docs
+Also check component directories (`ticdc/`, `tiflash/`, `tiproxy/`, `dm/`,
+`br/`) when the change touches a specific component.
 
-A single code change often affects multiple documentation pages. Assess the full
-impact before editing:
+## 2. Assess related docs (impact radius)
 
-### Direct impact
+A single code change often ripples into multiple pages.
 
-Pages that directly describe the changed behavior:
+### Direct impact (update in the same edit)
 
-- The primary reference page (config file, system variables, command flags)
-- The feature or task page that explains how to use the behavior
+- The primary reference page (config file, system variables, flags)
+- The feature/task page describing how to use the changed behavior
 - The SQL statement page if syntax changed
 
-### Indirect impact
-
-Pages that reference or summarize the changed behavior:
-
-- **Overview pages**: pages that list or summarize features in a category (for
-  example, `functions-and-operators-overview.md`, `sql-statement-overview.md`)
-- **Compatibility pages**: `mysql-compatibility.md`, feature compatibility tables
-- **Limitation pages**: `tidb-limitations.md`, feature-specific limitations
-- **Release notes**: if the change is user-facing in a specific version
-- **FAQ pages**: if the change affects commonly asked questions
-- **Best practice pages**: if the change affects recommended workflows
-- **Troubleshooting pages**: if the change resolves or introduces known issues
+### Indirect impact (assess case by case)
 
-### Discovering related pages
-
-```bash
-# Find pages that mention the feature or config item
-rg -l "<feature-name>|<config-name>" --type md
-
-# Find pages that link to the target page
-rg -l "/path-to-target-doc.md" --type md
-
-# Check if the feature appears in overview or summary docs
-rg -l "<feature-keyword>" *-overview.md basic-features.md
-```
+| Category | Examples |
+| --- | --- |
+| Overview pages | `sql-statement-overview.md`, `functions-and-operators-overview.md` |
+| Feature lists | `basic-features.md` |
+| Compatibility | `mysql-compatibility.md`, feature compat tables |
+| Limitations | `tidb-limitations.md`, feature-specific limitations |
+| FAQ | Feature FAQ pages |
+| Best practices | Operational or schema best practices |
+| Troubleshooting | If the change resolves or introduces known issues |
+| Release notes | If user-facing in a specific version |
 
-### Scope discipline
+**Scope rule:**
 
-- Update direct-impact pages in the same edit.
-- For indirect-impact pages, assess whether the update is **required for
-  correctness** or merely **nice to have**.
-- If an indirect page update is required (for example, a limitation was removed
-  and the limitations page still lists it), include it.
-- If an indirect page update is nice to have (for example, an overview page could
-  mention the enhancement), flag it in the output notes but do not expand scope
-  unless the user confirms.
+- Direct-impact pages → update them.
+- Indirect pages where the current text would become **incorrect** → update them.
+- Indirect pages where the update is merely **nice to have** → flag in output
+  notes, do not expand scope without user confirmation.
 
-## Step 3: Understand the existing page before editing
+## 3. Read the existing page before editing
 
-Before making changes, read the target page (or relevant sections) to understand:
+Before touching a file, understand:
 
-1. **Existing structure**: heading hierarchy, section order, and content flow.
-2. **Existing tone and voice**: formal vs. conversational, level of detail,
-   whether the page uses imperative ("Configure X") or descriptive ("X is
-   configured by") style.
-3. **Existing patterns**: how similar items are documented on the same page. For
-   example, if system variables use a specific description format, follow it.
-4. **Existing terminology**: which terms the page uses for concepts. Do not
-   introduce synonyms or alternate terms.
-5. **Existing scope**: what the page covers and what it explicitly excludes. Do
-   not expand scope without reason.
+| Aspect | What to look for |
+| --- | --- |
+| Structure | Heading hierarchy, section order, content flow |
+| Voice | Terse vs. explanatory, imperative vs. descriptive |
+| Pattern | How similar items on this page are documented |
+| Terminology | Which terms are used — do not introduce synonyms |
+| Scope | What the page covers and explicitly excludes |
+| Sort order | Alphabetical, logical grouping, or chronological |
 
-Key principle: **the updated section should read as if it were written by the
-same author as the rest of the page**. Do not let new content stand out
-stylistically.
+**Key principle:** the updated section must read as if written by the same author
+as the rest of the page. New content should not stand out stylistically.
 
-## Step 4: Plan the edit
+## 4. Plan the edit
 
 For each target page, determine:
 
-- **Where** in the page the new content goes (which section, which position
-  within the section).
-- **What** to add, change, or remove.
-- **How much** surrounding context to preserve or adjust for flow.
+- **Where**: which section, which position within the section.
+- **What**: add, change, or remove.
+- **How much**: surrounding context to adjust for flow.
 
-### Placement within a page
+### Placement conventions
 
-Follow existing ordering conventions on the page:
-
-| Page type | Typical ordering |
+| Page type | Typical order |
 | --- | --- |
-| System variables | Alphabetical by variable name |
-| Config parameters | Grouped by section, then by related functionality |
-| SQL statement | Synopsis → Description → Examples → See also |
-| Function reference | Syntax → Parameters → Return type → Examples |
-| Feature page sections | Conceptual intro → Usage → Limitations → Compatibility |
-
-When adding a new item to a list or table:
+| System variables | Alphabetical by name |
+| Config parameters | Grouped by `[section]`, then by functionality |
+| SQL statement page | Synopsis → Description → Examples → See also |
+| Function reference | Syntax → Parameters → Return → Examples |
+| Feature page | Intro → Usage → Limitations → Compatibility |
 
-- Insert in the correct sort order (alphabetical, logical grouping, or as
-  established by neighbors).
-- Match the existing column structure and description style exactly.
-- Do not reorder existing items unless correcting a clear sorting error.
+When adding a new item to a list, table, or parameter section:
 
-### Handling additions vs. modifications
+- Insert in the correct sort position.
+- Match the existing format exactly (fields, punctuation, backticks, spacing).
+- Do not reorder existing items unless fixing a clear sorting error.
 
-**Adding new content** (new parameter, new section, new example):
+## 5. Write — match style and format
 
-- Follow the format of adjacent entries.
-- If adding a new section, maintain heading level hierarchy—do not skip levels.
-- Add transitional context if needed so the addition flows with surroundings.
-
-**Modifying existing content** (changed default, updated behavior):
-
-- Change only the specific facts that are wrong or outdated.
-- Preserve the sentence structure and style when possible.
-- If the behavioral change is breaking, add a version note or warning.
-- Update any version-specific statements (for example, "Starting from v8.4" →
-  adjust the version scope).
-
-**Removing content** (deprecated feature, removed limitation):
-
-- Remove cleanly without leaving orphaned references or broken flow.
-- Check if other parts of the same page reference the removed content.
-- If the removal is for a deprecated feature, consider adding a deprecation note
-  instead of deleting entirely.
+### Match the entry format
 
-## Step 5: Maintain style consistency
+Study 2–3 neighboring entries on the same page and replicate their pattern.
 
-### Match the existing description format
-
-For structured reference docs (system variables, config files), each entry
-typically follows a pattern. Examples:
-
-**System variable entry pattern:**
+**System variable entry example:**
 
 ```markdown
 ### variable_name
 
-- Scope: SESSION | GLOBAL | SESSION | GLOBAL, SESSION
-- Persists to cluster: Yes | No
-- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): Yes | No
-- Type: Boolean | Integer | Enum | ...
-- Default value: `<value>`
-- Range: `[min, max]` (for numeric types)
+- Scope: SESSION | GLOBAL
+- Persists to cluster: Yes
+- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No
+- Type: Integer
+- Default value: `100`
+- Range: `[0, 10000]`
 - This variable controls ...
 ```
 
-**Config parameter entry pattern:**
+**Config parameter entry example:**
 
 ```markdown
 ### `parameter-name`
 
-- Default value: `<value>`
-- Range: ... (if applicable)
-- Description text explaining what the parameter controls.
+- Default value: `value`
+- Range: `[min, max]`
+- Description explaining what the parameter controls.
 ```
 
-When adding new entries, replicate the exact format including field order,
-punctuation, backtick usage, and description style.
+New entries must follow the identical field order, punctuation, and detail level.
 
-### Preserve voice and level of detail
+### Match voice and depth
 
-- If the page uses terse descriptions, keep new content terse.
-- If the page uses full explanatory paragraphs, write comparably.
-- If the page includes examples for each item, add an example for new items.
-- If the page does not include examples, do not add one only for the new item
-  unless it significantly aids understanding.
+- If the page uses terse descriptions → keep new content terse.
+- If the page writes full paragraphs → write comparably.
+- If the page includes examples for each item → add an example.
+- If the page omits examples → do not add one only for the new item unless
+  critical for understanding.
 
 ### Version annotations
 
-When a change is version-specific:
+For version-specific changes, use the established format on the page:
 
-- Use the established format: "Starting from vX.Y, ..." or "This variable was
-  introduced in vX.Y."
-- Place version notes consistently with how they appear elsewhere on the page.
-- For behavior changes, clearly state both the old and new behavior when helpful.
+- "Starting from vX.Y, ..." or "This variable was introduced in vX.Y."
+- For behavior changes, state both old and new behavior when helpful.
+- Ensure version notes are accurate for the target branch.
 
-## Step 6: Handle cross-document consistency
+### Additions vs. modifications vs. removals
 
-After editing, verify that related docs remain consistent:
+**Adding** (new param, new section, new example):
 
-1. **Same facts in multiple places**: if the same default value, limitation, or
-   behavior appears in multiple docs, update all of them.
-2. **Links still valid**: if you change a heading, check whether other docs link
-   to that anchor.
-3. **Feature lists and overviews**: if a feature gains new capabilities,
-   check whether summary pages need updating.
-4. **Compatibility tables**: if behavior changes for MySQL compatibility,
-   `mysql-compatibility.md` may need updating.
-5. **Code examples**: if a default changes, examples that rely on the old default
-   may produce different output.
+- Follow the format of adjacent entries.
+- Maintain heading level hierarchy.
+- Add transitional context if needed for flow.
 
-## Step 7: Handle version and branch scoping
+**Modifying** (changed default, updated behavior):
 
-Decide which branches the update targets:
+- Change only the specific facts that changed.
+- Preserve sentence structure and style when possible.
+- Add a version note if the change is version-specific.
+- If breaking, add a warning.
 
-| Change type | Target branch |
-| --- | --- |
-| New feature in development | `master` only |
-| Behavior change in released version | `master` + cherry-pick label for the release branch |
-| Bug fix in documentation (factual error) | `master` + cherry-pick label if error exists in release branch |
-| TiDB Cloud documentation | `release-8.5` |
-| AI / vector documentation | `release-8.5` |
-| Wording improvement not tied to a version | `master` only |
-
-When the update includes version-specific notes, ensure the phrasing is accurate
-for the target branch. A note saying "Starting from v8.5" makes sense in
-`master` and `release-8.5` but not in `release-8.4`.
-
-## Step 8: Validate
-
-1. Run `./scripts/markdownlint <changed-files>` to catch formatting issues.
-2. If headings changed, run `./scripts/verify-links.sh` to detect broken anchors.
-3. Re-read the changed section in context (at least 2–3 surrounding sections) to
-   verify it reads naturally and consistently.
-4. Verify facts against the source (code PR, issue, design doc).
-5. For procedural docs, mentally trace the steps with the new information.
-6. Check that no orphaned references remain if content was removed or moved.
+**Removing** (deprecated feature, removed limitation):
+
+- Remove cleanly; check for orphaned references on the same page.
+- For deprecated features, add a deprecation note rather than deleting docs for
+  still-functional features.
+- Link to the replacement or migration path.
+
+## 6. Verify cross-document consistency
+
+After editing, check:
+
+- [ ] Same fact appears in multiple docs → all updated?
+- [ ] Changed a heading → anchors/links from other docs still valid?
+- [ ] Feature gained capabilities → summary/overview pages still accurate?
+- [ ] Behavior changed for MySQL compat → `mysql-compatibility.md` updated?
+- [ ] Default changed → examples relying on old default still correct?
+- [ ] Removed content → no orphaned cross-references remain?
+
+## 7. Validate
+
+```bash
+./scripts/markdownlint <changed-files>
+./scripts/verify-links.sh  # if headings/anchors/links changed
+```
+
+Also:
+
+- [ ] Re-read the changed section with 2–3 surrounding sections — does it flow
+      naturally?
+- [ ] Facts match the source (code PR, issue, spec)?
+- [ ] For procedural content, mentally trace the steps with the new info.
+- [ ] No style discontinuity between new and existing content.
 
 ## Common update patterns
 
-### Adding a new system variable
+### New system variable
 
-1. Add the entry in `system-variables.md` in alphabetical order following the
-   existing entry format.
-2. If the variable is referenced in `system-variable-reference.md`, add it there
-   too.
-3. Check if the feature page that uses this variable should mention it.
-4. If the variable controls a new feature, the feature doc takes priority; the
+1. Add entry in `system-variables.md` in alphabetical order, matching format.
+2. Add to `system-variable-reference.md` if applicable.
+3. Update the feature page to mention the variable.
+4. If the variable controls a new feature, the feature doc is primary; the
    variable entry should link to it.
 
-### Adding a new config parameter
+### New config parameter
 
-1. Add the entry in the corresponding `*-configuration-file.md` under the
-   correct `[section]`.
-2. Follow the exact format of neighboring entries.
-3. If the parameter has a corresponding command-line flag, update the flag doc
-   too.
+1. Add entry in `*-configuration-file.md` under the correct `[section]`.
+2. Match the exact format of neighbors.
+3. If there is a corresponding CLI flag, update the flag doc too.
 
-### Updating default values or behavior
+### Changed default value
 
-1. Change the default value in the parameter/variable description.
-2. Add a version note if the change is version-specific.
-3. Check if examples elsewhere on the page (or in other docs) assume the old
-   default.
-4. If the change is breaking, add a compatibility or warning note.
+1. Change the value in the parameter/variable description.
+2. Add version note ("Starting from vX.Y, the default value changes to ...").
+3. Check if examples elsewhere assume the old default.
+4. If breaking, add a compatibility/warning note.
 
-### Adding a limitation or removing a limitation
+### Removed limitation
 
-1. Update the limitations section of the feature doc.
-2. If the limitation affects `tidb-limitations.md`, update that page too.
-3. If a limitation is removed, check whether workaround documentation should also
-   be removed or marked as no longer necessary.
+1. Update the feature doc's limitations section.
+2. Update `tidb-limitations.md` if listed there.
+3. Remove or mark as unnecessary any workaround documentation.
 
-### Documenting a deprecation
+### Deprecation
 
-1. Add a deprecation notice in the relevant section with the version it was
-   deprecated and expected removal timeline.
-2. Update any "recommended" guidance that points users to the deprecated feature.
-3. Link to the replacement feature or migration path.
-4. Do not delete documentation for deprecated features that are still functional.
+1. Add deprecation notice with version and expected removal timeline.
+2. Update "recommended" guidance that points to the deprecated feature.
+3. Link to the replacement.
+4. Keep documentation for still-functional deprecated features.
 
-## Common mistakes to avoid
+## Common mistakes
 
-- Changing only one occurrence of a fact that appears in multiple places.
-- Breaking the style or format consistency with surrounding entries.
-- Expanding scope into unrelated improvements while making a targeted fix.
-- Adding version notes that are inaccurate for the target branch.
-- Leaving orphaned cross-references when removing or moving content.
-- Introducing different terminology for the same concept within one page.
-- Rewriting surrounding content unnecessarily while making a targeted edit.
+- Updating one occurrence but missing the same fact in other docs.
+- Breaking format/style consistency with surrounding entries.
+- Expanding scope into unrelated improvements.
+- Adding version notes inaccurate for the target branch.
+- Leaving orphaned references when removing content.
+- Introducing new terminology that conflicts with existing usage on the page.
+- Rewriting surrounding text unnecessarily while making a targeted edit.

From bd3eaab196fb55c4f00d5d95a17ede880a69f7d3 Mon Sep 17 00:00:00 2001
From: qiancai <qqzczy@126.com>
Date: Thu, 18 Jun 2026 18:38:56 +0800
Subject: [PATCH 5/6] Update SKILL.md

---
 .ai/skills/write-update-tidb-docs/SKILL.md | 25 +++++++++-------------
 1 file changed, 10 insertions(+), 15 deletions(-)

diff --git a/.ai/skills/write-update-tidb-docs/SKILL.md b/.ai/skills/write-update-tidb-docs/SKILL.md
index 5516fd9023de7..5158703ac9cbc 100644
--- a/.ai/skills/write-update-tidb-docs/SKILL.md
+++ b/.ai/skills/write-update-tidb-docs/SKILL.md
@@ -5,8 +5,7 @@ description: Write new TiDB documentation or update existing TiDB documentation
 
 # Write or Update TiDB Docs
 
-Act as a senior documentation engineer. Turn engineering or product context into
-user-facing TiDB documentation in `pingcap/docs`.
+Act as a senior technical writer who has profound knowledge of TiDB. You task is write or update user-facing TiDB documentation in `pingcap/docs` based on code changes, PRs, issues, design docs, product specs, rough drafts, existing docs, or short feature descriptions.
 
 ## Quick start
 
@@ -116,8 +115,8 @@ Ask these questions:
 
 | Answer | Action |
 | --- | --- |
-| Fits in existing page(s) | → Load `ref-update-existing-doc.md` |
-| Needs a new standalone page | → Load `ref-create-new-doc.md` |
+| Fits in existing page(s) | → Load `ref-update-existing-doc.md` and refer to it to update the existing page(s) |
+| Needs a new standalone page | → Load `ref-create-new-doc.md` and refer to it to create a new standalone page |
 | New page + related updates to existing pages | → Load both; start with `ref-create-new-doc.md` |
 
 Then follow the loaded reference file's workflow from start to finish.
@@ -126,24 +125,20 @@ Then follow the loaded reference file's workflow from start to finish.
 
 These apply to both creating and updating:
 
-- The `/tidb-cloud/` and `/ai/` folders live only in `release-8.5`. Update
-  English only; Chinese is AI-translated weekly.
-- Do not change `CustomContent` blocks without understanding platform-specific
-  rendering.
+- The `/tidb-cloud/` and `/ai/` folders live only in `release-8.5`. Update English documentation only (which means content only in the pingcap/docs repository); Chinese documentation is AI-translated weekly.
+- Do not change `CustomContent` blocks without understanding platform-specific rendering.
 - Do not silently broaden scope from a targeted fix into cross-file rewrites.
 - Preserve code samples, commands, SQL, config names, API fields, JSON, EBNF,
   and UI strings unless the task requires changing them or they are clearly wrong.
 
 ## Coordinating with other skills
 
-| Need | Skill |
+| Task | Skill |
 | --- | --- |
-| Chinese translation | `create-or-update-zh-translation-pr` |
-| Release notes | `write-review-translate-release-notes` |
-| Doc PR review | `review-doc-pr` |
-| Front matter `summary` | `writing-doc-summaries` |
-
-Flag these to the user instead of silently switching.
+| Translate English documentation to Chinese | `create-or-update-zh-translation-pr` |
+| Review and update release notes | `write-review-translate-release-notes` |
+| Review and update documentation PR | `review-doc-pr` |
+| Update `summary` front matter | `writing-doc-summaries` |
 
 ## Output format
 

From 3530080145277be6bff7bdaf09920aa360985bd3 Mon Sep 17 00:00:00 2001
From: qiancai <qqzczy@126.com>
Date: Thu, 18 Jun 2026 19:07:46 +0800
Subject: [PATCH 6/6] enhance the skill for grounding every fact in the source

---
 .ai/skills/write-update-tidb-docs/SKILL.md    | 64 ++++++++++++++-----
 .../ref-create-new-doc.md                     | 12 ++--
 .../ref-update-existing-doc.md                |  2 +
 3 files changed, 57 insertions(+), 21 deletions(-)

diff --git a/.ai/skills/write-update-tidb-docs/SKILL.md b/.ai/skills/write-update-tidb-docs/SKILL.md
index 5158703ac9cbc..00f464555ac15 100644
--- a/.ai/skills/write-update-tidb-docs/SKILL.md
+++ b/.ai/skills/write-update-tidb-docs/SKILL.md
@@ -5,15 +5,27 @@ description: Write new TiDB documentation or update existing TiDB documentation
 
 # Write or Update TiDB Docs
 
-Act as a senior technical writer who has profound knowledge of TiDB. You task is write or update user-facing TiDB documentation in `pingcap/docs` based on code changes, PRs, issues, design docs, product specs, rough drafts, existing docs, or short feature descriptions.
+Act as a senior technical writer who has profound knowledge of TiDB. Your task is to write or update user-facing TiDB documentation in `pingcap/docs` based on code changes, PRs, issues, design docs, product specs, rough drafts, existing docs, or short feature descriptions.
 
 ## Quick start
 
-1. Read this file to analyze the input and decide the action type.
-2. Load one reference file based on your decision:
+This is an overview of the full workflow below — the create-vs-update decision is made in Step 4, not before.
+
+1. Load shared context (Step 1).
+2. Analyze the input and determine the target branch (Steps 2–3).
+3. Decide create vs. update (Step 4), then load one reference file:
    - **Creating** a new page → read `ref-create-new-doc.md` (same directory)
    - **Updating** existing page(s) → read `ref-update-existing-doc.md` (same directory)
-3. Follow that reference file's workflow end-to-end.
+4. Follow that reference file's workflow end-to-end.
+
+## Ground every fact in the source
+
+Documentation generated from code fails most often by being well-formatted but factually wrong. Before writing any specific value, follow these rules:
+
+- Every concrete fact — default value, range, type, scope, version number, behavior, error message, syntax — must be traceable to an authoritative source: the PR diff, the code, tests, or an existing doc.
+- Never infer or invent a value because it "looks reasonable." A plausible-but-wrong default is worse than an acknowledged gap.
+- If a fact cannot be derived from the available sources, insert a clearly marked placeholder (for example, `<!-- TODO: confirm default -->`) and list it under **Open questions** in the plan, rather than guessing.
+- When the source and an existing doc disagree, note the conflict under **Open questions** in the plan instead of silently picking one.
 
 ## Accepted inputs
 
@@ -61,16 +73,16 @@ gh pr view <PR-URL> --json title,body,labels,baseRefName,headRefName,files
 gh pr diff <PR-URL>
 ```
 
-Scan for documentation-relevant patterns:
+Scan for documentation-relevant patterns. This table is for **triage** — deciding whether docs are affected and which area. For the exact target-file mapping with specific file paths, see `ref-update-existing-doc.md`.
 
-| Code pattern | Likely doc impact |
+| Code pattern | Likely doc area |
 | --- | --- |
-| New/changed `SysVar` / `DefValue` | `system-variables.md` |
-| New/changed config field / `toml` tag | `*-configuration-file.md` |
-| New/changed command-line flag | `command-line-flags-for-*-configuration.md` |
-| New SQL statement or grammar change | `sql-statements/sql-statement-*.md` |
-| New built-in function | `functions-and-operators/` |
-| New `INFORMATION_SCHEMA` table | `information-schema/` |
+| New/changed `SysVar` / `DefValue` | System variables |
+| New/changed config field / `toml` tag | Configuration files |
+| New/changed command-line flag | Command-line flags |
+| New SQL statement or grammar change | SQL statements |
+| New built-in function | Functions and operators |
+| New `INFORMATION_SCHEMA` table | Information schema |
 | New feature flag or experimental gate | Feature doc (new or existing) |
 | Changed default or compatibility | Relevant docs + possibly release notes |
 
@@ -90,17 +102,27 @@ Extract:
 Extract key user-facing facts. Ask focused questions only for facts that cannot
 be derived from code, tests, or existing docs.
 
-## Step 3: Determine the target branch
+## Step 3: Determine the target branch and version
+
+### Target branch
 
 | Source context | Docs target branch |
 | --- | --- |
-| New development (default) | `master` |
-| Version-specific behavior | `release-X.Y` + `master` |
-| Cross-version change | `master` + `needs-cherry-pick-release-X.Y` labels |
+| New development (default) | `master` only |
+| Version-specific behavior across maintained versions | `master` + `needs-cherry-pick-release-X.Y` labels |
 | `/tidb-cloud/` content | `release-8.5` |
 | `/ai/` content | `release-8.5` |
 
-When in doubt, target `master`.
+Follow the repository's cherry-pick model (see `.ai/shared/repo-conventions.md`): default to a single PR on the latest applicable branch (usually `master`) and rely on cherry-pick labels for other maintained versions, rather than opening parallel PRs per branch. When in doubt, target `master`.
+
+### Version number for "Starting from vX.Y" notes
+
+Many entries need a precise version (for example, "This variable was introduced in vX.Y"). Determine it from the source — do not guess:
+
+- Code PR: derive from the PR milestone, the target release branch, or the next unreleased version on `master`.
+- Spec/issue/design doc: use the stated target version.
+
+If the version cannot be determined from the source, mark it with a placeholder and list it under **Open questions** instead of inventing a number.
 
 ## Step 4: Decide — create new page or update existing
 
@@ -131,6 +153,14 @@ These apply to both creating and updating:
 - Preserve code samples, commands, SQL, config names, API fields, JSON, EBNF,
   and UI strings unless the task requires changing them or they are clearly wrong.
 
+## Where this skill stops
+
+This skill produces **local edits + validation + a completion report**. It does not create branches, commit, push, or open a PR on its own.
+
+- After editing and validating, report the changed files and follow-ups, then stop.
+- Create a branch, commit, or open a PR only when the user explicitly asks, or hand off to the workflow the user prefers.
+- Chinese translation, release notes, and PR creation are separate steps — flag them as follow-ups (see **Coordinating with other skills**) rather than doing them inline.
+
 ## Coordinating with other skills
 
 | Task | Skill |
diff --git a/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md b/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md
index 39219cdc58296..bfe55e993fabf 100644
--- a/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md
+++ b/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md
@@ -6,6 +6,8 @@ needed.
 
 ## Confirm the decision to create
 
+This is a final sanity re-check of the create-vs-update decision already made in `SKILL.md` Step 4 (the authoritative decision point) — not a second, independent decision. If any criterion below fails, switch to `ref-update-existing-doc.md`.
+
 A new page is justified when all of these are true:
 
 - The content does not fit cleanly as a section of an existing page.
@@ -108,14 +110,16 @@ Every navigable page needs a TOC entry.
 
 ```yaml
 ---
-title: <same as H1, title case, ≤59 characters>
-summary: <115–145 characters, verb-led, SEO-friendly>
+title: <same as H1, title case>
+summary: <verb-led, SEO-friendly sentence>
 ---
 ```
 
-- `title` must match the H1 exactly.
+- `title` must match the H1 exactly, in title case, and stay within ~59 characters.
 - `summary` must not start with `>`, `*`, `#`, `-`, or `[`.
 - `summary` tells readers what they will learn or accomplish.
+- For exact `summary` length rules and verb guidance, follow the `writing-doc-summaries` skill (target 115–145 characters, 45-character absolute minimum).
+- SQL statement reference pages use a fixed template defined in the `writing-doc-summaries` skill that falls below 115 characters — that is expected.
 - Add `aliases` only if replacing an older page URL.
 
 ## 5. Draft the document
@@ -247,7 +251,7 @@ When the doc is expected to exceed ~800 words or has unclear scope:
 
 Also check:
 
-- [ ] Front matter: title matches H1, summary is 115–145 chars
+- [ ] Front matter: title matches H1; summary follows `writing-doc-summaries` length rules (115–145 chars target, ≥45 chars)
 - [ ] TOC: correct file, correct level, correct indentation
 - [ ] Heading levels: no skipped levels, exactly one H1
 - [ ] File name: lowercase, hyphen-separated, `.md` extension
diff --git a/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md b/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md
index f5c14acb1649f..396109629b1b6 100644
--- a/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md
+++ b/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md
@@ -8,6 +8,8 @@ that existing pages need updating.
 
 ### From code patterns
 
+This is the authoritative code-pattern → target-file mapping. It expands the triage table in `SKILL.md` with exact file paths.
+
 | Code pattern | Primary target |
 | --- | --- |
 | New/changed `SysVar` / `DefValue` | `system-variables.md` |