Przejdź do treści
Biblioteka skilli
AI i agenci · Analiza

debug-hooks

/debug-hooks

Diagnozuje niedziałające hooki Claude Code: błędy hooka przy starcie, błędy loadera Node i hooki, które milczą, z wyłączeniem błędów serwerów MCP.

Repozytorium
context_forge ↗
Licencja
MIT
Ostatnia zmiana repozytorium
06.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
1
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 06.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/validate-hooks.sh

Co robi i kiedy

Diagnozuje niedziałające hooki Claude Code: błędy hooka przy starcie, błędy loadera Node i hooki, które milczą, z wyłączeniem błędów serwerów MCP.

Wyzwalacze z opisu

hook not workingdebug hooks
Oryginalny opis (EN)

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.

Jak działa

  1. Common Hook Errors
  2. Full Diagnostic Procedure
  3. Fix Hook Schema Errors
  4. Remove Broken Hook
  5. LTX Schema
  6. Additional Resources
Sekcje z nagłówków SKILL.md, w oryginale · 126 linii, 514 słów
Podgląd SKILL.md
---
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
Pliki w paczce (3)
  • SKILL.md 4 KB
  • references/hook-errors.md 3 KB
  • scripts/validate-hooks.sh 5 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · kyuna0312/context_forge100MIT
vibeeval/vibecosystem100MIT

Migawka bazy z 13.11.2026 · wersja paczki 35f40ce12ae1 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100claude-code-hook-development
    Pomaga tworzyć hooki Claude Code oraz sugeruje je przy prośbach o automatyczne wykonanie czegoś przed lub po innej akcji.
  • 100write-hook
    Konfiguruje hooki Claude Code uruchamiane na początku sesji, przy każdym poleceniu lub po odpowiedzi i diagnozuje ich błędy.
  • 100hook-config-generator
    Prowadzi przez dodanie nowego hooka Claude Code do frameworka jako pary .ps1 i .sh: rejestracja w hooks.json, lista dozwolonych wywołań, testy i walidacja.
  • 100working-with-claude-code
    Dostarcza dokumentację Claude Code: CLI, wtyczki, hooki, serwery MCP, skille i konfigurację.
  • 100working-with-claude-code
    Opisuje Claude Code: instalację, wtyczki, hooki, MCP, skille i ustawienia na podstawie oficjalnej dokumentacji.
  • 100create-hook
    Tworzy hooki Cursor: plik hooks.json i skrypty automatyzujące zachowanie wokół zdarzeń agenta.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.