Claude Code Skill

WPfaker ships a Claude Code skill that gives Claude full context about the addon system when you are building a WPfaker addon. When the skill is installed in your project, Claude automatically knows about every hook, interface contract, registration pattern, and testing approach — so you can describe what you want in natural language and get working addon code without looking up the API yourself.

Install this skill in your AI agent

What the Skill Provides

The wpfaker-addon-dev skill gives Claude access to:

• Plugin structure — the directory layout and entry point pattern for a WPfaker addon
• Interface contracts — every method on FieldPluginAdapterInterface and AiProviderInterface with return types and descriptions
• Hook reference — all 7 action hooks and 4 filter hooks with their full signatures and parameters
• Registration patterns — how to register adapters via AdapterFactory::register() and AI providers via AiProviderFactory::register()
• Testing patterns — Pest PHP source-check testing and AdapterFactory::resetRegistry() for test isolation

Installation

Run this in your addon project root to download and install the skill:

mkdir -p .claude/skills/wpfaker-addon-dev && curl -sL https://docs.wpfaker.com/SKILL.md -o .claude/skills/wpfaker-addon-dev/SKILL.md

Claude Code automatically detects skills in .claude/skills/ — no further configuration needed. After running the command, your project will have:

your-addon-project/
└── .claude/
    └── skills/
        └── wpfaker-addon-dev/
            └── SKILL.md

TIP

Commit the .claude/skills/ directory to your repository so every developer on the project gets the skill automatically.

Skill Content

For reference, here is the full content of the skill file:

---
name: wpfaker-addon-dev
description: Guide for developing WPfaker addons — covers plugin structure, hook reference, adapter/provider registration, and testing patterns.
---

# WPfaker Addon Development

## Addon Plugin Structure

Minimal directory layout for a WPfaker addon WordPress plugin:

```
my-wpfaker-addon/
├── my-wpfaker-addon.php          # Plugin entry point
├── src/
│   ├── Adapters/
│   │   └── MyAdapter.php         # FieldPluginAdapterInterface implementation
│   └── AiProviders/
│       └── MyAiProvider.php      # AiProviderInterface implementation (optional)
├── tests/
│   └── Unit/
│       └── MyAdapterTest.php
├── composer.json
└── readme.txt
```

## Entry Point Pattern

The addon MUST wait for the `wpfaker_loaded` action before registering anything. This ensures WPfaker classes and contracts are available.

```php
<?php
/**
 * Plugin Name: My WPfaker Addon
 */

add_action('wpfaker_loaded', function (string $version) {
    // Register a custom field adapter
    add_action('wpfaker_register_adapters', function () {
        \WPFaker\Services\AdapterFactory::register('my_plugin', MyAdapter::class);
    });

    // Register a custom AI provider (optional)
    add_action('wpfaker_register_ai_providers', function () {
        \WPFaker\Services\AiProviderFactory::register('my_ai', MyAiProvider::class, 'My AI Service');
    });
});
```

## Registering a Custom Field Adapter

Your adapter must implement `\WPFaker\Contracts\FieldPluginAdapterInterface`. The adapter constructor receives a `FakerService` instance.

### Required Methods

| Method | Return | Purpose |
|--------|--------|---------|
| `isActive()` | `bool` | Return true if your field plugin is active |
| `getName()` | `string` | Human-readable plugin name |
| `getVersion()` | `string` | Plugin version string |
| `getCustomPostTypes()` | `array` | CPTs registered by the plugin |
| `getCustomTaxonomies()` | `array` | Taxonomies registered by the plugin |
| `getFieldGroups()` | `array` | All field group configs |
| `getFieldGroupsForPostType(string $postType)` | `array` | Field groups for a specific CPT |
| `getFields($fieldGroupId)` | `array` | Fields within a group |
| `getFieldsForPostType(string $postType)` | `array` | All fields for a CPT |
| `saveFieldValue(int $postId, string $fieldName, $value)` | `bool` | Save a field value |
| `getFieldConfig(string $fieldNameOrKey)` | `?array` | Get field config by name |
| `mapFieldTypeToFaker(array $field)` | `string` | Map field type to Faker method |
| `getSupportedFieldTypes()` | `array` | List of supported field type slugs |
| `setCptContext(string $slug, ?string $label)` | `self` | Set CPT context for detection |

### Registration

```php
\WPFaker\Services\AdapterFactory::register('my_plugin', MyAdapter::class);
```

## Registering a Custom AI Provider

Your provider must implement `\WPFaker\Contracts\AiProviderInterface`. Custom providers auto-appear in the Settings dropdown once registered.

### Required Methods

| Method | Return | Purpose |
|--------|--------|---------|
| `getProviderKey()` | `string` | Unique key |
| `getProviderName()` | `string` | Display name for Settings UI |
| `isAvailable()` | `bool` | Has API key + is enabled |
| `isEnabled()` | `bool` | Is enabled regardless of key |
| `getMaskedApiKey()` | `string` | Masked API key for display |
| `detectFieldType(...)` | `?array` | Single field detection |
| `detectFieldsBatch(...)` | `?array` | Batch field detection |
| `detectFieldsBatchWithConfig(...)` | `?array` | Batch with faker configs |
| `generateTitleTemplates(...)` | `?array` | Generate title templates |
| `generateCptContext(...)` | `?array` | Generate CPT context |
| `testConnection()` | `array` | Test API connection |

### Registration

```php
\WPFaker\Services\AiProviderFactory::register('my_ai', MyAiProvider::class, 'My AI Service');
```

## Available Hooks

### Actions

| Hook | Parameters | Purpose |
|------|-----------|---------|
| `wpfaker_loaded` | `string $version` | WPfaker fully loaded, addon entry point |
| `wpfaker_register_adapters` | none | Time to register custom adapters |
| `wpfaker_register_ai_providers` | none | Time to register custom AI providers |
| `wpfaker_activate` | none | Plugin activated |
| `wpfaker_deactivate` | `bool $deleteData` | Plugin deactivated |
| `wpfaker_after_generate_item` | `string $type, int $id, int $index, int $total, array $options` | After each item generated |
| `wpfaker_after_generate` | `string $type, array $ids, array $options` | After all items in batch |

### Filters

| Hook | Parameters | Purpose |
|------|-----------|---------|
| `wpfaker_post_data` | `array $postData, string $postType, int $index, int $total, array $options` | Modify post data before `wp_insert_post` |
| `wpfaker_field_value` | `mixed $value, array $config, string $postType, int $postId` | Modify field value before save |
| `wpfaker_adapter_priority` | `array $priority` | Change adapter resolution order |
| `wpfaker_field_name_detection_enabled` | `bool $enabled` | Enable/disable field name detection |

## Testing Pattern

Use Pest PHP with source-check patterns for adapter tests. Use `AdapterFactory::resetRegistry()` between tests for isolation:

```php
beforeEach(function () {
    \WPFaker\Services\AdapterFactory::resetRegistry();
});

it('registers the adapter', function () {
    \WPFaker\Services\AdapterFactory::register('my_plugin', MyAdapter::class);

    expect(\WPFaker\Services\AdapterFactory::has('my_plugin'))->toBeTrue();
});
```

## Key Classes

- **`\WPFaker\Services\AdapterFactory`** — Registry for field plugin adapters
- **`\WPFaker\Services\AiProviderFactory`** — Registry for AI providers
- **`\WPFaker\Contracts\FieldPluginAdapterInterface`** — Contract for field adapters
- **`\WPFaker\Contracts\AiProviderInterface`** — Contract for AI providers
- **`\WPFaker\Services\FakerService`** — Core faker data generation service (injected into adapters)

Usage

Once the skill file is in place, Claude Code detects it automatically when you work in your project directory. You do not need to configure anything else — just start a conversation and Claude will have the full addon development context available.

You can ask Claude things like:

• "Create a field adapter for the Toolset Types plugin"
• "Add an AI provider that uses Ollama for local field detection"
• "Hook into wpfaker_post_data to add a custom taxonomy assignment"
• "Set up a test suite for my adapter"

TIP

The skill works best when your project already has its basic structure in place (plugin entry file, composer.json). Claude uses the skill's patterns to fill in the implementation details.

INFO

For the full addon development guide with detailed explanations and examples for every hook, see the Addon Development page.