oceanbase-syntax_skill

Overview

This skill helps authors write clear, consistent SQL syntax sections for OceanBase documentation. It codifies rules that keep syntax definitions structural (no semicolons) and separates them from executable examples, ensuring documentation matches actual behavior and tests.

How this skill works

The skill inspects draft syntax sections and enforces OceanBase conventions: no semicolons in syntax blocks, square brackets for optional items, pipes for alternatives, and ellipses for repetition. It also guides authors to add a parameter table, provide examples as executable statements (with semicolons), and reconcile syntax with test cases.

When to use it

• Creating a new SQL statement page for OceanBase documentation.
• Reviewing or editing existing syntax sections to match OceanBase conventions.
• Converting executable examples into a separate Examples section.
• Validating that optional parameters and alternatives use consistent notation.
• Preparing documentation to match parser behavior and test cases.

Best practices

• Omit semicolons in syntax blocks; include them only in the Examples section.
• Use [] for optional parameters, | for alternatives, and ... for repetition.
• Keep syntax concise: show structure and choices, not implementation detail.
• Provide a parameter table that explains each parameter and reserved tokens.
• Verify syntax against test cases to document real, working behavior.

Example use cases

• Authoring the Syntax section for ALTER SYSTEM KILL SESSION without semicolons.
• Refactoring a page that mixed executable statements into syntax and example sections.
• Reviewing syntax notation across multiple statements for consistency.
• Adding or updating a parameter table after changing statement parameters.
• Checking that syntax variants are presented clearly and match tests.