Pre-Commit Hooks
Pre-commit hooks keep generated skill, registry, and config surfaces from silently drifting before work leaves the checkout.
Use this page when setting up a fresh clone, debugging a blocked commit, or changing skill/config generation. It is a quickref; the canonical operational contracts live in Skill Sync Workflow, Bootstrap Sync, and Generated Surface Contract.
Install
Run:
bash scripts/install-git-hooks.sh
That installs the repo hook entry points. Agent config symlinks and Cursor user-scope hooks are handled through npm run bootstrap and the config-sync contract.
Validation Layers
| Moment | Mechanism | Catches |
|---|---|---|
| Edit time | Harness rules and symlinked skill runtime | Obvious source edits in the wrong layer. |
| Commit time | scripts/sync-skills.sh --check |
Missing SKILL.md, stale generated registry, stale runtime symlinks, retired root skill mirrors. |
| Shell safety | config/cursor/hooks/git-guard.sh and project rules |
Destructive git operations that could hide another agent's work. |
| Manual closeout | npm run skills:check, npm run routing-doctor, npx tsx scripts/doctor.ts --quiet |
Broader routing and wiki health regressions. |
Hooks are guardrails, not a substitute for source/projection closeout. If a hook blocks a commit because a generated surface is stale, update the source or generator, regenerate, and rerun the check.
What Hooks Should Not Do
Hooks should not rewrite prose, discard local changes, stash other agents' work, or regenerate large surfaces without the operator seeing the result. They should fail loudly with the command to run.
Closeout
After changing hook behavior, run npm run bootstrap, npm run skills:check, npx tsx scripts/doctor.ts --only config-sync, npm run build-index, and qmd update && qmd embed.
Timeline
- 2026-07-01 | Updated the hook doc into a layered validation contract covering skill sync, config sync, destructive-git safety, and generated-surface closeout. Source: User request, 2026-07-01
- 2026-06-27 | Updated hook contract for the generated skill registry and retired individual skill catalog pages. Source: User request, 2026-06-27
- 2026-06-24 | Updated hook contract to catch orphan skill catalog pages as failures. Source: User request, 2026-06-24
- 2026-05-31 | Agent doc compiled from AGENTS.md skill validation table. Source: AGENTS.md, 2026-05-31