Validation

skill-forge’s validation engine catches problems before they reach users. Run it early and often during development.

Running Validation

# Validate the skill in the current directory
skill-forge validate

# Validate a specific directory
skill-forge validate ./path/to/skill

# Verbose output with rule explanations
skill-forge validate --verbose

# JSON output for CI integration
skill-forge validate --format json

Validation Levels

Each rule has a severity level:

Level	Meaning	Effect
error	Must fix before publishing	Blocks skill-forge publish
warning	Should fix, but not blocking	Shows yellow warning
info	Suggestion for improvement	Shows blue hint

Rule Reference

Structure Rules

Rule	Level	Description
skill-md-exists	error	SKILL.md must exist at skill root
skill-md-not-empty	error	SKILL.md must have content
no-nested-skills	error	No SKILL.md in subdirectories
references-valid	warning	References directory should exist if referenced

Content Rules

Rule	Level	Description
has-description	error	SKILL.md must have a Description section
has-when-to-use	error	SKILL.md must have a When to Use section
has-instructions	error	SKILL.md must have an Instructions section
no-duplicate-headers	warning	Section headers should be unique
no-empty-sections	warning	Sections should have content

Reference Integrity Rules

Rule	Level	Description
refs-resolve	error	All referenced file paths must exist
no-broken-symlinks	error	No broken symbolic links in references/
no-absolute-paths	warning	Use relative paths, not absolute
no-parent-traversal	warning	Avoid ../ in reference paths

Best Practice Rules

Rule	Level	Description
has-readme	info	Include a README.md for humans
reasonable-size	warning	SKILL.md should be under 500 lines
instructions-specific	info	Instructions should have numbered steps

CI Integration

Add validation to your CI pipeline:

.github/workflows/validate.yml

name: Validate Skill
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx skill-forge validate --format json

Custom Rules

Create project-specific validation rules:

.skill-forge/rules/custom-rule.js

export default {
  name: 'require-examples',
  level: 'warning',
  message: 'SKILL.md should include an Examples section',
  check(skill) {
    return skill.sections.some(s => s.title === 'Examples');
  }
};