wp-skills 1.0.0

package/LICENSE

@@ -0,0 +1,16 @@
+Agent Skills for WordPress
+Copyright (C) 2026 WordPress Contributors
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

package/README.md

@@ -0,0 +1,157 @@
+# Agent Skills for WordPress
+
+**Teach AI coding assistants how to build WordPress the right way.**
+
+Agent Skills are portable bundles of instructions, checklists, and scripts that help AI assistants (Claude, Copilot, Codex, Cursor, Antigravity IDE, etc.) understand WordPress development patterns, avoid common mistakes, and follow best practices.
+
+> **AI Authorship Disclosure:** These skills were generated using GPT-5.2 Codex (High Reasoning) from official Gutenberg and WordPress documentation, then reviewed and edited by WordPress contributors. We tested skills with AI assistants and iterated based on results. This is v1, and skills will improve as the community uses them and contributes fixes. See [docs/ai-authorship.md](docs/ai-authorship.md) for details. ([WordPress AI Guidelines](https://make.wordpress.org/ai/handbook/ai-guidelines/))
+
+## Why Agent Skills?
+
+AI coding assistants are powerful, but they often:
+- Generate outdated WordPress patterns (pre-Gutenberg, pre-block themes)
+- Miss critical security considerations in plugin development
+- Skip proper block deprecations, causing "Invalid block" errors
+- Ignore existing tooling in your repo
+
+Agent Skills solve this by giving AI assistants **expert-level WordPress knowledge** in a format they can actually use.
+
+## Available Skills
+
+| Skill | What it teaches |
+|-------|-----------------|
+| **wordpress-router** | Classifies WordPress repos and routes to the right workflow |
+| **wp-project-triage** | Detects project type, tooling, and versions automatically |
+| **wp-block-development** | Gutenberg blocks: `block.json`, attributes, rendering, deprecations |
+| **wp-block-themes** | Block themes: `theme.json`, templates, patterns, style variations |
+| **wp-plugin-development** | Plugin architecture, hooks, settings API, security |
+| **wp-rest-api** | REST API routes/endpoints, schema, auth, and response shaping |
+| **wp-interactivity-api** | Frontend interactivity with `data-wp-*` directives and stores |
+| **wp-abilities-api** | Capability-based permissions and REST API authentication |
+| **wp-wpcli-and-ops** | WP-CLI commands, automation, multisite, search-replace |
+| **wp-performance** | Profiling, caching, database optimization, Server-Timing |
+| **wp-phpstan** | PHPStan static analysis for WordPress projects (config, baselines, WP-specific typing) |
+| **wp-playground** | WordPress Playground for instant local environments |
+| **wpds** | WordPress Design System |
+
+## Quick Start
+
+### Install via npx (recommended)
+
+```bash
+# Install into current project
+npx wp-skills install --dest=. --targets=codex,vscode,claude,cursor,antigravity
+
+# List available skills
+npx wp-skills list
+```
+
+This installs from the published npm package without cloning this repository.
+
+### Install globally for Claude Code
+
+```bash
+# Clone agent-skills
+git clone https://github.com/WordPress/agent-skills.git
+cd agent-skills
+
+# Install all skills globally (available across all projects)
+node shared/scripts/skillpack-install.mjs --global
+
+# Or install specific skills only
+node shared/scripts/skillpack-install.mjs --global --skills=wp-playground,wp-block-development
+```
+
+This installs skills to `~/.claude/skills/` where Claude Code will automatically discover them.
+
+### Install into your repo
+
+```bash
+# Clone agent-skills
+git clone https://github.com/WordPress/agent-skills.git
+cd agent-skills
+
+# Install into your WordPress project
+node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor,antigravity
+```
+
+This copies skills into:
+- `.codex/skills/` for OpenAI Codex
+- `.github/skills/` for VS Code / GitHub Copilot
+- `.claude/skills/` for Claude Code (project-level)
+- `.cursor/skills/` for Cursor (project-level)
+- `.agent/skill/` for Antigravity IDE (project-level)
+
+### Install globally for Cursor
+
+```bash
+node shared/scripts/skillpack-install.mjs --targets=cursor-global
+```
+
+This installs skills to `~/.cursor/skills/` where Cursor will discover them.
+
+### Available options
+
+```bash
+# List available skills
+node shared/scripts/skillpack-install.mjs --list
+
+# Dry run (preview without installing)
+node shared/scripts/skillpack-install.mjs --global --dry-run
+
+# Install specific skills to a project (e.g. Claude + Antigravity)
+node shared/scripts/skillpack-install.mjs --dest=../my-repo --targets=claude,antigravity --skills=wp-wpcli-and-ops
+```
+
+### Manual installation
+
+Copy any skill folder from `skills/` into your project's instructions directory for your AI assistant.
+
+## How It Works
+
+Each skill contains:
+
+```
+skills/wp-block-development/
+├── SKILL.md              # Main instructions (when to use, procedure, verification)
+├── references/           # Deep-dive docs on specific topics
+│   ├── block-json.md
+│   ├── deprecations.md
+│   └── ...
+└── scripts/              # Deterministic helpers (detection, validation)
+    └── list_blocks.mjs
+```
+
+When you ask your AI assistant to work on WordPress code, it reads these skills and follows the documented procedures rather than guessing.
+
+## Compatibility
+
+- **WordPress 6.9+** (PHP 7.2.24+)
+- Works with any AI assistant that supports project-level instructions
+
+## Contributing
+
+**We welcome contributions!** This project is a great way to share your WordPress expertise—you don't need to be a coding wizard. Most skills are written in Markdown, focusing on clear procedures and best practices.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
+
+Quick commands:
+
+```bash
+# Scaffold a new skill
+node shared/scripts/scaffold-skill.mjs <skill-name> "<description>"
+
+# Validate skills
+node eval/harness/run.mjs
+```
+
+## Documentation
+
+- [Authoring Guide](docs/authoring-guide.md) - How to create and improve skills
+- [Principles](docs/principles.md) - Design philosophy
+- [Packaging](docs/packaging.md) - Build and distribution
+- [Compatibility Policy](docs/compatibility-policy.md) - Version targeting
+
+## License
+
+GPL-2.0-or-later

package/docs/ai-authorship.md

@@ -0,0 +1,60 @@
+# AI Authorship Disclosure
+
+This document describes how AI tools were used to create the skills in this repository, in accordance with the [WordPress AI Guidelines](https://make.wordpress.org/ai/handbook/ai-guidelines/).
+
+## Summary
+
+| Aspect | Details |
+|--------|---------|
+| **AI Tool** | GPT-5.2 Codex (High Reasoning) |
+| **Source Material** | Official Gutenberg trunk documentation, WordPress developer docs |
+| **Human Review** | All skills reviewed and edited by WordPress contributors |
+| **Testing** | Skills tested with AI assistants (Claude, Copilot, Codex) |
+| **License** | GPL-2.0-or-later (compatible with WordPress) |
+
+## Process
+
+1. **Source Collection**: Up-to-date documentation was gathered from Gutenberg trunk and official WordPress developer resources.
+
+2. **AI Generation**: GPT-5.2 Codex (High Reasoning) processed the documentation to create semantically dense skill files, distilling large doc sets into actionable instructions AI assistants can follow.
+
+3. **Contributor Review**: WordPress contributors reviewed each skill for accuracy, alignment with current best practices, and completeness.
+
+4. **AI-Assisted Testing**: Skills were tested by using them with AI coding assistants (Codex and Claude Code) on real WordPress development tasks, sourced from [WP Bench](https://make.wordpress.org/ai/2026/01/14/introducing-wp-bench-a-wordpress-ai-benchmark/) to verify they produce correct guidance. That said, skills have not (yet) been run across a formal evaluation system, *as one does not exist*.
+
+5. **Iteration**: Based on testing results, skills were refined before the v1 release.
+
+## Per-Skill Breakdown
+
+All v1 skills followed the same process described above. As skills diverge in their development history, this table will be updated.
+
+| Skill | AI Generated | Human Reviewed | Tested |
+|-------|--------------|----------------|--------|
+| [wordpress-router](../skills/wordpress-router/SKILL.md) | Yes | Yes | Yes |
+| [wp-project-triage](../skills/wp-project-triage/SKILL.md) | Yes | Yes | Yes |
+| [wp-block-development](../skills/wp-block-development/SKILL.md) | Yes | Yes | Yes |
+| [wp-block-themes](../skills/wp-block-themes/SKILL.md) | Yes | Yes | Yes |
+| [wp-plugin-development](../skills/wp-plugin-development/SKILL.md) | Yes | Yes | Yes |
+| [wp-rest-api](../skills/wp-rest-api/SKILL.md) | Yes | Yes | Yes |
+| [wp-interactivity-api](../skills/wp-interactivity-api/SKILL.md) | Yes | Yes | Yes |
+| [wp-abilities-api](../skills/wp-abilities-api/SKILL.md) | Yes | Yes | Yes |
+| [wp-wpcli-and-ops](../skills/wp-wpcli-and-ops/SKILL.md) | Yes | Yes | Yes |
+| [wp-performance](../skills/wp-performance/SKILL.md) | Yes | Yes | Yes |
+| [wp-phpstan](../skills/wp-phpstan/SKILL.md) | Yes | Yes | Yes |
+| [wp-playground](../skills/wp-playground/SKILL.md) | Yes | Yes | Yes |
+| [wpds](../skills/wpds/SKILL.md) | Yes | Yes | Yes |
+
+## Quality Commitment
+
+These skills are curated distillations of official documentation, reviewed by people who understand WordPress development. That said:
+
+- Skills will contain errors. Please [report issues](https://github.com/WordPress/agent-skills/issues).
+- Skills will improve over time as the community uses them and contributes fixes.
+- We welcome PRs that improve accuracy, fix outdated patterns, or add missing guidance.
+
+## Evolution
+
+This disclosure will be updated as:
+- Individual skills receive significant human rewrites
+- New skills are added with different authorship processes
+- Community feedback identifies areas needing clarification

package/docs/authoring-guide.md

@@ -0,0 +1,56 @@
+# Authoring guide (AI-assisted)
+
+This repo is built for **AI-assisted authoring** with **deterministic guardrails**.
+
+## Golden rules
+
+- Keep `SKILL.md` short and procedural; push depth into `references/` and scripts.
+- Prefer deterministic scripts for anything the agent would otherwise “guess” (repo detection, version checks, lint/test command discovery).
+- Don’t add a new skill without at least one scenario in `eval/scenarios/`.
+- Keep file references 1 hop from `SKILL.md` (avoid deep chains).
+- Include a `compatibility:` frontmatter line matching `docs/compatibility-policy.md`.
+
+## Workflow: draft → harden → ship
+
+1. **Route first**
+   - Start from `skills/wordpress-router/SKILL.md` to classify the repo and pick the domain.
+2. **Collect inputs**
+   - What repo type(s) does triage detect?
+   - What WP/PHP/Node versions are targeted (if known)?
+   - What tooling exists (Composer, @wordpress/scripts, PHPUnit, Playwright, wp-env)?
+3. **Draft the skill (AI-assisted)**
+   - Write `SKILL.md` as a checklist/procedure with explicit “Verification” and “Failure modes”.
+   - Keep examples short; link to topic references when needed.
+4. **Add deterministic helpers**
+   - If the skill depends on detection (versions, project layout, build system), add a script under `scripts/`.
+5. **Add evaluation scenario(s)**
+   - Add at least 1 prompt-style scenario under `eval/scenarios/` describing expected behavior.
+6. **Validate**
+   - Run `node eval/harness/run.mjs`.
+   - Optionally validate frontmatter using `skills-ref validate` (see `docs/upstream-sync.md` for CI guidance).
+
+## Scaffolding a new skill
+
+Use the scaffold script to create a minimal, spec-compliant starting point:
+
+- `node shared/scripts/scaffold-skill.mjs <skill-name> "<description>"`
+
+## “Skill generation” prompt template (recommended)
+
+When using an LLM to draft a skill, provide:
+
+- The repo triage JSON output
+- The user’s task statement(s)
+- Any version constraints and non-goals
+- The required sections: When to use, Inputs required, Procedure, Verification, Failure modes, Escalation
+
+Then ask the model to output:
+
+1. `skills/<skill-name>/SKILL.md`
+2. Any `references/*.md` files it mentions
+3. Any `scripts/*` stubs needed for deterministic checks
+4. One scenario markdown file under `eval/scenarios/`
+
+## Suggested initial domain skills (v1)
+
+See `docs/skill-set-v1.md`.

package/docs/compatibility-policy.md

@@ -0,0 +1,18 @@
+# Compatibility policy
+
+This repo is an authoring workspace for WordPress-focused Agent Skills.
+
+## Compatibility contract (v1)
+
+Skills in this repo target:
+
+- WordPress core **6.9+**
+- PHP **7.2.24+** (minimum supported by WordPress 6.9)
+
+## Authoring rules
+
+Skills should:
+
+- Prefer stable WordPress APIs and best practices.
+- Prefer detection + guardrails (triage) over hard-coded assumptions.
+- If a task requires behavior that differs across core versions, ask for a target version (but default guidance should assume WP 6.9+).

package/docs/packaging.md

@@ -0,0 +1,35 @@
+# Packaging and installation
+
+This repo is the **source of truth** under `skills/`.
+
+To distribute skills to other repos/tools (without symlinks), use the skillpack scripts or npm CLI.
+
+## Install directly (no dist required)
+
+Install from source layout (or from npm package via `npx`):
+
+- `node shared/scripts/skillpack-install.mjs --dest=../some-repo --targets=codex,vscode,claude,cursor,antigravity`
+- `npx wp-skills install --dest=. --targets=codex,vscode,claude,cursor,antigravity`
+
+## Build dist
+
+Build a packaged copy under `dist/`:
+
+- `node shared/scripts/skillpack-build.mjs --clean`
+
+Outputs:
+
+- `dist/codex/.codex/skills/*` (OpenAI Codex repo layout)
+- `dist/vscode/.github/skills/*` (VS Code / Copilot repo layout)
+- `dist/claude/.claude/skills/*` (Claude Code repo layout)
+- `dist/cursor/.cursor/skills/*` (Cursor repo layout)
+- `dist/antigravity/.agent/skill/*` (Antigravity IDE repo layout)
+
+## Install into another repo
+
+1. Build dist (above), or skip this when installing from source/npm.
+2. Install into a destination repo:
+
+- `node shared/scripts/skillpack-install.mjs --dest=../some-repo --targets=codex,vscode,claude,cursor,antigravity`
+
+By default, install mode is `replace` (it replaces only the skill directories it installs).

package/docs/principles.md

@@ -0,0 +1,7 @@
+# Principles
+
+- Prefer small, composable skills over a single "mega-skill".
+- Keep `SKILL.md` bodies short; move depth into `references/`.
+- Bundle deterministic checks as scripts when reliability matters.
+- Treat upstream docs as canonical; store agent-first checklists and decision trees.
+- Every new skill must include at least one eval scenario under `eval/scenarios/`.

package/docs/skill-set-v1.md

@@ -0,0 +1,21 @@
+# WordPress skill set (v1)
+
+This repo currently includes:
+
+- `wordpress-router`
+- `wp-project-triage`
+- `wp-block-development`
+- `wp-block-themes`
+- `wp-plugin-development`
+- `wp-rest-api`
+- `wp-interactivity-api`
+- `wp-abilities-api`
+- `wp-wpcli-and-ops`
+- `wp-performance`
+- `wp-phpstan`
+
+Planned next skills (not yet implemented):
+
+- `wp-build-tooling`
+- `wp-testing`
+- `wp-security`

package/docs/upstream-sync.md

@@ -0,0 +1,52 @@
+# Upstream sync (automation plan)
+
+Goal: when upstream changes (WordPress core releases, Gutenberg releases, docs updates), the repo should **regenerate indexes** and (eventually) **open PRs** that update affected skills/references.
+
+## What to automate first (low risk)
+
+1. **Indexes and matrices**
+   - WordPress core version list (latest stable + recent).
+   - Gutenberg releases list (latest stable + recent).
+   - WordPress ↔ Gutenberg mapping table (derived from canonical docs where available).
+2. **Routing metadata refresh**
+   - Update `shared/references/*.json` files only.
+
+This keeps automation deterministic and reviewable before it starts rewriting skill prose.
+
+## Later automation (higher risk)
+
+- “Reference chunk regeneration” from upstream docs into `skills/*/references/*.md`.
+- Task-shaped deltas (e.g. a new Gutenberg package, new block APIs, changes in theme.json schema).
+- Semi-automated PRs that include:
+  - regenerated references
+  - updated checklists
+  - updated eval scenarios
+
+## Scripts
+
+- `shared/scripts/update-upstream-indices.mjs`
+  - Fetches upstream sources and rewrites JSON indexes in `shared/references/`.
+
+## CI / PR bot design (recommended)
+
+- Schedule a workflow (daily/weekly).
+- Run `shared/scripts/update-upstream-indices.mjs`.
+- If `git diff` is non-empty, open a PR with:
+  - a summary of changes
+  - links to upstream release notes
+  - a checklist for human review (“does this impact blocks/themes/plugin workflows?”)
+
+## Validation
+
+- Always run `node eval/harness/run.mjs`.
+- Optional: use Agent Skills reference validator:
+  - `skills-ref validate skills/<skill-name>`
+
+## Canonical sources
+
+The automation should prefer canonical sources and avoid scraping where possible.
+
+- WordPress core releases and API endpoints (official WordPress APIs)
+- Gutenberg releases (GitHub releases)
+- WordPress developer docs (used for the WP↔Gutenberg mapping when no API exists)
+

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "wp-skills",
+  "version": "1.0.0",
+  "description": "WordPress Agent Skills installer and packager",
+  "license": "GPL-2.0-or-later",
+  "type": "module",
+  "bin": {
+    "wp-skills": "shared/scripts/skillpack-cli.mjs",
+    "agent-skills": "shared/scripts/skillpack-cli.mjs"
+  },
+  "files": [
+    "skills",
+    "shared/scripts",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}