harveyz-skill 0.5.0 → 0.6.1

package/bin/cli.js

@@ -1,16 +1,21 @@
 #!/usr/bin/env node
-import { checkbox, select } from '@inquirer/prompts'
+import { select } from '@inquirer/prompts'
 import chalk from 'chalk'
-import { execSync } from 'child_process'
+import { execSync, spawnSync } from 'child_process'
 import { createRequire } from 'module'
+import os from 'os'
+import path from 'path'
+import { fileURLToPath } from 'url'
 import {
-  buildAllChoices, getAllSkillItems, getAllToolItems,
+  getAllSkillItems, getAllToolItems,
+  checkInstalled, checkToolInstalled, scopeSummary,
   resolveSkills, resolveSkillsByName, resolveTools, resolveToolsByName,
   TOOL_BUNDLE_CHOICES,
 } from '../lib/bundles.js'
 import { buildTargetChoices, resolveTargets, TARGETS } from '../lib/targets.js'
 import { installSkills, installTools } from '../lib/installer.js'
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const require = createRequire(import.meta.url)
 const { version } = require('../package.json')
 
@@ -32,15 +37,20 @@ function printHelp() {
     hskill install --scope <s>     set scope: user (default) or project
     hskill install --force         overwrite existing installs
     hskill list                    list available skills and bundles
+    hskill status                  show install status for all skills and tools
+    hskill outdated                list skills and tools with available updates
+    hskill info <name>             show install detail for a skill or tool
     hskill update                  update hskill to the latest version
-    hskill --version               show version
+    hskill version                 show version
     hskill --help                  show this help
 
   ${chalk.cyan('Examples:')}
     hskill install --bundle dev --target claude
     hskill install --skill git-workflow-init --target claude --scope project
     hskill install --tool p-launch
-    hskill update
+    hskill status
+    hskill outdated
+    hskill info git-workflow-init
 `)
 }
 
@@ -49,7 +59,7 @@ if (args[0] === '--help' || args[0] === '-h') {
   process.exit(0)
 }
 
-if (args[0] === '--version' || args[0] === '-v') {
+if (args[0] === '--version' || args[0] === '-v' || subcommand === 'version') {
   console.log(version)
   process.exit(0)
 }
@@ -87,6 +97,155 @@ if (subcommand === 'list') {
   process.exit(0)
 }
 
+// ── Status / Outdated ─────────────────────────────────────────────────────────
+if (subcommand === 'status' || subcommand === 'outdated') {
+  const outdatedOnly = subcommand === 'outdated'
+  const skillItems   = getAllSkillItems()
+  const toolItems    = getAllToolItems()
+
+  function icon(status) {
+    if (status === 'up-to-date') return chalk.green('✓')
+    if (status === 'update')     return chalk.yellow('↑')
+    return chalk.dim('—')
+  }
+
+  const skillRows = skillItems.map(s => {
+    const inst = checkInstalled(s.skillName, s.version ?? '—')
+    return {
+      name: s.skillName, version: s.version ?? '—',
+      userStatus: scopeSummary(inst.user), projectStatus: scopeSummary(inst.project),
+      userDetail: inst.user, projectDetail: inst.project,
+    }
+  })
+  const toolRows = toolItems.map(t => {
+    const inst = checkToolInstalled(t.toolName, t.srcPath)
+    return { name: t.toolName, version: t.version ?? '—', ...inst }
+  })
+
+  if (outdatedOnly) {
+    const outdatedSkills = skillRows.filter(r => r.userStatus === 'update' || r.projectStatus === 'update')
+    const outdatedTools  = toolRows.filter(r => r.status === 'update')
+
+    if (!outdatedSkills.length && !outdatedTools.length) {
+      console.log(chalk.green.bold('\n  ✓ All installed skills and tools are up to date\n'))
+      process.exit(0)
+    }
+
+    const targets = ['claude', 'cursor', 'codex']
+
+    if (outdatedSkills.length) {
+      console.log('\n  ' + chalk.bold('SKILLS WITH UPDATES'))
+      const nw = Math.max(...outdatedSkills.map(r => r.name.length))
+      for (const r of outdatedSkills) {
+        console.log('  ' + r.name.padEnd(nw) + '  available: ' + chalk.yellow(r.version))
+        for (const scope of ['user', 'project']) {
+          const detail = scope === 'user' ? r.userDetail : r.projectDetail
+          for (const t of targets) {
+            if (detail[t].status === 'update') {
+              console.log('    ' + chalk.dim(scope.padEnd(8) + t.padEnd(8)) + detail[t].version + ' → ' + chalk.yellow(r.version))
+            }
+          }
+        }
+      }
+    }
+
+    if (outdatedTools.length) {
+      console.log('\n  ' + chalk.bold('TOOLS WITH UPDATES'))
+      const nw = Math.max(...outdatedTools.map(r => r.name.length))
+      for (const r of outdatedTools) {
+        console.log('  ' + r.name.padEnd(nw) + '  ' + chalk.dim(r.version) + ' → ' + chalk.yellow(r.version))
+      }
+    }
+    console.log('')
+    process.exit(0)
+  }
+
+  // Full status table
+  const allNames = [...skillRows, ...toolRows].map(r => r.name)
+  const allVers  = [...skillRows, ...toolRows].map(r => r.version)
+  const nw = Math.max(...allNames.map(n => n.length), 4)
+  const vw = Math.max(...allVers.map(v => v.length), 7)
+  const sep = chalk.dim('  ' + '─'.repeat(nw + vw + 20))
+
+  console.log('')
+  console.log('  ' + chalk.bold('SKILLS') + chalk.dim(`  — ${skillRows.length} available`))
+  console.log(sep)
+  console.log('  ' + ''.padEnd(nw + vw + 3) + chalk.dim('user    project'))
+  for (const r of skillRows) {
+    const u = icon(r.userStatus), p = icon(r.projectStatus)
+    console.log('  ' + r.name.padEnd(nw) + '  ' + chalk.dim(r.version.padEnd(vw)) + '  ' + u + '       ' + p)
+  }
+
+  console.log('')
+  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))
+  }
+
+  const installedSkills = skillRows.filter(r => r.userStatus !== 'none' || r.projectStatus !== 'none').length
+  const installedTools  = toolRows.filter(r => r.status !== 'none').length
+  const outdatedCount   = skillRows.filter(r => r.userStatus === 'update' || r.projectStatus === 'update').length
+                        + toolRows.filter(r => r.status === 'update').length
+  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('')
+  process.exit(0)
+}
+
+// ── Info ──────────────────────────────────────────────────────────────────────
+if (subcommand === 'info') {
+  const name = args[1]
+  if (!name) {
+    console.error(chalk.red('  ✗ Usage: hskill info <skill-or-tool-name>'))
+    process.exit(1)
+  }
+
+  const skillItems = getAllSkillItems()
+  const toolItems  = getAllToolItems()
+  const skill = skillItems.find(s => s.skillName === name)
+  const tool  = toolItems.find(t => t.toolName === name)
+
+  if (!skill && !tool) {
+    console.error(chalk.red(`  ✗ Unknown: "${name}"`))
+    process.exit(1)
+  }
+
+  const targets = ['claude', 'cursor', 'codex']
+
+  function statusLabel(status) {
+    if (status === 'up-to-date') return chalk.green('✓ up to date')
+    if (status === 'update')     return chalk.yellow('↑ update available')
+    return chalk.dim('— not installed')
+  }
+
+  console.log('')
+  if (skill) {
+    const inst = checkInstalled(skill.skillName, skill.version ?? '—')
+    console.log('  ' + chalk.bold(skill.skillName) + chalk.dim('  skill'))
+    console.log('  ' + chalk.dim('available: ') + (skill.version ?? '—'))
+    console.log('')
+    for (const [scopeLabel, detail] of [['USER LEVEL', inst.user], ['PROJECT LEVEL', inst.project]]) {
+      console.log('  ' + chalk.bold(scopeLabel))
+      for (const t of targets) {
+        const { version: v, status } = detail[t]
+        console.log('  ' + t.padEnd(8) + chalk.dim(v.padEnd(10)) + statusLabel(status))
+      }
+      console.log('')
+    }
+  } else {
+    const inst = checkToolInstalled(tool.toolName, tool.srcPath)
+    console.log('  ' + chalk.bold(tool.toolName) + chalk.dim('  shell tool'))
+    console.log('  ' + chalk.dim('available: ') + (tool.version ?? '—'))
+    console.log('')
+    console.log('  ' + chalk.bold('INSTALL STATUS'))
+    console.log('  ' + '~/.local/bin'.padEnd(14) + chalk.dim(inst.version.padEnd(10)) + statusLabel(inst.status))
+    console.log('')
+  }
+  process.exit(0)
+}
+
 // ── Install ───────────────────────────────────────────────────────────────────
 // subcommand is 'install' or omitted (default behavior)
 const installArgs = subcommand === 'install' ? args.slice(1) : args
@@ -105,19 +264,76 @@ const scopeArg  = scopeIdx  !== -1 ? installArgs[scopeIdx  + 1] : undefined
 
 const TOOL_BUNDLE_VALUES = new Set(TOOL_BUNDLE_CHOICES.map(c => c.value))
 
-function buildInteractiveChoices() {
-  const toolItems = getAllToolItems()
-  return [
-    ...buildAllChoices(),
-    ...(toolItems.length > 0
-      ? [
-          { type: 'separator', separator: '── shell tools ──' },
-          ...toolItems.map(t => ({ name: t.toolName, value: t })),
-        ]
-      : []),
-    { type: 'separator', separator: '────────────────' },
-    { name: 'all skills', value: 'all' },
+// 用 fzf 交互式选择 skill/tool，返回选中的 item 列表
+function fzfSelect() {
+  const skillItems  = getAllSkillItems()
+  const toolItems   = getAllToolItems()
+  const previewPath = path.join(__dirname, 'preview.mjs')
+
+  // 构建 fzf 输入：每行 "NAME\tVERSION\tBUNDLE\tKIND\tSRCPATH"
+  const lines = [
+    ...skillItems.map(s => {
+      const bundle = s.srcPath.split('/').slice(-2, -1)[0]
+      return `${s.skillName}\t${s.version ?? '—'}\t${bundle}\tskill\t${s.srcPath}`
+    }),
+    ...toolItems.map(t => `${t.toolName}\t${t.version ?? '—'}\tshell-tool\ttool\t${t.srcPath}`),
   ]
+
+  const nameWidth    = Math.max(...lines.map(l => l.split('\t')[0].length))
+  const versionWidth = Math.max(...lines.map(l => l.split('\t')[1].length))
+
+  const G = '\x1b[32m', Y = '\x1b[33m', D = '\x1b[2m', R = '\x1b[0m'
+  function colorIcon(status) {
+    if (status === 'up-to-date') return G + '✓' + R
+    if (status === 'update')     return Y + '↑' + R
+    return D + '—' + R
+  }
+
+  // fzf 展示格式：NAME   VERSION   U:?  P:?  BUNDLE
+  const displayLines = lines.map(l => {
+    const [name, ver, bundle, kind, srcPath] = l.split('\t')
+    let uIcon = D + '—' + R, pIcon = D + '—' + R
+    if (kind === 'skill') {
+      const installed = checkInstalled(name, ver)
+      uIcon = colorIcon(scopeSummary(installed.user))
+      pIcon = colorIcon(scopeSummary(installed.project))
+    } else if (kind === 'tool') {
+      uIcon = colorIcon(checkToolInstalled(name, srcPath).status)
+    }
+    return `${name.padEnd(nameWidth)}  ${ver.padEnd(versionWidth)}  U:${uIcon}  P:${pIcon}  ${bundle}`
+  })
+
+  // 把原始数据附在末尾（隐藏列，用于解析和 preview）
+  const fzfInput = displayLines.map((d, i) => `${d}\t${lines[i]}`).join('\n')
+
+  const header = `  hskill  ·  U=user P=project  ${G}✓${R}=ok ${Y}↑${R}=update ${D}—${R}=none  ·  tab 多选  ·  enter 确认`
+
+  const result = spawnSync('fzf', [
+    '--multi',
+    '--ansi',
+    '--delimiter=\t',
+    '--with-nth=1',
+    '--prompt=  › ',
+    `--header=${header}`,
+    '--layout=reverse',
+    '--border=rounded',
+    '--color=header:italic:dim,prompt:cyan,pointer:cyan,hl:cyan,hl+:cyan:bold',
+    `--preview=node ${previewPath} {2} {3} {5} {6}`,
+    '--preview-window=right:42%:wrap',
+  ], {
+    input: fzfInput,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'inherit'],
+  })
+
+  if (result.status !== 0 || !result.stdout.trim()) return []
+
+  return result.stdout.trim().split('\n').map(line => {
+    const parts = line.split('\t')
+    const [, name, ver, bundle, kind, srcPath] = parts
+    if (kind === 'skill') return { kind: 'skill', skillName: name, srcPath, version: ver }
+    return { kind: 'tool', toolName: name, srcPath, version: ver }
+  })
 }
 
 try {
@@ -137,24 +353,17 @@ try {
     if (skillBundles.length) skillItems = resolveSkills(skillBundles).map(s => ({ kind: 'skill', ...s }))
     if (toolBundles.length)  toolItems  = resolveTools(toolBundles).map(t => ({ kind: 'tool', ...t }))
   } else {
-    const selected = await checkbox({
-      message: 'Select items to install (space to select, enter to confirm):',
-      choices: buildInteractiveChoices(),
-    })
+    const selected = fzfSelect()
 
     if (!selected.length) {
       console.log(chalk.dim('  · Nothing selected, exiting'))
       process.exit(0)
     }
 
-    const hasAll = selected.includes('all')
-    const items  = selected.filter(s => s !== 'all')
-
-    const selectedSkills = hasAll ? getAllSkillItems() : items.filter(s => s.kind === 'skill')
-    toolItems = items.filter(s => s.kind === 'tool')
+    toolItems = selected.filter(s => s.kind === 'tool')
 
     const seen = new Set()
-    skillItems = selectedSkills.filter(s => {
+    skillItems = selected.filter(s => s.kind === 'skill').filter(s => {
       if (seen.has(s.skillName)) return false
       seen.add(s.skillName); return true
     })
@@ -170,13 +379,22 @@ try {
     // Resolve scope
     let scope = scopeArg ?? 'user'
     if (!scopeArg && !targetArg) {
-      scope = await select({
-        message: 'Scope:',
-        choices: [
-          { name: `user     — ~/.claude/skills/  (shared across all projects)`, value: 'user' },
-          { name: `project  — .claude/skills/    (current project only)`, value: 'project' },
-        ],
+      const scopeResult = spawnSync('fzf', [
+        '--prompt=  › ',
+        '--header=  Scope  ·  enter 确认  ·  esc 取消',
+        '--layout=reverse',
+        '--border=rounded',
+        '--color=header:italic:dim,prompt:cyan,pointer:cyan,hl:cyan,hl+:cyan:bold',
+      ], {
+        input: `user     — ~/.claude/skills/  (所有项目共享)\nproject  — .claude/skills/    (仅当前项目)`,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'inherit'],
       })
+      if (!scopeResult.stdout.trim()) {
+        console.log(chalk.dim('  · Cancelled'))
+        process.exit(0)
+      }
+      scope = scopeResult.stdout.trim().startsWith('project') ? 'project' : 'user'
     }
 
     // Resolve target
@@ -184,13 +402,26 @@ try {
     if (targetArg) {
       selectedTargets = targetArg === 'all' ? ['claude', 'cursor', 'codex'] : [targetArg]
     } else {
-      selectedTargets = await checkbox({
-        message: 'Install to which tools (space to select, enter to confirm):',
-        choices: [
-          ...buildTargetChoices(scope),
-          { name: 'all      — all tools', value: 'all' },
-        ],
+      const targetChoices = buildTargetChoices(scope)
+      const targetInput = targetChoices.map(c => c.name).join('\n') + '\nall      — all tools'
+      const targetResult = spawnSync('fzf', [
+        '--multi',
+        '--prompt=  › ',
+        '--header=  Install to  ·  tab 多选  ·  enter 确认  ·  esc 取消',
+        '--layout=reverse',
+        '--border=rounded',
+        '--color=header:italic:dim,prompt:cyan,pointer:cyan,hl:cyan,hl+:cyan:bold',
+      ], {
+        input: targetInput,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'inherit'],
       })
+      if (!targetResult.stdout.trim()) {
+        console.log(chalk.dim('  · Cancelled'))
+        process.exit(0)
+      }
+      selectedTargets = targetResult.stdout.trim().split('\n')
+        .map(l => l.trim().split(/\s+/)[0])
     }
 
     if (selectedTargets.length > 0) {

package/bin/preview.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const skillName        = process.argv[2]?.trim()
+const availableVersion = process.argv[3]?.trim() || '—'
+const kind             = process.argv[4]?.trim()
+const srcPath          = process.argv[5]?.trim()
+
+const G = '\x1b[32m', Y = '\x1b[33m', D = '\x1b[2m', R = '\x1b[0m', B = '\x1b[1m'
+
+if (!skillName) process.exit(0)
+
+if (kind !== 'skill') {
+  const home = os.homedir()
+  const installedBin  = path.join(home, '.local', 'bin', skillName)
+  const installedMeta = path.join(home, '.local', 'share', 'hskill', 'tools', `${skillName}.json`)
+
+  function readToolMeta(jsonPath) {
+    try {
+      const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'))
+      return data.version ?? '—'
+    } catch { return '—' }
+  }
+
+  const installed        = fs.existsSync(installedBin)
+  const installedVersion = installed ? readToolMeta(installedMeta) : '—'
+  const sourceVersion    = srcPath ? readToolMeta(path.join(srcPath, 'tool.json')) : availableVersion
+  const status = !installed ? 'none'
+    : installedVersion === '—' || installedVersion === sourceVersion ? 'up-to-date'
+    : 'update'
+
+  function statusLine(version, st) {
+    const ver = version.padEnd(8)
+    if (st === 'up-to-date') return ver + '  ' + G + '✓ up to date' + R
+    if (st === 'update')     return ver + '  ' + Y + '↑ update available' + R
+    return ver + '  ' + D + '— not installed' + R
+  }
+
+  console.log(B + skillName + R)
+  console.log(D + 'available: ' + R + sourceVersion)
+  console.log('')
+  console.log(B + 'INSTALL STATUS' + R)
+  console.log('  ' + '~/.local/bin'.padEnd(14) + '  ' + statusLine(installedVersion, status))
+  console.log('')
+  if (status === 'update') {
+    console.log(Y + 'ACTION: update → ~/.local/bin' + R)
+  } else if (status === 'none') {
+    console.log(D + 'STATUS: not installed' + R)
+  } else {
+    console.log(G + 'STATUS: ok' + R)
+  }
+  process.exit(0)
+}
+
+function readVersion(skillPath) {
+  try {
+    const content = fs.readFileSync(path.join(skillPath, 'SKILL.md'), 'utf8')
+    const m = content.match(/^---[\s\S]*?^version:\s*["']?([^"'\n]+)["']?/m)
+    return m ? m[1].trim() : '—'
+  } catch { return '—' }
+}
+
+function statusLine(version, status) {
+  const ver = version.padEnd(8)
+  if (status === 'up-to-date') return ver + '  ' + G + '✓ up to date' + R
+  if (status === 'update')     return ver + '  ' + Y + '↑ update available' + R
+  return ver + '  ' + D + '— not installed' + R
+}
+
+const targets = ['claude', 'cursor', 'codex']
+const home    = os.homedir()
+
+function checkScope(dirFn) {
+  return targets.map(t => {
+    const ver    = readVersion(path.join(dirFn(t), skillName))
+    const status = ver === '—' ? 'none'
+      : ver === availableVersion ? 'up-to-date'
+      : 'update'
+    return { tool: t, version: ver, status }
+  })
+}
+
+const cwd = process.cwd()
+const userDetails    = checkScope(t => path.join(home, `.${t}`, 'skills'))
+const projectDetails = cwd === home
+  ? targets.map(t => ({ tool: t, version: '—', status: 'none' }))
+  : checkScope(t => path.join(cwd, `.${t}`, 'skills'))
+
+console.log(B + skillName + R)
+console.log(D + 'available: ' + R + availableVersion)
+console.log('')
+
+console.log(B + 'USER LEVEL' + R)
+for (const { tool, version, status } of userDetails) {
+  console.log('  ' + tool.padEnd(8) + statusLine(version, status))
+}
+console.log('')
+
+console.log(B + 'PROJECT LEVEL' + R)
+for (const { tool, version, status } of projectDetails) {
+  console.log('  ' + tool.padEnd(8) + statusLine(version, status))
+}
+console.log('')
+
+const allDetails  = [...userDetails, ...projectDetails]
+const needsUpdate = allDetails.filter(d => d.status === 'update')
+const allNone     = allDetails.every(d => d.status === 'none')
+
+if (needsUpdate.length > 0) {
+  const tools = [...new Set(needsUpdate.map(d => d.tool))].join(', ')
+  console.log(Y + 'ACTION: update → ' + tools + R)
+} else if (allNone) {
+  console.log(D + 'STATUS: not installed' + R)
+} else {
+  console.log(G + 'STATUS: ok' + R)
+}

package/lib/bundles.js

@@ -1,3 +1,5 @@
+import fs from 'fs'
+import os from 'os'
 import { createRequire } from 'module'
 import path from 'path'
 import { fileURLToPath } from 'url'
@@ -9,6 +11,23 @@ const { bundleMeta, skills: skillDefs, toolBundleMeta = {}, tools: toolDefs = []
 const repoRoot = path.join(__dirname, '..')
 const skillsRoot = path.join(repoRoot, 'skills')
 
+// 从 SKILL.md frontmatter 读取 version 字段
+function readVersion(skillPath) {
+  try {
+    const content = fs.readFileSync(path.join(skillPath, 'SKILL.md'), 'utf8')
+    const m = content.match(/^---[\s\S]*?^version:\s*["']?([^"'\n]+)["']?/m)
+    return m ? m[1].trim() : '—'
+  } catch {
+    return '—'
+  }
+}
+
+// 格式化 checkbox 展示名：左对齐 skill 名，右侧对齐版本号
+function formatChoice(name, version, nameWidth) {
+  const padded = name.padEnd(nameWidth)
+  return `${padded}  ${version}`
+}
+
 // ── Skills ──────────────────────────────────────────────────────────────────
 const bundleSkills = {}
 for (const skill of skillDefs) {
@@ -57,14 +76,21 @@ export function resolveSkills(selectedBundles) {
 export function buildAllChoices() {
   const choices = []
 
+  // 预计算所有 skill 名的最大长度，统一对齐
+  const allSkillNames = skillDefs.map(s => s.path.split('/').pop())
+  const allToolNames  = toolDefs.map(t => t.name)
+  const nameWidth = Math.max(...[...allSkillNames, ...allToolNames].map(n => n.length))
+
   // ── skill ── 分组
   for (const [bundleName, skills] of Object.entries(bundleSkills)) {
     choices.push({ type: 'separator', separator: `── ${bundleName} ──` })
     for (const skill of skills) {
       const skillName = skill.path.split('/').pop()
+      const srcPath   = path.join(skillsRoot, skill.path)
+      const version   = readVersion(srcPath)
       choices.push({
-        name: skillName,
-        value: { kind: 'skill', skillName, srcPath: path.join(skillsRoot, skill.path) },
+        name:  formatChoice(skillName, version, nameWidth),
+        value: { kind: 'skill', skillName, srcPath },
       })
     }
   }
@@ -74,20 +100,90 @@ export function buildAllChoices() {
 
 // 所有 skill 展开为 { kind:'skill', skillName, srcPath } 列表（对应 all 选项）
 export function getAllSkillItems() {
-  return skillDefs.map(skill => ({
-    kind: 'skill',
-    skillName: skill.path.split('/').pop(),
-    srcPath: path.join(skillsRoot, skill.path),
-  }))
+  return skillDefs.map(skill => {
+    const srcPath = path.join(skillsRoot, skill.path)
+    return {
+      kind: 'skill',
+      skillName: skill.path.split('/').pop(),
+      srcPath,
+      version: readVersion(srcPath),
+    }
+  })
 }
 
-// 所有 tool 展开为 { kind:'tool', toolName, srcPath } 列表
+// 所有 tool 展开为 { kind:'tool', toolName, srcPath, version } 列表
 export function getAllToolItems() {
-  return toolDefs.map(tool => ({
-    kind: 'tool',
-    toolName: tool.name,
-    srcPath: path.join(repoRoot, 'tools', tool.name),
-  }))
+  return toolDefs.map(tool => {
+    const srcPath = path.join(repoRoot, 'tools', tool.name)
+    return {
+      kind: 'tool',
+      toolName: tool.name,
+      srcPath,
+      version: readToolMeta(path.join(srcPath, 'tool.json')),
+    }
+  })
+}
+
+// 检查某个 skill 在 user/project 级别每个工具的安装状态
+// 返回 { user: { claude, cursor, codex }, project: { claude, cursor, codex } }
+// 每个工具: { version: string, status: 'up-to-date'|'update'|'none' }
+export function checkInstalled(skillName, availableVersion) {
+  const home = os.homedir()
+  const targets = ['claude', 'cursor', 'codex']
+
+  function checkScope(dirFn) {
+    const result = {}
+    for (const t of targets) {
+      const skillPath = path.join(dirFn(t), skillName)
+      const version = readVersion(skillPath)
+      const status = version === '—' ? 'none'
+        : version === availableVersion ? 'up-to-date'
+        : 'update'
+      result[t] = { version, status }
+    }
+    return result
+  }
+
+  const cwd = process.cwd()
+  const noneScope = Object.fromEntries(targets.map(t => [t, { version: '—', status: 'none' }]))
+
+  return {
+    user:    checkScope(t => path.join(home, `.${t}`, 'skills')),
+    project: cwd === home ? noneScope : checkScope(t => path.join(cwd, `.${t}`, 'skills')),
+  }
+}
+
+// 将 scope detail 聚合为单一摘要状态
+export function scopeSummary(scopeDetail) {
+  const statuses = Object.values(scopeDetail).map(t => t.status)
+  if (statuses.some(s => s === 'update'))     return 'update'
+  if (statuses.some(s => s === 'up-to-date')) return 'up-to-date'
+  return 'none'
+}
+
+export { formatChoice, readVersion }
+
+const HSKILL_TOOLS_DATA = path.join(os.homedir(), '.local', 'share', 'hskill', 'tools')
+
+function readToolMeta(jsonPath) {
+  try {
+    const data = JSON.parse(fs.readFileSync(jsonPath, 'utf8'))
+    return data.version ?? '—'
+  } catch { return '—' }
+}
+
+// 检测工具安装状态：binary 存在于 ~/.local/bin，版本从安装时写入的 data JSON 读取
+export function checkToolInstalled(toolName, srcPath) {
+  const installedBin  = path.join(os.homedir(), '.local', 'bin', toolName)
+  const installedMeta = path.join(HSKILL_TOOLS_DATA, `${toolName}.json`)
+  try {
+    if (!fs.existsSync(installedBin)) return { version: '—', status: 'none' }
+    const installedVersion = readToolMeta(installedMeta)
+    const sourceVersion    = readToolMeta(path.join(srcPath, 'tool.json'))
+    const status = installedVersion === '—' || sourceVersion === '—' || installedVersion === sourceVersion
+      ? 'up-to-date' : 'update'
+    return { version: installedVersion, status }
+  } catch { return { version: '—', status: 'none' } }
 }
 
 // ── Tools ────────────────────────────────────────────────────────────────────

package/lib/installer.js

@@ -69,6 +69,14 @@ export async function installTools(tools, targetDir, force = false) {
       }
       const content = await fs.readFile(scriptSrc, 'utf-8')
       await fs.writeFile(destPath, substituteVars(content, varsMap), { encoding: 'utf-8', mode: 0o755 })
+
+      const toolJsonSrc = path.join(srcPath, 'tool.json')
+      if (await fs.pathExists(toolJsonSrc)) {
+        const dataDir = path.join(os.homedir(), '.local', 'share', 'hskill', 'tools')
+        await fs.ensureDir(dataDir)
+        await fs.copy(toolJsonSrc, path.join(dataDir, `${toolName}.json`))
+      }
+
       installed.push(toolName)
       await _patchZshrc(srcPath, toolName)
     } catch (err) {

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "harveyz-skill",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Skill manager for Claude Code, Cursor, and Codex",
   "type": "module",
   "bin": {
     "hskill": "bin/cli.js"
   },
   "scripts": {
-    "prepack": "node scripts/generate-npmignore.js"
+    "prepack": "node scripts/generate-npmignore.js",
+    "test": "bats tests/ tools/p-launch/tests/"
   },
   "files": [
     "bin/",
@@ -16,6 +17,7 @@
     "skills-index.json",
     "skills/analysis/skill-analyzer/CHANGELOG.md",
     "skills/analysis/skill-analyzer/SKILL.md",
+    "skills/analysis/skill-analyzer/references/",
     "skills/harness/diataxis-docs/",
     "skills/harness/full-stack-debug-env/",
     "skills/superpowers-fork/brainstorming/",

package/skills/analysis/skill-analyzer/CHANGELOG.md

@@ -1,5 +1,22 @@
 # CHANGELOG — skill-analyzer
 
+## v1.0.0 (2026-05-12)
+
+**基于：** v0.9 + 结构性重构
+
+### 主要变更
+
+- 补全 YAML frontmatter（新增 `name`、`description`、`user_invocable`、`version` 字段）
+- 新增 `references/` 目录，抽象三份模版：
+  - `prohibitions.md` — 完整 23 条禁忌（原 SKILL.md 仅保留第 23 条）
+  - `output-template.md` — 分析报告骨架模版
+  - `evaluation-template.md` — 评估报告骨架模版
+- SKILL.md 中 `禁忌` / `输出格式` / `Layer 1-4` 三个 section 改为引用 references
+- 新增 `输出路径` 规范：输出文件保存在被分析项目根目录 `skill-analysis/` 下
+- 删除 `research/` 目录（历史实验产物，路径不符合输出规范）
+
+---
+
 ## v0.7 (2026-03-28)
 
 **基于：** v0.6 + 第5轮评估反馈

package/skills/analysis/skill-analyzer/SKILL.md

@@ -1,8 +1,15 @@
+---
+name: skill-analyzer
+description: "对 Skill 仓库进行系统性分析。触发词：分析这个 skill 仓库、对这个 skill 仓库做系统性研究、输出 skill 仓库的分析报告、理解这个 skill 系统的设计意图"
+user_invocable: true
+version: "1.0.0"
+---
+
 # SKILL.md — skill-analyzer
 
-> **版本：** v0.9
-> **版本日期：** 2026-03-28
-> **基于：** v0.8 + 第7轮评估反馈
+> **版本：** v1.0.0
+> **版本日期：** 2026-05-12
+> **基于：** v0.9 + 结构性重构
 > **定位：** 对 Skill 仓库进行系统性分析的工具 Skill
 
 ---
@@ -111,40 +118,44 @@ cso, review, ship
 
 ---
 
-## Layer 1-4
+## Layer 1-4 执行指南
 
-按照洋葱模型框架执行。
+按洋葱模型从内到外逐层分析：
 
----
+- **Layer 1 — 设计意图（哲学视角）：** 读 ETHOS.md / ARCHITECTURE.md / README 等哲学文档，提炼系统定位和核心设计原则
+- **Layer 2 — 组件目录（结构视角）：** 实际运行命令列出所有目录和文件，统计各目录文件数，逐目录列清单，不能估算
+- **Layer 3 — 交互关系（系统视角）：** 识别三类关系（自动触发 / 建议序列 / 前置配置），分析 `allowed-tools` 权限矩阵（必须从实际 SKILL.md 读取）
+- **Layer 4 — 使用场景（用户视角）：** 提炼 3-5 个典型工作流场景，列出降级矩阵
 
-## 输出格式
+报告结构详见 → `references/output-template.md`
 
-```markdown
-# {仓库名} 系统分析报告
+---
 
-## 元信息
-- 分析版本：
-- 项目类型：
-- VERSION / package.json / CHANGELOG：
-- 版本根因分析：
+## 输出路径
 
-## 1-6. 各层分析
-...
+所有输出文件保存在**被分析项目的根目录**下，新建 `skill-analysis/` 目录：
 
-## 附录
-### 幽灵文件列表（如有）
-### allowed-tools 完整读取记录
-（每个 skill：工具数 + 具体工具名称）
 ```
+{被分析项目根目录}/
+└── skill-analysis/
+    ├── analysis/
+    │   └── {YYYY-MM-DD}-{仓库名}-report.md    # 分析报告
+    └── evaluation/
+        └── {YYYY-MM-DD}-{仓库名}-eval.md       # 评估报告（如有）
+```
+
+不得将输出文件保存在 skill 自身目录下。
+
+## 输出格式
+
+使用 `references/output-template.md` 中的结构填写报告，所有占位符替换为实际内容。
 
 ---
 
 ## 禁忌（共 23 条）
 
-1-22 条沿用 v0.8（略）
-
-**23. ❌ WebSearch 数量必须为 12 个（不是16！）。benchmark/canary/document-release/setup-deploy 均不含 WebSearch。browse/test/ = 18（不是11）。bin/ + browse/bin/ = 19（不是20）。**  ← 新增
+**执行前必须读取 `references/prohibitions.md`**，每条禁忌均来自真实迭代中发现的系统性错误。
 
 ---
 
-*skill-analyzer v0.9 | 2026-03-28*
+*skill-analyzer v1.0.0 | 2026-05-12*

package/skills/analysis/skill-analyzer/references/evaluation-template.md

@@ -0,0 +1,58 @@
+# 评估报告模版
+
+> 用于评估分析报告的质量。评估者对照源码逐项核实，填写此模版。
+> 保存路径：`{被分析项目根目录}/skill-analysis/evaluation/{YYYY-MM-DD}-{仓库名}-eval.md`
+
+---
+
+```markdown
+# 评估报告
+
+**评估对象：** `{分析报告文件名}`
+**源码仓库：** `{仓库路径}`
+**评估时间：** {YYYY-MM-DD}
+**对应 skill 版本：** {版本号}
+
+---
+
+## 遗漏项
+
+### {问题名称}（严重程度：高/中/低）
+
+**现象：** {报告中写了什么}
+**实际：** {源码中的真实情况}
+**影响：** {如果依据此报告会导致什么错误}
+
+---
+
+## 理解偏差
+
+### {偏差描述}
+
+**报告表述：** {引用原文}
+**源码验证：** {实际结果}
+**结论：** {是报告理解错误，还是源码本身有问题}
+
+---
+
+## 评估者无法理解的点
+
+### {问题}
+
+{描述无法理解的设计决策或代码现象，供后续向 maintainer 确认}
+
+---
+
+## 总结评分
+
+| 维度 | 评级 | 说明 |
+|------|------|------|
+| 版本信息核实 | ✅/⚠️/❌ | {说明} |
+| 文件数量准确性 | ✅/⚠️/❌ | {说明} |
+| 目录覆盖完整性 | ✅/⚠️/❌ | {说明} |
+| 幽灵文件检查 | ✅/⚠️/❌ | {说明} |
+| allowed-tools 准确性 | ✅/⚠️/❌ | {说明} |
+| 关系类型描述 | ✅/⚠️/❌ | {说明} |
+
+**综合结论：** {是否达到发布标准，需要哪些修正}
+```

package/skills/analysis/skill-analyzer/references/output-template.md

@@ -0,0 +1,153 @@
+# 分析报告输出模版
+
+> 使用此模版填写最终报告。所有 `{占位符}` 必须替换为实际内容。
+> 保存路径：`{被分析项目根目录}/skill-analysis/analysis/{YYYY-MM-DD}-{仓库名}-report.md`
+
+---
+
+```markdown
+# {仓库名} 系统分析报告
+
+## 元信息
+
+- **分析版本：** skill-analyzer {版本号}
+- **分析时间：** {YYYY-MM-DD}
+- **仓库路径：** `{路径}`
+- **VERSION 文件：** `{版本号}`
+- **package.json version：** `{版本号}`
+- **CHANGELOG 最新版本：** `{版本号}`
+- **HEAD commit：** `{hash}`
+
+> ⚠️ **版本一致性：** {描述三者是否一致，若不一致说明根因}
+
+---
+
+## 1. 设计意图（Layer 1）
+
+### 系统定位
+
+{用一句话概括：这个仓库是什么，核心资产是什么}
+
+### 哲学文档
+
+- {列出 ETHOS.md / ARCHITECTURE.md / DESIGN.md 等，说明是否存在}
+
+### 核心设计原则
+
+| 原则 | 含义 |
+|------|------|
+| {原则名} | {解释} |
+
+---
+
+## 2. 目录结构（Layer 2）
+
+```
+{仓库名}/
+├── {文件或目录}     # {说明}
+├── ...
+```
+
+### 幽灵文件检查
+
+{列出所有标注存在但实际不符预期的文件/目录，若无则写"无幽灵文件"}
+
+---
+
+## 3. 组件清单（Layer 2 详细）
+
+### 3.1 核心组件统计（实际计数）
+
+{根据仓库类型列出核心组件，如 skill 仓库列出所有 SKILL.md 目录}
+
+| # | 名称 | 路径 | 类型/层级 | 功能定位 |
+|---|------|------|---------|---------|
+| 1 | {名称} | {路径} | {类型} | {功能} |
+
+### 3.2 工具权限矩阵（如适用）
+
+{如果是 skill 仓库，列出每个 skill 的 allowed-tools，数据必须从实际文件读取}
+
+| Skill | Bash | Read | Write | Edit | Glob | Grep | Agent | AskUserQ | WebSearch |
+|-------|------|------|-------|------|------|------|-------|---------|-----------|
+
+### 3.3 模版文件（如适用）
+
+{列出所有 .tmpl 文件，说明其与生成产物的关系}
+
+### 3.4 关键目录文件清单
+
+{对每个重要目录，逐一列出实际文件，不能只报总数}
+
+---
+
+## 4. 交互关系（Layer 3）
+
+### 类型 1：自动触发（确定性）
+
+| 关系 | 说明 |
+|------|------|
+| {触发方} → {被触发方} | {说明} |
+
+### 类型 2：建议序列（推荐顺序）
+
+| 关系 | 说明 |
+|------|------|
+| {步骤序列} | {说明} |
+
+### 类型 3：前置配置（运行时依赖）
+
+| 关系 | 说明 |
+|------|------|
+| {依赖项} | {缺少时的影响} |
+
+---
+
+## 5. 构建流水线（如适用）
+
+```
+{源文件} → [{构建工具}] → {产物}
+```
+
+{说明 CI 如何保障构建产物与源文件一致}
+
+---
+
+## 6. 使用场景（Layer 4）
+
+### 典型场景
+
+#### 场景 A：{场景名}（{频率}）
+
+```
+{用户输入} → {步骤1} → {步骤2} → {结果}
+```
+
+**覆盖组件：** {组件列表}
+
+### 降级场景矩阵
+
+| 组件不可用 | 降级行为 |
+|-----------|---------|
+| {组件} | {降级方式} |
+
+---
+
+## 附录
+
+### 幽灵文件列表
+
+| 文件路径 | 状态 | 说明 |
+|---------|------|------|
+| {路径} | {✅/⚠️/❌} | {说明} |
+
+### 版本信息不一致分析（如存在）
+
+| 来源 | 版本号 | 说明 |
+|------|-------|------|
+| VERSION 文件 | {版本} | {说明} |
+| package.json | {版本} | {说明} |
+| CHANGELOG | {版本} | {说明} |
+
+**根因：** {推断原因}
+```

package/skills/analysis/skill-analyzer/references/prohibitions.md

@@ -0,0 +1,27 @@
+# 禁忌清单（共 23 条）
+
+> 每条禁忌均来自真实迭代中发现的系统性错误，不得违反。
+
+1. ❌ 不能只统计 skill 数量，必须列出完整文件清单
+2. ❌ 不能忽略 `.tmpl` 文件的 auto-generate 机制
+3. ❌ 不能混淆 CLI 子项目（如 browse/）和普通 skill
+4. ❌ 不能混用三种关系类型（自动触发 / 建议序列 / 前置配置）
+5. ❌ 不能遗漏版本信息（VERSION 文件、package.json、CHANGELOG 三者都要检查）
+6. ❌ 不能估算文件数量，必须实际运行命令计数
+7. ❌ 不能忽略 `extension/`、`lib/`、`docs/`、`.github/` 等辅助目录
+8. ❌ 不能遗漏 CI workflow（`.github/workflows/` 必须列出）
+9. ❌ `allowed-tools` 描述不能与表格数据矛盾
+10. ❌ 每个列出的文件必须验证其确实存在，不得推断
+11. ❌ `allowed-tools` 必须从实际 `SKILL.md` 文件读取，不得从 `.tmpl` 推断
+12. ❌ 不得将 `browse/bin/` 与根目录 `bin/` 混淆，两者必须明确区分
+13. ❌ 不得假设每个 skill 都有独立的 `.tmpl` 文件（通常只有少数 skill 有）
+14. ❌ 不得在未完成项目类型检测的情况下假设目标是 skill 仓库
+15. ❌ 非 skill 仓库缺失 `SKILL.md` 等文件不算幽灵文件，属于正常
+16. ❌ ML 项目必须覆盖关键实现细节（模型结构、训练逻辑等），不能套用 skill 仓库框架
+17. ❌ 每个目录必须列出实际文件清单，不能只报总数
+18. ❌ 独立 `.tmpl` 数量必须实际统计，不得假设与 skill 数量一致
+19. ❌ 版本号不一致时必须探讨根因（为什么三者不同步），不能只记录数字
+20. ❌ `allowed-tools` 数据必须从实际文件读取，不得凭记忆或推断伪造
+21. ❌ 不存在"双 `allowed-tools` 块"的合理说法，如发现应标记为异常
+22. ❌ `WebSearch` 必须完整计入工具数；注意 `unfreeze` 只有 2 个工具；`gstack-upgrade` 版本为 v1.1.0
+23. ❌ 以下数量为已验证的正确值，报告时必须与实际计数一致，不得凭记忆填写旧值

package/skills/harness/diataxis-docs/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: diataxis-docs
+version: "1.0.0"
 description: Use when creating, updating, or deleting any file under docs/ — including writing a new guide, updating reference content, adding an ADR, or removing an outdated page. Also use when searching docs before writing, to avoid duplicating existing content.
 ---
 

package/skills/harness/full-stack-debug-env/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: full-stack-debug-env
+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
 ---
 

package/skills/task/pm-task-dispatch/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: pm-task-dispatch
+version: "1.0.0"
 description: PM 任务派发技能。当需要创建新任务并派发给其他 Agent 时触发。流程：理解任务 → 需求澄清 → 分析细化 → 创建任务文档 → sessions_send 派发 → 追踪反馈。触发场景包括：（1）Harvey 提出新任务需求，（2）要求向特定 Agent 分派任务，（3）询问任务如何派发。
 ---
 

package/skills/task/task-close/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: task-close
+version: "1.0.0"
 description: 任务收尾技能。当 Agent 完成接受的任务后自触发，执行任务验收、总结、文档归档和问题记录。触发条件：Agent 已实际完成任务，需要进行收尾工作时使用。
 ---
 

package/skills/web-fetch/article-fetcher/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: article-fetcher
+version: "1.0.0"
 description: "Use for the fetch-URL → translate → save-to-Obsidian workflow. Trigger whenever a user has a web URL (article, blog post, tweet, newsletter) and wants it fetched, translated into Chinese, and saved locally — even if they say it obliquely (e.g. \"存到 obsidian\", \"抓取\", \"save this\", \"translate and archive\"). Handles single URLs and batch lists, and X.com / Twitter (Playwright + Chrome Profile). Skip only if: no URL is present (user pasting raw text to translate), user wants a summary without archiving, or user is asking about a site's tech stack without wanting to save anything."
 ---
 

package/tools/p-launch/tool.json

@@ -0,0 +1 @@
+{ "name": "p-launch", "version": "1.0.0" }