wordpress-agent-kit 0.3.2 → 0.5.1

package/.github/skills/wp-wpengine/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: wp-wpengine
+description: "Optional: Use for WP Engine hosting workflows — SSH-based git push to WP Engine environments, managing installs/domains/cache/backups via the wpe-labs Claude Code skills, and WP Engine API access. Requires WPE_USERNAME and WPE_PASSWORD env vars."
+license: GPL-2.0-or-later
+optional: true
+---
+
+# WP Engine
+
+## When to use
+
+- Deploy WordPress code to a WP Engine environment via `git push`.
+- Manage WP Engine installs, domains, cache, backups, or users through natural language.
+- Generate monthly usage/bandwidth reports across WP Engine accounts.
+- Manage LargeFS media offload configuration.
+
+## Prerequisites
+
+- SSH key for WP Engine git push stored in 1Password (`Employee` vault, item `wpengine_ed25519`).
+- WP Engine API credentials in 1Password (`Employee` vault, item `WP Engine API`).
+- `op` CLI authenticated (`op whoami` works).
+- The `wpe-labs` Claude Code skills installed (`~/.claude/skills/wpe-labs:*`).
+
+## Procedure
+
+### 1) First-time SSH setup on a new machine
+
+Pull the private key from 1Password and configure SSH:
+
+```bash
+op read "op://Employee/wpengine_ed25519/private key" > ~/.ssh/wpengine_ed25519
+chmod 600 ~/.ssh/wpengine_ed25519
+ssh-keyscan git.wpengine.com >> ~/.ssh/known_hosts
+```
+
+Add to `~/.ssh/config` (before any `Host *` block):
+```
+Host git.wpengine.com
+  User git
+  IdentityFile ~/.ssh/wpengine_ed25519
+  IdentitiesOnly yes
+```
+
+Verify:
+```bash
+ssh git@git.wpengine.com info
+# Expected: hello <username> / R W <install-name>
+```
+
+The public key is already registered on WP Engine — no portal action needed on new machines.
+
+### 2) Add a WP Engine git remote
+
+Find the remote URL on the WP Engine portal: `https://my.wpengine.com/installs/<ENV>/git_push`
+
+```bash
+git remote add wpengine git@git.wpengine.com:<install-name>.git
+# Example for staging:
+git remote add wpengine-staging git@git.wpengine.com:<install-name>stg.git
+```
+
+### 3) Deploy via git push
+
+```bash
+git push wpengine main
+```
+
+- WP Engine deploys the pushed branch automatically.
+- Only the WordPress files are pushed (not `node_modules`, build artifacts, etc.).
+- After push, WP Engine may take 1–2 min to propagate the deploy.
+
+### 4) wpe-labs skills (natural language management)
+
+Load API credentials, then use any `/wpe-labs:*` skill:
+
+```bash
+# Load credentials from 1Password for the session
+eval $(op run --env-file ~/.config/op-ssh/.env.1pass -- env | grep ^WPE | sed 's/^/export /')
+```
+
+Available skills:
+
+| Skill | What it does | Risk |
+|---|---|---|
+| `/wpe-labs:account-usage` | Bandwidth, visits, storage across accounts | 🟢 Read-only |
+| `/wpe-labs:monthly-report` | Client-ready monthly usage report | 🟢 Read-only |
+| `/wpe-labs:backups` | On-demand backups + progress monitoring | 🟡 Write |
+| `/wpe-labs:cache` | Purge object/page/CDN cache | 🟡 Write |
+| `/wpe-labs:users` | List, invite, update roles, remove users | 🟡/🔴 |
+| `/wpe-labs:domains` | Manage domains, DNS, SSL | 🟡/🔴 |
+| `/wpe-labs:installs` | List, create, copy WordPress installs | 🟡/🔴 |
+| `/wpe-labs:offload` | LargeFS media offload config | 🟡 Write |
+
+Example prompts:
+```
+/wpe-labs:account-usage which accounts are closest to their bandwidth limit?
+/wpe-labs:cache purge all cache for uofdev production
+/wpe-labs:backups back up uofdev production before deployment
+/wpe-labs:installs copy uofdev production to staging
+/wpe-labs:monthly-report last month
+```
+
+### 5) Re-installing wpe-labs skills
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/wpengine/wpe-labs-platform-skills/main/install.sh | bash
+```
+
+## Verification
+
+- SSH: `ssh git@git.wpengine.com info` — should return `hello <username> / R W <install>`
+- API: `op run --env-file ~/.config/op-ssh/.env.1pass -- bash -c 'curl -s -u "$WPE_USERNAME:$WPE_PASSWORD" https://api.wpengineapi.com/v1/user | jq .email'`
+
+## Failure modes
+
+- **SSH: Host key verification failed** — re-run `ssh-keyscan git.wpengine.com >> ~/.ssh/known_hosts`
+- **SSH: Permission denied** — confirm the key is at `~/.ssh/wpengine_ed25519` with `chmod 600`
+- **git push rejected** — verify the remote URL matches the install name exactly
+- **wpe-labs: 401 Unauthorized** — regenerate API credentials at `https://my.wpengine.com/api_access` and update the `WP Engine API` item in 1Password
+- **wpe-labs: storage shows zero** — ask Claude to "refresh storage" (async recalculation, ~30–60s)
+
+## References
+
+- WP Engine git push portal: `https://my.wpengine.com/installs/<ENV>/git_push`
+- WP Engine API access: `https://my.wpengine.com/api_access`
+- wpe-labs skills source: `https://github.com/wpengine/wpe-labs-platform-skills`
+- SSH setup log (first machine): gist `602d6a16ddfea438c0611a8e5cc31d5e`

package/AGENTS.md

@@ -1,8 +1,9 @@
 # Project: WordPress Agent Kit (CLI)
 
-This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent configuration for WordPress projects. It helps developers quickly set up `AGENTS.md` and `.github` skills/instructions in their repositories.
+This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent configuration for WordPress projects. It helps developers quickly set up `AGENTS.md` and `.agents/skills/` in their repositories.
 
 ## Tech Stack
+
 - **Language**: TypeScript (Node.js)
 - **Framework**: Commander.js
 - **Prompting**: `@clack/prompts`
@@ -11,20 +12,24 @@ This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent config
 - **Lint/Format**: Biome + ESLint
 
 ## Architecture
+
 - **Entry Point**: `src/cli.ts`
 - **Commands**: `src/commands/*.ts` (e.g., `install`, `setup`, `sync-skills`, `playground`, `upgrade`)
 - **Core Logic**: `src/lib/*.ts` (e.g., `installer.ts` for file copying, `triage-mapper.ts` for project detection, `api.ts` for programmatic API)
 - **Utilities**: `src/utils/*.ts` (e.g., `paths.ts`, `run.ts`, `output.ts`, `exit-codes.ts`)
-- **Assets**: 
+- **Assets**:
   - `AGENTS.template.md`: The template file copied to user projects.
-  - `.github/`: The source of skills (14 WordPress skills), instructions, agents, and prompts copied to user projects.
-  - `vendor/wp-agent-skills/`: Submodule containing upstream skills.
+  - `.github/`: Platform-specific agents, instructions, and prompts (copied to target platform dir).
+  - `.agents/skills/`: Universal skills directory (AgentSkills.io convention), copied to target `.agents/skills/`.
+  - `skills-custom/`: Custom skills that survive upstream syncs, merged into `.agents/skills/` on install.
 
 ## Package Exports
+
 - `wordpress-agent-kit` → CLI entry (`dist/cli.js`)
 - `wordpress-agent-kit/api` → Programmatic API (`dist/lib/api.js`)
 
 ## Development Workflow
+
 - **Run locally**: `npm run dev` (uses `tsx src/cli.ts`)
 - **Build**: `npm run build` (outputs to `dist/`)
 - **TypeCheck**: `npm run check` (no-emit type checking)
@@ -34,29 +39,36 @@ This is a Node.js CLI tool (`wp-agent-kit`) designed to scaffold AI agent config
 - **Pre-commit**: Husky runs lint:check + test:run
 
 ## Key Commands
-- `install`: Copies `.github` and `AGENTS.md` template to a target directory. Supports `--json`, `--dry-run`, `--ndjson`.
+
+- `install`: Copies `.agents/skills/` (universal convention), platform agents/instructions, and `AGENTS.md` template to a target directory. Supports `--json`, `--dry-run`, `--ndjson`. Merges custom skills from `skills-custom/`.
 - `setup`: Interactive wizard that detects project type and configures the kit. Supports `--auto`, `--project-type`, `--tech-stack`, `--yes`.
-- `sync-skills`: Pulls skills from `WordPress/agent-skills` into `.github/skills`. Supports `--json`, `--dry-run`.
+- `sync-skills`: Pulls skills from `WordPress/agent-skills` into `.agents/skills/` (canonical, AgentSkills.io convention), merging custom skills from `skills-custom/`. Supports `--json`, `--dry-run`.
+- `clean-skills`: Detects and removes orphaned skills that are no longer part of the kit. Supports `--dry-run`, `--remove`, `--json`.
 - `playground`: Launches a local WordPress Playground instance using a blueprint.
 - `upgrade`: Checks for and applies newer versions. Supports `--check-only`, `--force`, `--json`.
 
 ## Agent-Friendly Features (v0.3.0+)
+
 - `--json`: Structured JSON output with success/data/error/time fields
 - `--dry-run`: Preview mode showing what would happen without making changes
 - `--ndjson`: Newline-delimited JSON for streaming long operations
 - `--quiet`: Suppress non-essential output
 - **Semantic exit codes**: 0=OK, 2=Invalid Args, 3=Not Found, 4=Permission Denied, 5=Already Exists, 6=Git Error, 7=Network Error, 8=Validation Error, 130=Cancelled
-- **Programmatic API**: `import { installKitApi, syncSkillsApi, runTriageApi, configureAgentsMdApi } from 'wordpress-agent-kit/api'`
+- **Programmatic API**: `import { installKitApi, syncSkillsApi, runTriageApi, configureAgentsMdApi, cleanSkillsApi } from 'wordpress-agent-kit/api'`
 
 ## Notes for Agents
+
 - When modifying commands, ensure you update the corresponding JSDoc comments.
 - The `src/lib/installer.ts` file is critical as it handles the file copying logic.
 - The `src/lib/triage-mapper.ts` file contains logic for mapping project detection results to configuration options.
 - The `src/lib/api.ts` file exposes the programmatic API — all changes to command logic should flow through to the API.
-- The `vendor` directory is gitignored and populated via submodule or script.
-- The `.github/skills/` directory contains 14 WordPress skills following the AgentSkills.io spec.
+- The `vendor` directory is gitignored and populated via submodule or script. Upstream skills sync to `.github/skills/` (sync buffer) then copy to `.agents/skills/` (canonical).
+- The `.agents/skills/` directory contains 18 WordPress skills (17 upstream + 1 custom `wp-wpengine`) following the AgentSkills.io spec. Skills are installed to `.agents/skills/` (universal convention) instead of platform-specific directories.
 - CI runs on every push: lint, typecheck, test, build. No publish workflow (manual npm publish only).
 
 ## Pi Extension (Package)
+
 - `pi.extensions`: `./extensions/wp-agent-kit` — registers WordPress agent tools
-- `pi.skills`: `./.github/skills` — 14 WordPress skills discoverable by Pi
+- `pi.skills`: `./.agents/skills` — 18 WordPress skills discoverable by Pi (17 upstream + `wp-wpengine` custom from `skills-custom/`). Uses AgentSkills.io convention.
+- Tools: `wp_triage`, `wp_install_kit`, `wp_sync_skills`, `wp_upgrade`, `wp_clean_skills`
+- Commands: `/wp-triage`, `/wp-install`, `/wp-sync-skills`, `/wp-upgrade`, `/wp-clean-skills`

package/AGENTS.template.md

@@ -6,23 +6,33 @@ This repository is WordPress-centric (plugin, theme, block theme, or site). Agen
 
 - **Core Agent**: `.github/agents/wp-architect.agent.md` — the primary agent persona
 - **Workflow Instructions**: `.github/instructions/wordpress-workflow.instructions.md` — project-specific conventions
-- **Skills**: `.github/skills/` — specialized agent skills for WordPress development
+- **Skills**: `.agents/skills/` — specialized agent skills for WordPress development
 
 ## Project Discovery (Required Before Changes)
 
 1. **Run project triage** to classify the codebase:
+
    ```bash
-   node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs
+   node .agents/skills/wp-project-triage/scripts/detect_wp_project.mjs
    ```
+
    This outputs a JSON report with project kind, signals, and tooling.
 
 2. **Route to the right skill**:
-   - If routing is unclear, consult `.github/skills/wordpress-router/references/decision-tree.md`
+   - If routing is unclear, consult `.agents/skills/wordpress-router/references/decision-tree.md`
    - For plugins: `wp-plugin-development`
    - For block themes: `wp-block-themes`
    - For Gutenberg blocks: `wp-block-development`
    - For REST API work: `wp-rest-api`
+   - For Interactivity API: `wp-interactivity-api`
+   - For Abilities API: `wp-abilities-api` / `wp-abilities-audit` / `wp-abilities-verify`
    - For WP-CLI operations: `wp-wpcli-and-ops`
+   - For Playground testing (PHPUnit, E2E, CI): `wp-playground`
+   - For Performance profiling: `wp-performance`
+   - For PHPStan static analysis: `wp-phpstan`
+   - For WP Engine hosting: `wp-wpengine` (optional, requires env vars)
+   - For Design System components: `wpds`
+   - For plugin directory submission: `wp-plugin-directory-guidelines`
 
 3. **Update repo-specific guidance** based on triage results:
    - Confirm the project prefix (functions, classes, constants)
@@ -43,13 +53,13 @@ This repository is WordPress-centric (plugin, theme, block theme, or site). Agen
 
 <!-- Populated by project triage — do not remove -->
 
-| Purpose | Command |
-|---------|---------|
-| Build | <!-- e.g., npm run build --> |
-| Lint (PHP) | <!-- e.g., composer lint --> |
-| Lint (JS/CSS) | <!-- e.g., npm run lint --> |
-| Test | <!-- e.g., npm test, composer test --> |
-| Dev server | <!-- e.g., npm start --> |
+| Purpose       | Command                                |
+| ------------- | -------------------------------------- |
+| Build         | <!-- e.g., npm run build -->           |
+| Lint (PHP)    | <!-- e.g., composer lint -->           |
+| Lint (JS/CSS) | <!-- e.g., npm run lint -->            |
+| Test          | <!-- e.g., npm test, composer test --> |
+| Dev server    | <!-- e.g., npm start -->               |
 
 ## Code Conventions
 

package/README.md

@@ -2,11 +2,11 @@
 
 [![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg?style=flat-square)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/Written%20in-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Version](https://img.shields.io/badge/version-0.3.2-blue?style=flat-square)](package.json)
+[![Version](https://img.shields.io/badge/version-0.5.1-blue?style=flat-square)](package.json)
 [![Node](https://img.shields.io/badge/node-%3E%3D20.18-green?style=flat-square)](package.json)
 [![CI](https://img.shields.io/badge/CI-passing-brightgreen?style=flat-square)](.github/workflows/ci.yml)
 
-**WordPress-focused AI agent starter kit** for GitHub Copilot, Cursor, Claude, and Pi Coding Agent. Installs 13 specialized WordPress agent skills, an agent persona, workflow instructions, and AGENTS.md configuration — everything an AI coding agent needs to build WordPress plugins, themes, and blocks correctly.
+**WordPress-focused AI agent starter kit** for GitHub Copilot, Cursor, Claude, and Pi Coding Agent. Installs 17 specialized WordPress agent skills (plus an optional WP Engine skill), an agent persona, workflow instructions, and AGENTS.md configuration — everything an AI coding agent needs to build WordPress plugins, themes, and blocks correctly.
 
 Maintained by [Kyle Brodeur](https://brodeur.me).
 
@@ -26,21 +26,17 @@ npx wp-agent-kit install /path/to/my-plugin --platform github
 npx wp-agent-kit setup /path/to/my-plugin --auto
 
 # 3. (Optional) Verify the triage report
-node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs
+node .agents/skills/wp-project-triage/scripts/detect_wp_project.mjs
 ```
 
 **What gets installed:**
+
 ```
 my-plugin/
 ├── AGENTS.md                  # Project-specific agent instructions
 ├── AGENTS.template.md         # Template reference for future updates
-├── .github/
-│   ├── agents/
-│   │   └── wp-architect.agent.md    # WordPress Architect agent persona
-│   ├── instructions/
-│   │   └── wordpress-workflow.instructions.md
-│   ├── prompts/
-│   └── skills/                      # 17 WordPress skills
+├── .agents/
+│   └── skills/                  # 18 WordPress skills (AgentSkills.io convention)
 │       ├── wp-project-triage/       # Project detection
 │       ├── wp-plugin-development/   # Plugin architecture
 │       ├── wp-block-development/    # Gutenberg blocks
@@ -51,9 +47,16 @@ my-plugin/
 │       ├── wp-performance/          # Performance profiling
 │       ├── wp-phpstan/              # Static analysis
 │       ├── wp-wpcli-and-ops/        # WP-CLI operations
-│       ├── wp-playground/           # Testing environments
+│       ├── wp-playground/           # Testing environments (PHPUnit, Playwright, CI)
 │       ├── wpds/                    # Design system
-│       └── wordpress-router/        # Repo classification
+│       ├── wordpress-router/        # Repo classification
+│       └── wp-wpengine/             # (optional) WP Engine hosting + git push
+├── .github/
+│   ├── agents/
+│   │   └── wp-architect.agent.md    # WordPress Architect agent persona
+│   ├── instructions/
+│   │   └── wordpress-workflow.instructions.md
+│   └── prompts/
 └── .wp-agent-kit-manifest.github.json  # Safe-update tracking
 ```
 
@@ -64,7 +67,7 @@ my-plugin/
 npx wp-agent-kit install /path/to/existing-plugin --platform github
 
 # 2. Run triage to detect your project's type, tech stack, and tooling
-node .github/skills/wp-project-triage/scripts/detect_wp_project.mjs
+node .agents/skills/wp-project-triage/scripts/detect_wp_project.mjs
 
 # 3. Configure based on detection (headless)
 npx wp-agent-kit setup /path/to/existing-plugin --auto
@@ -78,6 +81,7 @@ npx wp-agent-kit setup /path/to/existing-plugin \
 ```
 
 **Key behavior:**
+
 - Your existing `AGENTS.md` is **never overwritten** — only new sections are added
 - Triage inspects your codebase and returns structured JSON with project kind, signals, and tooling
 - Setup updates only the tooling/configuration sections of AGENTS.md
@@ -96,6 +100,7 @@ npx wp-agent-kit upgrade --force
 ```
 
 **Safe update behavior:**
+
 - Compares installed files against a manifest of original hashes
 - Files you haven't modified → automatically updated
 - Files you modified → **skipped** (preserved)
@@ -113,32 +118,32 @@ npx wp-agent-kit install --no-safe --force
 
 ### CLI Commands
 
-| Command | Purpose |
-|---------|---------|
-| `install [dir]` | Install kit into a project |
-| `setup [dir]` | Interactive or headless configuration |
+| Command             | Purpose                                        |
+| ------------------- | ---------------------------------------------- |
+| `install [dir]`     | Install kit into a project                     |
+| `setup [dir]`       | Interactive or headless configuration          |
 | `sync-skills [ref]` | Pull latest skills from WordPress/agent-skills |
-| `upgrade [dir]` | Check or apply version upgrades |
-| `playground` | Launch local WordPress Playground |
+| `upgrade [dir]`     | Check or apply version upgrades                |
+| `playground`        | Launch local WordPress Playground              |
 
 ### Platform Flags
 
-| Platform | Flag | Target Directory |
-|----------|------|-----------------|
-| GitHub Copilot / VS Code | `--platform github` | `.github/` |
-| Cursor IDE | `--platform cursor` | `.cursor/` |
-| Claude Code | `--platform claude` | `.claude/` |
-| Pi Coding Agent | `--platform pi` | `.pi/agent/` |
-| Generic .agent | `--platform agent` | `.agent/` |
+| Platform                 | Flag                | Target Directory |
+| ------------------------ | ------------------- | ---------------- |
+| GitHub Copilot / VS Code | `--platform github` | `.github/`       |
+| Cursor IDE               | `--platform cursor` | `.cursor/`       |
+| Claude Code              | `--platform claude` | `.claude/`       |
+| Pi Coding Agent          | `--platform pi`     | `.pi/agent/`     |
+| Generic .agent           | `--platform agent`  | `.agent/`        |
 
 ### Agent-Friendly Flags (All Commands)
 
-| Flag | Description |
-|------|-------------|
-| `--json` | Machine-readable JSON output |
-| `--dry-run` | Preview changes without applying |
-| `--ndjson` | Newline-delimited JSON for streaming |
-| `--quiet` | Suppress non-error output |
+| Flag        | Description                          |
+| ----------- | ------------------------------------ |
+| `--json`    | Machine-readable JSON output         |
+| `--dry-run` | Preview changes without applying     |
+| `--ndjson`  | Newline-delimited JSON for streaming |
+| `--quiet`   | Suppress non-error output            |
 
 ---
 
@@ -152,21 +157,21 @@ pi install npm:wordpress-agent-kit
 
 ### Pi Tools (Callable by the Agent)
 
-| Tool | What it does |
-|------|-------------|
-| `wp_triage` | Detect WordPress project type, signals, and tooling |
+| Tool             | What it does                                        |
+| ---------------- | --------------------------------------------------- |
+| `wp_triage`      | Detect WordPress project type, signals, and tooling |
 | `wp_install_kit` | Install/update kit into a project (safe by default) |
-| `wp_sync_skills` | Sync skills from WordPress/agent-skills upstream |
-| `wp_upgrade` | Check and apply version upgrades |
+| `wp_sync_skills` | Sync skills from WordPress/agent-skills upstream    |
+| `wp_upgrade`     | Check and apply version upgrades                    |
 
 ### Pi Commands (Type `/` in Pi TUI)
 
-| Command | What it does |
-|---------|-------------|
-| `/wp-triage [dir]` | Run project detection, show in status bar |
-| `/wp-install [dir]` | Install kit into current project |
-| `/wp-sync-skills [ref]` | Sync skills from upstream |
-| `/wp-upgrade` | Show installed vs latest version |
+| Command                 | What it does                              |
+| ----------------------- | ----------------------------------------- |
+| `/wp-triage [dir]`      | Run project detection, show in status bar |
+| `/wp-install [dir]`     | Install kit into current project          |
+| `/wp-sync-skills [ref]` | Sync skills from upstream                 |
+| `/wp-upgrade`           | Show installed vs latest version          |
 
 ---
 
@@ -176,24 +181,24 @@ Import directly into scripts, tests, or other tools:
 
 ```typescript
 import {
-  installKitApi,         // Install/update kit
-  syncSkillsApi,         // Sync skills from upstream
-  runTriageApi,          // Run project detection
-  configureAgentsMdApi,  // Configure AGENTS.md
-  computeChanges,        // Preview file changes (dry-run)
-  isKitInstalled,        // Check if kit is installed
-  loadManifest,          // Read install manifest
-  updateKit,             // Raw safe update
-  ExitCode,              // Semantic exit codes
+  installKitApi, // Install/update kit
+  syncSkillsApi, // Sync skills from upstream
+  runTriageApi, // Run project detection
+  configureAgentsMdApi, // Configure AGENTS.md
+  computeChanges, // Preview file changes (dry-run)
+  isKitInstalled, // Check if kit is installed
+  loadManifest, // Read install manifest
+  updateKit, // Raw safe update
+  ExitCode, // Semantic exit codes
 } from 'wordpress-agent-kit/api';
 
 // Install with safe update
 const result = await installKitApi({
   targetDir: '/path/to/my-plugin',
   platform: 'github',
-  safe: true,     // Use manifest-based diff
-  backup: true,   // Create backup before changes
-  force: false,   // Don't overwrite user mods
+  safe: true, // Use manifest-based diff
+  backup: true, // Create backup before changes
+  force: false, // Don't overwrite user mods
 });
 
 // Dry-run preview
@@ -211,42 +216,44 @@ console.log(triage.data.project.primary); // "plugin"
 
 ### Semantic Exit Codes
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 2 | Invalid arguments |
-| 3 | Not found |
-| 4 | Permission denied |
-| 5 | Already exists |
-| 6 | Git error |
-| 7 | Network error |
-| 8 | Validation failed |
-| 130 | Cancelled |
+| Code | Meaning           |
+| ---- | ----------------- |
+| 0    | Success           |
+| 2    | Invalid arguments |
+| 3    | Not found         |
+| 4    | Permission denied |
+| 5    | Already exists    |
+| 6    | Git error         |
+| 7    | Network error     |
+| 8    | Validation failed |
+| 130  | Cancelled         |
 
 ---
 
 ## Skills Reference
 
-All 13 skills follow the [AgentSkills.io](https://agentskills.io) specification:
-
-| Skill | When to Use |
-|-------|------------|
-| `wp-project-triage` | Run deterministic project detection (type, tooling, versions) |
-| `wp-plugin-development` | Develop WordPress plugins (hooks, settings, security, release) |
-| `wp-block-development` | Develop Gutenberg blocks (block.json, attributes, rendering) |
-| `wp-block-themes` | Develop block themes (theme.json, templates, patterns, variations) |
-| `wp-rest-api` | Build, extend, or debug REST API endpoints/routes |
-| `wp-interactivity-api` | Build Interactive blocks with data-wp-* directives |
-| `wp-abilities-api` | Register and consume WordPress Abilities API |
-| `wp-abilities-audit` | Audit a plugin's REST surface for Abilities API opportunities |
-| `wp-abilities-verify` | Verify registered Abilities match their annotations |
-| `wp-performance` | Profile and optimize WordPress performance |
-| `wp-phpstan` | Configure and run PHPStan static analysis |
-| `wp-wpcli-and-ops` | WP-CLI commands, automation, multisite operations |
-| `wp-playground` | Test in disposable WordPress Playground instances |
-| `blueprint` | Write and edit WordPress Playground blueprint JSON |
-| `wpds` | Build UIs with the WordPress Design System |
-| `wp-plugin-directory-guidelines` | GPL compliance, naming, slug rules for WP.org submission |
+All 18 skills follow the [AgentSkills.io](https://agentskills.io) specification. Skills in `skills-custom/` are project-specific (not from upstream) and survive `sync-skills`:
+
+| Skill                                  | When to Use                                                                        |
+| -------------------------------------- | ---------------------------------------------------------------------------------- |
+| `wp-project-triage`                    | Run deterministic project detection (type, tooling, versions)                      |
+| `wp-plugin-development`                | Develop WordPress plugins (hooks, settings, security, release)                     |
+| `wp-block-development`                 | Develop Gutenberg blocks (block.json, attributes, rendering)                       |
+| `wp-block-themes`                      | Develop block themes (theme.json, templates, patterns, variations)                 |
+| `wp-rest-api`                          | Build, extend, or debug REST API endpoints/routes                                  |
+| `wp-interactivity-api`                 | Build Interactive blocks with data-wp-\* directives                                |
+| `wp-abilities-api`                     | Register and consume WordPress Abilities API                                       |
+| `wp-abilities-audit`                   | Audit a plugin's REST surface for Abilities API opportunities                      |
+| `wp-abilities-verify`                  | Verify registered Abilities match their annotations                                |
+| `wp-performance`                       | Profile and optimize WordPress performance                                         |
+| `wp-phpstan`                           | Configure and run PHPStan static analysis                                          |
+| `wp-wpcli-and-ops`                     | WP-CLI commands, automation, multisite operations                                  |
+| `wp-playground`                        | Test with disposable Playground instances; PHPUnit, Playwright E2E, CI             |
+| `blueprint`                            | Write and edit WordPress Playground blueprint JSON                                 |
+| `wpds`                                 | Build UIs with the WordPress Design System                                         |
+| `wp-plugin-directory-guidelines`       | GPL compliance, naming, slug rules for WP.org submission                           |
+| `wordpress-router`                     | Route/classify repository type and select appropriate skills                       |
+| **`wp-wpengine`** _(optional, custom)_ | **WP Engine git push, install/domain/cache/backup management via wpe-labs skills** |
 
 ---
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
+import { cleanSkillsCommand } from './commands/clean-skills.js';
 import { installCommand } from './commands/install.js';
 import { runPlaygroundCommand } from './commands/run-playground.js';
 import { setupCommand } from './commands/setup.js';
@@ -25,6 +26,7 @@ program
     sortSubcommands: true,
 });
 // Add commands
+program.addCommand(cleanSkillsCommand);
 program.addCommand(installCommand);
 program.addCommand(setupCommand);
 program.addCommand(syncSkillsCommand);
@@ -52,9 +54,11 @@ Examples:
   $ wp-agent-kit install --platform github
   $ wp-agent-kit setup --auto --json
   $ wp-agent-kit sync-skills --ref trunk --ndjson
-  $ wp-agent-kit install --platform pi --dry-run --json
+  $ wp-agent-kit clean-skills --dry-run --json
+  $ wp-agent-kit clean-skills --remove --platform github
   $ wp-agent-kit upgrade --check-only --json
 
+
 Programmatic API:
   import { installKit, syncSkills, runTriage } from 'wordpress-agent-kit/api';
 

package/dist/commands/clean-skills.js

@@ -0,0 +1,64 @@
+import { Command } from 'commander';
+import { cleanSkillsApi } from '../lib/api.js';
+import { OutputFormatter } from '../utils/output.js';
+function isDryRunResult(result) {
+    return result.success && 'wouldExecute' in (result.data || {});
+}
+function isRegularResult(result) {
+    return result.success && !('wouldExecute' in (result.data || {}));
+}
+/**
+ * Command to detect and remove orphaned skills from an installation.
+ * Compares installed skills against the canonical set (upstream + custom).
+ */
+export const cleanSkillsCommand = new Command('clean-skills')
+    .description('Detect and remove orphaned skills from a WordPress Agent Kit installation')
+    .argument('[dir]', 'Target directory', process.cwd())
+    .option('--platform <platform>', 'Platform to clean (github, cursor, claude, agent, pi)', 'pi')
+    .option('--dry-run', 'Preview changes without applying (default: true)', true)
+    .option('--remove', 'Actually remove orphaned skills (default: false — report only)', false)
+    .option('--json', 'Output as JSON')
+    .option('--quiet', 'Suppress non-essential output')
+    .action(async (dir, options) => {
+    const targetDir = dir || process.cwd();
+    const platform = options.platform || 'pi';
+    const result = await cleanSkillsApi({
+        targetDir,
+        platform,
+        dryRun: !options.remove, // dry-run unless --remove is specified
+        remove: options.remove,
+    });
+    if (options.json || options.quiet) {
+        process.exit(OutputFormatter.getExitCode(result));
+    }
+    if (isRegularResult(result)) {
+        const data = result.data;
+        if (data.orphanedSkills.length === 0) {
+            console.log('✓ No orphaned skills found. All skills match the canonical set.');
+        }
+        else if (data.dryRun) {
+            console.log(`Found ${data.orphanedSkills.length} orphaned skill(s):`);
+            for (const skill of data.orphanedSkills) {
+                console.log(`  - ${skill}`);
+            }
+            console.log('\nRun with --remove to remove them.');
+        }
+        else {
+            console.log(`✓ Removed ${data.removedSkills.length} orphaned skill(s):`);
+            for (const skill of data.removedSkills) {
+                console.log(`  - ${skill}`);
+            }
+        }
+    }
+    else if (isDryRunResult(result)) {
+        const data = result.data;
+        console.log(`Dry-run: ${data.summary.orphanedSkills.length} orphaned skill(s) would be removed:`);
+        for (const skill of data.summary.orphanedSkills) {
+            console.log(`  - ${skill}`);
+        }
+    }
+    else {
+        console.error(`✗ Clean failed: ${result.error?.message}`);
+    }
+    process.exit(result.success ? 0 : 1);
+});