wordpress-agent-kit 0.4.0 → 0.5.1

package/dist/lib/installer.js

@@ -12,10 +12,78 @@ export const PLATFORM_FOLDERS = {
     agent: '.agent',
     pi: '.pi/agent',
 };
+/**
+ * Copy universal skills from .agents/skills/ to the target directory.
+ * Uses the AgentSkills.io convention (.agents/skills/) which is discovered
+ * automatically by Pi, GitHub Copilot, and other agents.
+ */
+function copyUniversalSkills(targetDir) {
+    const sourceSkillsDir = path.join(PACKAGE_ROOT, '.agents', 'skills');
+    const targetSkillsDir = path.join(targetDir, '.agents', 'skills');
+    const copied = [];
+    const skipped = [];
+    if (!fs.existsSync(sourceSkillsDir)) {
+        return { copied, skipped };
+    }
+    if (!fs.existsSync(targetSkillsDir)) {
+        fs.mkdirSync(targetSkillsDir, { recursive: true });
+    }
+    for (const skillName of fs.readdirSync(sourceSkillsDir)) {
+        const src = path.join(sourceSkillsDir, skillName);
+        if (!fs.statSync(src).isDirectory())
+            continue;
+        const dest = path.join(targetSkillsDir, skillName);
+        if (fs.existsSync(dest)) {
+            skipped.push(skillName);
+        }
+        else {
+            fs.cpSync(src, dest, { recursive: true });
+            copied.push(skillName);
+        }
+    }
+    return { copied, skipped };
+}
+/**
+ * Merge custom skills from skills-custom/ into the target's universal skills directory.
+ * Only copies skills that don't already exist in the target (avoids overwriting
+ * upstream versions that may have been user-modified).
+ * Returns arrays of skill names that were merged or skipped.
+ */
+function mergeCustomSkills(targetDir) {
+    const customSkillsDir = path.join(PACKAGE_ROOT, 'skills-custom');
+    if (!fs.existsSync(customSkillsDir)) {
+        return { merged: [], skipped: [] };
+    }
+    const targetSkills = path.join(targetDir, '.agents', 'skills');
+    const merged = [];
+    const skipped = [];
+    for (const skillName of fs.readdirSync(customSkillsDir)) {
+        const src = path.join(customSkillsDir, skillName);
+        if (!fs.statSync(src).isDirectory())
+            continue;
+        const dest = path.join(targetSkills, skillName);
+        if (fs.existsSync(dest)) {
+            // Don't overwrite — upstream or user version takes priority
+            skipped.push(skillName);
+        }
+        else {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.cpSync(src, dest, { recursive: true });
+            merged.push(skillName);
+        }
+    }
+    return { merged, skipped };
+}
 /**
  * Installs the WordPress Agent Kit into the specified directory for a given platform.
  * If the kit is already installed, uses safe update logic to preserve user modifications.
  *
+ * Installation layout:
+ * - .agents/skills/          — Universal skills (AgentSkills.io convention)
+ * - .github/ (or .pi/agent/, etc.) — Platform-specific agents, instructions, prompts
+ * - AGENTS.md                — Project-level agent instructions
+ * - AGENTS.template.md       — Template reference for future updates
+ *
  * @param targetDir - The directory where the kit should be installed.
  * @param platform - The target platform (github, cursor, claude, agent, pi)
  * @returns InstallKitResult with details of what was created/skipped
@@ -31,6 +99,49 @@ export function installKit(targetDir, platform = 'github', options = {}) {
     // Fresh install or fallback to full replacement
     return fullInstall(targetDir, platform, force);
 }
+/**
+ * Migrate legacy skill directories to the universal .agents/skills/ convention.
+ * Detects skills in platform-specific directories (e.g., .github/skills/, .pi/agent/skills/)
+ * and moves them to .agents/skills/ if they don't already exist there.
+ * Returns lists of migrated and removed skill names.
+ */
+function migrateLegacySkills(targetDir, platform) {
+    const platformFolder = PLATFORM_FOLDERS[platform];
+    const legacySkillsDir = path.join(targetDir, platformFolder, 'skills');
+    const universalSkillsDir = path.join(targetDir, '.agents', 'skills');
+    const migrated = [];
+    const removed = [];
+    if (!fs.existsSync(legacySkillsDir)) {
+        return { migrated, removed };
+    }
+    // Ensure universal directory exists
+    if (!fs.existsSync(universalSkillsDir)) {
+        fs.mkdirSync(universalSkillsDir, { recursive: true });
+    }
+    for (const skillName of fs.readdirSync(legacySkillsDir)) {
+        const srcPath = path.join(legacySkillsDir, skillName);
+        const destPath = path.join(universalSkillsDir, skillName);
+        if (!fs.statSync(srcPath).isDirectory())
+            continue;
+        if (!fs.existsSync(destPath)) {
+            // Migrate: copy to universal location
+            fs.cpSync(srcPath, destPath, { recursive: true });
+            migrated.push(skillName);
+        }
+        else {
+            // Already exists in universal location — just remove from legacy
+            removed.push(skillName);
+        }
+        // Remove from legacy location
+        fs.rmSync(srcPath, { recursive: true, force: true });
+    }
+    // Remove the legacy skills directory if empty
+    const remaining = fs.readdirSync(legacySkillsDir);
+    if (remaining.length === 0) {
+        fs.rmSync(legacySkillsDir, { recursive: true, force: true });
+    }
+    return { migrated, removed };
+}
 /**
  * Check if kit is already installed for a platform.
  */
@@ -53,18 +164,23 @@ function fullInstall(targetDir, platform, _force) {
     const sourceGithub = path.join(PACKAGE_ROOT, '.github');
     const filesCreated = [];
     const filesSkipped = [];
-    // Copy platform-specific folder
+    // Copy platform-specific folder (agents, instructions — NOT skills)
     const targetPlatform = path.join(targetDir, platformFolder);
     if (fs.existsSync(targetPlatform)) {
         fs.rmSync(targetPlatform, { recursive: true, force: true });
     }
     if (fs.existsSync(sourceGithub)) {
         fs.cpSync(sourceGithub, targetPlatform, { recursive: true });
+        // Remove skills from platform dir — skills go to .agents/skills/ instead
+        const platformSkills = path.join(targetPlatform, 'skills');
+        if (fs.existsSync(platformSkills)) {
+            fs.rmSync(platformSkills, { recursive: true, force: true });
+        }
     }
     else {
         throw new Error('Could not find source .github directory.');
     }
-    // Collect created files
+    // Collect created files (excluding skills which are in .agents/)
     const collectFiles = (dir, prefix) => {
         if (!fs.existsSync(dir))
             return;
@@ -81,6 +197,30 @@ function fullInstall(targetDir, platform, _force) {
         }
     };
     collectFiles(targetPlatform, platformFolder);
+    // Migrate legacy skills from platform-specific dir to .agents/skills/
+    const migrationResult = migrateLegacySkills(targetDir, platform);
+    for (const skill of migrationResult.migrated) {
+        filesCreated.push(`.agents/skills/${skill} (migrated from ${platformFolder}/skills/)`);
+    }
+    for (const skill of migrationResult.removed) {
+        filesSkipped.push(`.agents/skills/${skill} (already existed, removed legacy copy)`);
+    }
+    // Copy universal skills to .agents/skills/ (AgentSkills.io convention)
+    const universalResult = copyUniversalSkills(targetDir);
+    for (const skill of universalResult.copied) {
+        filesCreated.push(`.agents/skills/${skill}`);
+    }
+    for (const skill of universalResult.skipped) {
+        filesSkipped.push(`.agents/skills/${skill} (already exists, preserved)`);
+    }
+    // Merge custom skills from skills-custom/ (e.g., wp-wpengine)
+    const customResult = mergeCustomSkills(targetDir);
+    for (const skill of customResult.merged) {
+        filesCreated.push(`.agents/skills/${skill}`);
+    }
+    for (const skill of customResult.skipped) {
+        filesSkipped.push(`.agents/skills/${skill} (already exists, preserved)`);
+    }
     // Copy AGENTS.md template
     const targetAgentsTemplate = path.join(targetDir, 'AGENTS.template.md');
     if (fs.existsSync(templatePath)) {
@@ -140,6 +280,30 @@ function safeUpdateInstall(targetDir, platform, options) {
     else {
         filesSkipped.push('AGENTS.md (preserved)');
     }
+    // Migrate legacy skills from platform-specific dir to .agents/skills/
+    const migrationResult = migrateLegacySkills(targetDir, platform);
+    for (const skill of migrationResult.migrated) {
+        filesCreated.push(`.agents/skills/${skill} (migrated from ${PLATFORM_FOLDERS[platform]}/skills/)`);
+    }
+    for (const skill of migrationResult.removed) {
+        filesSkipped.push(`.agents/skills/${skill} (already existed, removed legacy copy)`);
+    }
+    // Copy universal skills to .agents/skills/ (AgentSkills.io convention)
+    const universalResult = copyUniversalSkills(targetDir);
+    for (const skill of universalResult.copied) {
+        filesCreated.push(`.agents/skills/${skill}`);
+    }
+    for (const skill of universalResult.skipped) {
+        filesSkipped.push(`.agents/skills/${skill} (already exists, preserved)`);
+    }
+    // Merge custom skills from skills-custom/ (e.g., wp-wpengine)
+    const customResult = mergeCustomSkills(targetDir);
+    for (const skill of customResult.merged) {
+        filesCreated.push(`.agents/skills/${skill}`);
+    }
+    for (const skill of customResult.skipped) {
+        filesSkipped.push(`.agents/skills/${skill} (already exists, preserved)`);
+    }
     return {
         targetDir,
         platform,

package/extensions/wp-agent-kit/index.ts

@@ -1,12 +1,13 @@
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
  * WordPress Agent Kit — Pi Extension
  *
  * Provides Pi Coding Agent with WordPress development tools:
- * - 17 WordPress agent skills (plugin/theme/block dev, REST API, WP-CLI, etc.)
+ * - 18 WordPress agent skills (17 upstream + wp-wpengine custom) at .agents/skills/ (AgentSkills.io convention)
  * - Project triage detection
- * - Skill installation, syncing, and upgrade management
+ * - Skill installation, syncing, upgrade, and orphan cleanup
  *
  * Follows Pi Coding Agent SDK conventions (extensions.md, packages.md, skills.md).
  */
@@ -25,17 +26,43 @@ try {
 	apiModule = (await import('../../src/lib/api.js')) as typeof import('../../dist/lib/api.js');
 }
 
-const { installKitApi, syncSkillsApi, runTriageApi, isKitInstalled, loadManifest } = apiModule;
+const { installKitApi, syncSkillsApi, runTriageApi, cleanSkillsApi, isKitInstalled, loadManifest } =
+	apiModule;
 
 export default function (pi: ExtensionAPI) {
 	// =========================================================================
 	// Skills Registration
 	// =========================================================================
+	// Primary skills (.agents/skills/) are registered via `pi.skills` in package.json.
+	// Pi also auto-discovers from .agents/skills/ at the project level (AgentSkills.io convention).
+	// The resources_discover handler ONLY supplements skills that aren't already
+	// covered by the static manifest — specifically, custom skills from
+	// skills-custom/ that haven't been synced into .agents/skills/ yet.
+	// This avoids name collisions (Pi keeps first-loaded, warns on duplicates).
 	pi.on('resources_discover', async (_event, _ctx) => {
-		const skillsDir = path.join(PACKAGE_ROOT, '.github', 'skills');
+		const canonicalSkillsDir = path.join(PACKAGE_ROOT, '.agents', 'skills');
+		const customSkillsDir = path.join(PACKAGE_ROOT, 'skills-custom');
 		const promptsDir = path.join(PACKAGE_ROOT, '.github', 'prompts');
+
+		// Only discover custom skills that aren't already in .agents/skills/
+		// (which is registered via pi.skills in package.json).
+		const skillPaths: string[] = [];
+		if (fs.existsSync(customSkillsDir)) {
+			const existingSkills = fs.existsSync(canonicalSkillsDir)
+				? new Set(fs.readdirSync(canonicalSkillsDir))
+				: new Set<string>();
+			for (const entry of fs.readdirSync(customSkillsDir)) {
+				if (!existingSkills.has(entry)) {
+					const entryPath = path.join(customSkillsDir, entry);
+					if (fs.statSync(entryPath).isDirectory()) {
+						skillPaths.push(entryPath);
+					}
+				}
+			}
+		}
+
 		return {
-			skillPaths: [skillsDir],
+			skillPaths: skillPaths.length > 0 ? skillPaths : undefined,
 			promptPaths: [promptsDir],
 		};
 	});
@@ -127,7 +154,7 @@ export default function (pi: ExtensionAPI) {
 		name: 'wp_install_kit',
 		label: 'WP Install Kit',
 		description:
-			'Install WordPress Agent Kit into a project directory. Copies 17 WordPress development skills, agent definitions, workflow instructions, and an AGENTS.md template. Safe by default — preserves user modifications on re-run.',
+			'Install WordPress Agent Kit into a project directory. Copies 18 WordPress skills to .agents/skills/ (AgentSkills.io convention), platform-specific agents/instructions/prompts, and an AGENTS.md template. Safe by default — preserves user modifications on re-run.',
 		promptSnippet: 'Install WordPress AI agent skills and configuration into a project',
 		promptGuidelines: [
 			'Use wp_install_kit when setting up a new WordPress project for AI agent development.',
@@ -243,7 +270,7 @@ export default function (pi: ExtensionAPI) {
 		name: 'wp_sync_skills',
 		label: 'WP Sync Skills',
 		description:
-			'Sync WordPress agent skills from the upstream WordPress/agent-skills repository. Fetches the latest 17 skill definitions and replaces the local skills directory.',
+			'Sync WordPress agent skills from the upstream WordPress/agent-skills repository. Fetches the latest upstream skill definitions and merges custom skills from skills-custom/ — custom skills survive upstream syncs.',
 		promptSnippet: 'Sync latest WordPress agent skills from upstream',
 		promptGuidelines: [
 			'Use wp_sync_skills to pull the latest WordPress development skills from WordPress/agent-skills.',
@@ -273,11 +300,14 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			const data = result.data as { skillsSynced: number; method: string };
+			const customSkillNote = fs.existsSync(path.join(PACKAGE_ROOT, 'skills-custom'))
+				? '\n**Custom skills**: Merged from skills-custom/'
+				: '';
 			return {
 				content: [
 					{
 						type: 'text',
-						text: `# Skills Synced\n\n**Synced**: ${data.skillsSynced} skills\n**Method**: ${data.method}`,
+						text: `# Skills Synced\n\n**Synced**: ${data.skillsSynced} skills\n**Method**: ${data.method}${customSkillNote}`,
 					},
 				],
 				details: data,
@@ -315,7 +345,6 @@ export default function (pi: ExtensionAPI) {
 			const currentVersion = manifest?.version || 'not installed';
 			const latestVersion = (() => {
 				try {
-					const fs = require('node:fs');
 					return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'))
 						.version;
 				} catch {
@@ -393,6 +422,114 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// --- wp_clean_skills ---
+	pi.registerTool({
+		name: 'wp_clean_skills',
+		label: 'WP Clean Skills',
+		description:
+			'Detect and remove orphaned skills from a WordPress Agent Kit installation. Compares installed skills against the canonical set (upstream + custom) and reports or removes skills that are no longer part of the kit. Safe by default — use dryRun first to preview.',
+		promptSnippet: 'Clean up orphaned WordPress agent skills',
+		promptGuidelines: [
+			'Use wp_clean_skills after upgrading to remove skills that are no longer part of the kit.',
+			'Always run with dryRun: true first to preview what would be removed.',
+			'This only removes skill directories — it does not modify AGENTS.md or other config files.',
+		],
+		parameters: Type.Object({
+			targetDir: Type.Optional(
+				Type.String({
+					description: 'WordPress project directory (defaults to current working directory)',
+				})
+			),
+			dryRun: Type.Optional(
+				Type.Boolean({
+					description: 'Preview changes without applying (default: true for safety)',
+				})
+			),
+			remove: Type.Optional(
+				Type.Boolean({
+					description: 'Actually remove orphaned skills (default: false — report only)',
+				})
+			),
+		}),
+		async execute(_callId, params, _signal, _onUpdate, _ctx) {
+			const targetDir = params.targetDir || process.cwd();
+			const dryRun = params.dryRun ?? true;
+			const remove = params.remove ?? false;
+
+			const result = await cleanSkillsApi({
+				targetDir,
+				platform: 'pi',
+				dryRun,
+				remove,
+			});
+
+			if (!result.success) {
+				return {
+					content: [
+						{ type: 'text', text: `Clean failed: ${result.error?.message || 'Unknown error'}` },
+					],
+					isError: true,
+				};
+			}
+
+			const data = result.data as {
+				orphanedSkills: string[];
+				removedSkills: string[];
+				legacySkillDirs: string[];
+				migratedSkills: string[];
+				dryRun: boolean;
+			};
+
+			const hasNoIssues = data.orphanedSkills.length === 0 && data.legacySkillDirs.length === 0;
+			if (hasNoIssues) {
+				return {
+					content: [
+						{
+							type: 'text',
+							text: '# All Clean\n\nAll installed skills match the canonical set. No orphaned or legacy skills found.',
+						},
+					],
+					details: data,
+				};
+			}
+
+			const lines = [dryRun ? '# Skills Cleanup Preview (Dry Run)' : '# Skills Cleaned Up', ''];
+
+			if (data.orphanedSkills.length > 0) {
+				lines.push(`**Orphaned skills** (${data.orphanedSkills.length}):`);
+				for (const skill of data.orphanedSkills) {
+					lines.push(`- ${skill}`);
+				}
+			}
+
+			if (data.legacySkillDirs.length > 0) {
+				lines.push('', `**Legacy skill directories** (${data.legacySkillDirs.length}):`);
+				for (const dir of data.legacySkillDirs) {
+					lines.push(`- ${dir}`);
+				}
+				lines.push('These will be migrated to `.agents/skills/` and then removed.');
+			}
+
+			if (dryRun) {
+				lines.push('', 'Run with `remove: true` to clean up.');
+			} else {
+				if (data.removedSkills.length > 0) {
+					lines.push('', `Removed **${data.removedSkills.length}** orphaned skill(s).`);
+				}
+				if (data.migratedSkills.length > 0) {
+					lines.push(
+						`Migrated **${data.migratedSkills.length}** skill(s) from legacy directories.`
+					);
+				}
+			}
+
+			return {
+				content: [{ type: 'text', text: lines.join('\n') }],
+				details: data,
+			};
+		},
+	});
+
 	// =========================================================================
 	// Commands
 	// =========================================================================
@@ -431,7 +568,15 @@ export default function (pi: ExtensionAPI) {
 				`${data.isUpdate ? 'Updated' : 'Installed'} (${data.filesCreated.length} entries)`,
 				'info'
 			);
-			ctx.ui.setStatus('wp-agent-kit', 'v0.3.0 installed');
+			const pkgVersion = (() => {
+				try {
+					return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'))
+						.version;
+				} catch {
+					return 'unknown';
+				}
+			})();
+			ctx.ui.setStatus('wp-agent-kit', `v${pkgVersion} installed`);
 		},
 	});
 
@@ -449,4 +594,34 @@ export default function (pi: ExtensionAPI) {
 			ctx.ui.setStatus('wp-agent-kit', `${data.skillsSynced} skills`);
 		},
 	});
+
+	pi.registerCommand('wp-clean-skills', {
+		description: 'Detect and remove orphaned/legacy skills from WordPress Agent Kit',
+		handler: async (args, ctx) => {
+			const targetDir = args?.trim() || ctx.cwd;
+			ctx.ui.setStatus('wp-clean', 'Checking for orphaned and legacy skills...');
+			const result = await cleanSkillsApi({
+				targetDir,
+				platform: 'pi',
+				dryRun: true,
+				remove: false,
+			});
+			if (!result.success) {
+				ctx.ui.notify(`Clean failed: ${result.error?.message}`, 'error');
+				return;
+			}
+			const data = result.data as { orphanedSkills: string[]; legacySkillDirs: string[] };
+			const total = data.orphanedSkills.length + data.legacySkillDirs.length;
+			if (total === 0) {
+				ctx.ui.notify('No orphaned or legacy skills found', 'info');
+			} else {
+				const parts: string[] = [];
+				if (data.orphanedSkills.length > 0) parts.push(`${data.orphanedSkills.length} orphaned`);
+				if (data.legacySkillDirs.length > 0)
+					parts.push(`${data.legacySkillDirs.length} legacy dir(s)`);
+				ctx.ui.notify(`Found ${parts.join(', ')}`, 'info');
+			}
+			ctx.ui.setStatus('wp-clean', total === 0 ? 'clean' : `${total} issues`);
+		},
+	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wordpress-agent-kit",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "WordPress-focused AGENTS.md + Agent Skills starter kit for AI coding agents.",
   "license": "GPL-2.0-or-later",
   "author": "Kyle Brodeur <kyle@brodeur.me> (https://brodeur.me)",
@@ -31,7 +31,7 @@
       "./extensions/wp-agent-kit"
     ],
     "skills": [
-      "./.github/skills"
+      "./.agents/skills"
     ]
   },
   "dependencies": {
@@ -44,28 +44,20 @@
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
-    "@eslint/js": "^9.17.0",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
     "@types/node": "^22.10.1",
     "@vitest/coverage-v8": "^2.1.8",
-    "eslint": "^9.16.0",
     "husky": "^9.1.6",
-    "prettier": "^3.4.1",
     "ts-node": "^10.9.2",
     "tsx": "^4.19.2",
+    "typebox": "*",
     "typescript": "^5.7.2",
-    "typescript-eslint": "^8.18.0",
-    "vitest": "^2.1.8",
-    "@earendil-works/pi-coding-agent": "^0.78.1",
-    "typebox": "*"
+    "vitest": "^2.1.8"
   },
   "scripts": {
     "dev": "tsx src/cli.ts",
     "build": "tsc",
     "check": "tsc --noEmit",
-    "lint": "eslint src/ tests/ --fix && biome check --write .",
-    "lint:check": "eslint src/ tests/ && biome check .",
-    "format": "prettier --write . && biome format --write .",
-    "format:check": "prettier --check . && biome format --check .",
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
@@ -73,6 +65,10 @@
     "sync:skills": "tsx src/cli.ts sync-skills",
     "setup": "tsx src/cli.ts setup",
     "playground": "tsx src/cli.ts playground",
-    "build:bundles": "tsx scripts/build-bundles.ts"
+    "build:bundles": "tsx scripts/build-bundles.ts",
+    "lint": "biome check --write .",
+    "lint:check": "biome check .",
+    "format": "biome format --write .",
+    "format:check": "biome format --check ."
   }
 }