Repo Structure Navigate
Developmentrepo-structure-navigateRepo Structure Navigate is an Agent Skill for development published in the open-circle/valibot repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Navigate the Valibot repository structure. Use when looking for files, understanding the codebase layout, finding schema/action/method implementations, locating tests, API docs, or guide pages. Covers monorepo layout, library architecture, file naming conventions, and quick lookups.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/open-circle/valibot/blob/HEAD/.agents/skills/repo-structure-navigate/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/repo-structure-navigate, 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.
Valibot Repository Structure
Monorepo Layout
valibot/
├── library/ # Core valibot package (zero dependencies)
├── packages/
│ ├── i18n/ # Translated error messages (25+ languages)
│ └── to-json-schema/ # JSON Schema converter
├── codemod/
│ ├── migrate-to-v0.31.0/ # Version migration
│ └── zod-to-valibot/ # Zod converter
├── website/ # valibot.dev (Qwik + Vite)
├── brand/ # Brand assets
├── skills/ # Agent skills (this folder)
└── prompts/ # Legacy AI agent guides
Core Library (/library/src/)
Directory Structure
| Directory | Purpose | Examples |
|---|---|---|
schemas/ | Data type validators | string/, object/, array/, union/ |
actions/ | Validation & transformation | email/, minLength/, trim/, transform/ |
methods/ | High-level API | parse/, safeParse/, pipe/, partial/ |
types/ | TypeScript definitions | schema.ts, issue.ts, dataset.ts |
utils/ | Internal helpers (prefixed _) | _addIssue/, _stringify/, ValiError/ |
storages/ | Global state | Config, message storage |
Schema Categories
- Primitives:
string,number,boolean,bigint,date,symbol,blob,file - Objects:
object,strictObject,looseObject,objectWithRest - Arrays:
array,tuple,strictTuple,looseTuple,tupleWithRest - Advanced:
union,variant,intersect,record,map,set,lazy,custom - Modifiers:
optional,nullable,nullish,nonNullable,nonNullish,nonOptional
Action Types
Validation (return issues): email, url, uuid, regex, minLength, maxValue, check
Transformation (modify data): trim, toLowerCase, toUpperCase, mapItems, transform
Metadata: brand, flavor, metadata, description, title
File Naming Convention
Each schema/action/method has its own directory:
schemas/string/
├── string.ts # Implementation
├── string.test.ts # Runtime tests
├── string.test-d.ts # Type tests
└── index.ts # Re-export
Core Patterns
Schemas define data types:
export interface StringSchema<TMessage> extends BaseSchema<...> {
readonly kind: 'schema';
readonly type: 'string';
// ...
}
Actions validate/transform in pipelines:
export interface EmailAction<TInput, TMessage> extends BaseValidation<...> {
readonly kind: 'validation';
readonly type: 'email';
// ...
}
Methods provide API functions:
export function parse<TSchema>(
schema: TSchema,
input: unknown
): InferOutput<TSchema>;
Key Types
BaseSchema,BaseValidation,BaseTransformation- Base interfacesInferOutput<T>,InferInput<T>,InferIssue<T>- Type inferenceConfig,ErrorMessage<T>,BaseIssue<T>- Configuration and errors'~standard'property - Standard Schema compatibility
Website (/website/src/routes/)
API Documentation
routes/api/
├── (schemas)/string/ # Schema docs
│ ├── index.mdx # MDX content
│ └── properties.ts # Type definitions
├── (actions)/email/ # Action docs
├── (methods)/parse/ # Method docs
├── (types)/StringSchema/ # Type docs
└── menu.md # Navigation
Guides
routes/guides/
├── (get-started)/ # Intro, installation
├── (main-concepts)/ # Schemas, pipelines, parsing
├── (schemas)/ # Objects, arrays, unions
├── (advanced)/ # Async, i18n, JSON Schema
├── (migration)/ # Version upgrades
└── menu.md # Navigation
Development
Playground
Use library/playground.ts for quick experimentation.
Adding a Schema/Action
- Create directory:
library/src/schemas/yourSchema/ - Create files:
yourSchema.ts,yourSchema.test.ts,yourSchema.test-d.ts,index.ts - Follow existing patterns (copy similar implementation)
- Export from category
index.ts - Run
pnpm -C library test
Modifying Core Types
⚠️ Changes to library/src/types/ affect the entire library. Always run full test suite.
Quick Lookups
| Looking for... | Location |
|---|---|
| Schema implementation | library/src/schemas/[name]/[name].ts |
| Action implementation | library/src/actions/[name]/[name].ts |
| Method implementation | library/src/methods/[name]/[name].ts |
| Type definitions | library/src/types/ |
| Internal utilities | library/src/utils/ |
| Error messages (i18n) | packages/i18n/[lang]/ |
| API docs page | website/src/routes/api/(category)/[name]/ |
| Guide page | website/src/routes/guides/(category)/[name]/ |
| Tests | Same directory as source, .test.ts suffix |
| Type tests | Same directory as source, .test-d.ts suffix |
Commands
# Library
pnpm -C library build # Build
pnpm -C library test # Run tests
pnpm -C library lint # Lint
pnpm -C library format # Format
# Website
pnpm -C website dev # Dev server
pnpm -C website build # Production build
# Root
pnpm install # Install all
pnpm format # Format all
Key Principles
- Modularity - Small, focused functions; one per file
- Zero dependencies - Core library has no runtime deps
- 100% test coverage - Required for library
- Tree-shakable - Use
// @__NO_SIDE_EFFECTS__annotation - Type-safe - Full TypeScript with strict mode
- ESM only - Imports include
.tsextensions
Do's and Don'ts
Do:
- Follow existing code patterns
- Write runtime and type tests
- Add JSDoc documentation
- Keep functions small and focused
- Check bundle size impact
Don't:
- Add external dependencies
- Modify core types without full test run
- Skip tests
- Create large multi-purpose functions
- Modify generated files (
dist/,coverage/)