SkillAgentSearch skills...

wp-interactivity-api

Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior.

Install / Use

npx skills add WordPress/agent-skills --skill wp-interactivity-api

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

93/100

Category

Automation

Supported Platforms

Universal

Our assessment of wp-interactivity-api

wp-interactivity-api scores 93/100 on our quality scale, 676th of 2,790 Automation skills we index (top 25%).

Its SKILL.md is 6.0 KB long, well organised into 16 sections with 4 code examples: a thorough specification that gives an agent plenty to work with.

With 2,162 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
20/20
Description
15/15
Adoption
14/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so wp-interactivity-api is actively maintained.
  • Our last check on 2026-10-26 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

wp-interactivity-api compared with similar skills

All 4 of these similar skills score higher than wp-interactivity-api; compare them before choosing.

SkillScoreStarsUpdatedFormat
wp-interactivity-api (this skill)by WordPress932.2k54d agoSKILL.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.md

Frequently asked questions

How do I install wp-interactivity-api?
Run npx skills add WordPress/agent-skills --skill wp-interactivity-api. The install tabs above show the steps for each supported agent.
Which AI agents does wp-interactivity-api work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is wp-interactivity-api safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is wp-interactivity-api still maintained?
The repository was last updated about 2 months ago, so wp-interactivity-api is actively maintained.

name: wp-interactivity-api description: "Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior." compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."

WP Interactivity API

When to use

Use this skill when the user mentions:

  • Interactivity API, @wordpress/interactivity,
  • data-wp-interactive, data-wp-on--*, data-wp-bind--*, data-wp-context,
  • block viewScriptModule / module-based view scripts,
  • hydration issues or “directives don’t fire”.

Inputs required

  • Repo root + triage output (wp-project-triage).
  • Which block/theme/plugin surfaces are affected (frontend, editor, both).
  • Any constraints: WP version, whether modules are supported in the build.

Procedure

1) Detect existing usage + integration style

Search for:

  • data-wp-interactive
  • @wordpress/interactivity
  • viewScriptModule

Decide:

  • Is this a block providing interactivity via block.json view script module?
  • Is this theme-level interactivity?
  • Is this plugin-side “enhance existing markup” usage?

If you’re creating a new interactive block (not just debugging), prefer the official scaffold template:

  • @wordpress/create-block-interactive-template (via @wordpress/create-block)

2) Identify the store(s)

Locate store definitions and confirm:

  • state shape,
  • actions (mutations),
  • callbacks/event handlers used by data-wp-on--*.

3) Server-side rendering (best practice)

Pre-render HTML on the server before outputting to ensure:

  • Correct initial state in the HTML before JavaScript loads (no layout shift).
  • SEO benefits and faster perceived load time.
  • Seamless hydration when the client-side JavaScript takes over.

Enable server directive processing

For components using block.json, add supports.interactivity:

{
  "supports": {
    "interactivity": true
  }
}

For themes/plugins without block.json, use wp_interactivity_process_directives() to process directives.

Initialize state/context in PHP

Use wp_interactivity_state() to define initial global state:

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana', 'Cherry' ),
  'hasItems' => true,
));

For local context, use wp_interactivity_data_wp_context():

<?php
$context = array( 'isOpen' => false );
?>
<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
  ...
</div>

Define derived state in PHP

When derived state affects initial HTML rendering, replicate the logic in PHP:

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana' ),
  'hasItems' => function() {
    $state = wp_interactivity_state();
    return count( $state['items'] ) > 0;
  }
));

This ensures directives like data-wp-bind--hidden="!state.hasItems" render correctly on first load.

For detailed examples and patterns, see references/server-side-rendering.md.

4) Implement or change directives safely

When touching markup directives:

  • keep directive usage minimal and scoped,
  • prefer stable data attributes that map clearly to store state,
  • ensure server-rendered markup + client hydration align.

WordPress 6.9 changes:

  • data-wp-ignore is deprecated and will be removed in future versions. It broke context inheritance and caused issues with client-side navigation. Avoid using it.
  • Unique directive IDs: Multiple directives of the same type can now exist on one element using the --- separator (e.g., data-wp-on--click---plugin-a="..." and data-wp-on--click---plugin-b="...").
  • New TypeScript types: AsyncAction<ReturnType> and TypeYield<T> help with async action typing.

For quick directive reminders, see references/directives-quickref.md.

5) Build/tooling alignment

Verify the repo supports the required module build path:

  • if it uses @wordpress/scripts, prefer its conventions.
  • if it uses custom bundling, confirm module output is supported.

6) Debug common failure modes

If “nothing happens” on interaction:

  • confirm the viewScriptModule is enqueued/loaded,
  • confirm the DOM element has data-wp-interactive,
  • confirm the store namespace matches the directive’s value,
  • confirm there are no JS errors before hydration.

See references/debugging.md.

Verification

  • wp-project-triage indicates signals.usesInteractivityApi: true after your change (if applicable).
  • Manual smoke test: directive triggers and state updates as expected.
  • If tests exist: add/extend Playwright E2E around the interaction path.

Failure modes / debugging

  • Directives present but inert:
    • view script not loading, wrong module entrypoint, or missing data-wp-interactive.
  • Hydration mismatch / flicker:
    • server markup differs from client expectations; simplify or align initial state.
    • derived state not defined in PHP: use wp_interactivity_state() with closures.
  • Initial content missing or wrong:
    • supports.interactivity not set in block.json (for blocks).
    • wp_interactivity_process_directives() not called (for themes/plugins).
    • state/context not initialized in PHP before render.
  • Layout shift on load:
    • derived state like state.hasItems missing on server, causing hidden attribute to be absent.
  • Performance regressions:
    • overly broad interactive roots; scope interactivity to smaller subtrees.
  • Client-side navigation issues (WordPress 6.9):
    • getServerState() and getServerContext() now reset between page transitions—ensure your code doesn't assume stale values persist.
    • Router regions now support attachTo for rendering overlays (modals, pop-ups) dynamically.

Escalation

  • If repo build constraints are unclear, ask: "Is this using @wordpress/scripts or a custom bundler (webpack/vite)?"
  • Consult:
    • references/server-side-rendering.md
    • references/directives-quickref.md
    • references/debugging.md

Related Skills

View on GitHub
GitHub Stars2.2k
CategoryAutomation
Updated1mo ago
Forks322

Languages

JavaScript

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium