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:

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:

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:

# 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)"