OpenParable
Skip to content
← Back to skills

Repo Website Guide Create

Business
repo-website-guide-create

Repo Website Guide Create is an Agent Skill for business published in the open-circle/valibot repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Create conceptual documentation and tutorial pages for the Valibot website at website/src/routes/guides/. Use when adding guides about schemas, pipelines, async validation, migration, or other topics. Covers directory structure, MDX templates, frontmatter, and content guidelines.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/open-circle/valibot/blob/HEAD/.agents/skills/repo-website-guide-create/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/repo-website-guide-create, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Adding Guides to Website

Guide for creating conceptual documentation at website/src/routes/guides/.

Directory Structure

website/src/routes/guides/
├── menu.md                    # Navigation menu
├── (get-started)/             # Intro, installation, quick start
├── (main-concepts)/           # Schemas, pipelines, parsing
├── (schemas)/                 # Objects, arrays, unions
├── (advanced)/                # Async, i18n, JSON Schema
├── (migration)/               # Version upgrades, Zod migration
└── (category)/guide-slug/
    └── index.mdx              # Guide content

Note: Category folders use parentheses (Qwik route grouping).

Process

  1. Review 2-3 existing guides in the target category to understand style
  2. Choose category from existing or create new
  3. Create folder: (category)/guide-slug/
  4. Create index.mdx with content
  5. Update menu.md

index.mdx Template

---
title: Guide Title
description: >-
  A concise description of what this guide covers.
contributors:
  - github-username
---

import { ApiList, Link } from '~/components';

# Guide Title

Opening paragraph explaining what the reader will learn.

## Section Heading

Content with clear, concise language.

\`\`\`ts
import \* as v from 'valibot';

const Schema = v.object({
name: v.string(),
email: v.pipe(v.string(), v.email()),
});
\`\`\`

## Another Section

Continue with additional sections as needed.

Use <Link href="/api/pipe/">\`pipe\`</Link> for internal links.

Frontmatter

Required fields:

  • title: Page title and navigation label
  • description: SEO description (use >- for multi-line)
  • contributors: Array of GitHub usernames

Content Guidelines

Code Examples

  • Use TypeScript (ts language)
  • Import as import * as v from 'valibot';
  • Include comments for complex code

Links

Internal links use the Link component:

<Link href="/guides/schemas/">schemas guide</Link>
<Link href="/api/pipe/">\`pipe\`</Link>

Components

<ApiList label="Related schemas" items={['object', 'array', 'string']} />

Formatting

  • inline code for API names, variables, file names
  • bold for genuine emphasis only — not as inline section labels
  • Proper heading hierarchy (h1 title, h2 sections, h3 subsections)

Writing tone

  • Write conversational prose, not terse reference-doc style
  • Use first-person plural: "we recommend" not "you should"
  • Do not use bold as inline section labels (e.g. avoid **Label:** content). Use a proper subheading instead
  • Do not prefix blockquotes with bold labels (e.g. avoid > **Note:** ...). A plain > is correct
  • Bullet list items do not need a bold prefix on each item

Images

Place images in the same folder as index.mdx:

![Alt text](./diagram-light.jpg)

Consider light/dark theme variants if applicable (e.g., diagram-light.jpg, diagram-dark.jpg).

Update menu.md

Add to /website/src/routes/guides/menu.md:

## Category Name

- [Existing Guide](/guides/existing/)
- [New Guide Title](/guides/guide-slug/)

Maintain logical ordering within categories.

Checklist

  • Reviewed existing guides in the same category
  • Folder structure: (category)/guide-slug/index.mdx
  • Frontmatter: title, description, contributors
  • Internal links use Link component
  • Code examples use import * as v from 'valibot';
  • Added to menu.md
  • Style matches existing guides