# Wp Hooks

> This skill should be used when the user asks to "document hooks", "generate a hooks reference", "list hooks", "show custom hooks", "generate hook docs", or mentions "hook documentation", "what hooks exist", "do_action", "apply_filters". Scans PHP source for do_action() and apply_filters() calls and produces detailed documentation with parameters, examples, and usage context.

- Skill: `iwritec0de/wp-hooks` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iwritec0de/wp-hooks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iwritec0de/wp-hooks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: iwritec0de (https://skillmd.com/u/iwritec0de)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iwritec0de/wp-hooks

---


# WordPress Hook Documentation Skill

You are documenting custom WordPress hooks for this project. This is the **deep pass** — thorough documentation with parameters, examples, and context, beyond what the auto-scanner produces.

## Workflow

### Step 1: Run the Scanner

Run the hook scanner to get a fresh inventory:

```bash
SCAN_HOOKS_VERBOSE=1 bash "$CLAUDE_PROJECT_DIR/.claude/hooks/scan-hooks.sh" "$CLAUDE_PROJECT_DIR"
```

If `scan-hooks.sh` is not available at that path, check the plugin's scripts directory:
```bash
SCAN_HOOKS_VERBOSE=1 bash "${CLAUDE_PLUGIN_ROOT}/scripts/scan-hooks.sh" "$CLAUDE_PROJECT_DIR"
```

If neither is available, scan manually:
- Search all `.php` files (excluding `vendor/`, `node_modules/`, `wp-admin/`, `wp-includes/`) for `do_action(` and `apply_filters(` calls
- Skip WordPress core hooks (prefixed `wp_`, `admin_`, `the_`, etc.)

### Step 2: Read Existing Reference

Read `docs/hooks-reference.md` if it exists. Note any manually-written descriptions — these must be preserved.

### Step 3: Deep Analysis

For **each** custom hook found, read the surrounding code to determine:

1. **Parameters** — names, types, and purpose. Check:
   - PHPDoc `@param` tags on the enclosing function
   - Variable types from usage context
   - WordPress conventions (e.g., `$post_id` is always `int`)

2. **Purpose** — what the hook enables. Read:
   - The enclosing function's PHPDoc `@since` and description
   - What happens before/after the hook fires
   - Whether it's a lifecycle event, data modification point, or extension point

3. **Example usage** — write a working `add_action()` or `add_filter()` snippet:
   - Use realistic parameter names matching the hook's arguments
   - Include proper callback signature with type hints
   - Show a practical use case, not just a skeleton

4. **Version** — extract `@since` if available from the enclosing docblock

### Step 4: Generate Documentation

Write `docs/hooks-reference.md` with this structure:

```markdown
# Custom Hooks Reference

<!-- Auto-generated by wp-hooks skill — manual edits are preserved -->
<!-- Last documented: YYYY-MM-DD HH:MM:SS -->

## Overview

Brief description of the hook architecture in this plugin/theme.

## Actions

### `prefix_hook_name`

**Type:** Action
**Since:** 1.0.0
**File:** `path/to/file.php:42` (function `function_name`)

Description of what this action does and when it fires.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `$arg1` | `string` | Description of arg1 |
| `$arg2` | `int` | Description of arg2 |

**Example:**

\```php
add_action( 'prefix_hook_name', function( string $arg1, int $arg2 ): void {
    // Your code here
}, 10, 2 );
\```

---

## Filters

### `prefix_filter_name`

**Type:** Filter
**Since:** 1.0.0
**File:** `path/to/file.php:87` (function `function_name`)

Description of what this filter modifies.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `$value` | `array` | The value being filtered |
| `$context` | `string` | Additional context |

**Default:** Description of the unfiltered default value.

**Example:**

\```php
add_filter( 'prefix_filter_name', function( array $value, string $context ): array {
    // Modify and return $value
    return $value;
}, 10, 2 );
\```
```

## Rules

- **Preserve manual edits** — if a description already exists and was written by a human (not `<!-- TODO: describe -->`), keep it
- **Filters must document the return** — always describe what the unfiltered default value is and what the filter is expected to return
- **Actions should describe timing** — when in the lifecycle does this fire?
- **Group logically** — if hooks belong to a subsystem (e.g., "checkout", "import"), add subheadings
- **Skip core hooks** — only document project-specific hooks, not `wp_enqueue_scripts` or `init`
- **Flag dynamic hooks** — if a hook name is built from variables (e.g., `"prefix_{$type}_loaded"`), document the pattern and possible values
- **Include the hook count** — end with a summary line: "*N custom hooks (X actions, Y filters)*"