Handbook Validator

Name: Handbook Validator
Author: girijashankarj

girijashankarj/cursor-handbook

1 installs
27 repo stars
Updated April 25, 2026
girijashankarj/cursor-handbook

Validates cursor-handbook structure, config, and components by checking the .cursor directory, project.json, hooks, and rule files.

About

Validates that a cursor-handbook installation is correct, configured, and well-formed. A developer uses it to verify the setup or troubleshoot missing components.

Runs scripts/validate.sh for basic structure checks
Flags unresolved placeholders and missing hook scripts

Handbook Validator by the numbers

1 all-time installs (skills.sh)
Ranked #14,102 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Jul 22, 2026 (Skillselion catalog sync)

npx skills add https://github.com/girijashankarj/cursor-handbook --skill handbook-validator

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/girijashankarj/cursor-handbook/handbook-validator.svg)](https://skillselion.com/skills/girijashankarj/cursor-handbook/handbook-validator)

Installs	1
repo stars	★ 27
Last updated	April 25, 2026
Repository	girijashankarj/cursor-handbook ↗

What it does

Validates cursor-handbook structure, config, and components by checking the .cursor directory, project.json, hooks, and rule files.

Files

SKILL.mdMarkdownGitHub ↗

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

#!/bin/bash
# Validate cursor-handbook structure and config.

set -e

ERRORS=0

echo "Validating cursor-handbook..."

# Check .cursor exists
if [ ! -d ".cursor" ]; then
  echo "FAIL: .cursor directory not found"
  ERRORS=$((ERRORS + 1))
fi

# Check config
if [ ! -f ".cursor/config/project.json" ] && [ ! -f ".cursor/config/project.json.template" ]; then
  echo "WARN: No project.json or project.json.template in .cursor/config/"
fi

# Check hooks.json (Cursor reads .cursor/hooks.json at project root only)
if [ ! -f ".cursor/hooks.json" ]; then
  echo "WARN: No .cursor/hooks.json found (Cursor expects project-level hooks there)"
fi

# Check at least one rule
if [ ! -d ".cursor/rules" ] || [ -z "$(find .cursor/rules -name '*.mdc' 2>/dev/null | head -1)" ]; then
  echo "FAIL: No .mdc rules found in .cursor/rules/"
  ERRORS=$((ERRORS + 1))
fi

if [ $ERRORS -eq 0 ]; then
  echo "OK: Basic structure valid"
else
  echo "Found $ERRORS error(s)"
  exit 1
fi