mcpField
H
hook-scope-guide

hook-scope-guide

github.com/atholaAgent workflows34370 installsUpdated 1d ago
Repository

About hook-scope-guide

hook-scope-guide is a Claude Code skill for choosing plugin, project, or global hook scope based on audience, version control, and persistence needs. It also calls for verifying the configuration location and noting the security implications of global hooks.

Key features

  1. 01Choose scope by audience, version control, and persistence
  2. 02Distinguish plugin, project, and global hooks
  3. 03Confirm the relevant configuration file location
  4. 04Check security implications of global hooks

Use cases

  1. 01Select a scope for team hooks that belong in version control
  2. 02Decide where to place hooks limited to personal sessions
  3. 03Plan hook configuration that is enabled with a plugin

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/athola/claude-night-market --skill hook-scope-guide

After installing, type/hook-scope-guidein Claude Code to confirm it loaded.

Details

From the project README

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)

Decision Framework

Three questions pick the scope: who needs this hook, should it be version controlled, and how long should it persist. Plugin hooks (hooks/hooks.json in the plugin) serve plugin users while the plugin is enabled. Project hooks (.claude/settings.json) serve the team and are committed. Global hooks (~/.claude/settings.json) serve only you, in every session, and are never committed.

The question tree, per-scope configuration and examples, loading precedence, security considerations, migration and troubleshooting are written once, in plugins/abstract/skills/hook-authoring/modules/scope-selection.md. Read it before choosing. Agent-aware SessionStart hooks are covered in abstract:hook-authoring under Hook Event Types.

Related Skills

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

References

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.

Comments

Markdown supported