wp-skills 1.0.0 → 1.0.2

package/LICENSE

@@ -1,16 +1,15 @@
-Agent Skills for WordPress
-Copyright (C) 2026 WordPress Contributors
+Duke Dev License
 
-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.
+Copyright (c) 2026 Duke Dev
+All rights reserved.
 
-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.
+Permission to use, copy, modify, and distribute this software is granted only
+with explicit written permission from Duke Dev.
 
-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.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,157 +1,101 @@
-# Agent Skills for WordPress
+# WordPress Team Skills (Senior Dev Kit)
 
-**Teach AI coding assistants how to build WordPress the right way.**
+This skill pack helps WordPress teams (classic themes, block themes, and plugins) execute with senior-level standards: clear architecture, explicit guardrails, and verification-first workflows.
 
-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.
+## Quick Install
 
-> **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)
+Install all skills into the current project:
 
 ```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
+List available skills:
 
 ```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
+npx wp-skills list
 ```
 
-This installs skills to `~/.claude/skills/` where Claude Code will automatically discover them.
-
-### Install into your repo
+Install a single skill:
 
 ```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
+npx wp-skills install --dest=. --targets=codex,vscode,claude,cursor,antigravity --skills=classic-theme-dev
 ```
 
-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)
+Installed locations:
 
-### Install globally for Cursor
+- `.codex/skills/`
+- `.github/skills/`
+- `.claude/skills/`
+- `.cursor/skills/`
+- `.agent/skill/`
 
-```bash
-node shared/scripts/skillpack-install.mjs --targets=cursor-global
-```
+## Team Usage Flow
 
-This installs skills to `~/.cursor/skills/` where Cursor will discover them.
+1. Start with `wordpress-router` or `wp-project-triage` to classify repository context.
+2. Select the domain skill (theme, frontend, plugin/API, ops, review/migration).
+3. Provide explicit inputs: URL/page type, file scope, and compatibility constraints.
+4. Require explicit verification before merge or release.
 
-### Available options
+Prompt examples:
 
-```bash
-# List available skills
-node shared/scripts/skillpack-install.mjs --list
+- `Use wordpress-router and wp-project-triage, then choose the right skill for this repository.`
+- `Use classic-theme-dev to map URL -> template -> hook and implement the fix.`
+- `Use wp-dev-workflow for a WordPress-focused code review with security and performance findings.`
 
-# Dry run (preview without installing)
-node shared/scripts/skillpack-install.mjs --global --dry-run
+## Skill Catalog
 
-# 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
-```
+### Routing and triage
 
-### Manual installation
+- [wordpress-router](skills/wordpress-router/README.md)
+- [wp-project-triage](skills/wp-project-triage/README.md)
 
-Copy any skill folder from `skills/` into your project's instructions directory for your AI assistant.
+### Theme development
 
-## How It Works
+- [classic-theme-dev](skills/classic-theme-dev/README.md)
+- [block-theme-dev](skills/block-theme-dev/README.md)
+- [wp-block-themes](skills/wp-block-themes/README.md)
+- [wp-block-development](skills/wp-block-development/README.md)
 
-Each skill contains:
+### Frontend
 
-```
-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
-```
+- [frontend-wp](skills/frontend-wp/README.md)
+- [wp-interactivity-api](skills/wp-interactivity-api/README.md)
+- [wpds](skills/wpds/README.md)
 
-When you ask your AI assistant to work on WordPress code, it reads these skills and follows the documented procedures rather than guessing.
+### Plugin, API, and capabilities
 
-## Compatibility
+- [wp-plugin-development](skills/wp-plugin-development/README.md)
+- [wp-rest-api](skills/wp-rest-api/README.md)
+- [wp-abilities-api](skills/wp-abilities-api/README.md)
 
-- **WordPress 6.9+** (PHP 7.2.24+)
-- Works with any AI assistant that supports project-level instructions
+### Tooling, ops, and quality
 
-## Contributing
+- [wp-wpcli-and-ops](skills/wp-wpcli-and-ops/README.md)
+- [wp-performance](skills/wp-performance/README.md)
+- [wp-phpstan](skills/wp-phpstan/README.md)
+- [wp-playground](skills/wp-playground/README.md)
+- [wp-dev-workflow](skills/wp-dev-workflow/README.md)
 
-**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.
+## Recommended Team Bundles
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
+- `classic-theme-dev` + `frontend-wp` + `wp-dev-workflow`
+- `block-theme-dev` + `wp-block-development` + `wp-interactivity-api`
+- `wp-plugin-development` + `wp-rest-api` + `wp-abilities-api`
+- `wp-wpcli-and-ops` + `wp-performance` + `wp-phpstan`
 
-Quick commands:
+## Maintain and Validate
 
 ```bash
-# Scaffold a new skill
-node shared/scripts/scaffold-skill.mjs <skill-name> "<description>"
-
-# Validate skills
+# Validate the skill set
 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
+# List available skills from local repository
+node shared/scripts/skillpack-install.mjs --list
+```
 
-## License
+Related docs:
 
-GPL-2.0-or-later
+- [docs/authoring-guide.md](docs/authoring-guide.md)
+- [docs/packaging.md](docs/packaging.md)
+- [docs/skill-set-v1.md](docs/skill-set-v1.md)

package/docs/skill-set-v1.md

@@ -13,6 +13,12 @@ This repo currently includes:
 - `wp-wpcli-and-ops`
 - `wp-performance`
 - `wp-phpstan`
+- `wp-playground`
+- `wpds`
+- `classic-theme-dev`
+- `block-theme-dev`
+- `frontend-wp`
+- `wp-dev-workflow`
 
 Planned next skills (not yet implemented):
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "wp-skills",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "WordPress Agent Skills installer and packager",
-  "license": "GPL-2.0-or-later",
+  "license": "Duke Dev",
   "type": "module",
   "bin": {
     "wp-skills": "shared/scripts/skillpack-cli.mjs",

package/skills/block-theme-dev/README.md

@@ -0,0 +1,46 @@
+# Block Theme Dev
+
+## Purpose
+
+Use when building or migrating WordPress block themes using theme.json, templates/parts, patterns, and custom block integration.
+
+## Install this skill only
+
+Use npm package (recommended):
+
+```bash
+npx wp-skills install --dest=. --targets=codex,vscode,claude,cursor,antigravity --skills=block-theme-dev
+```
+
+Use local repository scripts:
+
+```bash
+node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor,antigravity --skills=block-theme-dev
+```
+
+## When to use
+
+- Apply this skill when your task matches the scope in [SKILL.md](./SKILL.md).
+- Typical trigger prompt: `Use block-theme-dev to handle this task in my WordPress repo`.
+
+## Inputs to provide
+
+- Repository root (or target project path).
+- Exact task goal (feature, refactor, debugging, migration, or review).
+- Constraints: WordPress/PHP versions, plugin/theme boundaries, timeline/risk constraints.
+
+## Expected output
+
+- Clear implementation plan tied to project context.
+- File-level changes or command steps with verification.
+- Guardrails and risks called out before high-impact operations.
+
+## Team guardrails
+
+- Prefer existing repo conventions and tooling over introducing new patterns.
+- Avoid destructive DB/content operations without explicit approval.
+- Keep backward compatibility visible for production WordPress sites.
+
+## References
+
+- Main instructions: [SKILL.md](./SKILL.md)

package/skills/block-theme-dev/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: block-theme-dev
+description: Use when building or migrating WordPress block themes using theme.json, templates/parts, patterns, and custom block integration.
+compatibility: Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node.
+---
+
+# Block Theme Dev
+
+## When to use
+
+Use this skill for block themes and hybrid migrations when the task touches:
+
+- `theme.json` settings/styles,
+- `templates/*.html` and `parts/*.html`,
+- block patterns,
+- classic -> block theme migration,
+- block-theme rendering/debugging in Site Editor workflows.
+
+## Inputs required
+
+- Repo root.
+- Target template/page type or user flow.
+- Desired design/system constraints (colors, spacing, typography, layout).
+- Migration scope (full block theme vs hybrid).
+
+## Procedure
+
+1. Classify and confirm block-theme context:
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+   - Confirm signals: `theme.json`, `templates/`, `parts/`, pattern registration.
+2. Audit current theme model:
+   - Review `theme.json` for global styles, presets, spacing/layout constraints.
+   - Map template and part coverage for home/single/page/archive/404/header/footer.
+3. Implement requested change in the smallest stable layer:
+   - Global design tokens -> `theme.json`.
+   - Page structure -> `templates/*.html` and `parts/*.html`.
+   - Reusable content sections -> patterns.
+4. For pattern work:
+   - Use deterministic slugs and categories.
+   - Prefer core blocks and minimal custom CSS hooks.
+   - Ensure pattern markup is editable by content teams.
+5. For classic -> block migration:
+   - Preserve parity first (header/footer/core layouts) before enhancement.
+   - Flag likely breakpoints: shortcode-dependent sections, widget areas, hard-coded template logic.
+   - Keep backward compatibility notes in the response.
+
+## Verification
+
+- Validate changed templates/parts and `theme.json` syntax.
+- Verify intended template selection for target URLs/page types.
+- Run project lint/build/test commands when available.
+
+## Failure modes / debugging
+
+- Styles not applying:
+  - check `theme.json` scope and preset references.
+- Wrong template used:
+  - verify template hierarchy and slug naming.
+- Pattern regressions:
+  - test insertion/editing in editor to ensure block validity.
+
+## Escalation
+
+If migration scope is unclear, ask one question:
+
+- "Do you want full block-theme migration or hybrid with classic templates kept?"
+
+## Do not do
+
+- Do not remove classic templates/widgets without explicit migration approval.
+- Do not hard-code environment-specific URLs/IDs in patterns/templates.
+- Do not bypass validation for block markup changes.

package/skills/classic-theme-dev/README.md

@@ -0,0 +1,46 @@
+# Classic Theme Dev
+
+## Purpose
+
+Use when building, refactoring, or debugging classic WordPress themes with template hierarchy, hooks, and URL-to-template mapping.
+
+## Install this skill only
+
+Use npm package (recommended):
+
+```bash
+npx wp-skills install --dest=. --targets=codex,vscode,claude,cursor,antigravity --skills=classic-theme-dev
+```
+
+Use local repository scripts:
+
+```bash
+node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor,antigravity --skills=classic-theme-dev
+```
+
+## When to use
+
+- Apply this skill when your task matches the scope in [SKILL.md](./SKILL.md).
+- Typical trigger prompt: `Use classic-theme-dev to handle this task in my WordPress repo`.
+
+## Inputs to provide
+
+- Repository root (or target project path).
+- Exact task goal (feature, refactor, debugging, migration, or review).
+- Constraints: WordPress/PHP versions, plugin/theme boundaries, timeline/risk constraints.
+
+## Expected output
+
+- Clear implementation plan tied to project context.
+- File-level changes or command steps with verification.
+- Guardrails and risks called out before high-impact operations.
+
+## Team guardrails
+
+- Prefer existing repo conventions and tooling over introducing new patterns.
+- Avoid destructive DB/content operations without explicit approval.
+- Keep backward compatibility visible for production WordPress sites.
+
+## References
+
+- Main instructions: [SKILL.md](./SKILL.md)

package/skills/classic-theme-dev/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: classic-theme-dev
+description: Use when building, refactoring, or debugging classic WordPress themes with template hierarchy, hooks, and URL-to-template mapping.
+compatibility: Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node.
+---
+
+# Classic Theme Dev
+
+## When to use
+
+Use this skill for classic themes (`style.css` header + PHP templates) when the task involves:
+
+- theme architecture analysis,
+- URL -> template -> hook mapping,
+- template hierarchy decisions,
+- hook/filter-based UI or query customization,
+- refactoring legacy `functions.php` and template logic.
+
+## Inputs required
+
+- Repo root.
+- Target URL or page type (home, single, archive, taxonomy, search).
+- Desired change (UI, query, metadata, behavior).
+- Constraints (child theme policy, backward compatibility requirements).
+
+## Procedure
+
+1. Classify project context:
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+   - Confirm classic theme signals: `style.css` theme header, PHP templates, no mandatory `templates/*.html` rendering path.
+2. Build architecture map (text output in response):
+   - Locate registration and bootstrap points with `rg`:
+     - `add_theme_support|register_nav_menus|register_sidebar|add_image_size`
+     - `register_post_type|register_taxonomy|add_shortcode`
+     - `add_action|add_filter|remove_action|remove_filter`
+   - Summarize: request entry -> query shaping -> template chosen -> key hooks/functions used.
+3. Map URL to template/hook path:
+   - Apply template hierarchy rules (`single-{post_type}.php`, `archive-{post_type}.php`, `category-{slug}.php`, etc.).
+   - Check custom overrides (`template_include`, `pre_get_posts`, custom query args).
+   - Provide exact candidate files and hook insertion points.
+4. Implement with safe theme patterns:
+   - Keep templates focused on rendering; move business logic to reusable functions/classes under `inc/` or `src/`.
+   - Prefer `get_template_part()` for repeated sections.
+   - Prefer hooks/filters over invasive template rewrites when possible.
+5. Produce hook map delta when editing hooks:
+   - Note added/changed/removed actions and filters.
+
+## Verification
+
+- Run available project checks from triage output (lint/tests/build).
+- Lint changed PHP files (at minimum `php -l <file>` when toolchain is absent).
+- Confirm affected URL/page type resolves to intended template and no fatal error is introduced.
+
+## Failure modes / debugging
+
+- Wrong template selected:
+  - inspect hierarchy-specific filenames and any `template_include` filters.
+- Query side effects:
+  - verify `pre_get_posts` guards (`is_admin`, `is_main_query`, conditional checks).
+- Mixed classic + block behavior:
+  - check whether hybrid/block templates are taking precedence.
+
+## Escalation
+
+Ask one clarifying question if URL/page target is ambiguous:
+
+- "Which exact URL and user-visible section should be changed?"
+
+## Do not do
+
+- Do not modify database schema/content directly.
+- Do not edit vendor/core/plugin files unless explicitly requested.
+- Do not perform destructive mass replacements without dry-run and approval.

package/skills/frontend-wp/README.md

@@ -0,0 +1,46 @@
+# Frontend WP
+
+## Purpose
+
+Use when implementing WordPress frontend CSS/SCSS architecture, JavaScript behavior, and asset loading/performance across classic and block themes.
+
+## Install this skill only
+
+Use npm package (recommended):
+
+```bash
+npx wp-skills install --dest=. --targets=codex,vscode,claude,cursor,antigravity --skills=frontend-wp
+```
+
+Use local repository scripts:
+
+```bash
+node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor,antigravity --skills=frontend-wp
+```
+
+## When to use
+
+- Apply this skill when your task matches the scope in [SKILL.md](./SKILL.md).
+- Typical trigger prompt: `Use frontend-wp to handle this task in my WordPress repo`.
+
+## Inputs to provide
+
+- Repository root (or target project path).
+- Exact task goal (feature, refactor, debugging, migration, or review).
+- Constraints: WordPress/PHP versions, plugin/theme boundaries, timeline/risk constraints.
+
+## Expected output
+
+- Clear implementation plan tied to project context.
+- File-level changes or command steps with verification.
+- Guardrails and risks called out before high-impact operations.
+
+## Team guardrails
+
+- Prefer existing repo conventions and tooling over introducing new patterns.
+- Avoid destructive DB/content operations without explicit approval.
+- Keep backward compatibility visible for production WordPress sites.
+
+## References
+
+- Main instructions: [SKILL.md](./SKILL.md)

package/skills/frontend-wp/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: frontend-wp
+description: Use when implementing WordPress frontend CSS/SCSS architecture, JavaScript behavior, and asset loading/performance across classic and block themes.
+compatibility: Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node.
+---
+
+# Frontend WP
+
+## When to use
+
+Use this skill when building or refactoring theme frontend behavior and styling for:
+
+- CSS/SCSS architecture,
+- Gutenberg editor vs frontend styling boundaries,
+- JavaScript behavior (menu, modal, accordion, tabs, lazy-load),
+- WordPress enqueue strategy and performance.
+
+## Inputs required
+
+- Repo root and target UI component/page.
+- Existing CSS strategy (BEM, ITCSS, utility-first, custom).
+- Browser/performance constraints and plugin compatibility constraints.
+
+## Procedure
+
+1. Discover stack and conventions:
+   - Identify existing CSS organization and naming rules.
+   - Identify JS build/runtime path and enqueue points (`wp_enqueue_style`, `wp_enqueue_script`).
+2. Align with one style strategy (do not mix ad hoc):
+   - Keep tokens/variables centralized.
+   - Separate base/layout/components/utilities if project supports layering.
+3. Implement styles with editor/frontend separation:
+   - Frontend styles for site output.
+   - Editor-specific styles only when necessary for parity.
+4. Implement JS behavior with WP-safe loading:
+   - Register/enqueue with dependencies and predictable handles.
+   - Avoid inline JS unless no alternative exists.
+   - Ensure behavior degrades safely if dependency is missing.
+5. Optimize delivery:
+   - Avoid duplicate bundles.
+   - Load only where needed.
+   - Minimize conflicts with plugins/page builders by scoping selectors and events.
+
+## Verification
+
+- Validate no console errors on affected pages.
+- Validate behavior works without breaking editor experience.
+- Run available lint/build/test commands.
+
+## Failure modes / debugging
+
+- Style leaks:
+  - tighten selector scope and component boundaries.
+- Script conflicts:
+  - verify handle uniqueness and dependency order.
+- Editor mismatch:
+  - check editor-only style loading and block wrapper classes.
+
+## Escalation
+
+If style system is inconsistent, ask one question:
+
+- "Should I standardize this change on the current project convention or introduce a new CSS architecture now?"
+
+## Do not do
+
+- Do not add large frontend dependencies without explicit approval.
+- Do not enqueue global assets for single-page-only features unless requested.
+- Do not use brittle selectors tied to dynamic plugin-generated markup when stable hooks exist.