skills.rest
pingcap
pingcapOFFICIAL
Explore all skills by this author →
Website𝕏@PingCAPGitHub

write-update-tidb-docs

Write and update TiDB documentation pages from code PRs, issues, and specs.

617|718|Updated Jul 23, 2016
Search Tags:#Markdown#Technical Writing#Documentation#docs-as-code#tidb#github pr#pingcap
One-click install
npx skills add https://github.com/pingcap/docs --skill write-update-tidb-docs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-update-tidb-docs
Source: https://github.com/pingcap/docs/tree/main/.agents/skills/write-update-tidb-docs
Command: npx skills add https://github.com/pingcap/docs --skill write-update-tidb-docs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Turning code changes, PRs, and product specs into accurate, user-facing TiDB documentation is slow and error-prone. This Skill guides an AI through the full editorial workflow in the pingcap/docs repository, ensuring every documented fact is traceable to an authoritative source.

Core Features & Use Cases

  • Create or update decision logic: Analyzes inputs (code PRs, GitHub issues, design docs, rough notes) and decides whether to create a new page or update existing ones, then follows a dedicated reference workflow for each path.
  • Fact grounding and version targeting: Maps code patterns (system variables, config fields, SQL grammar, flags) to exact target doc files, derives version numbers from PR milestones, and marks unverifiable facts as open questions instead of guessing.
  • Style and consistency enforcement: Matches existing page voice, entry formats, TOC placement rules, front matter conventions, and runs markdownlint and link verification before reporting.
  • Use Case: An engineer merges a PR adding a new system variable to pingcap/tidb. The Skill inspects the PR diff, updates system-variables.md in alphabetical order with the correct entry format, adds a version note, cross-links the feature page, and reports follow-ups for Chinese translation and release notes.

Quick Start

Ask the AI to write TiDB documentation for the changes in a given pingcap/tidb PR URL and update the affected pages in pingcap/docs.

Frequently Asked Questions about write-update-tidb-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write TiDB documentation from a code PR?▼

Provide the pingcap/tidb PR URL and the Skill inspects the diff with gh pr view and gh pr diff, maps code patterns to target doc files, then drafts or updates pages following the repository's style conventions. Every concrete value must be traceable to the PR, code, or tests.

How does the skill decide between creating a new doc page and updating an existing one?▼

It checks whether the content fits an existing page, has at least three meaningful sections, and needs standalone discoverability. Content that fits an existing page is updated in place; only substantial new features, SQL statements, or tools get new pages.

Which branch should TiDB documentation changes target?▼

New development targets master only, relying on cherry-pick labels for maintained release versions. Content under /tidb-cloud/ and /ai/ targets release-8.5 instead, since those folders exist only in that branch.

Does the skill create branches, commits, or pull requests automatically?▼

No. It produces local edits, validation results, and a completion report, then stops. Branch creation, commits, PRs, Chinese translation, and release notes are separate follow-up steps handled by other skills or explicit user requests.

What happens when a fact cannot be verified from the source?▼

The Skill inserts a clearly marked TODO placeholder and lists the item under Open questions in the plan rather than guessing. Conflicts between sources and existing docs are also flagged instead of silently resolved.

Related Skills

Explore More Content & Communication Skills→
pingcappingcap
617

review-doc-pr

Identify factual, structural, and stylistic issues in TiDB documentation pull requests.

Official
Intermediate
pingcappingcap
617

create-or-update-zh-translation-pr

Create or update Chinese translation PRs from English docs changes.

Official
Advanced
pingcappingcap
5

writing-doc-summaries

Generate compliant YAML front matter summaries for Markdown documents.

Official
Intermediate
SciMate-AISciMate-AI
1

markdown-mermaid-writing

Write Markdown documents with embedded Mermaid diagrams and frontmatter metadata.

Official
Advanced