docs: add repo AI guidance and skills (#22581)

Author: qiancai

.ai/AI-README.md

@@ -0,0 +1,43 @@
+# AI Collaboration Guide
+
+This directory stores repo-local guidance for AI agents working in `pingcap/docs`.
+
+## Structure
+
+- `.ai/shared/`: reusable repo policy, writing guidance, and translation guidance
+- `.ai/skills/`: workflow-specific instructions for recurring tasks in this repo
+
+## Shared guidance
+
+Read only the files that apply to the task:
+
+- `.ai/shared/repo-conventions.md`: repository scope, branch rules, file naming, TOC expectations, TiDB Cloud boundaries, and validation habits
+- `.ai/shared/writing-style.md`: document structure, wording, formatting, headings, front matter, and repo-compatible writing style
+- `.ai/shared/translation-rules.md`: EN -> ZH translation constraints, traceability, structure preservation, and workflow expectations
+- `.ai/shared/translation-terms.md`: quick terminology reference for frequent translation terms
+
+Use `resources/terms.md` when terminology is uncertain or not covered by the quick reference.
+
+## Current skills
+
+- `.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
+
+The translation skill includes bundled scripts under `.ai/skills/create-or-update-zh-translation-pr/scripts/` for:
+
+- preparing structured translation inputs from a source PR
+- preparing structured translation inputs from either a full source PR or an update commit range
+- creating or reusing the translation branch
+- applying high-confidence deterministic updates before AI editing
+- committing, pushing, and creating or updating the PR with `gh`
+
+## How to use it
+
+Use progressive loading so the task stays grounded but efficient:
+
+1. Start with the relevant shared guidance.
+2. Load a skill only when the task matches that workflow.
+3. If the selected skill includes bundled scripts, prefer the scripts over retyping ad hoc commands.
+4. Validate the files you changed with the repo's existing checks when practical.
+
+Keep the task grounded in the existing repository rules, templates, scripts, and workflows.

.ai/shared/repo-conventions.md

@@ -0,0 +1,116 @@
+# Repo Conventions
+
+This file captures the repository-specific rules that agents should follow in `pingcap/docs`.
+
+## Repository scope
+
+- `pingcap/docs` stores the English TiDB documentation source.
+- `pingcap/docs-cn` stores the Chinese documentation source.
+- This repository is the source for the English TiDB documentation published on the PingCAP documentation website.
+- TiDB documentation and TiDB Cloud documentation do not always follow the same maintenance model. Do not assume they use the same branch, scope, or publication rules.
+
+## Repository versions and branches
+
+- The `master` branch tracks the latest development version of TiDB documentation.
+- Published TiDB documentation is maintained in the corresponding `release-<version>` branches.
+- Archived documentation is no longer maintained and should not receive normal documentation updates.
+- By default, target `master` unless the change clearly belongs to a maintained release branch.
+- Preserve branch intent. Do not treat release-branch behavior as the default development behavior, and do not move dev-only content into release branches.
+
+## Choosing affected versions
+
+Follow the repository's affected-version model when proposing or reviewing changes.
+
+- By default, affected versions should be `master` only for documentation enhancements, missing-content additions, wording fixes, refactors within a topic, and general corrections that are not tied to a specific released behavior.
+- Choose the affected release branch or branches together with `master` when the change involves version-specific behavior, compatibility changes, changed default values, changed system variable behavior, display fixes, or broken-link fixes in published docs.
+- If a change applies to multiple maintained versions, prefer the latest applicable branch and use cherry-pick labels instead of opening parallel PRs by default.
+- If most of the change can be cherry-picked but some branches require different wording or follow-up edits, account for version-specific follow-up work and the relevant reminder labels.
+
+## Cherry-pick and branch-follow-up conventions
+
+- Use the repository's cherry-pick label workflow instead of inventing a custom multi-branch process.
+- If a change applies only to one documentation version, use that branch directly and do not add unnecessary cherry-pick labels.
+- If a change applies to multiple documentation versions, prefer a single PR on the latest applicable branch and rely on cherry-pick labels for the remaining maintained versions.
+- If branch-specific differences are expected, flag that clearly so reviewers know follow-up edits are required in the cherry-picked PRs.
+
+## Repository layout and navigation
+
+- Use the existing repository structure and nearby documents as the primary guide for where new content should live.
+- New navigable documents usually require a matching update in the appropriate `TOC.md` file.
+- When a document is added, removed, moved, or renamed, check whether related TOC files, aliases, links, and cross-document references also need updates.
+- Reuse existing document patterns in the same area before introducing a new structure.
+
+## TiDB Cloud conventions
+
+- In this repository, TiDB Cloud documentation is maintained in the `release-8.5` branch for content reuse.
+- To contribute to TiDB Cloud documentation, make sure the PR is based on `release-8.5`.
+- Use `TOC-tidb-cloud.md` and `TOC-tidb-cloud-*.md` to understand which documents are TiDB Cloud-only and which TiDB documents are reused by TiDB Cloud.
+- If a path in `TOC-tidb-cloud.md` or `TOC-tidb-cloud-*.md` starts with `/tidb-cloud/`, it is TiDB Cloud-only content.
+- If a path in `TOC-tidb-cloud.md` or `TOC-tidb-cloud-*.md` does not start with `/tidb-cloud/`, it is reused from TiDB documentation.
+- Be careful with `CustomContent` tags such as `<CustomContent platform="tidb">` and `<CustomContent platform="tidb-cloud">`. Do not change, remove, or expand them casually, because they control platform-specific rendering behavior.
+- When editing shared TiDB and TiDB Cloud content, verify whether the change applies to both platforms or only one.
+
+## Contribution model
+
+- New documents should follow the templates in `resources/doc-templates/` when applicable.
+- Keep PR descriptions compatible with `.github/pull_request_template.md`.
+- Keep changes scoped to the requested task. Do not broaden a focused doc update into unrelated cleanup.
+- Prefer existing repository workflows, labels, and conventions over ad hoc alternatives.
+- When contributing diagrams, follow the existing diagram-style guidance rather than introducing a new visual style.
+
+## File naming rules
+
+- Use file names that briefly describe the document content, for example, `destroy-tidb-cluster.md`.
+- Keep file names concise and general. Avoid overly specific wording that might require frequent renaming and cause unnecessary URL changes.
+- Except for special files such as `TOC.md`, `CONTRIBUTING.md`, and `README.md`, use lowercase letters only in file names.
+- If a file name contains multiple English words, separate them with hyphens (`-`).
+- Do not use underscores (`_`) in file names.
+- Use lowercase file extensions only.
+- Markdown files must use the `.md` extension.
+
+## Content boundaries
+
+- Preserve product behavior, version numbers, links, anchors, file intent, and branch intent unless the task explicitly requires changing them.
+- Do not silently change technical meaning while improving wording.
+- Avoid changing commands, code samples, UI strings, configuration names, API fields, JSON, EBNF content, or generated helper files unless the task directly requires it or they are factually wrong.
+- When editing syntax-related content, be careful not to break EBNF or other structured source formats.
+- Keep cross-repo translation traceability when work maps between `docs` and `docs-cn`.
+- When a translation-related task maps content across repositories, preserve the source PR relationship, terminology intent, and affected-file mapping.
+
+## Front matter and document metadata
+
+- Preserve existing front matter structure unless the task requires a metadata change.
+- When front matter is present, keep `title`, `summary`, `aliases`, and other metadata aligned with the document content.
+- If a file is moved or renamed, check whether `aliases` should be updated to preserve inbound links.
+- Do not add or remove metadata fields casually. Follow existing patterns in nearby documents.
+
+## Linking and cross-document consistency
+
+- Preserve repository-relative absolute links when that is the repository convention.
+- When editing a document that summarizes or references other docs, check whether those related docs also need updates.
+- If a term, version statement, feature behavior, workflow, or compatibility note changes in one place, check nearby overview, task, reference, and release-note content for possible follow-up updates.
+- When changing headings, verify whether anchors, intra-repo links, TOC entries, or external references might be affected.
+
+## Validation habits
+
+Use existing repository checks instead of inventing new ones.
+
+- `./scripts/markdownlint <files>` for Markdown formatting
+- `./scripts/verify-links.sh` for link validation when links, anchors, moved files, or renamed files are involved
+- targeted repository scripts when the task touches glossary terms, keywords, anchor conflicts, or other specialized checks
+
+If a full check is too expensive for the task, validate the files you changed and any directly affected TOC or link targets.
+
+## Existing helpers
+
+Look for established scripts and workflows before automating from scratch.
+
+Use them as references for expected behavior, even when local credentials, permissions, or secrets prevent direct execution.
+
+## Agent behavior in this repository
+
+- Read the shared guidance in `.ai/shared/` before making non-trivial changes.
+- Use a matching skill in `.ai/skills/` when the task is workflow-specific.
+- Prefer minimal, targeted edits over broad rewrites.
+- Reuse existing wording, terminology, and document structure when they are already correct.
+- When unsure, check nearby docs, templates, and repository patterns before introducing a new approach.

.ai/shared/translation-rules.md

@@ -0,0 +1,44 @@
+# Translation Rules
+
+Use this file for EN -> ZH translation work that starts from changes in `pingcap/docs`.
+
+## Scope
+
+- This guidance is for mapping English docs work in `pingcap/docs` to Chinese docs work in `pingcap/docs-cn`.
+- Keep the translation faithful to the source change unless the target repo or branch requires a documented difference.
+
+## Preserve structure
+
+Keep the following stable unless translation requires a language-only adjustment:
+
+- heading hierarchy
+- lists and numbering
+- tables and column order
+- code fences and info strings
+- links, anchors, and repo paths
+- commands, flags, API names, config keys, and version numbers
+- product names and branch names
+
+Do not invent new product behavior, prerequisites, warnings, or version claims.
+
+## Terminology
+
+- Use `resources/terms.md` as the source of truth for terminology.
+- Use `.ai/shared/translation-terms.md` as a quick reference for high-frequency terms.
+- If a term is missing or ambiguous, keep the source term until you can verify the preferred translation.
+
+## PR traceability
+
+When preparing a translation PR:
+
+- reference the source English PR or file links
+- preserve the intended affected versions as much as the target repo allows
+- keep the PR body compatible with `.github/pull_request_template.md`
+- make the relationship to the source PR explicit
+
+## Workflow expectations
+
+- Identify the source files and the target files before translating.
+- Check whether the target branch should be `master` or a release branch.
+- If a helper script is available, prefer adapting it over rewriting the workflow from scratch.
+- If local automation depends on unavailable tokens or secrets, still prepare the branch, file list, PR body, and follow-up instructions so a human can finish the workflow quickly.

.ai/shared/translation-terms.md

@@ -0,0 +1,52 @@
+# Translation Terms
+
+Use this file as a quick terminology reference for EN -> ZH translation work in the TiDB docs workflow.
+
+For anything missing or unclear, check `resources/terms.md` before making a translation choice.
+
+## High-frequency terms
+
+| English | Preferred Chinese |
+| :-- | :-- |
+| cluster | 集群 |
+| node | 节点 |
+| instance | 实例 |
+| component | 组件 |
+| deployment | 部署 |
+| upgrade | 升级 |
+| configuration item | 配置项 |
+| parameter | 参数 |
+| system variable | 系统变量 |
+| feature | 特性 |
+| experimental feature | 实验特性 |
+| compatibility | 兼容性 |
+| limitation | 限制 |
+| high availability | 高可用 |
+| disaster recovery | 容灾 |
+| backup | 备份 |
+| restore | 恢复 |
+| migration | 迁移 |
+| replication | 复制 |
+| transaction | 事务 |
+| statement | 语句 |
+| table | 表 |
+| schema | 数据库模式 |
+| index | 索引 |
+| query | 查询 |
+| SQL statement | SQL 语句 |
+| access | 访问 |
+| authentication | 身份验证 |
+| authorization | 授权 |
+| privilege | 权限 |
+| role | 角色 |
+| monitoring | 监控 |
+| alert | 报警/告警 |
+| log file | 日志文件 |
+| troubleshooting | 故障排查 |
+| glossary | 术语表 |
+
+## Usage notes
+
+- Keep product and feature names in English when that is the established repo usage.
+- Keep commands, flags, file paths, and configuration keys unchanged.
+- Prefer consistency with the target repo over ad hoc wording improvements.

.ai/shared/writing-style.md

@@ -0,0 +1,113 @@
+# Writing Style
+
+Use this guidance for authoring, editing, or reviewing Markdown in `pingcap/docs`.
+
+## Overall principles
+
+- Write for TiDB users, not for internal teams.
+- Use a conversational and friendly tone, but do not sound casual, playful, or promotional.
+- Prefer clear, direct, and practical language.
+- Do not pre-announce what the document will do. Start with useful information directly.
+- Write for a global audience. Avoid culture-specific references, vague shorthand, and region-specific assumptions.
+- Write accessibly. Prefer simple sentence structures and wording that is easy to scan and understand.
+
+## File naming rules
+
+- Use file names that briefly describe the document content, for example, `destroy-tidb-cluster.md`.
+- Keep file names concise and general. Avoid overly specific wording that might require frequent renaming and cause unnecessary URL changes.
+- Except for special files such as `TOC.md`, `CONTRIBUTING.md`, and `README.md`, use lowercase letters only in file names.
+- If a file name contains multiple English words, separate them with hyphens (`-`).
+- Do not use underscores (`_`) in file names.
+- Use lowercase file extensions only.
+- Markdown files must use the `.md` extension.
+
+## Language and grammar
+
+- Use second person, such as `you` and `your`, instead of `we`.
+- Use active voice whenever possible. Make it clear who performs the action.
+- Put conditions before instructions, not after.
+- Use standard American English spelling and punctuation.
+- Use serial commas.
+- Prefer concise and precise wording over decorative phrasing.
+- Preserve technical meaning. Do not rewrite in ways that change product behavior or scope.
+
+## Structure and organization
+
+- Keep the structure easy to scan with meaningful headings and short paragraphs.
+- Keep exactly one top-level heading per file.
+- Do not skip heading levels.
+- When frontmatter is present, keep the `title` aligned with the H1.
+- Write a concise `summary` that tells the reader what they will learn or do.
+- In `summary`, do not start with a special character such as `>`, `*`, `#`, `-`, or `[`. If the summary must begin with a special character, wrap the summary content in quotation marks.
+
+## Choose the right document pattern
+
+Use the existing templates in `resources/doc-templates/` as the primary shape guide.
+
+- Task-style documents explain how to complete a procedure step by step.
+- Reference-style documents explain commands, parameters, options, system variables, configuration items, or APIs.
+- Use concept, troubleshooting, or new-feature templates when they better match the user task.
+
+Match the document structure to the document type. Do not force a task flow into a reference document or a reference layout into a task document.
+
+## Heading capitalization
+
+Use capitalization consistently based on the file type and heading level:
+
+- In TOC-related Markdown files, use title case for headings and navigation titles.
+- In regular Markdown files, use title case for the frontmatter `title`.
+- In regular Markdown files, use title case for the H1 heading.
+- In regular Markdown files, use sentence case for all headings below H1.
+
+Keep the frontmatter `title` and the H1 aligned in wording and capitalization.
+
+## Instructions and lists
+
+- Use numbered lists for sequences of actions or ordered procedures.
+- Use bulleted lists for most other lists.
+- Use description lists for pairs of related items, such as a term and its definition.
+- In procedural content, make each step a clear action.
+- Put prerequisites, conditions, and important context before the steps they affect.
+- Keep lists parallel in grammar and structure.
+
+## Links
+
+- Use descriptive link text.
+- Do not use vague link text such as `here`, `click here`, or `this page`.
+- Preserve repository-relative absolute paths such as `/foo/bar.md` when that is the repository convention.
+- Prefer linking to the most relevant destination instead of adding multiple redundant links nearby.
+
+## Formatting conventions
+
+- Put code-related text in code font, including commands, file names, directory names, configuration items, parameter names, field names, environment variables, and literal values.
+- Put UI elements in bold.
+- Preserve code samples, commands, UI strings, API fields, JSON keys, and configuration names unless they are factually wrong or the task explicitly requires changing them.
+- Keep blank lines around headings, lists, and fenced code blocks.
+- Indent nested list content with 4 spaces in normal Markdown files.
+- Use unambiguous date formats when dates are necessary.
+- Keep punctuation and capitalization consistent within lists, headings, and tables.
+
+## Notes, warnings, and emphasis
+
+- Use notes and warnings only when they help the reader make a decision, avoid risk, or prevent confusion.
+- Do not overuse callouts for ordinary information.
+- Make warnings specific and actionable.
+- Do not use emphasis for decoration. Use it only when it improves clarity.
+
+## Images
+
+- Provide alt text for images.
+- Use images only when they add value that text alone cannot provide.
+- Keep screenshots and diagrams aligned with the current product behavior and UI text.
+
+## Review lens
+
+When reviewing or rewriting content, check these in order:
+
+1. Is the content factually correct?
+2. Is the logic complete and easy to follow?
+3. Are other related documents also affected and likely to need updates?
+4. Does the structure match the document type?
+5. Does the wording improve clarity without changing product meaning?
+
+Make feedback specific, actionable, and tied to the changed content. Avoid praise-only edits.