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

hook-scope-guide

/hook-scope-guide

Pomaga wybrać zakres hooka (plugin, projekt, globalny) według grona odbiorców przy jego tworzeniu.

Licencja
MIT
Ostatnia zmiana repozytorium
01.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
2
Przestarzałość

Brak sygnałów. Repozytorium zmienione 01.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

Pomaga wybrać zakres hooka (plugin, projekt, globalny) według grona odbiorców przy jego tworzeniu.

Oryginalny opis (EN)

Select hook scope (plugin, project, global) by audience. Use when authoring a hook.

Jak działa

  1. Overview
  2. When NOT To Use
  3. Important: Auto-Loading Behavior
  4. The Three Scopes
  5. Decision Framework
  6. Scope Details
  7. Loading Order & Precedence
  8. Quick Reference: Scope Selection
  9. Security Considerations
  10. Common Patterns by Scope
Sekcje z nagłówków SKILL.md, w oryginale · 284 linii, 1 196 słów
Podgląd SKILL.md
---
name: hook-scope-guide
description: 'Select hook scope (plugin, project, global) by audience. Use when authoring a hook.'
category: hook-development
---

# Hook Scope Decision Guide

## Overview

This skill helps you choose the right location for Claude Code hooks based on their purpose, audience, and persistence needs.

## When NOT To Use

- Writing the hook itself (use `abstract:hook-authoring`)
- Scoring an existing hook (use `abstract:hooks-eval`)

## Important: Auto-Loading Behavior

> **`hooks/hooks.json` is automatically loaded** by Claude Code when the plugin is enabled.
> Do NOT add `"hooks": "./hooks/hooks.json"` to your `plugin.json` - this causes duplicate load errors.
> The `hooks` field in `plugin.json` is only needed for additional hook files beyond the standard `hooks/hooks.json`.

## The Three Scopes

| Scope | Location | Audience | Committed? | Persistence |
|-------|----------|----------|------------|-------------|
| **Plugin** | `hooks/hooks.json` in plugin | Plugin users | With plugin | When plugin enabled |
| **Project** | `.claude/settings.json` | Team members | Yes (repo) | Per project |
| **Global** | `~/.claude/settings.json` | Only you | Never | All sessions |

## Decision Framework

### Question 1: Who needs this hook?

**Only plugin users** → Plugin hooks
- Hook is part of plugin's core functionality
- Users expect it when they enable your plugin
- Example: A YAML plugin validates YAML syntax on edit

**All team members on this project** → Project hooks
- Codebase-specific rules or protections
- Team conventions that should be enforced
- Example: Block modifications to `/src/production/` configs

**Only me, everywhere** → Global hooks
- Personal preferences or workflow optimizations
- Cross-project utilities like logging
- Example: Log all bash commands to personal audit trail

### Question 2: Should this be version controlled?

**Yes, as part of a distributable plugin** → Plugin hooks
**Yes, shared with team in repo** → Project hooks
**No, keep private** → Global hooks

### Question 3: What's the persistence requirement?

**Only when my plugin is active** → Plugin hooks
**Always in this specific project** → Project hooks
**Always, in every project I work on** → Global hooks

## Scope Details

### Plugin Hooks

**Location**: `<plugin-root>/hooks/hooks.json`

**When to use**:
- The hook is intrinsic to your plugin's functionality
- It should automatically activate when users enable your plugin
- It only makes sense in the context of your plugin's features

**Configuration**:
```json
{
  "PreToolUse": [
    {
      "matcher": "Read",
      "hooks": [{
        "type": "command",
        "command": "echo \"Plugin reading: $(jq -r '.tool_input.file_path')\" >> ${CLAUDE_PLUGIN_ROOT}/log.txt"
      }]
    }
  ]
}
```

> **Note**: Use string matchers (`"Read"`) not object matchers (`{"toolName": "Read"}`).

**Key features**:
- Use `${CLAUDE_PLUGIN_ROOT}` for plugin-relative paths
- Auto-merges when plugin is enabled
- Deactivates when plugin is disabled

**Examples**:
- Validation hook for a linting plugin
- Auto-formatting hook for a code style plugin
- Logging hook for a debugging plugin

### Project Hooks

**Location**: `.claude/settings.json` (in project root)

**When to use**:
- Enforcing team-wide policies
- Protecting project-specific resources
- Codebase conventions that should survive across team members
- Rules that should be reviewed in PRs

**Configuration**:
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "cmd=$(jq -r '.tool_input.command // empty'); if [[ \"$cmd\" == *\"production\"* ]]; then echo 'BLOCKED: Production access requires approval'; exit 1; fi"
        }]
      }
    ]
  }
}
```

> **Note**: Use string matchers (`"Bash"`) not object matchers.

**Key features**:
- Committed to version control
- Shared across all team members
- Changes are visible in PRs (governance trail)
- Project-specific, not personal

**Examples**:
- Block modifications to production configs
- Require test commands before completion
- Warn about editing sensitive directories
- Enforce project naming conventions

### Global Hooks

**Location**: `~/.claude/settings.json`

**When to use**:
- Personal workflow preferences
- Cross-project utilities
- Organization-wide compliance you want everywhere
- Private rules that shouldn't be shared

**Configuration**:
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "echo \"$(date): $(jq -r '.tool_name')\" >> ~/.claude/audit.log"
        }]
      }
    ]
  }
}
```

**Key features**:
- Never committed to any repo
- Applies to ALL Claude Code sessions
- Personal to your user account
- Survives across projects

**Examples**:
- Personal audit logging
- Cross-project safety rules
- Custom notification integrations
- Development environment preferences

## Loading Order & Precedence

Claude Code loads settings in this priority (highest first):

1. **Enterprise policies** (organization-managed)
2. **Command-line arguments** (`claude --flag`)
3. **Local project settings** (`.claude/settings.local.json`)
4. **Shared project settings** (`.claude/settings.json`)
5. **User settings** (`~/.claude/settings.json`)

**Important**: Multiple hooks from different scopes can respond to the same event. When they do, **all matching hooks execute in parallel**.

## Quick Reference: Scope Selection

```
Is this hook part of a plugin's core functionality?
├─ YES → Plugin hooks (hooks/hooks.json in plugin)
└─ NO ↓

Should all team members on this project have this hook?
├─ YES → Project hooks (.claude/settings.json)
└─ NO ↓

Should this hook apply to all my Claude sessions?
├─ YES → Global hooks (~/.claude/settings.json)
└─ NO → Reconsider if you need a hook at all
```

## Security Considerations

**Plugin hooks**:
- Audited as part of plugin installation
- Users consent when enabling plugin
- Scope limited to plugin's purpose

**Project hooks**:
- Visible to all team members
- Changes reviewed in PRs
- Should reflect team consensus

**Global hooks**:
- Execute with your credentials everywhere
- Can affect all projects unexpectedly
- Review security implications carefully
- Test thoroughly before adding

## Common Patterns by Scope

### Plugin Hook Patterns
- **Validation**: Check files match plugin's format
- **Auto-completion**: Suggest plugin-specific completions
- **Logging**: Track plugin-specific operations

### Project Hook Patterns
- **Protection**: Block dangerous operations on sensitive paths
- **Enforcement**: Require tests, linting, or builds
- **Conventions**: Warn about style or naming violations

### Global Hook Patterns
- **Auditing**: Log all operations for personal review
- **Safety**: Universal dangerous command detection
- **Integration**: Personal tool notifications

## SessionStart Hook Enhancements (Claude Code 2.1.2+)

SessionStart hooks now receive additional input fields via stdin:

| Field | Type | Description |
|-------|------|-------------|
| `session_id` | string | Unique session identifier |
| `source` | enum | `"startup"` \| `"resume"` \| `"clear"` \| `"compact"` |
| `agent_type` | string | Agent name if `--agent` flag used, empty otherwise |

### Agent-Aware Hooks

The `agent_type` field enables scope-appropriate context injection:

```python
# Skip heavy context for review agents
input_data = json.loads(sys.stdin.read())
if input_data.get("agent_type") in ["code-reviewer", "quick-query"]:
    print(json.dumps({"hookSpecificOutput": {"additionalContext": "Minimal"}}))
```

This is particularly useful for:
- **Plugin hooks**: Reduce overhead for lightweight agents
- **Project hooks**: Skip governance for review-only agents
- **Global hooks**: Customize logging verbosity per agent

## Related Skills

- **abstract:hook-authoring** - For hook rule syntax and patterns
- **abstract:validate-plugin** - For validating plugin structure including hooks

## References

- [Claude Code Hooks Documentation](https://docs.anthropic.com/en/docs/claude-code/hooks)
- [Settings Configuration](https://docs.anthropic.com/en/docs/claude-code/settings)

## Exit Criteria

- [ ] A single scope (plugin / project / global) is selected and the rationale traces through at
  least two of the three decision questions (audience, version control, persistence).
- [ ] The selected scope's file location (`hooks/hooks.json`, `.claude/settings.json`, or
  `~/.claude/settings.json`) is confirmed to exist or is created at the correct path.
- [ ] Plugin hooks do not add `"hooks": "./hooks/hooks.json"` to `plugin.json` (duplicate-load
  guard); this absence is verified before the hook is deployed.
- [ ] Global hooks are flagged with a security note confirming they apply to all Claude sessions
  on this machine.

Wersje

W bazie nie ma innych skilli o nazwie hook-scope-guide.

Migawka bazy z 13.11.2026 · wersja paczki 1863dfec2fa0 (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

  • 95hook-authoring
    Prowadzi przy tworzeniu hooków Claude Code z projektem nastawionym na bezpieczeństwo, do walidacji i egzekwowania reguł.
  • 100hook-publisher
    Umieszcza skrypty hooków w poprawnej strukturze repozytorium claude-code-plugin: weryfikuje strukturę, sprawdza duplikaty, generuje plugin.json i rejestruje w marketplace.json.
  • 100mem0-scope
    Pokazuje lub zmienia domyślny zakres pamięci (projekt, sesja lub globalny) używany przy zapisie i wyszukiwaniu wspomnień Mem0.
  • 100hook-template
    Generuje skrypt hooka z szablonu przy dodawaniu nowego hooka PreToolUse, PostToolUse, Stop lub Notification oraz konfiguracji w settings.json.
  • 100authoring-claude-extensions
    Pomaga wybrać, które rozszerzenie Claude Code pasuje do potrzeby (skill, subagent, hook czy plugin), a następnie je napisać.
  • 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.

Uwagi i zgłoszenia

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