docs: add write-update-tidb-docs skill

.ai/AI-README.md

@@ -24,6 +24,8 @@ Use `resources/terms.md` when terminology is uncertain or not covered by the qui
 - `.ai/skills/review-doc-pr/`: review documentation PRs and Markdown diffs for factual accuracy, user usefulness, completeness, version fit, related-doc impact, links, and style
 - `.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, 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`)
 - `.ai/skills/write-review-translate-release-notes/`: write, review, revise, and translate TiDB release note entries for the Feature details/Features, Compatibility changes, Improvements, and Bug fixes sections in English and Chinese
 - `.ai/skills/docs-pr-metadata-guard/`: guard PR template structure when creating or editing pull requests, such as version checkboxes, required sections, HTML comments, related-link fields, and cherry-pick conventions
 - `.ai/skills/docs-issue-metadata-guard/`: guard issue template structure when creating or editing issues, such as template selection, required fields, scope boundaries, and label hygiene

.ai/skills/write-update-tidb-docs/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: write-update-tidb-docs
+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
+
+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
+
+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)
+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
+
+| 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 |
+
+Multiple inputs can be combined. More context = fewer questions needed.
+
+## Defaults
+
+- Inspect first, confirm when uncertain, then edit.
+- 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 only when relevant:
+
+- `.ai/shared/translation-rules.md` — when translation is involved
+- `resources/terms.md` — when terminology is uncertain
+
+## Step 2: Analyze the input
+
+### From a code PR
+
+```bash
+gh pr view <PR-URL> --json title,body,labels,baseRefName,headRefName,files
+gh pr diff <PR-URL>
+```
+
+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 area |
+| --- | --- |
+| 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 |
+
+Focus on user-facing changes. Skip internal refactors that do not affect behavior.
+
+### From a product spec, issue, or design doc
+
+Extract:
+
+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?
+
+### From rough notes or verbal description
+
+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 and version
+
+### Target branch
+
+| Source context | Docs target branch |
+| --- | --- |
+| 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` |
+
+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
+
+Ask these questions:
+
+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)?
+
+| Answer | Action |
+| --- | --- |
+| 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.
+
+## Shared gotchas
+
+These apply to both creating and updating:
+
+- 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.
+
+## 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 |
+| --- | --- |
+| 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
+
+**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>
+```
+
+**Completion report:**
+
+```
+Changed files:
+- <path>: <what changed>
+
+Source: <link or description>
+
+Validation:
+- <check>: <result>
+
+Follow-up:
+- <translation, release notes, or other needs>
+```