open-circle/valibot

Overview

This skill creates new API reference pages under website/src/routes/api/ for Valibot. It reads TypeScript source, generates properties.ts and index.mdx files, updates menu.md, and cross-references related API pages and type docs. Use it when adding documentation for new schemas, actions, methods, or types.

How this skill works

The skill inspects the library source in /library/src/ to extract JSDoc, function overloads, generics, parameters, return types, and type interfaces (issues, schema/action interfaces). It emits a properties.ts that describes Property component types and an index.mdx (or type MDX) following established frontmatter and section conventions. Finally, it inserts the new entry into menu.md alphabetically and updates Related sections across other API pages and relevant guides.

When to use it

• Adding documentation for a new schema, action, method, utility, or storage.
• Creating type pages for Issue or Schema/Action interfaces.
• Updating website navigation (menu.md) to include a newly published API.
• Cross-linking related APIs when introducing interoperable functions or validators.
• Preparing examples and realistic error messages for new validation features.

Best practices

• Read the entire source file first: JSDoc, overloads, and exported interfaces inform docs and properties.ts.
• Mirror source types precisely in properties.ts using the DefinitionData conventions (primitive, custom, union, object, function, template, etc.).
• Include JSDoc hints as blockquote text in the Explanation section and copy one-line description to frontmatter description.
• Keep Examples realistic and progressive; always include friendly, actionable error messages.
• Update related API docs and concept guides (schemas, pipelines, methods) so cross-references stay consistent and navigable.
• Ensure all href links use trailing slashes and menu.md remains alphabetical.

Example use cases

• Document a new string-based validator: extract StringIssue and StringSchema, create properties.ts and index.mdx, add examples showing error messages.
• Add a new action (e.g., email): generate action page, list related schemas (string) and methods (pipe) in Related, and update string’s Related to include email.
• Introduce a new Schema interface type page: create (types)/TypeName/ with Definition section and no source field in frontmatter.
• Add a method (e.g., parse) and update concept guides: add method doc, include it in the methods guide and update ApiList entries across schemas.