hr-skills: Skill for Claude Code

Valibot in hr-skills

This skill covers how Valibot is used within the hr-skills monorepo specifically. It is not a general Valibot reference — see valibot.dev for the full API. The focus here is on the patterns, conventions, and pitfalls that appear in this codebase.

Where Valibot is used

Two files define schemas; all other packages consume them:

• packages/hr-skills-ref/src/client/schema.ts — SkillPropertiesSchema, the generic Agent Skills shape used by readProperties() in loader.ts
• packages/hr-skills-build/src/client/shared/schema.ts — MarketplaceJsonSchema (validates .claude-plugin/marketplace.json), SkillFrontmatterSchema (used by parseSkillFrontmatter() in parser.ts), and RegistrySchema (used by validateRegistryConsistency() in validate-registry.ts to check registry/skills.json against its schema)

Import pattern used throughout the repo:

import * as v from 'valibot';

Never use named imports (import { object, string } from 'valibot') — the wildcard * as v is the established convention here.

Supported tasks

• Write or extend a schema in schema.ts for a new frontmatter field
• Add a v.pipe(v.string(), v.trim()) field to an existing object schema
• Handle a v.safeParse() result correctly in parser.ts or loader.ts
• Infer the output type from a schema with v.InferOutput<typeof Schema>
• Add an optional field to SkillPropertiesSchema or SkillFrontmatterSchema
• Validate marketplace.json shape against MarketplaceJsonSchema in sync.ts
• Add a v.record() field for arbitrary string metadata
• Debug a failed v.safeParse() result using v.summarize(result.issues)
• Make a field optional without breaking the existing type contract
• Understand why v.safeParse is used instead of v.parse in this repo

Key prompts

Schema authoring

1. "Add an optional [field] field to SkillPropertiesSchema that accepts a trimmed string."
2. "Write the Valibot schema for a new marketplace plugin entry with fields [list]."
3. "I need to validate a [shape] object in hr-skills-build. Write the schema."
4. "Add a required string field [name] to SkillFrontmatterSchema with trim applied."