validate-skill-docs

Validate Skill Docs

After modifying skill workflows, flags, or documentation surfaces, run this validation to catch content drift between SKILL.md files and their docs/skills-meta.ts/README representations.

When to Use

Invoke this skill when you have modified any of:

• plugins/sdlc-utilities/skills/*/SKILL.md (workflow steps or flags changed)
• docs/skills/*.md (documentation content)
• site/src/data/skills-meta.ts (metadata entries)

Step 1 — Run the Validation Script

node .claude/skills/validate-skill-docs/check-docs-consistency.js

If the script exits 0: all checks pass — proceed.

If the script exits 1: fix each issue before finishing the task (see Step 2).

If the script exits 2: run from the repository root or pass --project-root <path>.

Step 2 — Fix Issues Found

For each finding, apply the appropriate fix:

user-invocable-match (error)

The userInvocable boolean in skills-meta.ts does not match the user-invocable frontmatter value in the skill's SKILL.md. Update one to match the other — the SKILL.md frontmatter is the source of truth.

connections-valid (error)

A connections[].to value in skills-meta.ts references a slug that does not exist in the skillsMeta array. Fix the typo or add the missing skill entry.

doc-template-sections (warning)

A docs/skills/<name>.md file is missing one or more required sections from the doc template. Add the missing sections using docs/skill-doc-template.md as the reference.

Required sections: Overview, Usage, Examples, Prerequisites, What It Creates or Modifies, Related Skills. The Flags section is optional.

doc-flags-present (warning)

A skill has -- flags in its argument-hint but the corresponding docs/skills/<name>.md Flags table does not mention any of them. Add the missing flags to the Flags table.

Step 3 — Re-run Validation

After fixing all issues:

node .claude/skills/validate-skill-docs/check-docs-consistency.js

Confirm exit 0 before marking work complete.