wp-interactivity-api

Overview of wp-interactivity-api skill

What this skill does

The wp-interactivity-api skill helps you build or debug WordPress Interactivity API features without guessing at directives, store shape, or server/client wiring. It is most useful when you are working with data-wp-* markup, @wordpress/interactivity, viewScriptModule, or wp_interactivity_*() functions and need a practical path from a broken interaction to a working one.

Who it is for

Use the wp-interactivity-api skill if you are doing Frontend Development in a WordPress block, theme, or plugin and need interactive UI that survives the first render cleanly. It is a strong fit when you already have a repo and need help tracing why hydration fails, why a directive does not fire, or how to structure a new interactive region correctly.

Why it is worth installing

The main value is decision speed: it tells you what to search for, what inputs matter, and how to separate block-based, theme-level, and plugin-enhancement approaches. That makes the wp-interactivity-api guide more useful than a generic prompt because it reflects the actual constraints of WordPress 6.9+ and the way this API is wired.

How to Use wp-interactivity-api skill

Install and scope it correctly

Use the wp-interactivity-api install pattern from the directory entry point, then apply the skill inside a filesystem-backed agent session with bash and Node available. The repository notes WordPress 6.9+ compatibility and, for some workflows, WP-CLI; if your environment cannot inspect the project files or run WordPress commands, results will be weaker.

Give it the right starting inputs

The wp-interactivity-api usage works best when you provide:

• repo root
• triage output from wp-project-triage
• affected surface: frontend, editor, or both
• WordPress version and any module/build constraints

A weak prompt is: “Fix the Interactivity API.”
A stronger prompt is: “Debug why data-wp-on--click does not fire in this block on the frontend, WordPress 6.9, module scripts enabled, triage attached, and the issue only appears after navigation.”

Read these files first

Start with SKILL.md, then open:

• references/directives-quickref.md for directive names and search anchors
• references/debugging.md for the failure checklist
• references/server-side-rendering.md for PHP-side setup and hydration rules

If you are deciding whether the skill fits the current task, those three files show the real workflow faster than the repo tree alone.

Follow the practical workflow

The skill is organized around a simple sequence:

1. detect existing usage with searches for data-wp-interactive, @wordpress/interactivity, and viewScriptModule
2. identify the store namespace and whether markup expects the same name
3. verify server-rendered context and initial state
4. check whether the root element, view script module, and event directives are all present in rendered HTML
5. reduce scope until the broken directive or state path is isolated

For new interactive blocks, prefer the official scaffold template rather than inventing structure from scratch.

wp-interactivity-api skill FAQ

Is this only for debugging?

No. The wp-interactivity-api skill covers both build and debug work. It is especially useful when you need to decide whether to add interactivity through a block viewScriptModule, enhance existing markup in a plugin, or wire theme-level behavior in a way that still hydrates correctly.

How is it different from a normal prompt?

A normal prompt often skips the WordPress-specific details that actually decide success: directive naming, store namespace matching, server-side context, and WordPress 6.9 behavior changes. This skill bakes in those checks, which reduces false starts and helps the agent read the right files first.

Is it beginner-friendly?

Yes, if you can describe the goal and point the agent at the right repo area. It is not a tutorial for learning the whole API from scratch, but it does help beginners avoid the most common adoption mistakes: missing the interactive root, mismatched namespaces, and using the wrong rendering path.

When should I not use it?

Do not use it for unrelated JavaScript UI work outside WordPress Interactivity API, or when your feature is purely static and does not need server-rendered directives. It is also a poor fit if you cannot inspect the actual repo files, because the skill relies on repo-specific markup and PHP/JS integration details.

How to Improve wp-interactivity-api skill

Give more precise source context

The best results come from showing the current block, theme, or plugin surface plus the exact directive or function you want reviewed. Include snippets around data-wp-interactive, data-wp-context, and the matching store namespace so the agent can compare intent against implementation instead of inferring it.

State the failure mode, not just the symptom

For the wp-interactivity-api skill, “button does nothing” is too vague. Better inputs name the observable break and the expected behavior: “click handler is bound but state does not update after server render,” or “hydration works on first load but fails after client-side navigation.” That helps distinguish directive issues from state initialization or module loading problems.

Ask for repository-reading output, then iterate

A good wp-interactivity-api guide workflow is to ask for:

• the likely root cause
• the exact files to inspect next
• the minimal code change
• any WordPress 6.9 compatibility risk

Then iterate with the first result in hand. If the issue is about server rendering, include the relevant PHP and rendered HTML. If it is about event handling, include the directive markup and the store actions file. That turns the skill from a search helper into a usable implementation checklist.