harveyz-skill 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# Harvey Skills
+
+Harvey 的个人 Claude Code 技能仓库。
+
+## 技能清单
+
+| 技能 | 说明 | 外部依赖 |
+|------|------|---------|
+| **harvey-plain** | 白话引擎 — 把任何内容改写到聪明的十二岁小孩也能懂 | 无 |
+| **skill-analyzer** | 系统化分析 Skill 仓库的框架，基于洋葱模型四层结构 | 无 |
+
+> 更多技能陆续添加中。
+
+## 安装
+
+### 全部安装
+
+```bash
+mkdir -p ~/.claude/skills
+cp -r skills/* ~/.claude/skills/
+```
+
+### 安装依赖（如有）
+
+```bash
+bash scripts/install.sh
+```
+
+## 工作流
+
+```
+harvey-plain: 内容 → org-mode 文件（~/Documents/notes/）
+```
+
+## Skill 开发指南
+
+### 命名规范
+
+- 前缀：`harvey-`（例：`harvey-plain`、`harvey-card`）
+- 每个 skill 独立目录，`SKILL.md` 是唯一入口
+
+### SKILL.md 格式
+
+```yaml
+---
+name: skill-name
+description: "做什么。触发词..."
+user_invocable: true
+version: "x.x.x"
+---
+```
+
+### 共享规范
+
+**Org-mode 输出：**
+- 加粗：`*text*`（单星号）
+- 文件名：`{时间戳}--{标题}__{type}.org`
+- 输出目录：`~/Documents/notes/`
+- 时间戳：`date +%Y%m%dT%H%M%S`
+
+**ASCII Art：**
+- 允许：`+ - | / \ > < v ^ * = ~ . : # [ ] ( ) _ , ; ! ' "`
+- 禁止：Unicode 绘图符号
+
+## 许可证
+
+Private — 仅供个人使用。

package/bin/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { checkbox } from '@inquirer/prompts'
+import chalk from 'chalk'
+import { BUNDLE_CHOICES, resolveSkills } from '../lib/bundles.js'
+import { TARGET_CHOICES, resolveTargets, TARGETS } from '../lib/targets.js'
+import { installSkills } from '../lib/installer.js'
+
+const args = process.argv.slice(2)
+const forceFlag = args.includes('--force')
+const bundleIdx = args.indexOf('--bundle')
+const targetIdx = args.indexOf('--target')
+const bundleArg = bundleIdx !== -1 ? args[bundleIdx + 1] : undefined
+const targetArg = targetIdx !== -1 ? args[targetIdx + 1] : undefined
+
+// list 子命令
+if (args[0] === 'list') {
+  const { createRequire } = await import('module')
+  const require = createRequire(import.meta.url)
+  const bundles = require('../bundles.json')
+  for (const b of bundles) {
+    console.log(chalk.bold(b.name) + ' — ' + b.description)
+    if (b.skills) for (const s of b.skills) console.log('  ' + s)
+  }
+  process.exit(0)
+}
+
+try {
+  // 解析 bundle 选择
+  let selectedBundles
+  if (bundleArg) {
+    selectedBundles = bundleArg.split(',').map(s => s.trim()).filter(Boolean)
+  } else {
+    selectedBundles = await checkbox({
+      message: '选择要安装的 bundle（空格多选）:',
+      choices: BUNDLE_CHOICES,
+    })
+  }
+
+  if (!selectedBundles.length) {
+    console.log(chalk.red('未选择任何 bundle，退出。'))
+    process.exit(1)
+  }
+
+  // 解析 target 选择
+  let selectedTargets
+  if (targetArg) {
+    selectedTargets = targetArg === 'all' ? Object.keys(TARGETS) : [targetArg]
+  } else {
+    selectedTargets = await checkbox({
+      message: '安装到哪些工具（空格多选）:',
+      choices: [
+        ...TARGET_CHOICES,
+        { name: 'all      — 全部工具', value: 'all' },
+      ],
+    })
+  }
+
+  if (!selectedTargets.length) {
+    console.log(chalk.red('未选择任何目标工具，退出。'))
+    process.exit(1)
+  }
+
+  const skills = resolveSkills(selectedBundles)
+  const targets = resolveTargets(selectedTargets)
+
+  console.log('')
+  const summary = await installSkills(skills, targets, forceFlag)
+
+  console.log('')
+  if (Object.keys(summary).length === 0) {
+    console.log(chalk.yellow('  没有 skill 被安装。'))
+  } else {
+    console.log(chalk.green('✔ 安装完成：'))
+    for (const [target, names] of Object.entries(summary)) {
+      console.log(`  ${chalk.bold(target)} ← ${names.join(', ')}`)
+    }
+  }
+} catch (err) {
+  console.error(chalk.red('Error: ' + err.message))
+  process.exit(1)
+}

package/bundles.json

@@ -0,0 +1,24 @@
+[
+  {
+    "name": "brainstorming",
+    "description": "设计与规划工具（brainstorming + writing-plans）",
+    "skills": [
+      "superpowers-fork/brainstorming",
+      "superpowers-fork/writing-plans"
+    ]
+  },
+  {
+    "name": "dev",
+    "description": "开发工作流（executing-plans + systematic-debugging + using-git-worktrees）",
+    "skills": [
+      "superpowers-fork/executing-plans",
+      "superpowers-fork/systematic-debugging",
+      "superpowers-fork/using-git-worktrees"
+    ]
+  },
+  {
+    "name": "all",
+    "description": "全部 skill",
+    "dynamic": true
+  }
+]

package/lib/bundles.js

@@ -0,0 +1,39 @@
+import { createRequire } from 'module'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const require = createRequire(import.meta.url)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const bundleDefs = require('../bundles.json')
+const skillsRoot = path.join(__dirname, '..', 'skills')
+
+export const BUNDLE_CHOICES = bundleDefs.map(b => ({
+  name: `${b.name.padEnd(16)} — ${b.description}`,
+  value: b.name,
+}))
+
+// 返回选中 bundles 对应的去重 skill 路径列表 { skillName, srcPath }
+export function resolveSkills(selectedBundles) {
+  // 展开 dynamic bundle（all）为所有非 dynamic bundle 的 union
+  const expanded = selectedBundles.flatMap(name => {
+    const def = bundleDefs.find(b => b.name === name)
+    if (!def) throw new Error(`Unknown bundle: "${name}"`)
+    if (def.dynamic) return bundleDefs.filter(b => !b.dynamic).map(b => b.name)
+    return name
+  })
+
+  const seen = new Set()
+  const result = []
+  for (const name of expanded) {
+    const def = bundleDefs.find(b => b.name === name)
+    if (!def) continue
+    for (const rel of def.skills) {
+      if (seen.has(rel)) continue
+      seen.add(rel)
+      const skillName = rel.split('/').pop()
+      result.push({ skillName, srcPath: path.join(skillsRoot, rel) })
+    }
+  }
+  return result
+}

package/lib/installer.js

@@ -0,0 +1,46 @@
+import fs from 'fs-extra'
+import path from 'path'
+import { confirm } from '@inquirer/prompts'
+import chalk from 'chalk'
+
+// skills: [{ skillName, srcPath }]
+// targets: [{ name, dir }]
+// force: boolean
+export async function installSkills(skills, targets, force = false) {
+  const summary = {}
+
+  for (const { name: targetName, dir: targetDir } of targets) {
+    const exists = await fs.pathExists(targetDir)
+    if (!exists) {
+      console.log(chalk.yellow(`  跳过 ${targetName}（目录不存在：${targetDir}）`))
+      continue
+    }
+
+    const installed = []
+    for (const { skillName, srcPath } of skills) {
+      const destPath = path.join(targetDir, skillName)
+      const destExists = await fs.pathExists(destPath)
+
+      if (destExists && !force) {
+        const ok = await confirm({ message: `${targetName}/${skillName} 已存在，覆盖？`, default: false })
+        if (!ok) {
+          console.log(chalk.gray(`  跳过 ${targetName}/${skillName}`))
+          continue
+        }
+      }
+
+      try {
+        await fs.copy(srcPath, destPath, { overwrite: true })
+        installed.push(skillName)
+      } catch (err) {
+        console.log(chalk.red(`  复制失败 ${targetName}/${skillName}: ${err.message}`))
+      }
+    }
+
+    if (installed.length > 0) {
+      summary[targetName] = installed
+    }
+  }
+
+  return summary
+}

package/lib/targets.js

@@ -0,0 +1,23 @@
+import os from 'os'
+import path from 'path'
+
+export const TARGETS = {
+  claude: path.join(os.homedir(), '.claude', 'skills'),
+  cursor: path.join(os.homedir(), '.cursor', 'skills'),
+  codex: path.join(os.homedir(), '.codex', 'skills'),
+}
+
+export const TARGET_CHOICES = Object.entries(TARGETS).map(([name, dir]) => ({
+  name: `${name.padEnd(8)} (${dir})`,
+  value: name,
+}))
+
+// 返回选中 targets 的 { name, dir } 列表，all 展开为全部
+export function resolveTargets(selected) {
+  if (selected.includes('all')) return Object.entries(TARGETS).map(([name, dir]) => ({ name, dir }))
+  return selected.map(name => {
+    const dir = TARGETS[name]
+    if (!dir) throw new Error(`Unknown target: "${name}"`)
+    return { name, dir }
+  })
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "harveyz-skill",
+  "version": "0.1.0",
+  "description": "One-click skill installer for Claude Code, Cursor, and Codex",
+  "type": "module",
+  "bin": {
+    "harveyz-skill": "bin/cli.js"
+  },
+  "scripts": {
+    "prepack": "node scripts/generate-npmignore.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "bundles.json",
+    "skills/analysis/skill-analyzer/CHANGELOG.md",
+    "skills/analysis/skill-analyzer/SKILL.md",
+    "skills/document/diataxis-docs/",
+    "skills/harness/full-stack-debug-env/",
+    "skills/superpowers-fork/brainstorming/",
+    "skills/superpowers-fork/executing-plans/",
+    "skills/superpowers-fork/systematic-debugging/",
+    "skills/superpowers-fork/using-git-worktrees/",
+    "skills/superpowers-fork/writing-plans/",
+    "skills/task/pm-task-dispatch/",
+    "skills/task/task-close/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.4.2",
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0"
+  },
+  "author": "harveyzhang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harveyzhang814/harveyz-skill.git"
+  },
+  "license": "MIT"
+}

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

@@ -0,0 +1,78 @@
+# CHANGELOG — skill-analyzer
+
+## v0.7 (2026-03-28)
+
+**基于：** v0.6 + 第5轮评估反馈
+
+### 核心修复：删除所有"双 allowed-tools 块"相关内容（禁忌 21）
+
+**问题：** 第4轮和第5轮分析报告仍然描述"双 allowed-tools 块"，但经人工源码核查验证：
+- **每个 skill 只有 1 个 `allowed-tools` YAML 块**
+- `---` 是 frontmatter 分隔符，不是"第二个块"
+- `<!-- AUTO-GENERATED -->` 是 HTML 注释，与 allowed-tools 无关
+- `# zsh-compatible` 是 bash 脚本注释，与 allowed-tools 无关
+- 所有 skill 的 `grep "allowed-tools"` 返回值均为 **1**
+
+"双块一致性验证"是两个错误数据互验的伪命题。
+
+**修复：**
+- 禁忌 21：明确不存在"双块"，删除所有相关描述
+- 新增概念澄清：YAML frontmatter 结构说明
+- 提供正确读取命令：`grep "allowed-tools"` 返回值应为 1
+
+---
+
+## v0.6 (2026-03-27)
+
+**基于：** v0.5 + 第4轮评估反馈
+
+### 禁止伪造 allowed-tools 数据（禁忌 20）
+
+**问题：** v0.5 分析报告大量伪造数据（browse 报8个，实际3个；捏造10个双块等）
+
+**修复：**
+- 必须从实际文件读取 allowed-tools
+- 提供已知基准数据交叉验证
+- 禁忌 20
+
+---
+
+## v0.5 (2026-03-27)
+
+**基于：** v0.4 + 第3轮评估反馈
+
+### 文件清单必须逐项列出（禁忌 17-19）
+
+- lib/ 实际只有 worktree.ts
+- 独立 .tmpl 实际有 29 个
+- 版本根因必须探讨
+
+---
+
+## v0.4 (2026-03-27)
+
+**基于：** v0.3 + 第2轮评估反馈
+
+### 项目类型检测机制（禁忌 14-15）
+
+---
+
+## v0.3 (2026-03-27)
+
+**基于：** v0.2 + 第1轮评估反馈
+
+### allowed-tools 验证机制（禁忌 11-13）
+
+---
+
+## v0.2 (2026-03-27)
+
+**基于：** v0.1-baseline
+
+### 必检清单（VERSION、数量、Ghost、CI）
+
+---
+
+## v0.1-baseline (2026-03-27)
+
+初始版本：洋葱模型四层框架

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

@@ -0,0 +1,150 @@
+# SKILL.md — skill-analyzer
+
+> **版本：** v0.9
+> **版本日期：** 2026-03-28
+> **基于：** v0.8 + 第7轮评估反馈
+> **定位：** 对 Skill 仓库进行系统性分析的工具 Skill
+
+---
+
+## 触发条件
+
+当用户提供以下任意表述时触发本 Skill：
+- "分析这个 skill 仓库"
+- "对这个 skill 仓库做系统性研究"
+- "输出 skill 仓库的分析报告"
+- "理解这个 skill 系统的设计意图"
+
+---
+
+## ⚠️ 第一步：项目类型检测
+
+1. 检查是否存在 `SKILL.md` 或 `SKILL.md.tmpl` → 有则继续
+2. 检查是否存在 `program.md` 或 ML 关键词 → 非 skill 仓库
+3. 项目类型分类：Skill 仓库 / ML项目 / CLI工具 / 未知
+
+---
+
+## 分析框架：洋葱模型（四层）
+
+```
+┌─────────────────────────────────────────┐
+│  Layer 4：使用场景（用户视角）              │
+├─────────────────────────────────────────┤
+│  Layer 3：交互关系（系统视角）              │
+├─────────────────────────────────────────┤
+│  Layer 2：组件目录（结构视角）              │
+├─────────────────────────────────────────┤
+│  Layer 1：设计意图（哲学视角）              │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## ⚠️ 必检清单
+
+### 版本信息
+- [ ] VERSION 文件内容
+- [ ] package.json version
+- [ ] CHANGELOG 最新版本
+- [ ] 版本根因分析
+
+### 文件数量（必须实际计数）
+```bash
+ls ~/Repositories/gstack/bin/ | wc -l          # bin/ 文件数
+ls ~/Repositories/gstack/browse/bin/ | wc -l   # browse/bin/ 文件数
+ls ~/Repositories/gstack/browse/test/*.test.ts | wc -l  # browse/test/ .test.ts 数
+ls ~/Repositories/gstack/scripts/ | wc -l      # scripts/ 文件数
+ls ~/Repositories/gstack/scripts/resolvers/ | wc -l  # scripts/resolvers/ 文件数
+```
+
+**正确数量（必须全部记住）：**
+- **bin/ = 17**（不是20！）
+- **browse/bin/ = 2**（find-browse, remote-slug）
+- **bin/ + browse/bin/ 合计 = 19**
+- **browse/test/ = 18**（.test.ts 文件，不是11！）
+- **scripts/resolvers/ = 10**（含 index.ts）
+
+### 目录覆盖
+- [ ] 所有目录均列出实际文件清单
+
+### 独立 .tmpl 数量
+- [ ] 29 个（已验证）
+
+---
+
+## ⚠️ allowed-tools（最关键！）
+
+### 含 WebSearch 的 Skill（12个，不是16个！）
+
+**正确列表（12个）：**
+autoplan, cso, design-consultation, design-review, investigate, office-hours, plan-ceo-review, plan-eng-review, qa, qa-only, review, ship
+
+**不含 WebSearch 的 Skill（不要误列）：**
+- benchmark ❌（无 WebSearch）
+- canary ❌（无 WebSearch）
+- document-release ❌（无 WebSearch）
+- setup-deploy ❌（无 WebSearch，只有 Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion）
+
+### 正确工具数参考
+
+| Skill | 正确工具数 | 注意事项 |
+|-------|-----------|---------|
+| browse | 3 | Bash, Read, AskUserQuestion |
+| qa | 8 | 含 WebSearch，无 Agent |
+| review | 9 | 含 Agent 和 WebSearch |
+| ship | 9 | 含 Agent 和 WebSearch |
+| cso | 8 | 含 Agent 和 WebSearch |
+| office-hours | 8 | 含 WebSearch |
+| setup-browser-cookies | 3 | Bash, Read, AskUserQuestion |
+| **unfreeze** | **2** | Bash, Read |
+| setup-deploy | 7 | 无 WebSearch |
+| benchmark | — | 无 WebSearch |
+| canary | — | 无 WebSearch |
+| document-release | — | 无 WebSearch |
+
+### v0.1.0 skill（5个）
+careful, connect-chrome, freeze, guard, unfreeze
+
+### 含 Agent 的 skill（3个）
+cso, review, ship
+
+---
+
+## Layer 1-4
+
+按照洋葱模型框架执行。
+
+---
+
+## 输出格式
+
+```markdown
+# {仓库名} 系统分析报告
+
+## 元信息
+- 分析版本：
+- 项目类型：
+- VERSION / package.json / CHANGELOG：
+- 版本根因分析：
+
+## 1-6. 各层分析
+...
+
+## 附录
+### 幽灵文件列表（如有）
+### allowed-tools 完整读取记录
+（每个 skill：工具数 + 具体工具名称）
+```
+
+---
+
+## 禁忌（共 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）。**  ← 新增
+
+---
+
+*skill-analyzer v0.9 | 2026-03-28*