AI i agenci · Automatyzacja
create-hook
/create-hook
Tworzy hooki Cursor: plik hooks.json i skrypty automatyzujące zachowanie wokół zdarzeń agenta.
- Autor
- kensaurus ↗
- Repozytorium
- cursor-kenji ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 19.10.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
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Przestarzałość
Brak sygnałów. Repozytorium zmienione 19.10.2026, bez odwołań do wycofanych modeli i API.
Licencja
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Tworzy hooki Cursor: plik hooks.json i skrypty automatyzujące zachowanie wokół zdarzeń agenta.
Oryginalny opis (EN)
Create Cursor hooks. Use to create a hook, write hooks.json, add hook scripts, or automate behavior around agent events.
Jak działa
- Gather Requirements
- Choose the Right Location
- Choose the Hook Event
- Hooks File Format
- Matchers
- Command Hooks
- Prompt Hooks
- Event Output Cheat Sheet
- Implementation Workflow
- Validation and Troubleshooting
Sekcje z nagłówków SKILL.md, w oryginale · 234 linii, 1 357 słów
Podgląd SKILL.md
---
name: create-hook
description: Create Cursor hooks. Use to create a hook, write hooks.json, add hook scripts, or automate behavior around agent events.
disable-model-invocation: true
---
# Creating Cursor Hooks
Create hooks when you want Cursor to run custom logic before or after agent events. Hooks are scripts or prompt-based checks that exchange JSON over stdin/stdout and can observe, block, modify, or follow up on behavior.
When the user asks for a hook, don't stop at describing the format. Gather the missing requirements, then create or update the hook files directly.
## Gather Requirements
Before you write anything, determine:
1. **Scope**: Should this be a project hook or a user hook?
2. **Trigger**: Which event should run the hook?
3. **Behavior**: Should it audit, deny/allow, rewrite input, inject context, or continue a workflow?
4. **Implementation**: Should it be a command hook (script) or a prompt hook?
5. **Filtering**: Does it need a matcher so it only runs for certain tools, commands, or subagent types?
6. **Safety**: Should failures fail open or fail closed?
Infer these from the conversation when possible. Only ask for the missing pieces.
## Choose the Right Location
- **Project hooks**: `.cursor/hooks.json` and `.cursor/hooks/*`
- **User hooks**: `~/.cursor/hooks.json` and `~/.cursor/hooks/*`
Path behavior matters:
- **Project hooks** run from the project root, so use paths like `.cursor/hooks/my-hook.sh`
- **User hooks** run from `~/.cursor/`, so use paths like `./hooks/my-hook.sh` or `hooks/my-hook.sh`
Prefer **project hooks** when the behavior should be shared with the repository and checked into version control.
## Choose the Hook Event
Use the narrowest event that matches the user's goal.
### Common Agent events
- `sessionStart`, `sessionEnd`: set up or audit a session
- `preToolUse`, `postToolUse`, `postToolUseFailure`: work across all tools
- `subagentStart`, `subagentStop`: control or continue Task/subagent workflows
- `beforeShellExecution`, `afterShellExecution`: gate or audit terminal commands
- `beforeMCPExecution`, `afterMCPExecution`: gate or audit MCP tool calls
- `beforeReadFile`, `afterFileEdit`: control file reads or post-process edits
- `beforeSubmitPrompt`: validate prompts before they are sent
- `preCompact`: observe context compaction
- `stop`: handle agent completion
- `afterAgentResponse`, `afterAgentThought`: track agent output or reasoning
### Tab events
- `beforeTabFileRead`: control file access for inline completions
- `afterTabFileEdit`: post-process edits made by Tab
### Quick event chooser
- **Block or approve shell commands** -> `beforeShellExecution`
- **Audit shell output** -> `afterShellExecution`
- **Format files after edits** -> `afterFileEdit`
- **Block or rewrite a specific tool call** -> `preToolUse`
- **Add follow-up context after a tool succeeds** -> `postToolUse`
- **Control whether subagents can run** -> `subagentStart`
- **Chain subagent loops** -> `subagentStop`
- **Check prompts for secrets or policy violations** -> `beforeSubmitPrompt`
- **Protect MCP calls** -> `beforeMCPExecution`
## Hooks File Format
Create a `hooks.json` file with schema version 1:
```json
{
"version": 1,
"hooks": {
"afterFileEdit": [
{
"command": ".cursor/hooks/format.sh"
}
]
}
}
```
Each hook definition can include:
- `command`: shell command or script path
- `type`: `"command"` or `"prompt"` (defaults to `"command"`)
- `timeout`: timeout in seconds
- `matcher`: filter for when the hook runs
- `failClosed`: block the action when the hook crashes, times out, or returns invalid JSON
- `loop_limit`: mainly for `stop` and `subagentStop` follow-up loops
## Matchers
Use matchers to avoid running the hook on every event.
- `preToolUse` / `postToolUse` / `postToolUseFailure`: match on tool type such as `Shell`, `Read`, `Write`, `Task`, or MCP tools in `MCP: ...` form
- `subagentStart` / `subagentStop`: match on subagent type such as `generalPurpose`, `explore`, or `shell`
- `beforeShellExecution` / `afterShellExecution`: match on the full shell command string
- `beforeReadFile`: match on tool type such as `Read` or `TabRead`
- `afterFileEdit`: match on tool type such as `Write` or `TabWrite`
- `beforeSubmitPrompt`: matches the value `UserPromptSubmit`
Important matcher warning:
- Matchers use JavaScript-style regular expressions, not POSIX/grep syntax
- Do not use POSIX classes like `[[:space:]]`; use JavaScript equivalents like `\s`
- If the matcher is at all tricky, start by getting the hook working without one or with a very simple matcher, then tighten it after the hook is confirmed to load and fire
If the user wants a hook for only one risky command family, prefer script-side filtering for the first working version and add a matcher afterward only if it is simple and clearly correct.
## Command Hooks
Command hooks are the default. They receive JSON on stdin and can return JSON on stdout.
Before using a command hook, verify that every executable it depends on will actually run in the hook environment:
- the script itself has a valid shebang and is executable
- any helper binary it calls is already installed and on `$PATH`
- if the script depends on tools like `jq`, `python3`, `node`, or repo-local CLIs, verify that explicitly before finishing
Do not assume a binary exists just because it is common on your machine.
### Minimal project-level example
```json
{
"version": 1,
"hooks": {
"beforeShellExecution": [
{
"command": ".cursor/hooks/approve-network.sh",
"matcher": "curl|wget|nc ",
"failClosed": true
}
]
}
}
```
```bash
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.command // empty')
if [[ "$command" =~ curl|wget|nc ]]; then
echo '{
"permission": "ask",
"user_message": "This command may make a network request. Please review it before continuing.",
"agent_message": "A hook flagged this shell command as a possible network call."
}'
exit 0
fi
echo '{ "permission": "allow" }'
exit 0
```
Important behavior:
- Exit code `0`: success
- Exit code `2`: block the action, same as returning deny
- Other non-zero exit codes: fail open by default unless `failClosed: true`
Make hook scripts executable after creating them (`chmod +x`): a non-executable script errors, and by default that fails open, so the hook silently does nothing.
## Prompt Hooks
Prompt hooks are useful when the policy is easier to describe than to script.
```json
{
"version": 1,
"hooks": {
"beforeShellExecution": [
{
"type": "prompt",
"prompt": "Does this command look safe to execute? Only allow read-only operations. Here is the hook input: $ARGUMENTS",
"timeout": 10
}
]
}
}
```
Use prompt hooks for lightweight policy decisions. Prefer command hooks when the logic must be deterministic or when the user needs exact, auditable behavior.
## Event Output Cheat Sheet
Use the event's supported output fields only.
- `preToolUse`: can return `permission`, `user_message`, `agent_message`, and `updated_input`
- `postToolUse`: can return `additional_context`; for MCP tools it can also return `updated_mcp_tool_output`
- `subagentStart`: can return `permission` and `user_message`
- `subagentStop`: can return `followup_message`
- `beforeShellExecution` / `beforeMCPExecution`: can return `permission`, `user_message`, and `agent_message`
When the user wants to rewrite a tool call, prefer `preToolUse`. When they want to gate only shell commands, prefer `beforeShellExecution`.
## Implementation Workflow
1. Pick the correct location and event
2. Create or update the correct `hooks.json` file
3. Start with no matcher or the simplest safe matcher
4. Create the script under the matching hooks directory
5. Read stdin JSON and implement the required behavior
6. Make the script executable
7. Verify any helper executables the script uses are installed and on `$PATH`
8. Trigger the relevant action to test the hook
9. Verify behavior in Cursor's **Hooks** settings tab or the **Hooks** output channel
If you are editing an existing hooks setup, preserve unrelated hooks and only change the minimum necessary entries.
## Validation and Troubleshooting
- Cursor watches `hooks.json` and reloads on save
- If hooks still do not load, restart Cursor
- Double-check relative paths:
- project hooks -> relative to the project root
- user hooks -> relative to `~/.cursor/`
- If the hook does not appear to load at all, suspect matcher/config parsing first; remove the matcher and confirm the base hook works before tightening it
- If the script runs external commands, verify each one is installed and reachable from the hook process with `command -v` or equivalent
- If the hook should block on failure, set `failClosed: true`
- If a command hook should intentionally block, returning exit code `2` is valid
## Final Checklist
- [ ] Used the correct hook location and path style
- [ ] Chose the narrowest correct event
- [ ] Added a matcher when appropriate
- [ ] Returned only fields supported by that hook event
- [ ] Made the script executable
- [ ] Tested the hook by triggering the real event
- [ ] Checked the Hooks tab or Hooks output channel if debugging was needed
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · kensaurus/cursor-kenji | 100 | MIT |
| khaledsaeed18/dotclaude | 100 | MIT |
| hwells4/create-hooks | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki eb0a00d46451 (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
- 90Codex CLI Hooks
Tworzy i konfiguruje hooki Codex CLI: zdarzenia sesji, blokowanie poleceń oraz format wejścia i wyjścia. - 100claude-code-hook-development
Pomaga tworzyć hooki Claude Code oraz sugeruje je przy prośbach o automatyczne wykonanie czegoś przed lub po innej akcji. - 100hooks-create
Tworzy działający hook Claude Code z opisu zachowania w zwykłym języku: dobiera zdarzenie, pisze skrypt i podłącza go w .claude/settings.json. - 90hook-inventory
Inwentaryzuje hooki w ustawieniach użytkownika, projektu i lokalnych oraz w katalogu ~/.claude/hooks przez API Config Explorer i oznacza hooki wysyłające dane do sieci lub uruchamiające dowolne polecenia. - 100ac-meta-hook-writer
Pomaga pisać skrypty hook w Pythonie: poprawny schemat JSON, zgodność z formatami PreToolUse i PostToolUse oraz zasadę bezpiecznego działania przy błędzie. - 100codex-hooks-builder
Tworzy paczki hooków Codex, waliduje schemat hooks.json, sprawdza uprawnienia skryptów, migruje konfigurację i diagnozuje błędy wykonania hooków cyklu życia subagentów i narzędzi.