This directory stores repo-local guidance for AI agents working in pingcap/docs.

• .agents/shared/: reusable repo policy, writing guidance, and translation guidance
• .agents/skills/: workflow-specific instructions for recurring tasks in this repo

Read only the files that apply to the task:

• .agents/shared/repo-conventions.md: repository scope, branch rules, file naming, TOC expectations, TiDB Cloud boundaries, and validation habits
• .agents/shared/writing-style.md: document structure, wording, formatting, headings, front matter, and repo-compatible writing style
• .agents/shared/translation-rules.md: EN -> ZH translation constraints, traceability, structure preservation, and workflow expectations
• .agents/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.

• .agents/skills/add-related-resources/: produce and merge related resources cards for TiDB docs pages using the RelatedResources and ResourceCard MDX components for blog, video, and TiDB Lab links in English, Simplified Chinese, and Japanese docs
• .agents/skills/review-doc-pr/: review documentation PRs and Markdown diffs for factual accuracy, user usefulness, completeness, version fit, related-doc impact, links, and style
• .agents/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
• .agents/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
• .agents/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)
• .agents/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
• .agents/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
• .agents/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

The related resources skill includes bundled scripts under .agents/skills/add-related-resources/scripts/ for:

• fetching card metadata from blog, YouTube, and TiDB Lab URLs
• validating RelatedResources blocks and ResourceCard formatting in modified docs

The translation skill includes bundled scripts under .agents/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

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.