feat: Add skill structure validation script and CI job

[mcj-coder]

Summary

Implement the structure validation automation recommended in the retrospective
(2026-01-16-skills-repository-improvement-plan.md).

Requirements

1. Create validation script that checks:

   • Required files exist (SKILL.md, *.test.md)
   • Required sections present (Overview, When to Use, Core Workflow)
   • Frontmatter has required fields (name, description)
   • references/README.md exists if references/ directory exists

2. Add validation to CI workflow

3. Add npm script for local validation

Acceptance Criteria

• Script created at scripts/validate-skill-structure.cjs (PR #389)
• Script validates all structure requirements from SKILL-FORMAT.md (evidence)
• Script has clear error messages with file paths and line numbers (evidence)
• CI job added to .github/workflows/ci.yml (PR #389)
• npm script added: npm run validate:skills (PR #389)
• Validation script runs successfully on all 55 skills (evidence)
• Lint passes (evidence)

Plan

See docs/plans/2026-01-16-skill-structure-validation.md

Note

The validation script correctly identifies 45 compliance issues in existing skills. This is expected behavior - the tooling is working as designed and will drive future compliance work. The CI job is set to continue-on-error: true temporarily.

Labels

enhancement, ci

[mcj-coder]

Plan

Implementation plan created: docs/plans/2026-01-16-skill-structure-validation.md

Tasks Overview

Task	Description	Files
1	Create script foundation	scripts/validate-skill-structure.cjs
2	Add file existence validation	scripts/validate-skill-structure.cjs
3	Add frontmatter validation	scripts/validate-skill-structure.cjs
4	Add section validation	scripts/validate-skill-structure.cjs
5	Add npm script	package.json
6	Add CI job	.github/workflows/ci.yml
7	Final verification and PR	Issue #388, PR

[mcj-coder]

Verification Evidence

Validation Script

npm run validate:skills runs successfully and validates all 55 skills.

Results:

• Files validated: SKILL.md, *.test.md, references/README.md
• Frontmatter validated: name, description fields
• Sections validated: Overview, When to Use, Core Workflow

Current findings: 45 validation errors across 28 skills that don't meet the SKILL-FORMAT.md standard. This is expected - the script is working correctly and will drive future compliance.

Lint

npm run lint passes with 0 errors across 454 files.

CI Job

Added skill-validation job to .github/workflows/ci.yml

Files Changed

• scripts/validate-skill-structure.cjs (new - validation script)
• package.json (added validate:skills script)
• .github/workflows/ci.yml (added skill-validation job)
• docs/plans/2026-01-16-skill-structure-validation.md (implementation plan)

[mcj-coder]

Plan approved. Proceeding with implementation.