Documentation Skill

This skill provides comprehensive guidelines for AI coding assistants working on Kubb documentation.

When to Use

• •Adding a new plugin, feature, or option
• •Changing plugin behavior or API signatures
• •Fixing bugs that affect code generation
• •Writing or updating functionalities/component/composable documentation

What It Does

• •Create clear, concise, practical documentation optimized for developer experience.

Writing Standard

Override: When writing documentation, maintain proper grammar and complete sentences. The "sacrifice grammar for brevity" rule does NOT apply here.

Documentation must be:

• •Grammatically correct
• •Clear and unambiguous
• •Properly punctuated
• •Complete sentences (not fragments)

Brevity is still valued, but never at the cost of clarity or correctness.

Available References

Load based on context:

• •Writing prose → documentation/references/writing-style.md
• •Props, options, usage patterns → documentation/references/content-patterns.md
• •Adding navigation or sections → documentation/references/config-json.md

Language and Tone

• •Use the US spelling. For example, use license, not licence.

Naming Conventions

• •Use kebab-case: how-to-do-thing.md
• •Be descriptive: multipart-form-data.md not form.md
• •Match URL structure: File name becomes the URL path

Writing Patterns

Modal Verbs

Component Patterns (WHEN to use)

Headings

• •H1 (#): No backticks
• •H2-H4: Backticks work fine

Links and Cross-References

• •Internal links: Use relative paths: /plugins/plugin-ts/
• •Anchor links: Link to specific sections: /plugins/plugin-ts/#output-path
• •External links: Use full URLs with descriptive text
• •Placement: Add links section at the very end of the document

Images and assets

• •Location: docs/public/
• •Reference: Use relative paths from markdown files
• •Formats: Use optimized formats (webp/png/jpg)
• •Sizing: Keep file sizes reasonable
• •Naming: Use descriptive names: plugin-react-query-example.png

Configuration (config.json)

The docs/config.json file defines navigation and sidebar structure using the Kubb.dev schema.

• •Schema: https://kubb.dev/schemas/config/schema.json
• •Required: sidebars (array), sidebar (route mapping)
• •Optional: nav (navigation), $schema (validation)
• •Link format: Use absolute paths with trailing slash: /getting-started/introduction/
• •Route mapping: /getting-started maps to gettingStarted sidebar name

When adding new sections:

1. •Define sidebar in sidebars array with unique name
2. •Add navigation items to nav array
3. •Map route prefix to sidebar name in sidebar object

See ./references/config-json.md for complete schema reference.

Checklist

• • Active voice (85%+)
• • Present tense
• • 2-4 sentences per paragraph
• • Explanation before code
• • File path labels on code blocks
• • Check if the links work
• • Test that all code groups display properly
• • Validate frontmatter syntax
• • Edge cases and limitations documented
• • Update config.json when adding new pages/sections
• • Usage section: minimal snippet with ::: code-group and output
• • Examples section: realistic scenarios with meaningful names
• • Props/Options: correct table format (right-aligned labels, left-aligned values)
• • Props/Options: Type and Required always present, Default only if applicable
• • For functionalities/hooks/composables: include "When to Use" section with bullet points
• • Cross-references to related documentation (minimum 2-3 links)