wordpress-agent-kit 0.4.0 → 0.5.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![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.4.0-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)
 
@@ -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 + 1 optional
+├── .agents/
+│   └── skills/                  # 18 WordPress skills (AgentSkills.io convention)
 │       ├── wp-project-triage/       # Project detection
 │       ├── wp-plugin-development/   # Plugin architecture
 │       ├── wp-block-development/    # Gutenberg blocks
@@ -55,6 +51,12 @@ my-plugin/
 │       ├── wpds/                    # Design system
 │       ├── 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
 ```
 
@@ -65,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
@@ -79,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
@@ -97,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)
@@ -114,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            |
 
 ---
 
@@ -153,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          |
 
 ---
 
@@ -177,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
@@ -212,44 +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 17 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** |
+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);
+});

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

@@ -267,21 +267,35 @@ export async function syncSkillsApi(options = {}) {
             // 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 });
-                        skillsSynced++;
+                        if (isNew) {
+                            skillsSynced++;
+                        }
+                        customMerged++;
                     }
                 }
             }
-            return { success: true, skillsSynced, method };
+            // 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,
@@ -334,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,
@@ -342,6 +362,7 @@ function dryRunSyncSkills(targetDir, ref) {
         summary: {
             targetDir,
             skillsSynced: 0,
+            customMerged: 0,
             sourceUrl: 'https://github.com/WordPress/agent-skills.git',
             ref,
             durationMs: 0,
@@ -356,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));
@@ -530,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';