Skip to content
Skills Library
AI & agents · Analysis

debug-hooks

/debug-hooks

Claude Code only. Diagnose failing hooks: startup hook error, node loader errors, silent hooks. Use for "hook not working", "debug hooks". Not for MCP server errors.

Licence
MIT
Last repository change
06.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 06.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/validate-hooks.sh

What it does and when to use it

Claude Code only. Diagnose failing hooks: startup hook error, node loader errors, silent hooks. Use for "hook not working", "debug hooks". Not for MCP server errors.

Triggers from the description

hook not workingdebug hooks
Original author description

Claude Code only. Diagnose failing hooks: startup hook error, node loader errors, silent hooks. Use for "hook not working", "debug hooks". Not for MCP server errors.

How it works

  1. Common Hook Errors
  2. Full Diagnostic Procedure
  3. Fix Hook Schema Errors
  4. Remove Broken Hook
  5. LTX Schema
  6. Additional Resources
Original SKILL.md headings · 126 lines, 514 words
SKILL.md preview
---
name: debug-hooks
description: Claude Code only. Diagnose failing hooks: startup hook error, node loader errors, silent hooks. Use for "hook not working", "debug hooks". Not for MCP server errors.
---

# Debug Hooks

Diagnose and fix Claude Code hook errors. Covers startup hook failures, broken MCP configs, missing dependencies, and invalid hook schemas.

## Common Hook Errors

### Error: `node:internal/modules/cjs/loader`

Cause: Hook script references a Node.js file that doesn't exist or has bad require/import.

Fix procedure:
1. Read `~/.claude/settings.json` — find `SessionStart` hooks
2. Locate the referenced script path
3. Check if file exists: `ls [script-path]`
4. If missing: recreate or remove the hook entry
5. If exists: check for bad `require()` paths inside

### Error: `startup hook error`

Cause: Hook command fails on session start.

Fix procedure:
1. Run the hook command manually in terminal
2. Read error output
3. Common causes:
   - Missing npm package → `npm install [package]`
   - Wrong node version → check `node --version`
   - Bad file path → fix path in settings.json
   - Permission denied → `chmod +x [script]`

### Error: Hook silently does nothing

Cause: Wrong event matcher or hook not registered.

Fix procedure:
1. Read `hooks/hooks.json` or `settings.json` hooks section
2. Verify event name is exact: `PreToolUse`, `PostToolUse`, `SessionStart`, `Stop`, `SubagentStop`, `SessionEnd`, `UserPromptSubmit`, `PreCompact`, `Notification`
3. Verify matcher regex matches tool names
4. Test with `claude --debug` to see hook execution logs

## Full Diagnostic Procedure

```bash
# Step 1: Find all hook configs
find ~/.claude -name "hooks.json" 2>/dev/null
grep -r "hooks" ~/.claude/settings.json

# Step 2: Static-check each hook script (safe — no side effects)
bash -n [script].sh
node --check [script].mjs

# Step 3: Check node/python availability
which node && node --version
which python3 && python3 --version

# Step 4: Validate JSON syntax
python3 -m json.tool ~/.claude/settings.json
```

Run a hook script manually only when it's plausibly side-effect-free — a
hook may write files or hit a database; reproduce errors with static checks
first. Or run the bundled validator, which does all of the above:

```bash
CLAUDE_PLUGIN_ROOT=[plugin-dir] bash [plugin-dir]/skills/config/debug-hooks/scripts/validate-hooks.sh [config-file]
```

## Fix Hook Schema Errors

Valid hook entry structure:
```json
{
  "SessionStart": [{
    "hooks": [{
      "type": "command",
      "command": "bash $CLAUDE_PLUGIN_ROOT/scripts/my-hook.sh",
      "timeout": 30
    }]
  }]
}
```

Common schema mistakes:
- Missing `hooks` array wrapper
- `type` not set to `"command"`
- Hardcoded absolute path instead of `$CLAUDE_PLUGIN_ROOT`
- Timeout as string instead of number

## Remove Broken Hook

To safely remove a broken hook from settings.json:
1. Read the file
2. Identify the broken hook entry
3. Show user the entry to remove
4. Confirm before editing
5. Remove entry and validate JSON

## LTX Schema

Emit structured output as LTX rows when reporting hook validation results.

```
@v1:hook|status|error|fix
```

| Field | Description |
|-------|-------------|
| `hook` | Hook identifier or script path |
| `status` | `ok`, `warn`, `error`, `missing` |
| `error` | Short error description or `-` if none |
| `fix` | Suggested fix command/action or `-` if none |

Example:
```
@v1:hook|status|error|fix
SessionStart:session-start.sh|ok|-|-
SessionStart:broken-hook.sh|error|file not found|recreate or remove hook entry
```

## Additional Resources

- **`references/hook-errors.md`** — Full error catalog with root causes and fixes
- **`scripts/validate-hooks.sh`** — Script to validate all hook configs
- **`agents/hook-error-fixer.md`** — for multi-step diagnosis, hand off to this agent instead of debugging inline
Files in this package (3)
  • SKILL.md 4 KB
  • references/hook-errors.md 3 KB
  • scripts/validate-hooks.sh 5 KB

Versions

RepositoryScoreLicence
This page · kyuna0312/context_forge100MIT
vibeeval/vibecosystem100MIT

Database snapshot: 13.11.2026 · package version 35f40ce12ae1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100claude-code-hook-development
    This skill should be used when the user asks to "create a hook", "add a hook", "write a hook", or mentions Claude Code hooks. Also suggest this skill when the user asks to "automatically do X" or "run X before/after Y" as these are good candidates for hooks.
  • 100write-hook
    Use when Claude Code should do something by itself - at session start (`SessionStart`), on every prompt (`UserPromptSubmit`), or after each response (`Stop`) - or when that automation misbehaves. Symptoms: a hook script that runs but whose output never reaches the model, a…
  • 100hook-config-generator
    Guide for adding a new real Claude Code hook to this framework as a .ps1/.sh pair, or .sh only for a silent advisory hook (registration in hooks/hooks.json as a shell-form chain, dispatch allowlist, tests, validation) — use when asked to create, generate, or extend a hook or quality gate.
  • 100working-with-claude-code
    Use when working with Claude Code CLI, plugins, hooks, MCP servers, skills, configuration, or any Claude Code feature - provides comprehensive official documentation for all aspects of Claude Code
  • 100working-with-claude-code
    Use when working with Claude Code CLI, plugins, hooks, MCP servers, skills, configuration, or any Claude Code feature - provides comprehensive official documentation for all aspects of Claude Code
  • 100create-hook
    Create Cursor hooks. Use to create a hook, write hooks.json, add hook scripts, or automate behavior around agent events.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.