harveyz-skill 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-06-15
+
 ## [0.16.0] - 2026-06-15
 
 ### Added

package/bin/cli.js

@@ -184,7 +184,7 @@ if (subcommand === 'list') {
   const sorted = [...skills].sort((a, b) => a.bundle.localeCompare(b.bundle) || a.path.split('/').pop().localeCompare(b.path.split('/').pop()))
   if (jsonFlag) {
     console.log(JSON.stringify({
-      skills: sorted.map(s => ({ name: s.path.split('/').pop(), path: s.path, bundle: s.bundle })),
+      skills: sorted.map(s => ({ name: s.path.split('/').pop(), path: s.path, bundle: s.bundle, global: s.global ?? false })),
       tools: tools.map(t => t.name),
     }, null, 2))
     process.exit(0)
@@ -225,7 +225,22 @@ if (subcommand === 'status' || subcommand === 'outdated') {
 
   function icon(status) {
     if (status === 'up-to-date') return chalk.green('✓')
-    if (status === 'update')     return chalk.yellow('↑')
+    if (status === 'update')     return chalk.red('↑')
+    return chalk.dim('—')
+  }
+
+  function userIcon(status, installScope) {
+    if (status === 'up-to-date')          return chalk.green('✓')
+    if (status === 'update')              return chalk.red('↑')
+    if (installScope === 'essential')     return chalk.yellow('»')
+    if (installScope === 'global')        return chalk.cyan('▸')
+    return chalk.dim('—')
+  }
+
+  function projectIcon(status, installScope) {
+    if (status === 'up-to-date')          return chalk.green('✓')
+    if (status === 'update')              return chalk.red('↑')
+    if (installScope === 'project')       return chalk.cyan('▸')
     return chalk.dim('—')
   }
 
@@ -233,13 +248,14 @@ if (subcommand === 'status' || subcommand === 'outdated') {
     const inst = checkInstalled(s.skillName, s.version ?? '—')
     return {
       name: s.skillName, bundle: s.bundle ?? '—', version: s.version ?? '—',
+      installScope: s.installScope ?? null,
       userStatus: scopeSummary(inst.user), projectStatus: scopeSummary(inst.project),
       userDetail: inst.user, projectDetail: inst.project,
     }
   }).sort((a, b) => a.bundle.localeCompare(b.bundle) || a.name.localeCompare(b.name))
   const toolRows = toolItems.map(t => {
     const inst = checkToolInstalled(t.toolName, t.srcPath)
-    return { name: t.toolName, version: t.version ?? '—', ...inst }
+    return { name: t.toolName, version: t.version ?? '—', installScope: t.installScope ?? null, ...inst }
   })
 
   if (jsonFlag) {
@@ -317,7 +333,8 @@ if (subcommand === 'status' || subcommand === 'outdated') {
   console.log(sep)
   console.log('  ' + ''.padEnd(nw + vw + bw + 5) + chalk.dim('user    project'))
   for (const r of skillRows) {
-    const u = icon(r.userStatus), p = icon(r.projectStatus)
+    const u = userIcon(r.userStatus, r.installScope)
+    const p = projectIcon(r.projectStatus, r.installScope)
     console.log('  ' + r.name.padEnd(nw) + '  ' + chalk.dim(r.version.padEnd(vw)) + '  ' + chalk.dim(r.bundle.padEnd(bw)) + '  ' + u + '       ' + p)
   }
 
@@ -325,7 +342,7 @@ if (subcommand === 'status' || subcommand === 'outdated') {
   console.log('  ' + chalk.bold('TOOLS') + chalk.dim(`  — ${toolRows.length} available`))
   console.log(sep)
   for (const r of toolRows) {
-    console.log('  ' + r.name.padEnd(nw) + '  ' + chalk.dim(r.version.padEnd(vw)) + '  ' + icon(r.status))
+    console.log('  ' + r.name.padEnd(nw) + '  ' + chalk.dim(r.version.padEnd(vw)) + '  ' + userIcon(r.status, r.installScope))
   }
 
   // ── hooks ──
@@ -333,15 +350,17 @@ if (subcommand === 'status' || subcommand === 'outdated') {
     console.log('')
     console.log('  ' + chalk.bold('HOOKS') + chalk.dim(`  — ${hookItems.length} available`))
     console.log(sep)
-    function hIcon(s) {
-      if (s === 'installed') return chalk.green('✓')
-      if (s === 'partial')   return chalk.yellow('~')
+    function hIcon(s, installScope) {
+      if (s === 'installed')            return chalk.green('✓')
+      if (s === 'partial')              return chalk.yellow('~')
+      if (installScope === 'essential') return chalk.yellow('»')
+      if (installScope === 'global')    return chalk.cyan('›')
       return chalk.dim('—')
     }
     for (const h of hookItems) {
       const inst = checkHookInstalled(h.name)
       const ver = resolveHookDisplayVersion(inst, h.version)
-      console.log('  ' + h.name.padEnd(nw) + '  ' + chalk.dim(ver.padEnd(vw)) + '  ' + hIcon(inst.user.status) + '       ' + hIcon(inst.project.status) + '  ' + chalk.dim(h.description))
+      console.log('  ' + h.name.padEnd(nw) + '  ' + chalk.dim(ver.padEnd(vw)) + '  ' + hIcon(inst.user.status, h.installScope) + '       ' + hIcon(inst.project.status, h.installScope) + '  ' + chalk.dim(h.description))
     }
   }
 
@@ -352,6 +371,7 @@ if (subcommand === 'status' || subcommand === 'outdated') {
   const outdatedNote    = outdatedCount ? '  ·  ' + chalk.yellow(outdatedCount + ' outdated') : ''
   console.log('')
   console.log(chalk.dim(`  ${installedSkills} of ${skillRows.length} skills installed  ·  ${installedTools} of ${toolRows.length} tools installed${outdatedNote}`))
+  console.log(chalk.dim(`  ${chalk.green('✓')} installed  ${chalk.red('↑')} update  ${chalk.yellow('»')} essential  ${chalk.cyan('▸')} global/project  — other`))
   console.log('')
   process.exit(0)
 }

package/lib/bundles.js

@@ -109,6 +109,7 @@ export function getAllSkillItems() {
       kind: 'skill',
       skillName: skill.path.split('/').pop(),
       bundle: skill.bundle,
+      installScope: skill.installScope ?? null,
       srcPath,
       version: readVersion(srcPath),
     }
@@ -122,6 +123,7 @@ export function getAllToolItems() {
     return {
       kind: 'tool',
       toolName: tool.name,
+      installScope: tool.installScope ?? null,
       srcPath,
       version: readToolMeta(path.join(srcPath, 'tool.json')),
     }
@@ -184,6 +186,7 @@ export function getAllHookItems() {
     const srcPath = path.join(repoRoot, hook.path, `${hook.name}.sh`)
     return {
       ...hook,
+      installScope: hook.installScope ?? null,
       srcPath,
       version: readHookVersion(srcPath),
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Skill manager for Claude Code, Cursor, and Codex",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "bundles.json",
     "skills-index.json",
     "CHANGELOG.md",
+    "skills/research/learn-skill/",
     "skills/research/extract-url/",
     "skills/research/extract-vision/",
     "skills/research/learn-video/",

package/skills/research/learn-skill/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: learn-skill
+description: "Deep-reads a single skill's SKILL.md to help you understand its internal logic. Analyzes across four dimensions: Design Philosophy (why it was designed this way), Execution Flow (how it runs), Standards (what conventions it follows), and Editing Conditions (when to modify it). Use when you want to understand a skill's design intent, how a skill works, its workflow, or the reasoning behind its design. Trigger phrases: 'help me understand this skill', 'how does this skill work', 'explain this skill', 'what is this skill doing', 'walk me through this skill', 'what's the design philosophy of this skill'."
+user_invocable: true
+version: "1.4.0"
+---
+
+# inspect-skill
+
+深度解读单个 skill 的 SKILL.md，帮助用户理解它的设计意图、运作方式、规范约定和维护逻辑。输出的是解读，不是评审。
+
+如果用户的 prompt 含有评估意图（「有什么问题」、「可以发布了吗」、「quality report」等），不要顺着评估——这个 skill 的定位是帮用户理解 skill，不是审查它。完成解读后，在结尾询问用户是否需要另外做评审。
+
+---
+
+## Step 1 — 定位目标 skill
+
+从上下文判断要分析哪个 skill：
+
+1. **直接路径**：用户提供了路径（如 `skills/meta/analyze-skill/`）→ 直接使用
+2. **名称推断**：用户提到了 skill 名称 → 在 `~/.claude/skills/` 和当前 repo 的 `skills/` 目录中搜索
+3. **当前上下文**：对话中刚刚在讨论某个 skill → 直接分析该 skill
+4. **不明确**：列出候选，请用户选择
+
+读取目标 `SKILL.md`。若存在 `references/` 子目录，读取其中每个不超过 200 行的文件（逐个判断，不合并计算）。
+
+---
+
+## Step 2 — 四维解读
+
+从以下四个维度解读 skill。每个维度的目标是让读者理解，而不是评判好坏。具体引用 skill 中的实际段落或步骤来说明，不要泛泛而谈。
+
+### 维度 1：设计哲学（Design Philosophy）
+
+解释这个 skill 背后的设计意图和取舍逻辑。大多数 SKILL.md 不会直接写「我的设计哲学是…」，需要从它做了什么、省略了什么、在哪里明确约束而在哪里信任模型来推断：
+
+- 这个 skill 做了哪些有意识的取舍？为什么选择这种方式而不是另一种？
+- 它在哪些地方信任模型自己判断，在哪些地方选择了明确约束？
+- 它的「lean」体现在哪里——哪些东西被刻意省略了？
+- 如果有一个核心设计原则贯穿整个 skill，那是什么？
+
+### 维度 2：流程执行（Execution Flow）
+
+解释这个 skill 实际上是怎么跑的：
+
+- 它的入口在哪里？什么触发条件会启动它？
+- 执行路径是什么？主流程的步骤顺序是什么？
+- 有哪些分支或条件判断？不同情况下走哪条路？
+- 它在什么时候「结束」？输出或退出条件是什么？
+- 步骤之间有哪些依赖关系——前一步的产物被后一步怎么用？
+
+### 维度 3：规范标准（Standards）
+
+解释这个 skill 遵循了哪些约定和规范：
+
+- Frontmatter 字段的设置方式（name、description、version 各写了什么、为什么这样写）
+- Description 的触发策略（覆盖了哪些使用场景，用了什么语言）
+- 篇幅和结构的组织方式（是否使用了 bundled resources，如何分层）
+- 输出格式的约定（期望产出什么，格式如何定义）
+- 写作风格的选择（祈使句、中英文混用、注释方式等）
+
+### 维度 4：编辑条件（Editing Conditions）
+
+解释在什么情况下应该修改这个 skill：
+
+- 哪些外部变化会让这个 skill 失效或过时？（依赖的工具、路径、API 变了怎么办）
+- 哪些使用场景目前没有被覆盖——如果用户遇到这些情况，skill 会怎么处理？
+- skill 里有没有硬编码的内容？它们在什么条件下需要更新？
+- 如果要扩展这个 skill 的能力，最自然的切入点在哪里？
+
+---
+
+## Step 3 — 完整性自查（输出前）
+
+分析完成后，**先不要输出报告**，对照原始 SKILL.md 检查一遍：
+
+- **遗漏**：skill 里的关键步骤、分支、约定，分析里有没有覆盖？
+- **准确性**：描述是否和原文一致，有没有误读？
+- **心理模型**：读完报告的人，能不能不翻原文就理解这个 skill 是怎么工作的？
+
+发现问题就补进分析，然后进入 Step 4 输出。
+
+---
+
+## Step 4 — 输出解读报告
+
+**语言：全部中文。** 保留英文的只有：维度标题括号内的英文名、代码/命令/字段名。
+
+报告覆盖四个维度，顺序和格式灵活，不要加评分、verdict，或建议修改的段落。
+
+报告结尾询问用户：「还有哪个部分想深入了解？」

package/skills/research/learn-skill/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "inspect-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "帮我分析一下 contribute-skill 这个 skill，它有什么问题，有没有什么需要改进的地方？目录在 /Users/harveyzhang96/Projects/harveyz-skill/skills/meta/contribute-skill/",
+      "expected_output": "中文解读报告，以设计哲学为第一个维度，涵盖四维，不含额外评估段落，结尾以收尾问句收口。",
+      "files": ["/Users/harveyzhang96/Projects/harveyz-skill/skills/meta/contribute-skill/SKILL.md"],
+      "assertions": [
+        "报告包含四个维度，且设计哲学（Design Philosophy）是第一个出现的维度标题",
+        "报告不包含评分标签（Excellent / Good / Needs Work / Poor 或数字评分）",
+        "报告不包含额外评估段落（如 '## 问题与改进建议'、'## 发布评估'、'## 改进建议'、'## 总体结论' 等评审性标题）",
+        "报告主体叙述使用中文",
+        "报告结尾包含收尾问句（询问用户是否想深入了解某部分），而不是以改进建议或评审内容结束"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "can you inspect the analyze-skill skill and give me a quality report? path is /Users/harveyzhang96/Projects/harveyz-skill/skills/meta/analyze-skill/SKILL.md",
+      "expected_output": "中文解读报告，以设计哲学为第一个维度，涵盖四维，不含额外评估段落，结尾以收尾问句收口。",
+      "files": ["/Users/harveyzhang96/Projects/harveyz-skill/skills/meta/analyze-skill/SKILL.md"],
+      "assertions": [
+        "报告包含四个维度，且设计哲学（Design Philosophy）是第一个出现的维度标题",
+        "报告不包含评分标签（Excellent / Good / Needs Work / Poor 或数字评分）",
+        "报告不包含额外评估段落（如 '## 问题与改进建议'、'## 发布评估'、'## 改进建议'、'## 总体结论' 等评审性标题）",
+        "报告主体叙述使用中文",
+        "报告结尾包含收尾问句（询问用户是否想深入了解某部分），而不是以改进建议或评审内容结束"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "这个 clean-git skill 可以发布了吗？帮我做个全面的 skill 质量审查。路径：/Users/harveyzhang96/Projects/harveyz-skill/skills/meta/clean-git/SKILL.md",
+      "expected_output": "中文解读报告，以设计哲学为第一个维度，涵盖四维，不含额外评估段落，结尾以收尾问句收口。",
+      "files": ["/Users/harveyzhang96/Projects/harveyz-skill/skills/meta/clean-git/SKILL.md"],
+      "assertions": [
+        "报告包含四个维度，且设计哲学（Design Philosophy）是第一个出现的维度标题",
+        "报告不包含评分标签（Excellent / Good / Needs Work / Poor 或数字评分）",
+        "报告不包含额外评估段落（如 '## 问题与改进建议'、'## 发布评估'、'## 改进建议'、'## 总体结论' 等评审性标题）",
+        "报告主体叙述使用中文",
+        "报告结尾包含收尾问句（询问用户是否想深入了解某部分），而不是以改进建议或评审内容结束"
+      ]
+    }
+  ]
+}

package/skills-index.json

@@ -4,22 +4,12 @@
     "tools": "开发者 OS 工具（hub — 项目管理 + git 状态 + 任务跟踪）"
   },
   "tools": [
-    {
-      "name": "p-launch",
-      "bundle": "shell-tools"
-    },
-    {
-      "name": "todo-tool",
-      "bundle": "shell-tools"
-    },
-    {
-      "name": "hub",
-      "path": "tools/hub",
-      "bundle": "tools"
-    }
+    { "name": "p-launch",  "bundle": "shell-tools", "installScope": "global"    },
+    { "name": "todo-tool", "bundle": "shell-tools", "installScope": "global"    },
+    { "name": "hub",       "path": "tools/hub", "bundle": "tools", "installScope": "essential" }
   ],
   "bundleMeta": {
-    "research": "研究工具（extract-url + learn-video + extract-vision）",
+    "research": "研究工具（extract-url + learn-video + extract-vision + learn-skill）",
     "creative": "创意工具（capture-todo + capture-insight）",
     "coding": "程序工具（init-workflow + setup-debug + dispatch-task + close-task）",
     "writing": "写作工具（forge-doc + draw-diagram + manage-docs + manage-dir + migrate-spec）",
@@ -27,36 +17,38 @@
     "meta": "元操作工具（analyze-skill + clean-git + archive-skill + dedup-skill + contribute-skill + publish-skill + release-project + runby-opencode）"
   },
   "skills": [
-    { "path": "research/extract-url",           "bundle": "research" },
-    { "path": "research/extract-vision",        "bundle": "research" },
-    { "path": "research/learn-video",           "bundle": "research" },
-    { "path": "creative/capture-todo",          "bundle": "creative" },
-    { "path": "creative/capture-insight",       "bundle": "creative" },
-    { "path": "coding/init-workflow",           "bundle": "coding" },
-    { "path": "coding/setup-debug",             "bundle": "coding" },
-    { "path": "coding/dispatch-task",           "bundle": "coding" },
-    { "path": "coding/close-task",              "bundle": "coding" },
-    { "path": "writing/forge-doc",              "bundle": "writing" },
-    { "path": "writing/draw-diagram",           "bundle": "writing" },
-    { "path": "writing/manage-docs",            "bundle": "writing" },
-    { "path": "writing/manage-dir",             "bundle": "writing" },
-    { "path": "writing/migrate-spec",           "bundle": "writing" },
-    { "path": "design/scout-brand",             "bundle": "design" },
-    { "path": "design/build-style",             "bundle": "design" },
-    { "path": "design/sync-design",             "bundle": "design" },
-    { "path": "meta/analyze-skill",             "bundle": "meta" },
-    { "path": "meta/clean-git",                 "bundle": "meta" },
-    { "path": "meta/archive-skill",             "bundle": "meta" },
-    { "path": "meta/dedup-skill",               "bundle": "meta" },
-    { "path": "meta/contribute-skill",          "bundle": "meta" },
-    { "path": "meta/publish-skill",             "bundle": "meta" },
-    { "path": "meta/runby-opencode",            "bundle": "meta" },
-    { "path": "meta/release-project",           "bundle": "meta" }
+    { "path": "research/learn-skill",      "bundle": "research", "installScope": "global"     },
+    { "path": "research/extract-url",    "bundle": "research", "installScope": "global"     },
+    { "path": "research/extract-vision", "bundle": "research", "installScope": "global"     },
+    { "path": "research/learn-video",    "bundle": "research", "installScope": "global"     },
+    { "path": "creative/capture-todo",   "bundle": "creative", "installScope": "essential"  },
+    { "path": "creative/capture-insight","bundle": "creative", "installScope": "essential"  },
+    { "path": "coding/init-workflow",    "bundle": "coding",   "installScope": "essential"  },
+    { "path": "coding/setup-debug",      "bundle": "coding",   "installScope": "project"    },
+    { "path": "coding/dispatch-task",    "bundle": "coding",   "installScope": "global"     },
+    { "path": "coding/close-task",       "bundle": "coding",   "installScope": "global"     },
+    { "path": "writing/forge-doc",       "bundle": "writing",  "installScope": "global"     },
+    { "path": "writing/draw-diagram",    "bundle": "writing",  "installScope": "global"     },
+    { "path": "writing/manage-docs",     "bundle": "writing",  "installScope": "project"    },
+    { "path": "writing/manage-dir",      "bundle": "writing",  "installScope": "project"    },
+    { "path": "writing/migrate-spec",    "bundle": "writing",  "installScope": "project"    },
+    { "path": "design/scout-brand",      "bundle": "design",   "installScope": "project"    },
+    { "path": "design/build-style",      "bundle": "design",   "installScope": "project"    },
+    { "path": "design/sync-design",      "bundle": "design",   "installScope": "project"    },
+    { "path": "meta/analyze-skill",      "bundle": "meta"                                   },
+    { "path": "meta/clean-git",          "bundle": "meta",     "installScope": "essential"  },
+    { "path": "meta/archive-skill",      "bundle": "meta"                                   },
+    { "path": "meta/dedup-skill",        "bundle": "meta"                                   },
+    { "path": "meta/contribute-skill",   "bundle": "meta"                                   },
+    { "path": "meta/publish-skill",      "bundle": "meta"                                   },
+    { "path": "meta/runby-opencode",     "bundle": "meta"                                   },
+    { "path": "meta/release-project",   "bundle": "meta",     "installScope": "essential"  }
   ],
   "hooks": [
     {
       "name": "check-similar-branch",
       "description": "用 LLM 语义分析检测相似分支",
+      "installScope": "essential",
       "path": "hooks/check-similar-branch",
       "event": "PreToolUse",
       "matcher": "Bash",