oceanbase-sql-doc_skill

Overview

This skill creates and formats OceanBase SQL statement reference documentation following official style guidelines. It ensures consistent meta tables, section structure, examples, and spacing so documentation is clear, executable, and publication-ready. Use it to produce or edit SQL docs that conform to OceanBase standards.

How this skill works

The skill enforces a document template: a meta information table, Purpose, Syntax, Parameters, Examples, and References. It validates syntax rules (no semicolons in Syntax section), example formatting (obclient> prompts, separate code blocks for results), and naming conventions for realistic examples. It also checks notice box usage, spacing, and a final quality checklist.

When to use it

• Writing new OceanBase SQL statement reference pages
• Editing or standardizing existing SQL documentation
• Creating executable examples and result blocks for docs
• Converting informal notes into publishable OceanBase docs
• Verifying docs against production test cases and syntax

Best practices

• Always start with the meta information table and fill only necessary fields (description, keywords; tenant-type only when applicable).
• Keep the Syntax section explanatory and free of semicolons; use sql code blocks for structure only.
• Prefix executable examples with obclient> or obclient [SCHEMA]> and include semicolons in those blocks.
• Place SQL statements and query results in separate code blocks and connect them with a short label like "Query results:".
• Use meaningful, business-oriented names in examples (e.g., order_table, product_tg) rather than generic t1 or tg1.
• Run examples against test cases and document the real, working syntax shown by tests, not theoretical parser definitions.

Example use cases

• Create an OceanBase reference page for a new DDL statement with full examples and results.
• Standardize a set of existing SQL docs to a single OceanBase documentation template.
• Edit examples to replace placeholder names with business-meaningful table and database names.
• Prepare documentation for publication, including notice boxes and final quality checklist validation.
• Translate test-case outputs into formatted examples that reflect production behavior.