Skip to content
Skills Library
AI & agents · Review & audit

hooks-eval

/hooks-eval

Evaluate hook security, performance, and SDK compliance. Use for audits.

Licence
MIT
Last repository change
01.10.2026

Assessment and security

96/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability21 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 01.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Evaluate hook security, performance, and SDK compliance. Use for audits.

Original author description

Evaluate hook security, performance, and SDK compliance. Use for audits.

How it works

  1. When NOT To Use
  2. Overview
  3. Quick Reference
  4. Detailed Resources
  5. Basic Evaluation Workflow
  6. Integration with Other Tools
  7. Related Skills
  8. Troubleshooting
  9. Exit Criteria
Original SKILL.md headings · 156 lines, 741 words
SKILL.md preview
---
name: hooks-eval
description: 'Evaluate hook security, performance, and SDK compliance. Use for audits.'
alwaysApply: false
category: hook-management
tags:
- hooks
- evaluation
- security
- performance
- claude-sdk
- agent-sdk
dependencies:
- hook-scope-guide
provides:
  infrastructure:
  - hook-evaluation
  - security-scanning
  - performance-analysis
  patterns:
  - hook-auditing
  - sdk-integration
  - compliance-checking
  sdk_features:
  - python-sdk-hooks
  - hook-callbacks
  - hook-matchers
estimated_tokens: 1200
modules:
- modules/evaluation-criteria.md
- modules/sdk-hook-types.md
model_hint: standard
role: entrypoint
---

## When NOT To Use

- Writing a new hook (use `abstract:hook-authoring`)
- Evaluating skills (use `abstract:skills-eval`)
- Evaluating rules in `.claude/rules/` (use `abstract:rules-eval`)

# Hooks Evaluation Framework

## Overview

This skill provides a detailed framework for evaluating, auditing, and implementing Claude Code hooks across all scopes (plugin, project, global) and both JSON-based and programmatic (Python SDK) hooks.

### Key Capabilities

- **Security Analysis**: Vulnerability scanning, dangerous pattern detection, injection prevention
- **Performance Analysis**: Execution time benchmarking, resource usage, optimization
- **Compliance Checking**: Structure validation, documentation requirements, best practices
- **SDK Integration**: Python SDK hook types, callbacks, matchers, and patterns

### Core Components

| Component | Purpose |
|-----------|---------|
| **Hook Types Reference** | Complete SDK hook event types and signatures |
| **Evaluation Criteria** | Scoring system and quality gates |
| **Security Patterns** | Common vulnerabilities and mitigations |
| **Performance Benchmarks** | Thresholds and optimization guidance |

## Quick Reference

### Hook Event Types

```python
HookEvent = Literal[
    "PreToolUse",  # Before tool execution
    "PostToolUse",  # After tool execution
    "UserPromptSubmit",  # When user submits prompt
    "Stop",  # When stopping execution
    "SubagentStop",  # When a subagent stops
    "TeammateIdle",  # When teammate agent becomes idle (2.1.33+)
    "TaskCompleted",  # When a task finishes execution (2.1.33+)
    "PreCompact",  # Before message compaction
]
```
**Verification:** Run the command with `--help` flag to verify availability.

**Note**: Python SDK does not support `SessionStart`, `SessionEnd`, or `Notification` hooks due to setup limitations. However, plugins can define `SessionStart` hooks via `hooks.json` using shell commands (e.g., leyline's `detect-git-platform.sh`).

### Plugin-Level hooks.json

Plugins can declare hooks via `"hooks": "./hooks/hooks.json"` in plugin.json. The evaluator validates:
- Referenced hooks.json exists and is valid JSON
- Shell commands referenced in hooks exist and are executable
- Hook matchers use valid event types

### Hook Callback Signature

```python
async def my_hook(
    input_data: dict[str, Any],  # Hook-specific input
    tool_use_id: str | None,  # Tool ID (for tool hooks)
    context: HookContext,  # Additional context
) -> dict[str, Any]:  # Return decision/messages
    ...
```
**Verification:** Run the command with `--help` flag to verify availability.

### Return Values

```python
return {
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",  # Match hook type
        "permissionDecision": "deny",  # Optional: block action
        "permissionDecisionReason": "...",  # Reason for denial
        "additionalContext": "...",  # Optional: context added
    }
}
```
**Verification:** Run the command with `--help` flag to verify availability.

### Quality Scoring (100 points)

| Category | Points | Focus |
|----------|--------|-------|
| Security | 30 | Vulnerabilities, injection, validation |
| Performance | 25 | Execution time, memory, I/O |
| Compliance | 20 | Structure, documentation, error handling |
| Reliability | 15 | Timeouts, idempotency, degradation |
| Maintainability | 10 | Code structure, modularity |

## Detailed Resources

- **SDK Hook Types**: See `modules/sdk-hook-types.md` for complete Python SDK type definitions, patterns, and examples
- **Evaluation Criteria**: See `modules/evaluation-criteria.md` for detailed scoring rubric and quality gates
- **Security Patterns**: See `modules/sdk-hook-types.md` for vulnerability detection and mitigation
- **Performance Guide**: See `modules/evaluation-criteria.md` for benchmarking and optimization

## Basic Evaluation Workflow

```bash
# 1. Run detailed evaluation
/hooks-eval --detailed

# 2. Focus on security issues
/hooks-eval --security-only --format sarif

# 3. Benchmark performance
/hooks-eval --performance-baseline

# 4. Check compliance
/hooks-eval --compliance-report
```
**Verification:** Run the command with `--help` flag to verify availability.

## Integration with Other Tools

```bash
# Complete plugin evaluation pipeline
/hooks-eval --detailed          # Evaluate all hooks
/analyze-hook hooks/specific.py      # Deep-dive on one hook
/validate-plugin .                   # Validate overall structure
```
**Verification:** Run the command with `--help` flag to verify availability.

## Related Skills

- `abstract:hook-scope-guide` - Decide where to place hooks (plugin/project/global)
- `abstract:hook-authoring` - Write hook rules and patterns
- `abstract:validate-plugin` - Validate complete plugin structure
## Troubleshooting

### Common Issues

**Hook not firing**
Verify hook pattern matches the event. Check hook logs for errors

**Syntax errors**
Validate JSON/Python syntax before deployment

**Permission denied**
Check hook file permissions and ownership

## Exit Criteria

- [ ] Every hook in scope receives a composite quality score (0-100) across the five weighted
  categories: Security (30), Performance (25), Compliance (20), Reliability (15),
  Maintainability (10).
- [ ] Any hook scoring below 60 on the Security category is flagged as a blocking issue before
  the evaluation report is returned.
- [ ] Shell commands referenced in `hooks.json` are verified to exist and be executable; missing
  scripts are listed as FAIL findings.
- [ ] The evaluation report distinguishes between JSON hooks (Claude Code) and Python SDK hooks
  and applies the correct signature expectations for each type.
Files in this package (3)
  • SKILL.md 6 KB
  • modules/evaluation-criteria.md 8 KB
  • modules/sdk-hook-types.md 9 KB

Versions

The database has no other skills named hooks-eval.

Database snapshot: 13.11.2026 · package version c4b763861410 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100eval-hooks
    Audit Claude Code hooks defined in settings.json files for validity, performance safety, and correctness. Resolves each command against the filesystem, checks exit-code strategy for blocking hooks, flags missing timeouts, and reviews interactive vs async patterns. Use when…
  • 100evaluate-connector
    Evaluate a Fivetran connector for correctness, SDK compliance, security, and reliability. Use when the user wants a code review or quality report before deploying.
  • 100evaluate-connector
    Evaluate a Fivetran connector for correctness, SDK compliance, security, and reliability. Use when the user wants a code review or quality report before deploying.
  • 100create-hook
    Create Cursor hooks. Use to create a hook, write hooks.json, add hook scripts, or automate behavior around agent events.
  • 90agentic-eval
    Plan, implement, or review agentic eval work in an existing codebase with compatibility, security, and verification controls. Use when the user explicitly requests agentic eval work.
  • 100rules-eval
    Evaluate Claude Code rules in .claude/rules/. Use for frontmatter, globs, and quality audits.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.