Skip to content

Commit d72c7a1

Browse files
OreoxmtOreoxmt
authored
.ai: add "add-related-resources" skill (#22912)
1 parent 5d9ab62 commit d72c7a1

9 files changed

Lines changed: 736 additions & 6 deletions

File tree

‎.ai/AI-README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,17 @@ Use `resources/terms.md` when terminology is uncertain or not covered by the qui
2020

2121
## Current skills
2222

23+
- `.ai/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
2324
- `.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
2425
- `.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
2526
- `.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
2627
- `.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
2728

29+
The related resources skill includes bundled scripts under `.ai/skills/add-related-resources/scripts/` for:
30+
31+
- fetching card metadata from blog, YouTube, and TiDB Lab URLs
32+
- validating `RelatedResources` blocks and `ResourceCard` formatting in modified docs
33+
2834
The translation skill includes bundled scripts under `.ai/skills/create-or-update-zh-translation-pr/scripts/` for:
2935

3036
- preparing structured translation inputs from a source PR

‎.ai/skills/add-related-resources/SKILL.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
name: add-related-resources
3+
description: Produces and merges Related resources cards for TiDB docs pages using the RelatedResources and ResourceCard MDX components. Use when the user asks to add or update a related resource card, resource link, blog card, video card, YouTube card, or TiDB Lab card in English, Simplified Chinese, or Japanese Markdown docs.
4+
---
5+
6+
# Add Related Resource Cards to TiDB Docs
7+
8+
## Overview
9+
10+
A "Related resources" section is a final h2 in a TiDB docs page, containing a `<RelatedResources>` block with one or more `<ResourceCard />` entries. Each card links to a blog post, YouTube video, or TiDB Lab.
11+
12+
This skill produces those cards correctly for English, Simplified Chinese, and Japanese docs, and merges them into the target file.
13+
14+
## Component syntax
15+
16+
```mdx
17+
## Related resources
18+
19+
<RelatedResources>
20+
<ResourceCard title="..." type="blog|video|lab" link="..." imgSrc="..." author="..." date="YYYY-MM-DD" duration="..." />
21+
</RelatedResources>
22+
```
23+
24+
Rules:
25+
26+
- Use one `<ResourceCard ... />` per line. Do not wrap attributes.
27+
- Indent cards by two spaces inside `<RelatedResources>`.
28+
- Use double quotes for all attributes and a space before `/>`.
29+
- Do not add blank lines inside `<RelatedResources>`.
30+
- Add one blank line before the heading and one blank line after it when creating the container section.
31+
- Append as the last H2 unless the user gives another location.
32+
33+
## Language heading mapping
34+
35+
Infer language from the target file path and surrounding document language.
36+
37+
| Language | Heading | Duration |
38+
|---|---|---|
39+
| English | `## Related resources` | `8 mins` |
40+
| Simplified Chinese | `## 相关资源` | `8 分钟` |
41+
| Japanese | `## 関連リソース {#related-resources}` | `8 分` |
42+
43+
Japanese headings must include `{#related-resources}`.
44+
45+
## Card attributes
46+
47+
Required for every card: `title`, `type`, `link`, `imgSrc`.
48+
49+
Optional:
50+
51+
- `author`: include only when clearly shown by the source.
52+
- `date`: use `YYYY-MM-DD`; mainly for blogs. Omit for videos/labs unless clearly shown or requested.
53+
- `duration`: include for videos and labs when available; omit for blogs.
54+
55+
Do not invent values. If any required attribute cannot be found, stop and ask the user.
56+
57+
## Source handling
58+
59+
When the user provides only a URL, first run:
60+
61+
```bash
62+
python3 .ai/skills/add-related-resources/scripts/fetch_resource_metadata.py "<url>" --lang en|zh|ja
63+
```
64+
65+
The script emits a JSON card draft with `type`, `title`, `link`, `imgSrc`, optional fields, and warnings. Use it as a helper, not as unquestioned truth: review warnings, verify missing fields, and ask the user before fallbacks or substitutions.
66+
67+
If the script cannot fetch a source or returns missing required fields, use the available web, browser, or shell tools to inspect the page manually. Do not invent values.
68+
69+
### Blogs
70+
71+
Use the blog host that matches the target document language:
72+
73+
| Language | Host |
74+
|---|---|
75+
| English | `https://www.pingcap.com/blog/<slug>` |
76+
| Simplified Chinese | `https://pingkai.cn/tidbcommunity/blog/<slug>` |
77+
| Japanese | `https://pingcap.co.jp/blog/<slug>` |
78+
79+
Extract:
80+
81+
- `title`: visible page title, preferably H1 or `og:title`.
82+
- `imgSrc`: page `og:image`.
83+
- `author`: visible byline.
84+
- `date`: `datePublished` or visible publish date, normalized to `YYYY-MM-DD`.
85+
86+
Japanese blog rules:
87+
88+
- If the JP URL redirects, use the final URL as `link`.
89+
- If the JP URL is 404 or missing, ask before falling back to English or substituting another JP post.
90+
- Do not rewrite `static.pingcap.com/...` image URLs to `static.pingcap.co.jp/...`; use the page's actual `og:image`.
91+
92+
### Videos
93+
94+
Supported URLs: `youtube.com/watch?v=<ID>` and `youtu.be/<ID>`.
95+
96+
Extract:
97+
98+
- `title`: YouTube video title.
99+
- `link`: preserve the user-provided canonical video URL unless substituting with confirmation.
100+
- `imgSrc`: `https://i.ytimg.com/vi/<ID>/hqdefault.jpg`.
101+
- `author`: channel name.
102+
- `duration`: video length rounded to minutes and localized.
103+
104+
Use the same video ID in `link` and `imgSrc`. For Japanese docs, prefer a Japanese-language `PingCAP Japan` video only after confirming substitution with the user.
105+
106+
### Labs
107+
108+
Use the lab URL that matches the target document language:
109+
110+
| Language | URL |
111+
|---|---|
112+
| English | `https://labs.tidb.io/labs/<slug>` |
113+
| Simplified Chinese | `https://labs.pingcap.com/labs/<slug>` |
114+
| Japanese | `https://labs.tidb.io/ja/labs/<slug>` |
115+
116+
Extract:
117+
118+
- `title`: localized lab title from the page or embedded page data. Do not translate manually.
119+
- `imgSrc`: lab cover image, typically `https://lab-static.pingcap.com/...`.
120+
- `duration`: estimated time, localized.
121+
122+
Keep the page's actual image filename, including `_en.png` images used by localized labs. Do not invent `_zh` or `_ja` variants.
123+
124+
## Workflow
125+
126+
1. Identify target file(s), source URL(s), resource type(s), and target language.
127+
2. Read each target file and find the merge location: an existing `Related resources` block, or the end of the file if the container section must be created.
128+
3. For each source URL, run `scripts/fetch_resource_metadata.py` with the target language.
129+
4. Review the JSON draft. Ask the user if a required value is unavailable, a localized URL is missing, or a substitution/fallback is needed.
130+
5. Merge the card into the target file: append to an existing `<RelatedResources>` block, or create the final localized h2 container and place the card inside it.
131+
6. Verify formatting with:
132+
133+
```bash
134+
python3 .ai/skills/add-related-resources/scripts/validate_related_resources.py "<target-file>"
135+
```
136+
137+
7. Fix validation errors and rerun the validator until it prints `OK`.
138+
139+
## Examples
140+
141+
English lab:
142+
143+
```mdx
144+
## Related resources
145+
146+
<RelatedResources>
147+
<ResourceCard title="TiDB SQL Tuning Lab 1: Clustered and Non-Clustered Indexes" type="lab" link="https://labs.tidb.io/labs/dba_307_lab_ff0" imgSrc="https://lab-static.pingcap.com/quick-demo/307-01.png" duration="90 mins" />
148+
</RelatedResources>
149+
```
150+
151+
Chinese lab:
152+
153+
```mdx
154+
## 相关资源
155+
156+
<RelatedResources>
157+
<ResourceCard title="管理 TiDB 实验 8: 备份与还原" type="lab" link="https://labs.pingcap.com/labs/dba_303_lab_ff7" imgSrc="https://lab-static.pingcap.com/quick-demo/dba_303_ch09_en.png" duration="60 分钟" />
158+
</RelatedResources>
159+
```
160+
161+
Japanese mixed cards:
162+
163+
```mdx
164+
## 関連リソース {#related-resources}
165+
166+
<RelatedResources>
167+
<ResourceCard title="管理 TiDB 演習 8: バックアップと復元" type="lab" link="https://labs.tidb.io/ja/labs/dba_303_lab_ff7" imgSrc="https://lab-static.pingcap.com/quick-demo/dba_303_ch09_en.png" duration="60 分" />
168+
<ResourceCard title="3分で分かるNewSQLデータベースのTiDB Cloud" type="video" link="https://www.youtube.com/watch?v=kWrT4Qd1xA0" imgSrc="https://i.ytimg.com/vi/kWrT4Qd1xA0/hqdefault.jpg" author="PingCAP Japan" duration="3 分" />
169+
</RelatedResources>
170+
```
171+
172+
## Common mistakes
173+
174+
- Creating a duplicate container section instead of appending cards to the existing block.
175+
- Omitting `{#related-resources}` from Japanese headings.
176+
- Using `type="Blog"` or `type="YouTube"` instead of `blog`, `video`, or `lab`.
177+
- Using non-ISO dates.
178+
- Formatting English duration as `8 minutes` instead of `8 mins`.
179+
- Omitting the space in Chinese or Japanese durations.
180+
- Silently falling back to English when a localized source page is missing.
181+
- Mismatching YouTube IDs between `link` and `imgSrc`.

0 commit comments

Comments
 (0)