oh-skillhub 0.1.10 → 0.1.11

package/README.md

@@ -9,6 +9,7 @@ npx oh-skillhub@latest
 npx oh-skillhub list
 npx oh-skillhub install --domain arkui --agent codex
 npx oh-skillhub install --domain arkui --agent all --scope user
+npx oh-skillhub clean --agent claude --scope user --dry-run
 ```
 
 Running without arguments starts a TUI selector. Choose the install target first (`Codex`, `Claude`, `OpenCode`, or `All`), then choose the skill groups to install.
@@ -35,6 +36,8 @@ printf "1\n3 9\n" | npx oh-skillhub@latest
 - Support interactive target selection for `Codex`, `Claude`, `OpenCode`, and `All`.
 - Support `--scope user|project`.
 - Support `--dry-run` install plans.
+- Scan installed skills and clean selected skills with `clean`.
+- Move cleaned skills to `.oh-skillhub/trash` by default, with `--purge` for permanent deletion.
 - Run a TUI matching the `skills/common/*` and `skills/domain/*` repository layout.
 - Keep anonymous telemetry events in a local retry queue.
 
@@ -45,6 +48,7 @@ The installer uses sparse Git checkout so it downloads only the selected skill d
 ```bash
 oh-skillhub list [--domain <name>] [--stage <name>]
 oh-skillhub install [skill...] [--domain <name>] [--preset <name>] [--agent codex|claude|opencode|all]
+oh-skillhub clean [skill...] [--agent codex|claude|opencode|all] [--scope user|project] [--dry-run] [--purge]
 oh-skillhub doctor [--agent codex|claude|opencode|all]
 oh-skillhub telemetry status
 ```
@@ -63,6 +67,8 @@ Examples:
 npx oh-skillhub install --domain arkui --agent claude --scope user
 npx oh-skillhub install --preset app-dev --agent opencode --scope project
 npx oh-skillhub install --domain security --agent all --dry-run
+npx oh-skillhub clean --agent claude --scope user --dry-run
+npx oh-skillhub clean --agent claude --scope user ohos-test-capi-xts-generation
 ```
 
 ## Telemetry

package/docs/superpowers/specs/2026-05-25-skill-cleaner-design.md

@@ -0,0 +1,411 @@
+# Skill 扫描与清理能力设计方案
+
+## 1. 背景与目标
+
+`oh-skillhub` 当前已经支持通过 `npx oh-skillhub@latest` 为 Codex、Claude Code、OpenCode 安装 OpenHarmony skills。随着安装次数增加，用户会遇到几个管理问题：
+
+- 不知道当前 agent 下已经安装了哪些 skills。
+- 不知道哪些 skills 是 `oh-skillhub` 安装的，哪些是用户手动放进去的。
+- 旧版安装过的残缺 skill、过期 skill 或不再使用的 skill 需要清理。
+- 清理时需要避免误删用户自定义 skill。
+
+本方案设计一个 **Skill 管理/清理模式**，用于扫描当前 agent 已有的 skills，并在用户确认后清理选中的 skill。
+
+目标：
+
+- 支持扫描 Codex、Claude Code、OpenCode 的 user/project skill 目录。
+- 在 TUI 中展示当前已安装 skill 列表。
+- 区分 `managed`、`unmanaged`、`broken` 三类状态。
+- 支持用户多选后清理。
+- 默认采用安全删除，先移动到 `.oh-skillhub/trash`。
+- 支持 `--dry-run` 预览和 `--purge` 永久删除。
+- 清理后同步更新 `.oh-skillhub/installed.json`。
+
+非目标：
+
+- 第一版不实现 restore 恢复命令。
+- 第一版不做远端 manifest 实时刷新。
+- 第一版不自动判断“当前正在使用的 agent”。
+- 第一版不清理 agent 自身配置文件，只处理 skill 目录。
+
+## 2. 命令设计
+
+新增命令：
+
+```bash
+npx oh-skillhub@latest clean
+```
+
+支持参数：
+
+```bash
+npx oh-skillhub clean [--agent codex|claude|opencode|all] [--scope user|project]
+npx oh-skillhub clean --agent claude --scope user
+npx oh-skillhub clean --agent opencode --scope project --dry-run
+npx oh-skillhub clean --agent codex --scope user --purge
+```
+
+参数含义：
+
+- `--agent`：指定扫描目标。默认进入 TUI 选择。
+- `--scope`：扫描 user 或 project scope。默认 `user`。
+- `--dry-run`：只展示将清理的内容，不执行移动或删除。
+- `--purge`：永久删除 skill 目录，不移动到 trash。
+- `--target`：复用现有安装逻辑中的自定义目录能力，作为高级参数保留。
+
+## 3. Agent 目录规则
+
+沿用现有 `resolveAgentTargets()` 规则：
+
+| Agent | User scope | Project scope |
+| --- | --- | --- |
+| Codex | `$CODEX_HOME/skills`，否则 `~/.codex/skills` | `<cwd>/.codex/skills` |
+| Claude Code | `~/.claude/skills` | `<cwd>/.claude/skills` |
+| OpenCode | `~/.config/opencode/skill` | `<cwd>/.opencode/skill` |
+
+当 `--agent all` 时，扫描三个 agent 的目标目录，并按 agent 分组展示。
+
+## 4. 扫描规则
+
+扫描目标目录的一级子目录。
+
+识别为 skill 的条件：
+
+- 子目录下存在 `SKILL.md`。
+- 子目录名不是 `.oh-skillhub`。
+- 子目录不是 trash、cache、临时目录。
+
+扫描结果字段：
+
+```json
+{
+  "name": "ohos-test-capi-xts-generation",
+  "agent": "claude",
+  "scope": "user",
+  "status": "managed",
+  "path": "C:\\Users\\Geralt\\.claude\\skills\\ohos-test-capi-xts-generation",
+  "sourcePath": "skills/common/testing/ohos-test-capi-xts-generation",
+  "domain": "capi",
+  "stage": "testing",
+  "description": "Use this skill when generating C API XTS tests."
+}
+```
+
+状态分类：
+
+- `managed`：存在于 `.oh-skillhub/installed.json` 中，并且目录下存在 `SKILL.md`。
+- `unmanaged`：目录下存在 `SKILL.md`，但不在 `.oh-skillhub/installed.json` 中。
+- `broken`：安装记录中存在，但目录不存在或缺失 `SKILL.md`。
+
+对于 `unmanaged` skill，优先从 `SKILL.md` front matter 解析 `name`、`description`、`metadata.domain`、`metadata.stage`。解析失败时使用目录名，并将 domain/stage 标记为 `unknown`。
+
+## 5. TUI 交互设计
+
+### 5.1 入口流程
+
+当用户运行：
+
+```bash
+npx oh-skillhub@latest clean
+```
+
+交互步骤：
+
+1. 选择安装目标：`Codex / Claude / OpenCode / All`
+2. 选择 scope：`user / project`
+3. 扫描目标目录。
+4. 展示可清理 skill 列表。
+5. 用户用空格选择要清理的 skill。
+6. Enter 后进入二次确认。
+7. 确认后执行清理。
+
+### 5.2 列表界面
+
+示例：
+
+```text
+OH SkillHub
+Clean Installed Skills
+
+Target
+  Agent: claude
+  Scope: user
+  Path: C:\Users\Geralt\.claude\skills
+
+Detected skills
+> [ ] ohos-test-arkts-xts-generation     managed    common/testing
+  [ ] ohos-test-capi-xts-generation      managed    common/testing
+  [ ] ohos-test-fuzz-generation          managed    common/testing
+  [ ] my-local-skill                     unmanaged  unknown
+
+Space: select   Enter: clean   a: select all   m: managed only   Esc: cancel
+```
+
+交互按键：
+
+- `Up/Down` 或 `j/k`：移动光标。
+- `Space`：选择或取消选择。
+- `a`：全选或取消全选。
+- `m`：只选择 managed skills。
+- `Enter`：进入确认。
+- `Esc` 或 `Ctrl+C`：取消。
+
+### 5.3 二次确认
+
+示例：
+
+```text
+Remove 3 selected skill(s) from claude:user?
+
+The selected directories will be moved to:
+C:\Users\Geralt\.claude\skills\.oh-skillhub\trash\20260525-213000
+
+Enter: confirm   Esc: cancel
+```
+
+如果使用 `--purge`：
+
+```text
+Permanently delete 3 selected skill(s) from claude:user?
+This cannot be undone.
+
+Enter: confirm   Esc: cancel
+```
+
+## 6. 非 TTY 与命令行模式
+
+第一版支持 TUI 为主，同时保留非 TTY 能力。
+
+建议增加：
+
+```bash
+npx oh-skillhub clean --agent claude --scope user --dry-run
+npx oh-skillhub clean --agent claude --scope user ohos-test-capi-xts-generation
+npx oh-skillhub clean --agent claude --scope user ohos-test-capi-xts-generation --purge
+```
+
+如果命令行直接传入 skill 名称：
+
+- 不进入选择列表。
+- 仍然需要确认，除非未来增加 `--yes`。
+- `--dry-run` 时只输出计划。
+
+第一版不建议加入 `--yes`，避免误删。
+
+## 7. 清理策略
+
+默认清理方式：移动到 trash。
+
+trash 目录：
+
+```text
+<skill-root>/.oh-skillhub/trash/<timestamp>/<skill-name>
+```
+
+例如：
+
+```text
+C:\Users\Geralt\.claude\skills\.oh-skillhub\trash\20260525-213000\ohos-test-capi-xts-generation
+```
+
+执行清理：
+
+1. 创建 trash 目录。
+2. 将选中的 skill 目录移动到 trash。
+3. 更新 `.oh-skillhub/installed.json`。
+4. 输出清理结果。
+
+如果目标 trash 已存在同名目录：
+
+- 追加短随机后缀，例如 `ohos-test-capi-xts-generation-7f3a`。
+- 不覆盖已有 trash 内容。
+
+永久删除：
+
+```bash
+npx oh-skillhub clean --purge
+```
+
+执行时直接递归删除 skill 目录，不进入 trash。
+
+## 8. 安装记录更新
+
+当前安装记录：
+
+```text
+<skill-root>/.oh-skillhub/installed.json
+```
+
+清理 managed skill 时：
+
+- 从 `skills` map 中删除该 skill。
+- 追加 `history` 记录。
+
+建议结构：
+
+```json
+{
+  "installedAt": "2026-05-25T12:00:00.000Z",
+  "source": "https://gitcode.com/openharmonyinsight/openharmony-skills",
+  "ref": "release",
+  "skills": {},
+  "history": [
+    {
+      "event": "skill_removed",
+      "removedAt": "2026-05-25T13:20:00.000Z",
+      "skill": "ohos-test-capi-xts-generation",
+      "agent": "claude",
+      "scope": "user",
+      "action": "trash",
+      "from": "C:\\Users\\Geralt\\.claude\\skills\\ohos-test-capi-xts-generation",
+      "to": "C:\\Users\\Geralt\\.claude\\skills\\.oh-skillhub\\trash\\20260525-213000\\ohos-test-capi-xts-generation"
+    }
+  ]
+}
+```
+
+清理 unmanaged skill 时：
+
+- 不从 `skills` map 删除。
+- 仍然追加 `history` 记录，标记 `managed: false`。
+
+## 9. 输出设计
+
+清理前 dry-run：
+
+```text
+Clean dry run
+TRASH ohos-test-capi-xts-generation -> claude:user C:\Users\Geralt\.claude\skills\.oh-skillhub\trash\...
+```
+
+清理完成：
+
+```text
+Clean summary
+TRASH ohos-test-capi-xts-generation -> claude:user C:\Users\Geralt\.claude\skills\.oh-skillhub\trash\...
+
+Done. Removed 1 skill(s) from claude:user.
+```
+
+未发现 skill：
+
+```text
+No skills found under claude:user.
+Path: C:\Users\Geralt\.claude\skills
+```
+
+用户取消：
+
+```text
+Cancelled. No skills were removed.
+```
+
+## 10. 模块设计
+
+新增模块：
+
+```text
+src/cleaner.js
+```
+
+职责：
+
+- `scanInstalledSkills(targets, options)`
+- `planClean(skills, options)`
+- `applyCleanPlan(plan, options)`
+- `readInstallRecord(targetDir)`
+- `writeInstallRecord(targetDir, record)`
+- `parseSkillMetadata(skillDir)`
+
+CLI 侧新增：
+
+- `clean` 命令解析。
+- TUI agent/scope 选择。
+- 清理列表渲染。
+- 二次确认渲染。
+
+测试：
+
+```text
+test/cleaner.test.js
+test/cli-clean.test.js
+```
+
+## 11. 安全边界
+
+清理能力涉及删除文件，需要更保守：
+
+- 只允许删除 target skill root 下的一级 skill 目录。
+- 禁止删除 `.oh-skillhub`。
+- 禁止删除 target root 本身。
+- 删除前必须 resolve path，并确认目标路径在 skill root 内。
+- 默认移动到 trash，不永久删除。
+- 永久删除必须显式传 `--purge`。
+- TUI 下必须二次确认。
+- `--agent all` 时按 agent 分组确认，避免用户看错目标。
+
+## 12. 推荐第一版范围
+
+第一版实现：
+
+- `clean` 命令。
+- TUI 选择 agent。
+- TUI 选择 user/project scope。
+- 扫描 existing skills。
+- 标记 managed/unmanaged/broken。
+- 多选清理。
+- 二次确认。
+- 默认 trash。
+- `--dry-run`。
+- `--purge`。
+- 更新 installed.json。
+
+第一版暂不实现：
+
+- `restore`。
+- `--yes`。
+- 按 domain/stage 过滤。
+- 远端 manifest 对照检查。
+- trash 自动过期清理。
+
+## 13. 后续扩展
+
+后续可以增加：
+
+```bash
+npx oh-skillhub restore
+npx oh-skillhub clean --managed-only
+npx oh-skillhub clean --domain testing
+npx oh-skillhub clean --older-than 30d
+npx oh-skillhub clean --trash-status
+```
+
+也可以把扫描能力抽象为：
+
+```bash
+npx oh-skillhub status
+```
+
+用于只查看当前 agent 已安装 skills，而不进入清理流程。
+
+## 14. 实施建议
+
+建议按以下顺序实现：
+
+1. 新增 `src/cleaner.js`，先完成扫描和计划生成。
+2. 增加 `clean --dry-run`，验证非破坏性输出。
+3. 增加 trash 移动和 installed.json 更新。
+4. 增加 TUI 列表选择。
+5. 增加二次确认。
+6. 增加 `--purge`。
+7. 增加真实 Codex/Claude/OpenCode 路径烟测。
+
+验收标准：
+
+- 能扫描出当前 agent 目录下所有含 `SKILL.md` 的 skill。
+- 能区分 managed/unmanaged/broken。
+- 默认清理后 skill 进入 trash。
+- `--purge` 才会永久删除。
+- 清理 managed skill 后 installed.json 中对应记录被删除。
+- TUI 取消时不改动任何文件。
+- 全量测试通过。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-skillhub",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "OpenHarmony Skills installer for Codex, Claude Code, and OpenCode.",
   "type": "commonjs",
   "bin": {

package/src/cleaner.js

@@ -0,0 +1,239 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+function scanInstalledSkills(targets) {
+  const results = [];
+  for (const target of targets) {
+    const record = readInstallRecord(target.dir);
+    const seen = new Set();
+    if (fs.existsSync(target.dir)) {
+      for (const entry of fs.readdirSync(target.dir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || shouldIgnoreEntry(entry.name)) {
+          continue;
+        }
+        const skillDir = path.join(target.dir, entry.name);
+        const skillPath = path.join(skillDir, "SKILL.md");
+        if (!fs.existsSync(skillPath)) {
+          continue;
+        }
+        const metadata = parseSkillMetadata(skillDir);
+        const managed = Boolean(record.skills[entry.name] && record.skills[entry.name].agent === target.agent);
+        results.push({
+          name: metadata.name || entry.name,
+          directoryName: entry.name,
+          description: metadata.description || "",
+          domain: metadata.domain || "unknown",
+          stage: metadata.stage || "unknown",
+          status: managed ? "managed" : "unmanaged",
+          agent: target.agent,
+          scope: target.scope,
+          rootDir: target.dir,
+          path: skillDir,
+          sourcePath: record.skills[entry.name] ? record.skills[entry.name].sourcePath || null : null,
+        });
+        seen.add(entry.name);
+      }
+    }
+    for (const [name, item] of Object.entries(record.skills)) {
+      if (item.agent !== target.agent || seen.has(name)) {
+        continue;
+      }
+      results.push({
+        name,
+        directoryName: name,
+        description: "",
+        domain: "unknown",
+        stage: "unknown",
+        status: "broken",
+        agent: target.agent,
+        scope: target.scope,
+        rootDir: target.dir,
+        path: path.join(target.dir, name),
+        sourcePath: item.sourcePath || null,
+      });
+    }
+  }
+  return results.sort((left, right) => {
+    const agent = left.agent.localeCompare(right.agent);
+    if (agent) return agent;
+    return left.name.localeCompare(right.name);
+  });
+}
+
+function planClean(skills, options = {}) {
+  const mode = options.mode === "purge" ? "purge" : "trash";
+  const timestamp = options.timestamp || timestampId(new Date());
+  const operations = skills.map((skill) => {
+    const action = mode;
+    const trashDir =
+      mode === "trash"
+        ? path.join(skill.rootDir, ".oh-skillhub", "trash", timestamp, skill.directoryName || skill.name)
+        : null;
+    return {
+      action,
+      agent: skill.agent,
+      scope: skill.scope,
+      skill,
+      rootDir: skill.rootDir,
+      source: skill.path,
+      destination: trashDir,
+    };
+  });
+  return { operations };
+}
+
+function applyCleanPlan(plan) {
+  const applied = [];
+  for (const operation of plan.operations) {
+    assertCleanPath(operation.rootDir, operation.source);
+    if (operation.destination) {
+      assertCleanPath(operation.rootDir, operation.destination);
+    }
+
+    if (operation.skill.status !== "broken" && fs.existsSync(operation.source)) {
+      if (operation.action === "trash") {
+        const destination = uniqueDestination(operation.destination);
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.renameSync(operation.source, destination);
+        operation.destination = destination;
+      } else {
+        fs.rmSync(operation.source, { recursive: true, force: true });
+      }
+    }
+    updateInstallRecordAfterClean(operation);
+    applied.push(operation);
+  }
+  return applied;
+}
+
+function readInstallRecord(targetDir) {
+  const recordPath = path.join(targetDir, ".oh-skillhub", "installed.json");
+  const empty = { skills: {}, history: [] };
+  if (!fs.existsSync(recordPath)) {
+    return empty;
+  }
+  try {
+    const parsed = JSON.parse(stripBom(fs.readFileSync(recordPath, "utf8")));
+    return {
+      ...parsed,
+      skills: parsed.skills || {},
+      history: parsed.history || [],
+    };
+  } catch {
+    return empty;
+  }
+}
+
+function writeInstallRecord(targetDir, record) {
+  const recordDir = path.join(targetDir, ".oh-skillhub");
+  fs.mkdirSync(recordDir, { recursive: true });
+  fs.writeFileSync(path.join(recordDir, "installed.json"), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+}
+
+function updateInstallRecordAfterClean(operation) {
+  const record = readInstallRecord(operation.rootDir);
+  const key = operation.skill.directoryName || operation.skill.name;
+  const managed = Boolean(record.skills[key]);
+  delete record.skills[key];
+  record.history = record.history || [];
+  record.history.push({
+    event: "skill_removed",
+    removedAt: new Date().toISOString(),
+    skill: operation.skill.name,
+    agent: operation.agent,
+    scope: operation.scope,
+    action: operation.action,
+    managed,
+    from: operation.source,
+    to: operation.destination || null,
+  });
+  writeInstallRecord(operation.rootDir, record);
+}
+
+function parseSkillMetadata(skillDir) {
+  const skillPath = path.join(skillDir, "SKILL.md");
+  const metadata = {};
+  if (!fs.existsSync(skillPath)) {
+    return metadata;
+  }
+  const contents = fs.readFileSync(skillPath, "utf8");
+  const match = contents.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) {
+    return metadata;
+  }
+  let inMetadata = false;
+  for (const line of match[1].split(/\r?\n/)) {
+    if (/^metadata:\s*$/.test(line)) {
+      inMetadata = true;
+      continue;
+    }
+    const top = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (top) {
+      inMetadata = false;
+      if (["name", "description"].includes(top[1])) {
+        metadata[top[1]] = unquote(top[2].trim());
+      }
+      continue;
+    }
+    const nested = line.match(/^\s+([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (inMetadata && nested && ["domain", "stage"].includes(nested[1])) {
+      metadata[nested[1]] = unquote(nested[2].trim());
+    }
+  }
+  return metadata;
+}
+
+function shouldIgnoreEntry(name) {
+  return name === ".oh-skillhub" || name === "trash" || name === "cache" || name.startsWith(".");
+}
+
+function assertCleanPath(rootDir, candidate) {
+  const root = path.resolve(rootDir);
+  const resolved = path.resolve(candidate);
+  if (resolved === root || !resolved.startsWith(`${root}${path.sep}`)) {
+    throw new Error(`Refusing to clean outside target root: ${resolved}`);
+  }
+}
+
+function uniqueDestination(destination) {
+  if (!fs.existsSync(destination)) {
+    return destination;
+  }
+  for (let index = 1; index < 1000; index += 1) {
+    const candidate = `${destination}-${index}`;
+    if (!fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(`Unable to find unique trash destination for ${destination}`);
+}
+
+function timestampId(date) {
+  const pad = (value) => String(value).padStart(2, "0");
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+    "-",
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds()),
+  ].join("");
+}
+
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+function unquote(value) {
+  return value.replace(/^["']|["']$/g, "");
+}
+
+module.exports = {
+  applyCleanPlan,
+  parseSkillMetadata,
+  planClean,
+  readInstallRecord,
+  scanInstalledSkills,
+  writeInstallRecord,
+};

package/src/cli.js

@@ -5,6 +5,7 @@ const readline = require("node:readline");
 const readlinePromises = require("node:readline/promises");
 
 const { resolveAgentTargets } = require("./agents");
+const { applyCleanPlan, planClean, scanInstalledSkills } = require("./cleaner");
 const { loadLocalManifest, loadProfiles, selectSkills } = require("./manifest");
 const { applyInstallPlan, planInstall } = require("./planner");
 const { ensureSkillSourceRoot } = require("./source");
@@ -66,6 +67,10 @@ async function main(argv = []) {
     console.log(renderDoctor(options));
     return;
   }
+  if (command === "clean") {
+    await runClean(options);
+    return;
+  }
   if (command === "telemetry") {
     console.log(renderTelemetry(rest));
     return;
@@ -89,12 +94,162 @@ function parseArgs(args) {
     else if (arg === "--offline") options.offline = true;
     else if (arg === "--no-telemetry") options.noTelemetry = true;
     else if (arg === "--force") options.force = true;
+    else if (arg === "--purge") options.purge = true;
     else if (!arg.startsWith("-")) options.names.push(arg);
     else throw new Error(`Unknown option "${arg}".`);
   }
   return options;
 }
 
+async function runClean(options, input = process.stdin, output = process.stdout) {
+  const scriptedAnswers = input.isTTY ? null : splitPromptAnswers(await readAll(input));
+  let answerIndex = 0;
+  const takeAnswer = () => {
+    if (!scriptedAnswers) return null;
+    const answer = scriptedAnswers[answerIndex] || "";
+    answerIndex += 1;
+    return answer;
+  };
+  let agent = options.agent;
+  if (!agent && !options.target) {
+    if (input.isTTY && output.isTTY) {
+      agent = await runRawAgentSelection(input, output);
+    } else {
+      output.write(renderAgentMenu());
+      output.write("Select target [1]: \n");
+      agent = AGENT_CHOICES[parseSingleSelection(takeAnswer() || "", AGENT_CHOICES.length, 1)].agent;
+    }
+  }
+  const targets = resolveAgentTargets({
+    agent: agent || "codex",
+    scope: options.scope || "user",
+    target: options.target,
+    cwd: process.cwd(),
+    homeDir: os.homedir(),
+    env: process.env,
+  });
+  const discovered = scanInstalledSkills(targets);
+  if (!discovered.length) {
+    output.write(renderNoSkillsFound(targets));
+    return;
+  }
+  let selected;
+  let prefilledConfirmation = null;
+  if (!options.names.length && !options.dryRun) {
+    if (input.isTTY) {
+      selected = await promptCleanSelection(input, output, discovered);
+    } else {
+      output.write(renderCleanSelectionMenu(discovered));
+      output.write("Select skills [1]: \n");
+      selected = parseSelection(takeAnswer() || "", discovered.length, 1).map((index) => discovered[index]);
+      prefilledConfirmation = takeAnswer() || "";
+    }
+  } else {
+    selected = selectCleanSkills(discovered, options.names);
+    if (!input.isTTY) {
+      prefilledConfirmation = takeAnswer();
+    }
+  }
+  if (!selected.length) {
+    throw new Error(`No installed skills matched: ${options.names.join(", ")}`);
+  }
+  const plan = planClean(selected, { mode: options.purge ? "purge" : "trash" });
+  if (options.dryRun) {
+    output.write(`${renderCleanPlan("Clean dry run", plan)}\n`);
+    return;
+  }
+  await confirmClean(input, output, plan, prefilledConfirmation);
+  const applied = applyCleanPlan(plan);
+  output.write(`${renderCleanPlan("Clean summary", { operations: applied })}\n`);
+  output.write(`${renderCleanCompletion(applied)}\n`);
+}
+
+async function promptCleanSelection(input, output, skills) {
+  output.write(renderCleanSelectionMenu(skills));
+  const rl = readlinePromises.createInterface({ input, output });
+  try {
+    const answer = await rl.question("Select skills [1]: ");
+    return parseSelection(answer, skills.length, 1).map((index) => skills[index]);
+  } finally {
+    rl.close();
+  }
+}
+
+function selectCleanSkills(skills, names = []) {
+  if (!names.length) {
+    return skills;
+  }
+  const wanted = new Set(names);
+  return skills.filter((skill) => wanted.has(skill.name) || wanted.has(skill.directoryName));
+}
+
+async function confirmClean(input, output, plan, prefilledAnswer = null) {
+  const first = plan.operations[0];
+  const action = first.action === "purge" ? "Permanently delete" : "Remove";
+  const target = plan.operations.length
+    ? `${first.agent}:${first.scope}`
+    : "selected target";
+  output.write(`${action} ${plan.operations.length} selected skill(s) from ${target}?\n`);
+  if (first.action === "purge") {
+    output.write("This cannot be undone.\n");
+  } else {
+    output.write("Selected directories will be moved to .oh-skillhub/trash.\n");
+  }
+  if (prefilledAnswer !== null) {
+    output.write("Press Enter to confirm, or type anything else to cancel: \n");
+    if (prefilledAnswer.trim()) {
+      throw new Error("Cancelled. No skills were removed.");
+    }
+    return;
+  }
+  const rl = readlinePromises.createInterface({ input, output });
+  try {
+    const answer = await rl.question("Press Enter to confirm, or type anything else to cancel: ");
+    if (answer.trim()) {
+      throw new Error("Cancelled. No skills were removed.");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function renderCleanSelectionMenu(skills) {
+  const lines = ["Detected skills"];
+  skills.forEach((skill, index) => {
+    const group = `${skill.domain || "unknown"}/${skill.stage || "unknown"}`;
+    lines.push(
+      `${String(index + 1).padStart(2, " ")}. [ ] ${skill.name.padEnd(36, " ")} ${skill.status.padEnd(9, " ")} ${group}`,
+    );
+  });
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+function renderCleanPlan(title, plan) {
+  const lines = [title];
+  for (const operation of plan.operations) {
+    const destination = operation.destination || operation.source;
+    lines.push(
+      `${operation.action.toUpperCase()} ${operation.skill.name} -> ${operation.agent}:${operation.scope} ${destination}`,
+    );
+  }
+  return lines.join("\n");
+}
+
+function renderCleanCompletion(applied) {
+  const first = applied[0];
+  const target = first ? `${first.agent}:${first.scope}` : "selected target";
+  return ["", `Done. Removed ${applied.length} skill(s) from ${target}.`].join("\n");
+}
+
+function renderNoSkillsFound(targets) {
+  const lines = ["No skills found."];
+  for (const target of targets) {
+    lines.push(`${target.agent}:${target.scope} ${target.dir}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
 function renderList(options) {
   const manifest = loadLocalManifest();
   const skills = manifest.skills
@@ -624,6 +779,7 @@ function helpText() {
     "Commands:",
     "  list [--domain <name>] [--stage <name>]",
     "  install [skill...] [--domain <name>] [--preset <name>] [--agent codex|claude|opencode|all]",
+    "  clean [skill...] [--agent codex|claude|opencode|all] [--scope user|project] [--dry-run] [--purge]",
     "  doctor [--agent codex|claude|opencode|all]",
     "  telemetry status",
     "",
@@ -642,6 +798,7 @@ module.exports = {
   renderTelemetry,
   buildRepositoryChoices,
   renderAgentMenu,
+  renderCleanPlan,
   renderRawAgentMenu,
   parseSelection,
   renderRawTuiMenu,