smartworldarafath/Google_Antigravity_Plugins / plugins/antigravity-plugin-dev/skills/hook-development
hook-development
VerifiedThis skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${ANTIGRAVITY_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Google Antigravity plugin hooks with focus on advanced prompt-based hooks API.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.2 KB |
| examples/load-context.sh | script | 1.7 KB |
| examples/validate-bash.sh | script | 1.3 KB |
| examples/validate-write.sh | script | 1.2 KB |
| references/advanced.md | markdown | 10.0 KB |
| references/migration.md | markdown | 8.2 KB |
| references/patterns.md | markdown | 7.1 KB |
| scripts/README.md | markdown | 3.7 KB |
| scripts/hook-linter.sh | script | 4.1 KB |
| scripts/test-hook.sh | script | 5.2 KB |
| scripts/validate-hook-schema.sh | script | 5.0 KB |
references/migration.md
View on GitHub# Migrating from Basic to Advanced Hooks
This guide shows how to migrate from basic command hooks to advanced prompt-based hooks for better maintainability and flexibility.
## Why Migrate?
Prompt-based hooks offer several advantages:
- **Natural language reasoning**: LLM understands context and intent
- **Better edge case handling**: Adapts to unexpected scenarios
- **No bash scripting required**: Simpler to write and maintain
- **More flexible validation**: Can handle complex logic without coding
## Migration Example: run_command Command Validation
### Before (Basic Command Hook)
**Configuration:**
```json
{
"PreToolUse": [
{
"matcher": "run_command",
"hooks": [
{
"type": "command",
"command": "bash validate-bash.sh"
}
]
}
]
}
```
**Script (validate-bash.sh):**
```bash
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')
# Hard-coded validation logic
if [[ "$command" == *"rm -rf"* ]]; then
echo "Dangerous command detected" >&2
exit 2
fi
```
**Problems:**
- Only checks for exact "rm -rf" pattern
- Doesn't catch variations like `rm -fr` or `rm -r -f`
- Misses other dangerous commands (`dd`, `mkfs`, etc.)
- No context awareness
- Requires bash scripting knowledge
### After (Advanced Prompt Hook)
**Configuration:**
```json
{
"PreToolUse": [
{
"matcher": "run_command",
"hooks": [
{
"type": "prompt",
"prompt": "Command: $TOOL_INPUT.command. Analyze for: 1) Destructive operations (rm -rf, dd, mkfs, etc) 2) Privilege escalation (sudo) 3) Network operations without user consent. Return 'approve' or 'deny' with explanation.",
"timeout": 15
}
]
}
]
}
```
**Benefits:**
- Catches all variations and patterns
- Understands intent, not just literal strings
- No script file needed
- Easy to extend with new criteria
- Context-aware decisions
- Natural language explanation in denial
## Migration Example: File write_to_file Validation
### Before (Basic Command Hook)
**Configuration:**
```json
{
"PreToolUse": [
{
"matcher": "write_to_file",
"hooks": [
{
"type": "command",
"command": "bash validate-write.sh"
}
]
}
]
}
```
**Script (validate-write.sh):**
```bash
#!/bin/bash
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
# Check for path traversal
if [[ "$file_path" == *".."* ]]; then
echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2
exit 2
fi
# Check for system paths
if [[ "$file_path" == "/etc/"* ]] || [[ "$file_path" == "/sys/"* ]]; then
echo '{"decision": "deny", "reason": "System file"}' >&2
exit 2
fi
```
**Problems:**
- Hard-coded path patterns
- Doesn't understand symlinks
- Missing edge cases (e.g., `/etc` vs `/etc/`)
- No consideration of file content
### After (Advanced Prompt Hook)
**Configuration:**
```json
{
"PreToolUse": [
{
"matcher": "write_to_file|replace_file_content",
"hooks": [
{
"type": "prompt",
"prompt": "File path: $TOOL_INPUT.file_path. Content preview: $TOOL_INPUT.content (first 200 chars). Verify: 1) Not system directories (/etc, /sys, /usr) 2) Not credentials (.env, tokens, secrets) 3) No path traversal 4) Content doesn't expose secrets. Return 'approve' or 'deny'."
}
]
}
]
}
```
**Benefits:**
- Context-aware (considers content too)
- Handles symlinks and edge cases
- Natural understanding of "system directories"
- Can detect secrets in content
- Easy to extend criteria
## When to Keep Command Hooks
Command hooks still have their place:
### 1. Deterministic Performance Checks
```bash
#!/bin/bash
# Check file size quickly
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
size=$(stat -f%z "$file_path" 2>/dev/null || stat -c%s "$file_path" 2>/dev/null)
if [ "$size" -gt 10000000 ]; then
echo '{"decision": "deny", "reason": "File too large"}' >&2
exit 2
fi
```
**Use command hooks when:** Validation is purely mathematical or deterministic.
### 2. External Tool Integration
```bash
#!/bin/bash
# Run security scanner
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
scan_result=$(security-scanner "$file_path")
if [ "$?" -ne 0 ]; then
echo "Security scan failed: $scan_result" >&2
exit 2
fi
```
**Use command hooks when:** Integrating with external tools that provide yes/no answers.
### 3. Very Fast Checks (< 50ms)
```bash
#!/bin/bash
# Quick regex check
command=$(echo "$input" | jq -r '.tool_input.command')
if [[ "$command" =~ ^(ls|pwd|echo)$ ]]; then
exit 0 # Safe commands
fi
```
**Use command hooks when:** Performance is critical and logic is simple.
## Hybrid Approach
Combine both for multi-stage validation:
```json
{
"PreToolUse": [
{
"matcher": "run_command",
"hooks": [
{
"type": "command",
"command": "bash ${ANTIGRAVITY_PLUGIN_ROOT}/scripts/quick-check.sh",
"timeout": 5
},
{
"type": "prompt",
"prompt": "Deep analysis of bash command: $TOOL_INPUT",
"timeout": 15
}
]
}
]
}
```
The command hook does fast deterministic checks, while the prompt hook handles complex reasoning.
## Migration Checklist
When migrating hooks:
- [ ] Identify the validation logic in the command hook
- [ ] Convert hard-coded patterns to natural language criteria
- [ ] Test with edge cases the old hook missed
- [ ] Verify LLM understands the intent
- [ ] Set appropriate timeout (usually 15-30s for prompt hooks)
- [ ] Document the new hook in README
- [ ] Remove or archive old script files
## Migration Tips
1. **Start with one hook**: Don't migrate everything at once
2. **Test thoroughly**: Verify prompt hook catches what command hook caught
3. **Look for improvements**: Use migration as opportunity to enhance validation
4. **Keep scripts for reference**: Archive old scripts in case you need to reference the logic
5. **Document reasoning**: Explain why prompt hook is better in README
## Complete Migration Example
### Original Plugin Structure
```
my-plugin/
├── .claude-plugin/plugin.json
├── hooks/hooks.json
└── scripts/
├── validate-bash.sh
├── validate-write.sh
└── check-tests.sh
```
### After Migration
```
my-plugin/
├── .claude-plugin/plugin.json
├── hooks/hooks.json # Now uses prompt hooks
└── scripts/ # Archive or delete
└── archive/
├── validate-bash.sh
├── validate-write.sh
└── check-tests.sh
```
### Updated hooks.json
```json
{
"PreToolUse": [
{
"matcher": "run_command",
"hooks": [
{
"type": "prompt",
"prompt": "Validate bash command safety: destructive ops, privilege escalation, network access"
}
]
},
{
"matcher": "write_to_file|replace_file_content",
"hooks": [
{
"type": "prompt",
"prompt": "Validate file write safety: system paths, credentials, path traversal, content secrets"
}
]
}
],
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Verify tests were run if code was modified"
}
]
}
]
}
```
**Result:** Simpler, more maintainable, more powerful.
## Common Migration Patterns
### Pattern: String Contains → Natural Language
**Before:**
```bash
if [[ "$command" == *"sudo"* ]]; then
echo "Privilege escalation" >&2
exit 2
fi
```
**After:**
```
"Check for privilege escalation (sudo, su, etc)"
```
### Pattern: Regex → Intent
**Before:**
```bash
if [[ "$file" =~ \.(env|secret|key|token)$ ]]; then
echo "Credential file" >&2
exit 2
fi
```
**After:**
```
"Verify not writing to credential files (.env, secrets, keys, tokens)"
```
### Pattern: Multiple Conditions → Criteria List
**Before:**
```bash
if [ condition1 ] || [ condition2 ] || [ condition3 ]; then
echo "Invalid" >&2
exit 2
fi
```
**After:**
```
"Check: 1) condition1 2) condition2 3) condition3. Deny if any fail."
```
## Conclusion
Migrating to prompt-based hooks makes plugins more maintainable, flexible, and powerful. Reserve command hooks for deterministic checks and external tool integration.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |