handbook-validator

name	handbook-validator
description	Validate cursor-handbook structure, config, and component integrity. Use when the user asks to validate the setup, check for issues, or verify the handbook installation.

Skill: Handbook Validator

Validate that the cursor-handbook structure is correct, configuration is present, and components are well-formed.

Trigger

When the user asks to validate the handbook, check the setup, verify configuration, or troubleshoot missing components.

Prerequisites

• Inside a project with .cursor/ directory

Usage

Run the bundled script from the project root:

scripts/validate.sh

Steps

Step 1: Run Basic Validation

• Execute scripts/validate.sh using the Shell tool
• Capture pass/fail output
• The script checks:
  • .cursor/ directory exists
  • project.json or project.json.template present
  • hooks.json present
  • At least one .mdc rule file exists

Step 2: Extended Validation (if basic passes)

• Check for unresolved {{PLACEHOLDER}} values in project.json
• Verify all skill folders contain a SKILL.md
• Verify all agent files have a title and description
• Check that hook scripts referenced in hooks.json exist and are executable
• Verify .mdc rule files have valid frontmatter (description, globs, or alwaysApply)

Step 3: Report Results

• Present a summary table:

Check	Status	Details
.cursor/ exists	PASS/FAIL	—
project.json configured	PASS/WARN	Placeholder count
Rules present	PASS/FAIL	Count of .mdc files
Skills valid	PASS/WARN	Count with/without SKILL.md
Hooks wired	PASS/WARN	Missing scripts

Step 4: Suggest Fixes

• For each FAIL/WARN, provide a specific fix action
• Prioritize: FAIL items first, then WARN items
• Offer to auto-fix simple issues (e.g., create missing project.json from template)

Rules

• NEVER modify files without user confirmation
• Report all issues, don't stop at the first failure
• Distinguish between FAIL (blocking) and WARN (advisory)

Completion

Validation report with clear pass/fail status for each check and actionable fix suggestions for any issues found.

If a Step Fails

• .cursor/ not found: Suggest running the cursor-setup skill to bootstrap
• No rules found: Suggest copying from examples or running setup
• Permission errors: Check file permissions with ls -la