Validate And Fix

Validate and Fix

Run the repository validation and automatically fix common issues.

Usage

Run this skill when you want to check and fix all skills in the repository.

Step 1: Run Validation

just validate-verbose

Step 2: Parse and Categorize Errors

Common error types and their fixes:

Description contains newlines

Error: description contains newline characters

Fix: Edit the SKILL.md frontmatter to make the description a single line. Remove any \n or \r characters. Do not use YAML block scalars (|, >, |-, >-).

Name mismatch

Error: name 'X' doesn't match directory 'Y'

Fix: Edit the name field in frontmatter to match the parent directory name exactly (kebab-case).

Orphan files

Error: orphan file not referenced from SKILL.md: <path>

Fix: Either:

1. Add a reference to the file in SKILL.md (markdown link or backtick), or
2. Delete the file if it's not needed

Files exempt from orphan checks: package.json, bun.lock, .gitkeep.

Invalid sources format

Error: sources must use markdown link format

Fix: Convert plain URLs to [Title](url) format in the ## Sources section.

Word count exceeded

Error: word count exceeds 1500

Fix: Reduce content. Move detailed reference material into references/*.md files and link to them from SKILL.md.

Missing required fields

Error: missing required field: name|description

Fix: Add the missing field to the YAML frontmatter.

Step 3: Re-validate

After applying fixes, run validation again:

just validate

Repeat until all errors are resolved.

Step 4: Format

just fmt

Step 5: Final Check

just check

This runs lint + typecheck to confirm everything passes.