Convert prompts folder to agent skills standard

.github/copilot-instructions.md → AGENTS.md

@@ -33,6 +33,10 @@ pnpm -C website dev             # Start docs site
 - **JSDoc required** on exported functions (first overload only for overload sets)
 - **`// @__NO_SIDE_EFFECTS__`** before pure factory functions for tree-shaking
 
+## Other Rules
+
+- **Source code is the single source of truth.** All documentation must match `/library/src/`.
+
 ## Library Architecture
 
 Schemas, actions, and methods are plain objects with a `'~run'` method:
@@ -48,17 +52,8 @@ library/src/
 
 Each has its own folder: `name.ts`, `name.test.ts`, `name.test-d.ts`, `index.ts`.
 
-## Detailed Guides
-
-**Before performing any task listed below, OPEN and READ the corresponding guide file.**
+## Agent Skills
 
-| Task                          | Guide (read before starting)                                                      |
-| ----------------------------- | --------------------------------------------------------------------------------- |
-| Navigate repo, find files     | [prompts/repository-structure.md](../prompts/repository-structure.md)             |
-| Write JSDoc / inline comments | [prompts/document-source-code.md](../prompts/document-source-code.md)             |
-| Review PRs and source changes | [prompts/review-source-code-changes.md](../prompts/review-source-code-changes.md) |
-| Add new API page to website   | [prompts/add-new-api-to-website.md](../prompts/add-new-api-to-website.md)         |
-| Update existing API docs      | [prompts/update-api-on-website.md](../prompts/update-api-on-website.md)           |
-| Add guide/tutorial to website | [prompts/add-new-guide-to-website.md](../prompts/add-new-guide-to-website.md)     |
+This repository includes agent skills in `/skills/` following the [Agent Skills](https://agentskills.io) open standard.
 
-**Source code is the single source of truth.** All documentation must match `/library/src/`.
+**Naming:** Skills prefixed with `repo-` are local repository skills

prompts/document-source-code.md → skills/repo-source-code-document/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: repo-source-code-document
+description: Write JSDoc comments and inline documentation for Valibot library source code in /library/src/. Use when documenting schemas, actions, methods, or utilities. Covers interface documentation, function overloads, purity annotations, inline comment patterns, and terminology consistency.
+---
+
 # Valibot Source Code Documentation
 
 Documentation patterns for library source code in `/library/src/`.
@@ -82,10 +87,11 @@ Add hints after the main description, before `@param`:
 
 Link to external resources when relevant using markdown format:
 
-````typescript
+```typescript
 /**
  * Creates an [email](https://en.wikipedia.org/wiki/Email_address) validation action.
  */
+```
 
 ### Implementation Function
 
@@ -96,9 +102,11 @@ The implementation has **NO JSDoc** but uses `// @__NO_SIDE_EFFECTS__`:
 export function string(
   message?: ErrorMessage<StringIssue>
 ): StringSchema<ErrorMessage<StringIssue> | undefined> {
-  return { /* ... */ };
+  return {
+    /* ... */
+  };
 }
-````
+```
 
 **`// @__NO_SIDE_EFFECTS__` rules:**
 

prompts/review-source-code-changes.md → skills/repo-source-code-review/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: repo-source-code-review
+description: Review pull requests and source code changes in /library/src/. Use when reviewing PRs, validating implementation patterns, or checking code quality before merging. Covers code quality checks, type safety, documentation review, test coverage, and common issues to watch for.
+---
+
 # Reviewing Source Code Changes
 
 Guide for reviewing PRs and source code changes in `/library/src/`.
@@ -91,7 +96,7 @@ export function minLength<
 | Unwrap methods | `Unwraps ...`                                  |
 | Other methods  | `Creates a ...`, `Returns ...`, `Forwards ...` |
 
-See [document-source-code.md](./document-source-code.md) for full documentation rules.
+See `repo-source-code-document` skill for full documentation rules.
 
 ### Tests
 
@@ -123,7 +128,7 @@ See [document-source-code.md](./document-source-code.md) for full documentation
 - [ ] Type tests in `.test-d.ts`
 - [ ] Naming conventions followed
 
-## Related Guides
+## Related Skills
 
-- [repository-structure.md](./repository-structure.md) — Navigate the codebase
-- [document-source-code.md](./document-source-code.md) — JSDoc requirements
+- `repo-structure-navigate` — Navigate the codebase
+- `repo-source-code-document` — JSDoc requirements

prompts/repository-structure.md → skills/repo-structure-navigate/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: repo-structure-navigate
+description: 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.
+---
+
 # Valibot Repository Structure
 
 ## Monorepo Layout
@@ -13,7 +18,8 @@ valibot/
 │   └── zod-to-valibot/      # Zod converter
 ├── website/          # valibot.dev (Qwik + Vite)
 ├── brand/            # Brand assets
-└── prompts/          # AI agent guides
+├── skills/           # Agent skills (this folder)
+└── prompts/          # Legacy AI agent guides
 ```
 
 ## Core Library (`/library/src/`)

prompts/add-new-api-to-website.md → skills/repo-website-api-create/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: repo-website-api-create
+description: Create new API reference pages for the Valibot website at website/src/routes/api/. Use when adding documentation for new schemas, actions, methods, or types. Covers reading source code, creating properties.ts and index.mdx files, updating menu.md, and cross-referencing related APIs.
+---
+
 # Adding API Documentation to Website
 
 Guide for creating new API reference pages at `website/src/routes/api/`.
@@ -256,7 +261,7 @@ Existing API pages have a `## Related` section with `<ApiList>` components. When
 **Rule:** An API is "related" if:
 
 - It makes sense to use it as an argument of the other API, or vice versa
-- It make sense to use them together in the same `pipe` (e.g., `v.pipe(v.string(), v.email())` → `string` and `email` are related)
+- It makes sense to use them together in the same `pipe` (e.g., `v.pipe(v.string(), v.email())` → `string` and `email` are related)
 
 Examples:
 

prompts/update-api-on-website.md → skills/repo-website-api-update/SKILL.md

@@ -1,8 +1,13 @@
+---
+name: repo-website-api-update
+description: Update existing API documentation pages after source code changes. Use when syncing docs with library changes like new parameters, type constraint changes, interface updates, or function renames. Covers common change patterns and verification steps.
+---
+
 # Updating API Documentation
 
 Guide for syncing API docs with source code changes.
 
-**Prerequisite:** Read [add-new-api-to-website.md](./add-new-api-to-website.md) for `properties.ts` and `index.mdx` patterns.
+**Prerequisite:** Read the `repo-website-api-create` skill for `properties.ts` and `index.mdx` patterns.
 
 ## When to Update
 

prompts/add-new-guide-to-website.md → skills/repo-website-guide-create/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: repo-website-guide-create
+description: 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.
+---
+
 # Adding Guides to Website
 
 Guide for creating conceptual documentation at `website/src/routes/guides/`.