From a664f5d2670201614b4d6318ff4902fc714b19b8 Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 31 Mar 2026 15:26:31 +0800 Subject: [PATCH 1/5] ai: add writing-doc-summaries skill --- .ai/AI-README.md | 1 + .ai/skills/writing-doc-summaries/SKILL.md | 137 ++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 .ai/skills/writing-doc-summaries/SKILL.md diff --git a/.ai/AI-README.md b/.ai/AI-README.md index 2243ccfcdec6b..fce1d6a2fb9be 100644 --- a/.ai/AI-README.md +++ b/.ai/AI-README.md @@ -22,6 +22,7 @@ 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` frontmatter field in a document following the repo's 115–145 character SEO-friendly sentence rules The translation skill includes bundled scripts under `.ai/skills/create-or-update-zh-translation-pr/scripts/` for: diff --git a/.ai/skills/writing-doc-summaries/SKILL.md b/.ai/skills/writing-doc-summaries/SKILL.md new file mode 100644 index 0000000000000..bf8bc1692ab95 --- /dev/null +++ b/.ai/skills/writing-doc-summaries/SKILL.md @@ -0,0 +1,137 @@ +--- +name: writing-doc-summaries +description: Writes or updates the frontmatter `summary` field in pingcap/docs and pingcap/docs-cn Markdown files. The summary is an SEO-friendly sentence of 115–145 characters. Use when a document is missing a summary, when a reviewer or CI check flags a low-quality summary, or when an existing summary is outdated, inaccurate, or the wrong length. +--- + +# Writing Doc Summaries + +Write or improve the `summary` field in the YAML frontmatter of Markdown files in `pingcap/docs` and `pingcap/docs-cn`. + +## frontmatter example + +```yaml +--- +title: Back up and Restore Data Using Dumpling and TiDB Lightning +summary: Learn how to use Dumpling and TiDB Lightning to back up and restore full data of TiDB. +--- +``` + +## Summary rules + +1. **Length**: 115–145 characters including spaces. +2. **Opening verb**: Start with an SEO-friendly verb phrase (see table below) that tells the reader what they will get from this document. Never start with the document title, a product name alone, or a noun phrase. +3. **Perspective**: Reader-focused — tell them what they will learn or do. +4. **No special leading characters**: Do not start with `>`, `*`, `#`, `-`, or `[`. +5. **YAML quoting**: Wrap the value in double quotes if it contains `:` or other YAML special characters. +6. **No redundancy**: Do not repeat the document title word-for-word. Rephrase to add value. +7. **Language**: Match the document body language. Chinese body → Chinese summary. +8. **Self-contained**: Must be understandable without the title or body — it may appear as a standalone search snippet. +9. **Accuracy**: Must match the actual scope of the document. Do not promise content the document does not deliver. +10. **Tone**: Conversational but professional. No marketing language. + +## Structure formula + +For most document types, a reliable pattern is: + +**[Action/Topic] + [Object] + [Outcome/Value]** + +| Part | What it covers | Example | +|---|---|---| +| Action/Topic | Opening verb phrase | `Learn how to configure` | +| Object | What the document is about | `TLS encryption between TiDB components` | +| Outcome/Value | What the reader gains or achieves | `to secure data in transit and meet compliance requirements` | + +Full example: `Learn how to configure TLS encryption between TiDB components to secure data in transit and meet compliance requirements.` + +**Exceptions:** + +- **SQL statement reference**: Use fixed template — `An overview of the usage of for the TiDB database`. No outcome clause needed. +- **Focused task docs**: Omit the outcome clause if the action and object already imply it and the sentence meets minimum length. + +## Opening verb guidance + +Scan a few existing summaries in the same subdirectory first to match local conventions. + +### Preferred patterns + +| Document type | Preferred opening | +|---|---| +| Concept / overview | Learn what, Learn how X works, Learn about, Introduce the concept of | +| Feature introduction | Introduce, Introduce the, Learn about | +| Task / procedure | Learn how to | +| Quick start | Learn how to quickly get started with | +| Configuration | Learn all the configuration options for, Learn how to configure | +| Troubleshooting | Learn how to troubleshoot, Learn how to diagnose | +| SQL statement reference | An overview of the usage of `` for the TiDB database | +| Release notes | Learn about the new features, compatibility changes, improvements, and bug fixes in TiDB `` | + +### Patterns to avoid + +- Starting with the product name alone: `TiDB ...`, `TiKV ...` +- `This document`, `This guide`, `This article`, `This page` +- `Explains`, `Describes` (use `Learn` or `An overview of` instead) +- `The reference for`, `The usage of` +- Repeating the document title word-for-word + +## Before and after + +**Before** (vague, filler opening, no outcome): + +```yaml +summary: This document explains the auto-tune feature of Backup & Restore. +``` + +**After** (reader-focused, specific, includes outcome): +```yaml +summary: Learn how the BR auto-tune feature automatically limits backup resource usage to reduce impact on online TiDB cluster performance. +``` + +**Before** (generic, no user intent): +```yaml +summary: An introduction to metadata lock in TiDB. +``` + +**After** (introduces concept and explains why it matters): +```yaml +summary: Introduce the concept, principles, and implementation of metadata lock in TiDB, and learn how it prevents DDL and DML conflicts. +``` + +## Workflow + +1. **Read** the target Markdown file fully. Note the title, opening paragraph, main sections, scope, and any existing `summary`. + +2. **Draft** 2–3 candidate sentences using the structure formula and the opening-verb table. + +3. **Validate** each candidate: + - Count characters. Must be 115–145. + - Confirm opening verb fits the document type. + - Confirm it does not promise content the document lacks. + - Confirm language matches the document body. + - If it contains `:`, confirm the value is wrapped in double quotes. + +4. **If validation fails** → revise and re-validate. Repeat until all checks pass. + +5. **Apply** the best candidate: + - If frontmatter exists, update the `summary` line in place. + - If frontmatter is missing, add it at the top: + ```yaml + --- + title: + summary: + --- + ``` + - Preserve all other frontmatter fields. Do not change the document body. + +6. **Final check**: Re-count characters one more time after editing. Confirm `title` matches the H1. Confirm no special leading character without wrapping quotes. + +## Output expectations + +- Apply the change directly using the Edit tool. +- Report the final summary text and its character count. +- If the existing summary is already acceptable, say so and explain why. +- Prefer a full rewrite over minor edits when the existing summary is structurally weak. +- Do not rewrite or reformat any other part of the document. + +## Gut check + +Before applying: **would this make a TiDB user want to click through from search results?** If not, rewrite. \ No newline at end of file From 281ab5b3a701584bae0624ca0d2981cb4a750cd1 Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 31 Mar 2026 15:30:02 +0800 Subject: [PATCH 2/5] fix --- .ai/AI-README.md | 2 +- .ai/skills/writing-doc-summaries/SKILL.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.ai/AI-README.md b/.ai/AI-README.md index fce1d6a2fb9be..8e46a3e647684 100644 --- a/.ai/AI-README.md +++ b/.ai/AI-README.md @@ -22,7 +22,7 @@ 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` frontmatter field in a document following the repo's 115–145 character SEO-friendly sentence rules +- `.ai/skills/writing-doc-summaries/`: write or update the `summary` frontmatter field in a document following the repo's 115-145 character SEO-friendly sentence rules The translation skill includes bundled scripts under `.ai/skills/create-or-update-zh-translation-pr/scripts/` for: diff --git a/.ai/skills/writing-doc-summaries/SKILL.md b/.ai/skills/writing-doc-summaries/SKILL.md index bf8bc1692ab95..18559fb0679b4 100644 --- a/.ai/skills/writing-doc-summaries/SKILL.md +++ b/.ai/skills/writing-doc-summaries/SKILL.md @@ -1,6 +1,6 @@ --- name: writing-doc-summaries -description: Writes or updates the frontmatter `summary` field in pingcap/docs and pingcap/docs-cn Markdown files. The summary is an SEO-friendly sentence of 115–145 characters. Use when a document is missing a summary, when a reviewer or CI check flags a low-quality summary, or when an existing summary is outdated, inaccurate, or the wrong length. +description: Writes or updates the frontmatter `summary` field in pingcap/docs and pingcap/docs-cn Markdown files. The summary is an SEO-friendly sentence of 115-145 characters. Use when a document is missing a summary, when a reviewer or CI check flags a low-quality summary, or when an existing summary is outdated, inaccurate, or the wrong length. --- # Writing Doc Summaries @@ -18,7 +18,7 @@ summary: Learn how to use Dumpling and TiDB Lightning to back up and restore ful ## Summary rules -1. **Length**: 115–145 characters including spaces. +1. **Length**: 115-145 characters including spaces. 2. **Opening verb**: Start with an SEO-friendly verb phrase (see table below) that tells the reader what they will get from this document. Never start with the document title, a product name alone, or a noun phrase. 3. **Perspective**: Reader-focused — tell them what they will learn or do. 4. **No special leading characters**: Do not start with `>`, `*`, `#`, `-`, or `[`. @@ -100,10 +100,10 @@ summary: Introduce the concept, principles, and implementation of metadata lock 1. **Read** the target Markdown file fully. Note the title, opening paragraph, main sections, scope, and any existing `summary`. -2. **Draft** 2–3 candidate sentences using the structure formula and the opening-verb table. +2. **Draft** 2-3 candidate sentences using the structure formula and the opening-verb table. 3. **Validate** each candidate: - - Count characters. Must be 115–145. + - Count characters. Must be 115-145. - Confirm opening verb fits the document type. - Confirm it does not promise content the document lacks. - Confirm language matches the document body. From 008fbde3a9b6bb283f45e59f999d5fdd80c0a0e7 Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 31 Mar 2026 15:32:35 +0800 Subject: [PATCH 3/5] fix --- .ai/AI-README.md | 2 +- .ai/skills/writing-doc-summaries/SKILL.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.ai/AI-README.md b/.ai/AI-README.md index 8e46a3e647684..6edd2220824be 100644 --- a/.ai/AI-README.md +++ b/.ai/AI-README.md @@ -22,7 +22,7 @@ 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` frontmatter field in a document following the repo's 115-145 character SEO-friendly sentence rules +- `.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 The translation skill includes bundled scripts under `.ai/skills/create-or-update-zh-translation-pr/scripts/` for: diff --git a/.ai/skills/writing-doc-summaries/SKILL.md b/.ai/skills/writing-doc-summaries/SKILL.md index 18559fb0679b4..7e022beadfb06 100644 --- a/.ai/skills/writing-doc-summaries/SKILL.md +++ b/.ai/skills/writing-doc-summaries/SKILL.md @@ -1,13 +1,13 @@ --- name: writing-doc-summaries -description: Writes or updates the frontmatter `summary` field in pingcap/docs and pingcap/docs-cn Markdown files. The summary is an SEO-friendly sentence of 115-145 characters. Use when a document is missing a summary, when a reviewer or CI check flags a low-quality summary, or when an existing summary is outdated, inaccurate, or the wrong length. +description: Writes or updates the front matter `summary` field in pingcap/docs and pingcap/docs-cn Markdown files. The summary is an SEO-friendly sentence of 115-145 characters. Use when a document is missing a summary, when a reviewer or CI check flags a low-quality summary, or when an existing summary is outdated, inaccurate, or the wrong length. --- # Writing Doc Summaries -Write or improve the `summary` field in the YAML frontmatter of Markdown files in `pingcap/docs` and `pingcap/docs-cn`. +Write or improve the `summary` field in the YAML front matter of Markdown files in `pingcap/docs` and `pingcap/docs-cn`. -## frontmatter example +## Front matter example ```yaml --- @@ -112,15 +112,15 @@ summary: Introduce the concept, principles, and implementation of metadata lock 4. **If validation fails** → revise and re-validate. Repeat until all checks pass. 5. **Apply** the best candidate: - - If frontmatter exists, update the `summary` line in place. - - If frontmatter is missing, add it at the top: + - If front matter exists, update the `summary` line in place. + - If front matter is missing, add it at the top: ```yaml --- title: summary: --- ``` - - Preserve all other frontmatter fields. Do not change the document body. + - Preserve all other front matter fields. Do not change the document body. 6. **Final check**: Re-count characters one more time after editing. Confirm `title` matches the H1. Confirm no special leading character without wrapping quotes. From 6802f36a3b0b468cd4f0ab7fe8f272e1aad47f1a Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 31 Mar 2026 15:33:01 +0800 Subject: [PATCH 4/5] fix --- .ai/skills/writing-doc-summaries/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.ai/skills/writing-doc-summaries/SKILL.md b/.ai/skills/writing-doc-summaries/SKILL.md index 7e022beadfb06..dde92cc6fb310 100644 --- a/.ai/skills/writing-doc-summaries/SKILL.md +++ b/.ai/skills/writing-doc-summaries/SKILL.md @@ -134,4 +134,4 @@ summary: Introduce the concept, principles, and implementation of metadata lock ## Gut check -Before applying: **would this make a TiDB user want to click through from search results?** If not, rewrite. \ No newline at end of file +Before applying: **would this make a TiDB user want to click through from search results?** If not, rewrite. From 534d72cf4ad72acb3cddee557bbd86abf951530b Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 31 Mar 2026 15:34:04 +0800 Subject: [PATCH 5/5] make ci happy --- .ai/skills/writing-doc-summaries/SKILL.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.ai/skills/writing-doc-summaries/SKILL.md b/.ai/skills/writing-doc-summaries/SKILL.md index dde92cc6fb310..72f4b14249ea1 100644 --- a/.ai/skills/writing-doc-summaries/SKILL.md +++ b/.ai/skills/writing-doc-summaries/SKILL.md @@ -82,16 +82,19 @@ summary: This document explains the auto-tune feature of Backup & Restore. ``` **After** (reader-focused, specific, includes outcome): + ```yaml summary: Learn how the BR auto-tune feature automatically limits backup resource usage to reduce impact on online TiDB cluster performance. ``` **Before** (generic, no user intent): + ```yaml summary: An introduction to metadata lock in TiDB. ``` **After** (introduces concept and explains why it matters): + ```yaml summary: Introduce the concept, principles, and implementation of metadata lock in TiDB, and learn how it prevents DDL and DML conflicts. ``` @@ -114,12 +117,14 @@ summary: Introduce the concept, principles, and implementation of metadata lock 5. **Apply** the best candidate: - If front matter exists, update the `summary` line in place. - If front matter is missing, add it at the top: + ```yaml --- title: summary: --- ``` + - Preserve all other front matter fields. Do not change the document body. 6. **Final check**: Re-count characters one more time after editing. Confirm `title` matches the H1. Confirm no special leading character without wrapping quotes.