harveyz-skill 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-06-15
+
+### Added
+- `dedup-skill`：新增 meta skill，扫描并分析各 skill 间的重复内容，生成去重报告
+- `archive-skill`：新增 meta skill，将废弃 skill 移至 `skills/archived/` 并更新 skills-index.json
+- `article-fetcher`：归档（superseded by `url-extract`）
+
+### Changed
+- **Skill 命名规范**：22 个 skill 目录统一重命名为 verb-noun 格式（如 `skill-analyzer` → `analyze-skill`、`doc-forge` → `forge-doc`、`diagram` → `draw-diagram` 等）
+- `hskill update`：自动执行 skill 目录迁移，将旧名称映射到新 verb-noun 名称
+
+### Fixed
+- `archive-skill`：修复 eval 测试发现的 3 个 bug（v1.1.0）
+- `hub-tui`：修复 GitPanel 无法获得焦点的问题（`can_focus=True`）
+- `hub-tui`：Enter 键在 projects-list 焦点时正确触发打开项目
+- `hub-tui`：新增 ←/→ 键切换列，Tab 保留为辅助导航
+- `installer`：`migrateRenamedSkills` 新增输入校验和一致性日志
+
+## [0.14.2] - 2026-06-15
+
+### Changed
+- `project-release`：description 字段改为英文，符合 skill-publish F3 格式规范
+- `project-release`：移除 `npm-release` skill，以 `.hskill/release-profile.md` 替代，消除重复
+
 ## [0.14.1] - 2026-06-14
 
 ### Fixed

package/bin/cli.js

@@ -13,8 +13,8 @@ import {
   resolveSkills, resolveSkillsByName, resolveTools, resolveToolsByName,
   TOOL_BUNDLE_CHOICES,
 } from '../lib/bundles.js'
-import { buildTargetChoices, resolveTargets, TARGETS, USER_ONLY_TARGETS } from '../lib/targets.js'
-import { installSkills, installTools, installHooks, installHooksForTarget, uninstallHook, uninstallTool, uninstallSkill } from '../lib/installer.js'
+import { buildTargetChoices, resolveTargets, TARGETS, USER_ONLY_TARGETS, SKILL_TARGETS, userSkillDir } from '../lib/targets.js'
+import { installSkills, installTools, installHooks, installHooksForTarget, uninstallHook, uninstallTool, uninstallSkill, migrateRenamedSkills } from '../lib/installer.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const require = createRequire(import.meta.url)
@@ -154,6 +154,18 @@ if (subcommand === 'update') {
     console.error(chalk.red('  ✗ Update failed. Try: npm update -g harveyz-skill'))
     process.exit(1)
   }
+  // Run skill rename migrations
+  const { renames = [], skills: skillDefs = [] } = require('../skills-index.json')
+  if (renames.length > 0) {
+    console.log(chalk.dim('  · Migrating renamed skills…'))
+    const targets = SKILL_TARGETS.map(name => ({ name, dir: userSkillDir(name) }))
+    const skillsRoot = path.join(__dirname, '..', 'skills')
+    const migrationSummary = await migrateRenamedSkills(renames, targets, skillsRoot, skillDefs)
+    const totalMigrated = Object.values(migrationSummary).reduce((n, s) => n + s.migrated.length, 0)
+    const totalFailed   = Object.values(migrationSummary).reduce((n, s) => n + s.failed.length, 0)
+    if (totalMigrated > 0) console.log(chalk.green(`  ✔ Migrated ${totalMigrated} skill(s)`))
+    if (totalFailed   > 0) console.log(chalk.yellow(`  ⚠ ${totalFailed} migration(s) failed — check output above`))
+  }
   const legacyDir = path.join(os.homedir(), '.local', 'share', 'hskill')
   if (existsSync(legacyDir)) {
     console.log('')

package/lib/installer.js

@@ -702,3 +702,67 @@ export async function uninstallHook(hookName, scope, projectDir) {
 
   return { removed }
 }
+
+/**
+ * Migrate renamed skills across all user-level target platforms.
+ * Reads renames[] from skills-index.json and removes old dirs, installs new ones.
+ *
+ * @param {Array<{from: string, to: string}>} renames
+ * @param {Array<{name: string, dir: string}>} targets  - from resolveTargets()
+ * @param {string} skillsRoot  - absolute path to the skills/ source directory
+ * @param {Array<{path: string, bundle: string}>} skillDefs - skills[] from skills-index.json
+ * @returns {Promise<Object>} summary keyed by target name
+ */
+export async function migrateRenamedSkills(renames, targets, skillsRoot, skillDefs) {
+  // Fix 1: Guard against null/undefined renames
+  if (!renames?.length) return {}
+
+  const summary = {}
+
+  for (const { name: targetName, dir: targetDir } of targets) {
+    // Fix 2: Improved logging when targetDir doesn't exist
+    if (!await fs.pathExists(targetDir)) {
+      console.error(chalk.dim(`  · ${targetName}: skills dir not found, skipping`))
+      continue
+    }
+
+    const migrated = []
+    const skipped  = []
+    const failed   = []
+
+    for (const { from: oldName, to: newName } of renames) {
+      const oldPath = path.join(targetDir, oldName)
+      if (!await fs.pathExists(oldPath)) {
+        // Fix 3: Consistent logging for skipped items
+        skipped.push({ from: oldName, to: newName, reason: 'not_installed' })
+        console.error(chalk.dim(`  · ${targetName}: ${oldName} not installed, skipping`))
+        continue
+      }
+
+      // Find source for new name
+      const skillDef = skillDefs.find(s => s.path.split('/').pop() === newName)
+      if (!skillDef) {
+        failed.push({ from: oldName, to: newName, reason: 'source_not_found' })
+        console.error(chalk.red(`  ✗ No source found for ${newName}`))
+        continue
+      }
+
+      const srcPath = path.join(skillsRoot, skillDef.path)
+      const newPath = path.join(targetDir, newName)
+
+      try {
+        await fs.remove(oldPath)
+        await copyDir(srcPath, newPath, {})
+        migrated.push({ from: oldName, to: newName })
+        console.error(chalk.green(`  ✓ ${targetName}: ${oldName} → ${newName}`))
+      } catch (err) {
+        failed.push({ from: oldName, to: newName, reason: err.message })
+        console.error(chalk.red(`  ✗ ${targetName}: ${oldName} → ${newName}: ${err.message}`))
+      }
+    }
+
+    summary[targetName] = { migrated, skipped, failed }
+  }
+
+  return summary
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Skill manager for Claude Code, Cursor, and Codex",
   "type": "module",
   "bin": {
@@ -16,30 +16,31 @@
     "bundles.json",
     "skills-index.json",
     "CHANGELOG.md",
-    "skills/research/article-fetcher/",
-    "skills/research/url-extract/",
-    "skills/research/vision-extract/",
-    "skills/research/youtube-learner/",
-    "skills/creative/add-todo/",
-    "skills/creative/insight/",
-    "skills/coding/git-workflow-init/",
-    "skills/coding/full-stack-debug-env/",
-    "skills/coding/pm-task-dispatch/",
-    "skills/coding/task-close/",
-    "skills/writing/doc-forge/",
-    "skills/writing/diagram/",
-    "skills/writing/diataxis-docs/",
-    "skills/writing/dir-manage/",
-    "skills/writing/migrate-specs/",
-    "skills/design/brand-scout/",
-    "skills/design/style-build/",
-    "skills/design/sync-design-html/",
-    "skills/meta/skill-analyzer/",
-    "skills/meta/git-cleanup/",
+    "skills/research/extract-url/",
+    "skills/research/extract-vision/",
+    "skills/research/learn-video/",
+    "skills/creative/capture-todo/",
+    "skills/creative/capture-insight/",
+    "skills/coding/init-workflow/",
+    "skills/coding/setup-debug/",
+    "skills/coding/dispatch-task/",
+    "skills/coding/close-task/",
+    "skills/writing/forge-doc/",
+    "skills/writing/draw-diagram/",
+    "skills/writing/manage-docs/",
+    "skills/writing/manage-dir/",
+    "skills/writing/migrate-spec/",
+    "skills/design/scout-brand/",
+    "skills/design/build-style/",
+    "skills/design/sync-design/",
+    "skills/meta/analyze-skill/",
+    "skills/meta/clean-git/",
+    "skills/meta/archive-skill/",
+    "skills/meta/dedup-skill/",
     "skills/meta/contribute-skill/",
-    "skills/meta/skill-publish/",
-    "skills/meta/npm-release/",
-    "skills/meta/opencode-runner/",
+    "skills/meta/publish-skill/",
+    "skills/meta/runby-opencode/",
+    "skills/meta/release-project/",
     "tools/p-launch/",
     "tools/todo-tool/",
     "tools/hub/",

package/skills/coding/{task-close → close-task}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: task-close
+name: close-task
 version: "1.0.0"
 description: "Task wrap-up skill. Self-triggers after an Agent has completed its assigned task — performs task acceptance, summary, document archiving, and lessons-learned recording. Triggers when an Agent has actually finished a task and needs to carry out closing work."
 user_invocable: true

package/skills/coding/{pm-task-dispatch → dispatch-task}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pm-task-dispatch
+name: dispatch-task
 version: "1.0.0"
 description: "PM task dispatch skill. Triggers when a new task needs to be created and dispatched to another Agent. Workflow: understand task → clarify requirements → analyze and refine → create task document → dispatch via sessions_send → track feedback. Trigger scenarios: (1) Harvey proposes a new task, (2) asks to dispatch a task to a specific Agent, (3) asks how to dispatch a task."
 user_invocable: true

package/skills/coding/{git-workflow-init → init-workflow}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: git-workflow-init
+name: init-workflow
 description: "Initialize or update git branch management standards: reads workflow-config.yml, audits config, incrementally generates and deploys git hooks (pre-commit, commit-msg, pre-push, post-checkout), and generates workflow docs. Triggers: initializing a new git repo, first-time git setup, user asks to set/update branch protection or naming rules, reinstalling git hooks, or syncing after skill/template updates."
 user_invocable: true
 version: "4.1.0"

package/skills/coding/{full-stack-debug-env → setup-debug}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: full-stack-debug-env
+name: setup-debug
 version: "1.0.0"
 description: Use when setting up a log monitoring environment before running agents or test scenarios on a multi-component application — captures frontend browser console, backend processes, workers, daemons, and other services as independent log files so agents can query each layer precisely
 user_invocable: true

package/skills/creative/{insight → capture-insight}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: insight
+name: capture-insight
 version: "1.1.0"
 user_invocable: true
 description: "Capture and record a fleeting insight or observation. Triggers immediately when the user expresses an observation, judgment, or idea — phrases like 'I noticed', 'just an observation', 'record this', 'insight', 'I have a judgment', or tossing out an opinionated thought. Distinct from 'I have an idea to execute' (that's a task). Clarifies the core with 2-3 quick Q&As, then saves to the insights/ folder. Trigger early — insights are fragile."

package/skills/creative/{add-todo → capture-todo}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: add-todo
+name: capture-todo
 version: "4.5.0"
 user_invocable: true
 description: "Add a new requirement, task, or feature request to any project's TODO.md — from any working directory. Triggers whenever the user wants to capture a new need — even phrased casually like 'we should do X later', 'add this to the backlog', 'note this down', 'remember to build X', 'we need to do Y at some point', or 'record this for later'."

package/skills/design/{style-build → build-style}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: style-build
+name: build-style
 description: "Derive format-specific configs from a brand design knowledge doc. Trigger when the user wants to generate doc-forge JSON/CSS, HTML CSS variables, Mermaid color scheme, or PPT theme from a design system. E.g. 'derive configs for BCG', 'generate doc-forge style for rb', 'create HTML theme from custom-style'."
 user_invocable: true
 version: "1.4.0"
@@ -9,9 +9,9 @@ version: "1.4.0"
 
 读取 `knowledge/design/<brand>-style.md`，推导各输出格式的具体配置。
 
-**只做推导，不调查官网。** 官网调查由 `/brand-scout` 负责。
+**只做推导，不调查官网。** 官网调查由 `/scout-brand` 负责。
 
-**映射标准：** 格式字段 ↔ Token 的完整映射规则定义在 `skills/writing/style-build/references/FORMAT-MAPPING.md`，推导时以该文件为权威依据。品牌文件提供 Token 值，FORMAT-MAPPING.md 提供映射规则，两者分离。
+**映射标准：** 格式字段 ↔ Token 的完整映射规则定义在 `skills/writing/build-style/references/FORMAT-MAPPING.md`，推导时以该文件为权威依据。品牌文件提供 Token 值，FORMAT-MAPPING.md 提供映射规则，两者分离。
 
 支持输出格式：
 - **DOCX** — `doc-forge/<brand>-style.json`
@@ -49,7 +49,7 @@ BRAND="<brand>"
 KNOWLEDGE_FILE="knowledge/design/${BRAND}-style.md"
 ```
 
-用 Read 工具读取 `$KNOWLEDGE_FILE` 和 `skills/writing/style-build/references/FORMAT-MAPPING.md`。
+用 Read 工具读取 `$KNOWLEDGE_FILE` 和 `skills/writing/build-style/references/FORMAT-MAPPING.md`。
 
 **Token 解析方式（三层引用链）：**
 
@@ -148,9 +148,9 @@ H1_doc = 24
 
 ### Step 3 — 推导 DOCX 配置（按需）
 
-生成 `skills/writing/doc-forge/assets/<brand>-style.json`。
+生成 `skills/writing/forge-doc/assets/<brand>-style.json`。
 
-**映射规则参考 `skills/writing/style-build/references/FORMAT-MAPPING.md`：**
+**映射规则参考 `skills/writing/build-style/references/FORMAT-MAPPING.md`：**
 - 颜色字段 → 第二节 2.1（DOCX JSON 路径列）
 - 字体 → 第三节（CJK 始终为 `PingFang SC`，英文取降级栈第一项）
 - 尺度 → 第四节 4.1/4.2（JSON 路径列）
@@ -198,9 +198,9 @@ H1_doc = 24
 
 ### Step 4 — 推导 PDF CSS（按需）
 
-生成 `skills/writing/doc-forge/assets/<brand>.css`。
+生成 `skills/writing/forge-doc/assets/<brand>.css`。
 
-**映射规则参考 `skills/writing/style-build/references/FORMAT-MAPPING.md`：**
+**映射规则参考 `skills/writing/build-style/references/FORMAT-MAPPING.md`：**
 - 颜色属性 → 第二节 2.1（PDF CSS 属性列）
 - 字体栈 → 第三节（格式：`"官方字体", FONT_STACK`）
 - 尺度 → 第四节 4.1/4.2（CSS 属性列）
@@ -228,7 +228,7 @@ H1_doc = 24
 
 ### Step 5 — 推导 HTML CSS 变量（按需）
 
-**变量名查阅 `skills/writing/style-build/references/FORMAT-MAPPING.md` 第六节（HTML CSS 变量完整列表）。**
+**变量名查阅 `skills/writing/build-style/references/FORMAT-MAPPING.md` 第六节（HTML CSS 变量完整列表）。**
 
 按 Step 2 提取的 Semantic Token 值填入，打印完整 `:root { }` 块输出到对话，供用户粘贴使用。
 
@@ -236,9 +236,9 @@ H1_doc = 24
 
 ### Step 6 — 推导 Mermaid 主题并写入配置文件（按需）
 
-**themeVariables 键名查阅 `skills/writing/style-build/references/FORMAT-MAPPING.md` 第七节。**
+**themeVariables 键名查阅 `skills/writing/build-style/references/FORMAT-MAPPING.md` 第七节。**
 
-写入 `skills/writing/diagram/themes/<brand>.json`，同时在对话中打印可直接嵌入的 `%%{init}%%` 块。
+写入 `skills/writing/draw-diagram/themes/<brand>.json`，同时在对话中打印可直接嵌入的 `%%{init}%%` 块。
 
 主题文件按图类型分区存储，不同图类型使用不同样式机制。
 
@@ -419,7 +419,7 @@ semantic 的 `text` 字段：fill 深于 `rules.dark_text_threshold` → `#FFFFF
 
 ### Step 7 — 推导 PPT 主题（按需）
 
-**色槽对应查阅 `skills/writing/style-build/references/FORMAT-MAPPING.md` 第八节（PPT 色槽完整映射）。**
+**色槽对应查阅 `skills/writing/build-style/references/FORMAT-MAPPING.md` 第八节（PPT 色槽完整映射）。**
 
 以文字形式输出 PPT 主题配置（标题幻灯片 + 内容幻灯片 + 主题色板槽位）。
 
@@ -439,7 +439,7 @@ semantic 的 `text` 字段：fill 深于 `rules.dark_text_threshold` → `#FFFFF
 > 3. **表格模式** — `border_mode` 是否与设计文档一致？
 > 4. **Mermaid 深色节点** — subgraph/node 所有 fill 深于 `#4A4A4A` 的是否都有 `color:#fff`？
 >
-> 确认后可运行 `/doc-forge` 生成测试文档，或用 `/diagram` 测试配色效果。
+> 确认后可运行 `/forge-doc` 生成测试文档，或用 `/draw-diagram` 测试配色效果。
 
 ---
 

package/skills/design/{brand-scout → scout-brand}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: brand-scout
-description: "Survey a brand's visual design style from their official website and output a structured design knowledge document. Trigger when the user wants to analyze a company's design style — e.g. 'analyze McKinsey style', 'survey BCG design', 'extract style from URL'. Outputs to knowledge/design/<brand>-style.md only. Use /style-build to generate format-specific configs from the knowledge doc."
+name: scout-brand
+description: "Survey a brand's visual design style from their official website and output a structured design knowledge document. Trigger when the user wants to analyze a company's design style — e.g. 'analyze McKinsey style', 'survey BCG design', 'extract style from URL'. Outputs to knowledge/design/<brand>-style.md only. Use /build-style to generate format-specific configs from the knowledge doc."
 user_invocable: true
 version: "2.1.0"
 ---
@@ -9,11 +9,11 @@ version: "2.1.0"
 
 给定一个公司官网 URL，调查其设计风格，输出 `knowledge/design/<brand>-style.md`。
 
-**只做调查，不生成配置。** 配置生成由 `/style-build` 负责。
+**只做调查，不生成配置。** 配置生成由 `/build-style` 负责。
 
 调查分**两个阶段**：先全面调查主页（品牌色、导航、CTA 按钮、Hero 区域），再深入报告/文章正文页（排版、表格、引用块、代码块）。两阶段数据合并后写入知识文档。
 
-输出文档遵循 `skills/writing/brand-scout/references/TEMPLATE.md` 的完整结构，覆盖：色彩体系（三维分类）、字体体系、间距体系、组件规则、视觉层级、图像处理、数据可视化、各格式推导指南。
+输出文档遵循 `skills/writing/scout-brand/references/TEMPLATE.md` 的完整结构，覆盖：色彩体系（三维分类）、字体体系、间距体系、组件规则、视觉层级、图像处理、数据可视化、各格式推导指南。
 
 > **依赖：** 必须先通过 `/browse` skill 完成 browse 初始化。
 
@@ -329,7 +329,7 @@ $B screenshot /tmp/scout-quote.png --selector "blockquote,[class*=callout],[clas
 
 ### Step 13 — 合并两阶段数据，按三层 Token 模型写入知识文档
 
-综合主页调查（Step 3–6）和报告页调查（Step 8–12）的结果，按 `skills/writing/brand-scout/references/TEMPLATE.md` 的三层 Token 结构填写，写到 `knowledge/design/<brand>-style.md`。
+综合主页调查（Step 3–6）和报告页调查（Step 8–12）的结果，按 `skills/writing/scout-brand/references/TEMPLATE.md` 的三层 Token 结构填写，写到 `knowledge/design/<brand>-style.md`。
 
 **数据来源优先级：**
 
@@ -373,7 +373,7 @@ $B screenshot /tmp/scout-quote.png --selector "blockquote,[class*=callout],[clas
 > 3. **2.2 Text** — `[视觉近黑]` 标注是否准确？这些颜色是否确实在截图中接近黑色？
 > 4. **2.3 Component** — 若有非默认映射（如 blockquote 颜色），是否已修改对应行？
 >
-> 确认后可运行 `/style-build` 生成具体格式配置。
+> 确认后可运行 `/build-style` 生成具体格式配置。
 
 ---
 

package/skills/design/{sync-design-html → sync-design}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: sync-design-html
+name: sync-design
 description: Use after any UI source file change — detects changed view/component files via git diff and syncs them to high-fidelity HTML design backups. Maintains a manifest as the source-of-truth mapping between source files and HTML previews. Also invocable as a post-step from /ship or /review. Trigger when user says "sync design", "update HTML preview", "design changed", or after UI code edits.
 version: "3.0.0"
 user_invocable: true

package/skills/meta/{skill-analyzer → analyze-skill}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: skill-analyzer
+name: analyze-skill
 description: "Performs systematic analysis of the skill repository. Triggers: analyze this skill repo, do a systematic study of the skill repo, output skill repo analysis report, understand the design intent of this skill system."
 user_invocable: true
 version: "1.0.0"

package/skills/meta/archive-skill/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: archive-skill
+description: "Archive, retire, deprecate, or sunset a skill from the active registry. Use this skill whenever someone wants to remove a skill from active use — even if they don't use the word 'archive'. Moves it to skills/archived/, removes it from skills-index.json, regenerates packaging config, and commits on a chore branch merged back to the original branch. Triggers: 'archive X skill', 'retire X', 'deprecate X', '归档 skill', '退役 skill', 'remove X from bundle', 'sunset X skill'."
+user_invocable: true
+version: "1.1.0"
+---
+
+# archive-skill
+
+将一个已退役的 skill 从活跃注册表移入 `skills/archived/`，自动完成文件操作、index 更新、打包配置重新生成，并提交到 git。
+
+---
+
+## Step 1 — 匹配 skill
+
+从用户指令中提取 skill 名关键字，读取 `skills-index.json` 获取所有已注册 skill：
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+node -e "
+  const idx = JSON.parse(require('fs').readFileSync('${REPO_ROOT}/skills-index.json','utf8'));
+  idx.skills.forEach(s => console.log(s.path));
+"
+```
+
+在 path 末段（`<category>/<name>` 的 `<name>` 部分）中搜索关键字：
+
+| 匹配结果 | 行为 |
+|---------|------|
+| 完全匹配 1 个 | 直接进 Step 2 |
+| 部分匹配 1 个 | 展示候选并问用户："是否归档 `<name>`？(y/n)" — 确认后进 Step 2 |
+| 部分匹配多个 | 列出所有候选，让用户选择编号后进 Step 2 |
+| 0 匹配 | 报错：`未找到匹配的 skill，请检查名称后重试。` 退出 |
+
+---
+
+## Step 2 — 前置检查
+
+在执行任何操作前，检查三个条件，任一不满足则中止：
+
+**1. 不在 detached HEAD 状态**
+```bash
+ORIGINAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+```
+若结果为 `HEAD`（detached），提示：
+`当前处于 detached HEAD 状态，无法确定要 merge 回的目标分支。请先切换到一个具名分支后重试。`
+然后退出。
+
+**2. 无未提交变更**
+```bash
+git status --short
+```
+若有未提交修改，提示：`存在未提交的变更，请先 commit 或 stash 后重试。` 退出。
+
+**3. 归档目标不冲突**
+```bash
+ls "${REPO_ROOT}/skills/archived/<name>" 2>/dev/null
+```
+若已存在，提示：`skills/archived/<name>/ 已存在，请手动处理后重试。` 退出。
+
+---
+
+## Step 3 — 确认摘要
+
+展示操作预览，**等待用户明确确认后再执行**：
+
+```
+即将归档 <name>（bundle: <bundle>）：
+
+  移动：skills/<category>/<name>/ → skills/archived/<name>/
+  从 skills-index.json 移除该条目
+  更新 bundleMeta.<bundle>：去掉描述中的 "<name>"
+  重新生成：package.json files[] 和 .npmignore
+  Git：chore/archive-<name> → merge 回 <ORIGINAL_BRANCH>
+
+确认继续？(y/n)
+```
+
+用户输入 `n` 则中止，不做任何修改。
+
+---
+
+## Step 4 — 创建分支并移动文件
+
+```bash
+git checkout -b chore/archive-<name>
+mkdir -p "${REPO_ROOT}/skills/archived"
+git mv "skills/<category>/<name>" "skills/archived/<name>"
+```
+
+> 若创建分支时看到 check-similar-branch hook 的相似分支警告，可忽略——archive 分支之间相似是正常现象。
+
+---
+
+## Step 5 — 更新 skills-index.json
+
+读取并修改 `skills-index.json`，写回文件：
+
+**移除 skills[] 条目：** 删除 `path` 末段为 `<name>` 的对象。
+
+**更新 bundleMeta 描述：** 描述格式为 `"研究工具（a + b + c）"`，从中删除 `<name>`：
+- 若在中间：删除 ` + <name>` 或 `<name> + `
+- 若为最后一项：删除 ` + <name>`
+- 若括号内只剩该项：将整个 `（<name>）` 删除，或保留空括号（均可）
+- 若描述中无该 skill 名：跳过，不报错
+
+---
+
+## Step 6 — 重新生成打包配置
+
+```bash
+node scripts/generate-npmignore.js
+```
+
+若脚本失败，报错并中止，不执行 git 操作，保留已修改的文件供用户检查。
+
+---
+
+## Step 7 — Git commit
+
+`git mv` 已自动 stage 了文件移动，只需 add 配置文件的修改：
+
+```bash
+git add skills-index.json package.json .npmignore
+git commit -m "chore: archive <name> skill"
+```
+
+---
+
+## Step 8 — 合并回原分支
+
+```bash
+git checkout <ORIGINAL_BRANCH>
+git merge --no-ff chore/archive-<name>
+```
+
+完成后输出摘要：
+
+```
+✓ <name> 已归档
+
+  归档路径：skills/archived/<name>/
+  已从 skills-index.json 移除
+  已更新 package.json + .npmignore
+  已 merge 回 <ORIGINAL_BRANCH>
+
+  分支 chore/archive-<name> 可手动删除：
+    git branch -d chore/archive-<name>
+```
+
+---
+
+## 边界情况汇总
+
+| 情况 | 处理 |
+|------|------|
+| Detached HEAD | Step 2 中止，提示切换到具名分支 |
+| 有未提交变更 | Step 2 中止，提示 commit 或 stash |
+| `skills/archived/<name>/` 已存在 | Step 2 中止，提示手动处理 |
+| `generate-npmignore.js` 失败 | Step 6 中止，不执行 git 操作 |
+| skill 在磁盘但不在 index | 提示"仅做文件移动"，跳过 Step 5 |
+| bundleMeta 描述无该 skill 名 | 跳过描述更新，继续 |
+
+---
+
+## 不在范围内
+
+- 批量归档多个 skill
+- 自动删除归档分支
+- 恢复（un-archive）操作

package/skills/meta/{git-cleanup → clean-git}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: git-cleanup
+name: clean-git
 description: "Tidy and clean up local git branches using rule matching and LLM semantic analysis, then batch-delete stale branches after grouped confirmation. Triggers: clean up branches, branch cleanup, tidy branches, delete old branches, organize branches."
 user_invocable: true
 version: "1.0.0"