wordpress-agent-kit 0.3.2 → 0.5.1

package/dist/commands/setup.js

@@ -111,8 +111,12 @@ export const setupCommand = new Command('setup')
     let detectedTech = [];
     let detectedPackageManager = 'npm/pnpm';
     const triageScriptPaths = [
+        // Canonical location (AgentSkills.io convention)
+        path.join(targetDir, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+        // Legacy platform-specific location
         path.join(targetDir, platformFolder, 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
-        path.join(PACKAGE_ROOT, 'vendor/wp-agent-skills/skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+        // Source repo
+        path.join(PACKAGE_ROOT, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
     ];
     const triageScriptPath = triageScriptPaths.find((p) => fs.existsSync(p));
     if (triageScriptPath) {
@@ -291,6 +295,6 @@ export const setupCommand = new Command('setup')
     console.log('\nNext steps:');
     console.log(`  1. Review ${path.join(targetDir, 'AGENTS.md')}`);
     console.log(`  2. Customize ${path.join(targetDir, platformFolder, 'prompts/')}`);
-    console.log(`  3. Run triage: node ${path.join(targetDir, platformFolder, 'skills/wp-project-triage/scripts/detect_wp_project.mjs')}`);
+    console.log(`  3. Run triage: node ${path.join(targetDir, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs')}`);
     process.exit(0);
 });

package/dist/commands/sync-skills.js

@@ -30,6 +30,9 @@ export const syncSkillsCommand = new Command('sync-skills')
         const data = result.data;
         console.log(`✓ Synced ${data.skillsSynced} skills from WordPress/agent-skills@${ref}`);
         console.log(`  Method: ${data.method}`);
+        if (data.customMerged > 0) {
+            console.log(`  Custom skills merged: ${data.customMerged}`);
+        }
         console.log(`  Duration: ${data.durationMs}ms`);
     }
     else if (isDryRunResult(result)) {

package/dist/lib/api.js

@@ -264,11 +264,38 @@ export async function syncSkillsApi(options = {}) {
                 fs.cpSync(sourceSkills, targetSkills, { recursive: true });
                 skillsSynced = fs.readdirSync(targetSkills).length;
             }
-            return { success: true, skillsSynced, method };
+            // Merge custom skills (skills-custom/) — these are not part of the upstream
+            // WordPress/agent-skills repo and survive upstream syncs.
+            const customSkillsDir = path.join(PACKAGE_ROOT, 'skills-custom');
+            let customMerged = 0;
+            if (fs.existsSync(customSkillsDir)) {
+                for (const skillName of fs.readdirSync(customSkillsDir)) {
+                    const src = path.join(customSkillsDir, skillName);
+                    const dest = path.join(targetSkills, skillName);
+                    if (fs.statSync(src).isDirectory()) {
+                        const isNew = !fs.existsSync(dest);
+                        fs.cpSync(src, dest, { recursive: true });
+                        if (isNew) {
+                            skillsSynced++;
+                        }
+                        customMerged++;
+                    }
+                }
+            }
+            // Copy synced skills to the canonical .agents/skills/ directory
+            // (AgentSkills.io convention — the pi.skills path in package.json points here).
+            const canonicalSkills = path.join(PACKAGE_ROOT, '.agents', 'skills');
+            if (fs.existsSync(canonicalSkills)) {
+                fs.rmSync(canonicalSkills, { recursive: true, force: true });
+            }
+            fs.mkdirSync(path.join(PACKAGE_ROOT, '.agents'), { recursive: true });
+            fs.cpSync(targetSkills, canonicalSkills, { recursive: true });
+            return { success: true, skillsSynced, customMerged, method };
         });
         return formatter.success({
             targetDir,
             skillsSynced: result.skillsSynced,
+            customMerged: result.customMerged,
             sourceUrl: 'https://github.com/WordPress/agent-skills.git',
             ref,
             durationMs: Date.now() - startTime,
@@ -321,7 +348,13 @@ function dryRunSyncSkills(targetDir, ref) {
     actions.push({
         type: 'create',
         target: targetSkills,
-        description: 'Install synced skills',
+        description: 'Install synced skills to .github/skills (sync buffer), then copy to .agents/skills (canonical)',
+    });
+    const canonicalSkills = path.join(targetDir, '.agents', 'skills');
+    actions.push({
+        type: 'create',
+        target: canonicalSkills,
+        description: 'Copy synced skills to .agents/skills (canonical, AgentSkills.io convention)',
     });
     return new OutputFormatter('json', 'sync-skills', '0.0.0').success({
         wouldExecute: true,
@@ -329,6 +362,7 @@ function dryRunSyncSkills(targetDir, ref) {
         summary: {
             targetDir,
             skillsSynced: 0,
+            customMerged: 0,
             sourceUrl: 'https://github.com/WordPress/agent-skills.git',
             ref,
             durationMs: 0,
@@ -343,9 +377,13 @@ export async function runTriageApi(options) {
     const formatter = new OutputFormatter('json', 'triage', '0.0.0');
     const { targetDir, platform = 'github' } = options;
     try {
-        const platformFolder = getPlatformFolder(platform);
         const triageScriptPaths = [
-            path.join(targetDir, platformFolder, 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+            // Canonical location (AgentSkills.io convention)
+            path.join(targetDir, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+            // Legacy platform-specific location
+            path.join(targetDir, getPlatformFolder(platform), 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
+            // Source repo
+            path.join(PACKAGE_ROOT, '.agents', 'skills/wp-project-triage/scripts/detect_wp_project.mjs'),
             path.join(PACKAGE_ROOT, 'vendor/wp-agent-skills/skills/wp-project-triage/scripts/detect_wp_project.mjs'),
         ];
         const triageScriptPath = triageScriptPaths.find((p) => fs.existsSync(p));
@@ -517,6 +555,140 @@ function getInstalledSummary(targetDir, platform) {
     }
     return summary;
 }
+/**
+ * Detect and optionally remove orphaned skills from a target installation.
+ * Compares the skills in the target platform directory against the source kit
+ * (upstream .agents/skills + skills-custom/) and identifies skills that exist
+ * in the target but not in the source.
+ */
+export async function cleanSkillsApi(options) {
+    const startTime = Date.now();
+    const formatter = new OutputFormatter('json', 'clean-skills', '0.0.0');
+    const { targetDir, platform, dryRun = false, remove = false } = options;
+    try {
+        // Canonical skills come from .agents/skills/ (AgentSkills.io convention)
+        // with skills-custom/ as supplemental source for custom skills.
+        const canonicalSkillsDir = path.join(PACKAGE_ROOT, '.agents', 'skills');
+        const customSkillsDir = path.join(PACKAGE_ROOT, 'skills-custom');
+        const targetSkillsDir = path.join(targetDir, '.agents', 'skills');
+        // Build set of canonical skill names (upstream + custom)
+        const canonicalSkills = new Set();
+        if (fs.existsSync(canonicalSkillsDir)) {
+            for (const entry of fs.readdirSync(canonicalSkillsDir)) {
+                const entryPath = path.join(canonicalSkillsDir, entry);
+                if (fs.statSync(entryPath).isDirectory()) {
+                    canonicalSkills.add(entry);
+                }
+            }
+        }
+        if (fs.existsSync(customSkillsDir)) {
+            for (const entry of fs.readdirSync(customSkillsDir)) {
+                const entryPath = path.join(customSkillsDir, entry);
+                if (fs.statSync(entryPath).isDirectory()) {
+                    canonicalSkills.add(entry);
+                }
+            }
+        }
+        // Find orphaned skills in target .agents/skills/
+        const orphanedSkills = [];
+        if (fs.existsSync(targetSkillsDir)) {
+            for (const entry of fs.readdirSync(targetSkillsDir)) {
+                const entryPath = path.join(targetSkillsDir, entry);
+                if (fs.statSync(entryPath).isDirectory() && !canonicalSkills.has(entry)) {
+                    orphanedSkills.push(entry);
+                }
+            }
+        }
+        // Detect legacy skill directories (platform-specific skills/ dirs)
+        const platformFolder = getPlatformFolder(platform);
+        const legacySkillsDir = path.join(targetDir, platformFolder, 'skills');
+        const legacySkillDirs = [];
+        if (fs.existsSync(legacySkillsDir)) {
+            legacySkillDirs.push(legacySkillsDir);
+        }
+        // Also check .github/skills for github platform (common legacy location)
+        if (platform !== 'github') {
+            const githubSkills = path.join(targetDir, '.github', 'skills');
+            if (fs.existsSync(githubSkills)) {
+                legacySkillDirs.push(githubSkills);
+            }
+        }
+        // Migrate legacy skills to .agents/skills/ and remove legacy dirs
+        const migratedSkills = [];
+        if (remove && !dryRun && legacySkillDirs.length > 0) {
+            for (const legacyDir of legacySkillDirs) {
+                for (const entry of fs.readdirSync(legacyDir)) {
+                    const entryPath = path.join(legacyDir, entry);
+                    if (!fs.statSync(entryPath).isDirectory())
+                        continue;
+                    const destPath = path.join(targetSkillsDir, entry);
+                    if (!fs.existsSync(destPath)) {
+                        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+                        fs.cpSync(entryPath, destPath, { recursive: true });
+                        migratedSkills.push(entry);
+                    }
+                }
+                // Remove the legacy skills directory
+                fs.rmSync(legacyDir, { recursive: true, force: true });
+            }
+        }
+        // Remove orphans if requested
+        const removedSkills = [];
+        if (remove && !dryRun) {
+            for (const orphan of orphanedSkills) {
+                const orphanPath = path.join(targetSkillsDir, orphan);
+                fs.rmSync(orphanPath, { recursive: true, force: true });
+                removedSkills.push(orphan);
+            }
+        }
+        const _durationMs = Date.now() - startTime;
+        if (dryRun) {
+            const actions = orphanedSkills.map((s) => ({
+                type: 'delete',
+                target: path.join('.agents', 'skills', s),
+                description: `Remove orphaned skill: ${s}`,
+            }));
+            for (const legacyDir of legacySkillDirs) {
+                actions.push({
+                    type: 'delete',
+                    target: legacyDir,
+                    description: `Migrate and remove legacy skill directory: ${path.relative(targetDir, legacyDir)}`,
+                });
+            }
+            return formatter.success({
+                wouldExecute: true,
+                actions,
+                summary: {
+                    targetDir,
+                    platform,
+                    orphanedSkills,
+                    removedSkills: [],
+                    legacySkillDirs,
+                    migratedSkills: [],
+                    dryRun: true,
+                },
+            });
+        }
+        return formatter.success({
+            targetDir,
+            platform,
+            orphanedSkills,
+            removedSkills,
+            legacySkillDirs,
+            migratedSkills,
+            dryRun: false,
+        });
+    }
+    catch (error) {
+        const err = error;
+        return formatter.fail({
+            code: err.code || 'CLEAN_FAILED',
+            message: err.message || 'Clean failed',
+            exitCode: err.exitCode ?? ExitCode.ERROR,
+            details: { platform, targetDir },
+        });
+    }
+}
 export { ExitCode } from '../utils/exit-codes.js';
 export { OutputFormatter, createFormatter, parseOutputFormat } from '../utils/output.js';
 export { computeChanges, isKitInstalled, loadManifest, updateKit } from './updater.js';

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,