movq/claude-plugins
2
0
Fork 0
Code Issues Pull Requests Actions Releases Activity

Refinement for context size

Browse Source
This commit is contained in:
movq
2025-10-28 12:48:17 -05:00
parent 35d2069861
commit ddea00cb40
11 changed files with 1539 additions and 1196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
claude-code/skills/claude-hooks/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: Claude Code Hooks
description: Configure event-driven hooks for Claude Code to automate workflows, validate code, inject context, and control tool execution. Use PROACTIVELY when setting up automation, enforcing standards, integrating external tools, or when users mention "automatically run", "on save", "event-driven", "workflow automation", or "enforce rules". NOT for one-time scripts.
description: Configure event-driven hooks for Claude Code to automate workflows, validate code, inject context, and control tool execution. Use PROACTIVELY when users want automation that runs automatically (not manually), mention "automatically run", "on save", "after editing", "event-driven", "workflow automation", or "enforce rules". NOT for one-time scripts.
---
# Claude Code Hooks
@@ -8,74 +8,65 @@ description: Configure event-driven hooks for Claude Code to automate workflows,
## When to Use This Skill
Use this skill when:
- Automating workflows with event-driven triggers
- Enforcing code standards or security policies
- Automating workflows with event triggers
- Enforcing code standards or policies
- Validating changes before/after tool execution
- Injecting context at session start
- Logging or monitoring tool usage
- Setting up team-wide automation
Do NOT use this skill for:
- Creating slash commands (use claude-command-expert skill)
- Building full plugins (use claude-plugin skill)
- One-time scripts (just run them directly)
- Creating slash commands (use claude-commands skill)
- Building plugins (use claude-plugins skill)
- One-time scripts (run them directly)
## Quick Start
### 1. Hook Configuration File
### Configuration File Locations
```bash
# Project-wide (team shared)
.claude/settings.json
# User-specific (not shared)
.claude/settings.local.json
# Global (all projects)
~/.claude/settings.json
.claude/settings.json # Project (team)
.claude/settings.local.json # Project (personal)
~/.claude/settings.json # Global (personal)
```
### 2. Simple Example - Log File Changes
### Simple Example - Auto-Format
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "echo \"$(date): Modified $TOOL_ARGS\" >> .claude/changes.log"
}
]
}
]
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "npx prettier --write $TOOL_ARGS && exit 0"
}]
}]
}
}
```
## Hook Types
| Event | When It Runs | Common Use |
|-------|--------------|-----------|
| SessionStart | Session begins | Inject project context |
| Event | When | Common Use |
|-------|------|-----------|
| SessionStart | Session begins | Inject context |
| SessionEnd | Session ends | Cleanup, backups |
| PreToolUse | Before tool execution | Validation, permission checks |
| PreToolUse | Before tool execution | Validation, checks |
| PostToolUse | After tool completes | Formatting, linting |
| UserPromptSubmit | User submits prompt | Logging, analytics |
| UserPromptSubmit | User submits prompt | Logging |
| Notification | Claude sends notification | Desktop alerts |
| Stop | Agent finishes responding | Post-response processing |
| Stop | Agent finishes | Post-processing |
## Core Concepts
### Matcher Patterns
### Matchers
```json
// Single tool
"matcher": "Write"
// Multiple tools (OR)
// Multiple (OR)
"matcher": "Write|Edit|Read"
// All tools
@@ -88,23 +79,18 @@ Do NOT use this skill for:
### Exit Codes
```bash
# Success - Continue
exit 0
# Blocking Error - Stop operation
exit 2
# Non-Blocking Error - Continue
exit 1
exit 0 # Success - Continue
exit 1 # Non-blocking error - Continue
exit 2 # Blocking error - Stop operation
```
### Environment Variables
```bash
$CLAUDE_PROJECT_DIR # Current project directory
$TOOL_NAME # Name of the tool being used
$TOOL_ARGS # Arguments passed to the tool
$HOOK_EVENT # Event type (PreToolUse, etc.)
$CLAUDE_PROJECT_DIR # Current project
$TOOL_NAME # Tool being used
$TOOL_ARGS # Tool arguments
$HOOK_EVENT # Event type
```
## Common Use Cases
@@ -114,17 +100,13 @@ $HOOK_EVENT # Event type (PreToolUse, etc.)
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npx prettier --write $TOOL_ARGS && exit 0"
}
]
}
]
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npx prettier --write $TOOL_ARGS && exit 0"
}]
}]
}
}
```
@@ -134,18 +116,14 @@ $HOOK_EVENT # Event type (PreToolUse, etc.)
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "if grep -qiE '(password|api[_-]?key|secret)' $TOOL_ARGS 2>/dev/null; then echo 'Error: Possible secret detected' >&2; exit 2; fi; exit 0",
"timeout": 30
}
]
}
]
"PreToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "if grep -qiE '(password|api[_-]?key|secret)' $TOOL_ARGS 2>/dev/null; then echo 'Error: Possible secret' >&2; exit 2; fi; exit 0",
"timeout": 30
}]
}]
}
}
```
@@ -155,23 +133,19 @@ $HOOK_EVENT # Event type (PreToolUse, etc.)
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npm test -- --silent || (echo 'Tests failed' >&2; exit 2)",
"timeout": 120
}
]
}
]
"PreToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npm test -- --silent || (echo 'Tests failed' >&2; exit 2)",
"timeout": 120
}]
}]
}
}
```
For complete examples, see [examples.md](examples.md)
For more examples, see [examples.md](examples.md)
## Hook Configuration
@@ -185,32 +159,19 @@ For complete examples, see [examples.md](examples.md)
}
```
### Multiple Hooks
Run several hooks in sequence:
### Multiple Hooks (Sequential)
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $TOOL_ARGS"
},
{
"type": "command",
"command": "npx eslint --fix $TOOL_ARGS"
},
{
"type": "command",
"command": "git add $TOOL_ARGS"
}
]
}
]
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [
{"type": "command", "command": "npx prettier --write $TOOL_ARGS"},
{"type": "command", "command": "npx eslint --fix $TOOL_ARGS"},
{"type": "command", "command": "git add $TOOL_ARGS"}
]
}]
}
}
```
@@ -224,18 +185,18 @@ Run several hooks in sequence:
}
```
## Settings File Hierarchy
## Settings Hierarchy
**Load Order** (highest to lowest priority):
1. `.claude/settings.local.json` - Project, user-only (gitignored)
2. `.claude/settings.json` - Project, team-shared (in git)
3. `~/.claude/settings.json` - Global, user-only
1. `.claude/settings.local.json` - Project, personal (gitignored)
2. `.claude/settings.json` - Project, team (in git)
3. `~/.claude/settings.json` - Global, personal
**Use Cases**:
- **Global**: Personal preferences, universal logging
- **Project**: Team standards, project automation
- **Local**: Personal overrides, development experiments
- **Local**: Personal overrides, experiments
## Testing Hooks
@@ -244,17 +205,13 @@ Run several hooks in sequence:
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "echo 'Hook triggered for: $TOOL_ARGS' && exit 0"
}
]
}
]
"PostToolUse": [{
"matcher": "Write",
"hooks": [{
"type": "command",
"command": "echo 'Hook triggered: $TOOL_ARGS' && exit 0"
}]
}]
}
}
```
@@ -264,44 +221,28 @@ Run several hooks in sequence:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "echo 'This should block' >&2 && exit 2"
}
]
}
]
"PreToolUse": [{
"matcher": "Write",
"hooks": [{
"type": "command",
"command": "echo 'This blocks' >&2 && exit 2"
}]
}]
}
}
```
Try writing a file - should be blocked.
## Troubleshooting
| Problem | Solution |
|---------|----------|
| Hook not triggering | Check matcher pattern, restart Claude Code |
| Hook fails silently | Check exit codes (use 0 for success) |
| Command not found | Use full path: `/usr/local/bin/prettier` |
| Permission denied | `chmod +x .claude/hooks/script.sh` |
| Timeout | Increase timeout value or optimize command |
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
Try writing - should be blocked.
## Best Practices
### 1. Always Exit Explicitly
```bash
# Good
# ✓ Good
command && exit 0
# Bad
# ✗ Bad
command
```
@@ -310,7 +251,7 @@ command
```json
{
"command": "npm test",
"timeout": 120 // Don't let tests run forever
"timeout": 120 // Don't hang forever
}
```
@@ -328,29 +269,41 @@ exit 0 # Don't block on missing file
### 4. Use Scripts for Complex Logic
```json
// Bad - complex bash in JSON
// ✓ Good - external script
{
"command": "if [ -f $TOOL_ARGS ]; then cat $TOOL_ARGS | grep pattern | wc -l; fi"
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check.sh $TOOL_ARGS"
}
// Good - external script
// ✗ Bad - complex bash in JSON
{
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-file.sh $TOOL_ARGS"
"command": "if [ -f $TOOL_ARGS ]; then cat $TOOL_ARGS | grep pattern | wc -l; fi"
}
```
### 5. Test Before Team Deployment
Test in `.claude/settings.local.json` before adding to `.claude/settings.json`.
Test in `.claude/settings.local.json` before adding to team settings.
## Security Considerations
## Troubleshooting
| Problem | Solution |
|---------|----------|
| Not triggering | Check matcher, restart Claude |
| Fails silently | Check exit codes (use 0 for success) |
| Command not found | Use full path |
| Permission denied | `chmod +x script.sh` |
| Timeout | Increase timeout or optimize |
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
## Security
### Validate Input
```bash
# Sanitize TOOL_ARGS
if [[ ! $TOOL_ARGS =~ ^[a-zA-Z0-9/_.-]+$ ]]; then
echo "Invalid file path" >&2
echo "Invalid path" >&2
exit 2
fi
```
@@ -358,33 +311,26 @@ fi
### Limit Permissions
```json
// Specific (good)
// ✓ Specific
"matcher": "Write|Edit"
// Too broad (risky)
// ✗ Too broad
"matcher": "*"
```
### Avoid Destructive Commands
```bash
# Dangerous
# ✗ Dangerous
rm -rf $TOOL_ARGS
# Safer
# ✓ Safer
if [[ -f "$TOOL_ARGS" ]] && [[ "$TOOL_ARGS" != "/" ]]; then
rm "$TOOL_ARGS"
fi
```
## Resources
- [Complete Examples](examples.md) - Working hook configurations
- [Advanced Patterns](patterns.md) - Complex workflows
- [Troubleshooting Guide](troubleshooting.md) - Problem-solution reference
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/hooks)
## Quick Reference Card
## Quick Reference
### Common Patterns
@@ -395,10 +341,20 @@ fi
// Block secrets
"PreToolUse": [{"matcher": "Write", "hooks": [{"type": "command", "command": "grep -q 'secret' $TOOL_ARGS && exit 2 || exit 0"}]}]
// Log all activity
// Log activity
"PreToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "echo \"$TOOL_NAME: $TOOL_ARGS\" >> .claude/log && exit 0"}]}]
```
## Additional Resources
**Need more?**
- [Complete Examples](examples.md) - Working hook configurations
- [Advanced Patterns](patterns.md) - Complex workflows
- [Troubleshooting Guide](troubleshooting.md) - Problem solutions
- [Official Docs](https://docs.claude.com/en/docs/claude-code/hooks)
💡 **Tip**: Start simple, test thoroughly, use exit codes correctly. Hooks are powerful - use them wisely.
---
**Remember**: Hooks are powerful automation tools. Start simple, test thoroughly, use exit codes properly to control flow.
**Remember**: Hooks automate workflows. Exit codes control flow. Test in local settings first. Use specific matchers for security.