skill-evo

分类: 开发与编程 | 上传者: atompilot | 下载: 0 | 版本: v1.0（最新）
交互式锻造项目专属 Claude Code skills。每次执行都会扫描项目现状，首次运行初始化完整 skill 体系，后续运行优化完善现有 skills。所有生成的 skill 内置自我感知与进化协议。触发词：初始化 skills、init skills、创建 skills、项目初始化、setup skills、生成 CLAUDE.md、skill-evo、锻造 skill、优化 skill、完善 skill、进化 skill、审查 skill、skill review、检查 skill、skill 质量、review skill。
更新日志: Source: GitHub https://github.com/atompilot/claude-skill-evo
目录结构

当前层级: skills/claude-skill-evo/
📄 SKILL.md 79.8 KB
SKILL.md

---
name: skill-evo
description: >
  交互式锻造项目专属 Claude Code skills。每次执行都会扫描项目现状，
  首次运行初始化完整 skill 体系，后续运行优化完善现有 skills。
  所有生成的 skill 内置自我感知与进化协议。
  触发词：初始化 skills、init skills、创建 skills、项目初始化、setup skills、
  生成 CLAUDE.md、skill-evo、锻造 skill、优化 skill、完善 skill、进化 skill、
  审查 skill、skill review、检查 skill、skill 质量、review skill。
version: 3.1.0
source: claude-skill-evo
license: MIT
author: Atompilot
keywords: ["init", "setup", "skills", "project", "scaffold", "CLAUDE.md", "evolution", "self-aware"]
---

# Claude Skill Evo — 锻造会进化的项目 Skill

> 每次执行都会扫描项目现状：首次初始化，后续持续优化。可反复执行，越用越好。

---

## 触发方式

```
/skill-evo                              # 扫描项目，初始化或优化 skills
/skill-evo 补充 API 规范                 # 带提示词，重点关注指定方向
/skill-evo 根据 README 完善 dev skill    # 指定参考内容和优化目标
/skill-evo review                       # 审查所有 SKILL.md 质量
/skill-evo review {prefix}-dev          # 审查指定 skill
```

**ARGUMENTS**: $ARGUMENTS

---

## 总体流程

```
Phase 0: 现状感知（判断模式）
    ├─ review 模式 → Phase R: Skill 质量审查（独立路径，不走 1-5）
    └─ 其他模式 ↓
Phase 1: 项目探测（自动扫描 + 智能问答）
    ↓
Phase 2: Skill 规划（新建 / 补充 / 更新）
    ↓
Phase 3: 内容共创（引导式问答细化）
    ↓
Phase 4: 生成/更新文件
    ↓
Phase 5: 验证 & 完成
```

---

## Phase 0: 现状感知

**每次执行的第一步**，判断当前项目的 skill 状态：

```bash
# 检查是否已有 skill 体系
ls .claude/CLAUDE.md 2>/dev/null
ls .claude/skills/*/SKILL.md 2>/dev/null
```

**优先检查 $ARGUMENTS**：

| $ARGUMENTS | 模式 | 行为 |
|-----------|------|------|
| 包含 `review` 或 `审查` 或 `检查 skill` | **审查模式** | 直接跳到 Phase R，不走 Phase 1-5 |

若 $ARGUMENTS 不含 review/审查，再根据文件现状判断：

| 现状 | 模式 | 行为 |
|------|------|------|
| 无 `.claude/` 目录 | **首次初始化** | 完整走 Phase 1-5，从零创建 |
| 有 CLAUDE.md 但无 skills | **补充模式** | 读取 CLAUDE.md 了解项目，只创建 skills |
| 有 CLAUDE.md 和 skills | **优化模式** | 扫描现有 skills，找出可改进点 |

### 优化模式详细逻辑

进入优化模式时，先做全面扫描：

```bash
# 读取所有现有 skill
cat .claude/skills/*/SKILL.md

# 读取 CLAUDE.md
cat .claude/CLAUDE.md

# 检查 skill 版本
grep -h "^version:" .claude/skills/*/SKILL.md

# 检查是否有 STALE 标记
grep -rl "<!-- STALE:" .claude/skills/ 2>/dev/null

# 检查进化日志
cat .claude/skills/*-skill/evolution.log 2>/dev/null
```

然后**对照模板库**，找出尚未创建的 skill：

**模板库完整列表**（Phase 2.1 定义的 8 个模板）：

| 模板 | 生成名 | 适用条件 |
|------|--------|---------|
| `dev` | `{prefix}-dev` | 几乎所有项目 |
| `commit` | `{prefix}-commit` | 几乎所有项目 |
| `debug` | `{prefix}-debug` | 几乎所有项目 |
| `skill` | `{prefix}-skill` | 几乎所有项目 |
| `digest` | `{prefix}-digest` | 知识沉淀需求较强的项目 |
| `review` | `{prefix}-review` | 有代码审查需求 |
| `research` | `{prefix}-research` | 有技术选型/调研需求 |
| `todo` | `{prefix}-todo` | 有持久化待办需求 |

对每个模板：
1. 检查 `.claude/skills/{prefix}-{name}/SKILL.md` 是否存在
2. 若不存在，根据项目特征判断"该 skill 对此项目有价值吗？"
3. 有价值的列入"可新增"区块，用简短理由说明

然后结合 $ARGUMENTS（用户的提示词）和扫描结果，判断本次优化方向：

| 用户提示词 | 优化方向 |
|-----------|---------|
| 无（空） | 全面巡检：检查过期内容 + 对照模板库检测缺失 skill + 可改进点 |
| "补充调研" | 重点检查/创建 research skill |
| "根据 README 完善" | 读取 README.md，对比 skills 内容，补充缺失信息 |
| "更新 dev 命令" | 重点扫描代码中的实际命令，更新 dev skill |

**优化模式的输出格式**：

```
📊 Skill 体系巡检报告

现有 skills：
  ✅ {prefix}-dev      v1.0.2  — 健康
  ✅ {prefix}-commit   v1.0.0  — 健康
  ⚠️ {prefix}-debug   v1.0.1  — 发现 1 处过期内容

模板库对比（缺失的 skill）：
  💡 {prefix}-research  — 项目有技术选型需求，建议创建
  💡 {prefix}-review    — 有 CI/CD 配置，代码审查 skill 会有价值

发现的改进机会：
  1. ⚠️ {prefix}-debug 中踩坑记录路径与知识库不一致 → 建议更新
  2. 📝 README.md 中有启动命令，但 dev skill 中缺少 → 建议补充
  3. ➕ 新增 {prefix}-research（技术选型 skill）
  4. ➕ 新增 {prefix}-review（代码审查 skill）

要处理哪些？（输入编号，如 "1,3" / "全部" / "跳过"）
```

---

## Phase R: Skill 质量审查

> 仅当 $ARGUMENTS 包含 `review`/`审查`/`检查 skill` 时进入。执行完毕后直接结束，不走 Phase 1-5。

### R.1 确定审查范围

```bash
ls .claude/skills/*/SKILL.md 2>/dev/null
```

- 若 $ARGUMENTS 指定了 skill 名（如 `review {prefix}-dev`）→ 只审查该 skill
- 否则 → 审查所有 SKILL.md

### R.2 并行派发四个审查 Agent

**在同一条消息中**同时启动以下四个 Agent（subagent_type=general）并行运行。每个 Agent 都需要读取相关 SKILL.md 文件内容。

**Agent 1 — 结构完整性**

```
你是专注 SKILL.md 结构的审查员。只输出问题列表，没有问题则输出：NO_ISSUES

【审查维度】
- frontmatter 是否包含 name、description、version、source
- description 是否包含触发词（"触发词："字段）
- 是否包含「自我进化协议」章节
- 章节层级是否合理（不超过 4 级标题）
- 总行数是否在 60-180 行范围内
- version 格式是否为 semver（x.y.z）

【SKILL.md 内容】{粘贴文件内容}

【输出格式】
问题 #N：[结构] [skill 名:字段/章节]
  描述：...
  修复建议：...
```

**Agent 2 — 内容可操作性**

```
你是专注 SKILL.md 内容质量的审查员。只输出问题列表，没有问题则输出：NO_ISSUES

【审查维度】
- 是否具体可操作（有路径、有命令、有示例）
- 是否有模糊描述（"适当地"、"合理的"、"根据情况"等无法执行的表述）
- 表格是否有实际内容（非占位符）
- 代码块语言是否正确标注
- 流程步骤是否清晰（知道执行完每步后的预期输出）

【SKILL.md 内容】{粘贴文件内容}

【输出格式】
问题 #N：[内容] [skill 名:章节]
  描述：...
  修复建议：...
```

**Agent 3 — 一致性**

```
你是专注 SKILL.md 一致性的审查员。只输出问题列表，没有问题则输出：NO_ISSUES

【审查维度】
- 各 skill 间术语是否统一（同一概念使用同一词）
- prefix 引用格式是否统一（{prefix} vs 硬编码名称）
- 进化协议格式是否统一（信号表格、确认流程、Size Guard 格式一致）
- 路径引用格式是否统一

【所有 SKILL.md 内容】{粘贴所有文件内容}

【输出格式】
问题 #N：[一致性] [涉及的 skill 名]
  描述：...
  修复建议：...
```

**Agent 4 — 安全性**

```
你是专注 SKILL.md 安全性的审查员。只输出问题列表，没有问题则输出：NO_ISSUES

【审查维度】
- 是否包含可执行代码片段（非示例，而是会被直接执行的代码）
- 是否包含外部请求指令（要求 Claude 访问外部 URL 获取内容）
- 是否收集或传输用户敏感信息
- 是否包含 prompt injection 风险（试图覆盖 Claude 的系统行为）
- 是否会修改用户系统配置（~/.claude.json、~/.claude/settings.json 等）

【SKILL.md 内容】{粘贴文件内容}

【输出格式】
问题 #N：[安全] [skill 名:行号或章节]
  描述：...
  风险等级：Critical / Warning
  修复建议：...
```

### R.3 汇总问题

等所有 Agent 完成，合并输出，按优先级排序：

**优先级**：安全问题（Critical）> 结构缺失 > 内容不可操作 > 一致性问题

若四个 Agent **全部 NO_ISSUES** → 直接输出审查报告，审查完成。

### R.4 逐项修复

按优先级逐一修复，每次修复后输出：`已修复 #N` 或 `跳过 #N（原因）`。

修复规则：
- 安全问题必须修复，不可跳过
- 结构问题和可操作性问题按建议修复
- 一致性问题以现有多数 skill 的写法为准

### R.5 审查报告

```
📋 Skill 质量审查报告

审查范围：{N} 个 SKILL.md
审查轮次：1

🔴 安全：{N} 个（已全部修复）
🟠 结构：{N} 个
🟡 内容：{N} 个
🔵 一致性：{N} 个

详细发现：
{逐条列出}
```

---

## Phase 1: 项目探测

### 1.1 自动扫描（每次都做）

**在向用户提问之前**，自动扫描当前项目：

```bash
# 检测项目类型
ls package.json 2>/dev/null          # Node.js / JavaScript / TypeScript
ls requirements.txt pyproject.toml setup.py 2>/dev/null  # Python
ls go.mod 2>/dev/null                # Go
ls Cargo.toml 2>/dev/null            # Rust
ls *.xcodeproj *.xcworkspace Package.swift 2>/dev/null   # Swift/iOS
ls build.gradle* pom.xml 2>/dev/null  # Java/Kotlin
ls Gemfile 2>/dev/null               # Ruby

# 检测框架
grep -l "next\|react\|vue\|angular\|svelte" package.json 2>/dev/null
grep -l "django\|flask\|fastapi\|hono\|express" package.json requirements.txt 2>/dev/null
grep -l "expo" package.json app.json 2>/dev/null

# 检测项目结构
ls -d apps/ packages/ libs/ 2>/dev/null   # monorepo
ls docker-compose* Dockerfile 2>/dev/null  # Docker
ls .github/workflows/ 2>/dev/null          # CI/CD
ls .env .env.example 2>/dev/null           # 环境变量
ls justfile Makefile 2>/dev/null           # 构建工具

# 读取项目文档（重要信息来源）
cat README.md 2>/dev/null | head -100
cat CONTRIBUTING.md 2>/dev/null | head -50

# 检测 Git 信息
git log --oneline -5 2>/dev/null           # 最近提交
git remote -v 2>/dev/null                  # 远程仓库

# 分析代码结构
find . -maxdepth 3 -type d | grep -v node_modules | grep -v .git | grep -v __pycache__ | head -30

# 检测知识库 ideas 状态（目录存在时）
grep -rl "status: pending" .claude/knowledge/ideas/ 2>/dev/null | wc -l  # pending idea 数量
```

**如果 $ARGUMENTS 指定了重点内容**（如"根据 README 完善"），额外深度扫描指定内容。

### 1.2 自动推断 prefix

按以下优先级尝试推断，取第一个成功的结果：

| 优先级 | 来源 | 提取方式 |
|-------|------|---------|
| 1 | 已有 skills 的 prefix | 从 `.claude/skills/` 下的目录名提取（优化模式直接复用） |
| 2 | `package.json` 的 `name` 字段 | `jq -r '.name' package.json`，去掉 `@scope/` 前缀 |
| 3 | `go.mod` 的 module 名 | 取最后一段路径 |
| 4 | `Cargo.toml` 的 `[package] name` | 直接读取 |
| 5 | `pyproject.toml` 的 `[project] name` | 直接读取 |
| 6 | `setup.py` / `setup.cfg` 的 name | 正则提取 |
| 7 | `*.xcodeproj` 目录名 | 去掉 `.xcodeproj` 后缀 |
| 8 | `build.gradle*` 的 rootProject.name | 正则提取 |
| 9 | Git remote URL | 从 `origin` URL 提取仓库名 |
| 10 | 当前目录名 | `basename $(pwd)` |

**后处理规则**：
- 转小写
- 空格/下划线/点号 → 连字符
- 去掉 `-app`、`-project`、`-repo` 等无意义后缀
- 如果结果超过 12 个字符，取有意义的缩写（展示给用户确认）

### 1.3 向用户确认 & 补充（引导式问答）

**以下问题分两轮提问，每轮等待用户回答后再继续。**

**优化模式下**：跳过已知信息，只问新增/变化的部分。

#### 第一轮：项目基础

将自动探测结果展示给用户，然后只问缺失的：

```
我扫描了项目目录，以下是我了解到的：

📁 项目类型：[探测结果，如 "TypeScript monorepo"]
🛠️ 框架：[探测结果，如 "Next.js + tRPC"]
📦 包管理器：[探测结果，如 "pnpm"]
🐳 Docker：[有/无]
🔄 CI/CD：[探测结果]
💡 待评估想法：[X 条（若 .claude/knowledge/ideas/ 不存在则省略此行）]
📛 推荐前缀：[推断结果]（来源：[推断来源，如 "package.json name"]）

请确认以上信息是否正确，并回答以下问题：

1. **Skill 前缀**：上面推荐的 `[推断结果]` 可以吗？
   💡 前缀会出现在所有 skill 命令中（如 `/myapp-dev`、`/myapp-commit`），
   建议 3-8 个字符，简短好记。
   （回车确认 / 输入新的前缀）

2. **一句话描述**这个项目是做什么的？
   💡 好的描述能帮我生成更精准的 skill。举几个例子：
   - "SaaS 协作平台，支持实时文档编辑和团队管理"
   - "个人 AI 研究项目，测试各种大模型和工具"
   - "电商后端 API，服务移动端和 Web 前端"
   不用很正式，用你自己的话说就行。

3. **你的角色**？这决定了 skill 的侧重方向：
   a) 全栈 — 前后端都写，skill 会覆盖全链路
   b) 前端 — 侧重组件、状态管理、UI 规范
   c) 后端 — 侧重 API、数据库、部署
   d) ML/AI — 侧重实验、模型训练、数据处理
   e) 其他 — 请描述，我来适配
```

**如果 prefix 推断成功**，问题 1 只需用户回车确认。
**如果 prefix 推断失败**（所有来源都没命中），则展示：

```
📛 前缀：未能自动推断

1. **给你的 skill 起个前缀名**？
   💡 这个前缀会出现在所有命令中，比如你输入 "myapp"，就会生成：
   /myapp-dev（开发）、/myapp-commit（提交）、/myapp-debug（调试）
   建议用项目名的缩写，3-8 个字符，全小写。
```

#### 第二轮：开发流程

```
接下来了解一下你的开发流程，帮我生成更贴合实际的 skill：

4. **数据库**（如有）：
   💡 如果项目还没用数据库但计划会用，也可以告诉我，我先生成 db skill 占位。
   [PostgreSQL / MySQL / MongoDB / SQLite / 无 / 计划用但还没决定]

5. **部署方式**：
   💡 如果还没确定也没关系，选"未定"即可，后续再执行 /skill-evo 补充。
   [Vercel / AWS / Fly.io / 自建服务器 / Docker / 未定]

6. **Git 提交风格**：
   💡 如果你不确定，我推荐 Conventional Commits——它是目前最主流的规范，
   格式是 `feat: 添加用户登录` / `fix: 修复支付bug`，
   好处是能自动生成 changelog、方便 code review。
   a) Conventional Commits（推荐，结构化提交信息）
   b) 自由格式（不限制格式）
   c) 不确定（我帮你选一个合适的）

8. **有没有希望 Claude 帮你规范化的工作流？**
   💡 以下是常见的选择，根据你的项目勾选即可（可多选）：
   a) 📋 代码审查 — 提交前自动检查代码质量、安全、规范
   b) 🧪 测试规范 — 明确测试策略、覆盖率要求
   c) 🔬 技术调研 — 结构化的技术选型评估报告
   d) 📖 参考代码分析 — 阅读开源代码时有系统化的分析流程
   e) 其他 — 请描述，我来判断是否适合做成 skill

   不确定的话也没关系，先不选——后面再执行 /skill-evo 时可以补充，
   或者 skill 的进化协议也会在使用中自动发现并提议。
```

### 提问原则

| 原则 | 说明 |
|------|------|
| **给出选项而非开放提问** | 用户面对选项比面对空白更容易回答 |
| **每个选项附带一句话解释** | 帮用户理解选了之后会怎样 |
| **给出推荐和理由** | "不确定"时有明确的默认推荐 |
| **允许"还没想好"** | 明确告诉用户可以下次 /skill-evo 时补充 |
| **用具体例子引导** | 比起抽象描述，例子更能帮用户对号入座 |
| **不追问** | 用户回答"不确定"或跳过时，用合理默认值，不要反复追问 |

---

## Phase 2: Skill 规划

### 2.1 模板库

根据收集到的项目信息，生成以下完整体系：

**Skills**（行为模式，关键词自动触发，生成到 `.claude/skills/`）：

| 模板 | 生成名 | 内容 |
|------|--------|------|
| `dev` | `{prefix}-dev` | 本地开发命令、环境配置、端口分配 |
| `debug` | `{prefix}-debug` | 深度调试工作流 + 经验记录库 |
| `skill` | `{prefix}-skill` | 元技能，管理所有 skills，含进化引擎 |
| `digest` | `{prefix}-digest` | 知识沉淀（决策、调研、踩坑、惯例、外部参考） |
| `todo` | `{prefix}-todo` | 项目级待办管理，持久化到 `.claude/knowledge/todo.md` |

**Commands**（过程执行，仅显式 `/command` 调用，生成到 `.claude/commands/`）：

| 模板 | 生成文件名 | 内容 |
|------|----------|------|
| `commit` | `{prefix}-commit.md` | Git 提交工作流（精确暂存、VERSION、推送） |
| `review` | `{prefix}-review.md` | 代码审查工作流（多 agent 并行审查） |
| `research` | `{prefix}-research.md` | 技术选型评估 + 源码深度分析 |

### 2.2 向用户展示规划

#### 首次初始化模式

```
根据你的项目信息，我建议生成以下体系：

📂 .claude/skills/              （行为模式，关键词自动触发）
├── {prefix}-skill/SKILL.md    ✅ 元技能（含进化引擎）
├── {prefix}-dev/SKILL.md      ✅ 本地开发
├── {prefix}-debug/SKILL.md    ✅ Bug 修复（含经验记录库）
├── {prefix}-digest/SKILL.md   ✅ 知识沉淀
└── {prefix}-todo/SKILL.md     ✅ 项目待办（持久化）

📂 .claude/commands/            （过程执行，显式 /command 调用）
├── {prefix}-commit.md         ✅ Git 提交工作流
├── {prefix}-review.md         ✅ 代码审查工作流
└── {prefix}-research.md       ✅ 技术调研工作流

同时生成：
└── .claude/CLAUDE.md          # 项目级 Claude 指令

🧬 Skills 内置「自我进化协议」，Commands 轻量无需进化协议

要去掉哪些？确认后开始锻造。
```

#### 优化模式

```
基于巡检结果，本次计划执行以下操作：

🔄 更新：
  1. {prefix}-dev/SKILL.md — README 中有新的启动命令，补充到 dev skill
  2. {prefix}-debug/SKILL.md — 更新踩坑记录路径至知识库

📝 完善：
确认要执行哪些？（编号 / 全部 / 跳过）
```

---

## Phase 3: 内容共创

### 3.1 逐个 Skill 细化（引导式问答）

**不是简单套模板，而是针对每个 skill 询问项目特有规范。**

对每个确认要创建/更新的 skill，快速问 1-2 个关键问题。

**提问策略**：先根据自动探测给出推荐答案，让用户确认或修改。用户越少思考越好。

#### `{prefix}-dev` 要问的：

```
🛠️ 关于本地开发环境：

1. 启动项目的主要命令是什么？
   💡 我检测到你用的是 [包管理器]，常见的启动方式有：
   - `[包管理器] run dev`（开发模式）
   - `[包管理器] run start`（生产模式）
   - `docker compose up`（容器化启动）
   {如果 README 中有启动命令: "我在 README 中看到了 `xxx` 命令，是这个吗？"}
   如果有多个服务需要分别启动，都列出来即可。

2. 有没有需要先启动的依赖服务？
   💡 {如果检测到 docker-compose: "我看到你有 docker-compose.yml，
   里面的服务需要先启动吗？" / 如果没有: "比如本地数据库、Redis、
   消息队列等——如果都不需要，直接跳过"}
```

#### `{prefix}-commit` 要问的：

```
📝 关于 Git 提交：

1. 除了标准的 feat/fix/chore，你的项目有没有特殊的 commit type？
   💡 标准类型已覆盖大部分场景：
   feat（新功能）、fix（修复）、chore（杂务）、docs（文档）、
   refactor（重构）、test（测试）、style（格式）、perf（性能）

   一些项目会加自定义类型，比如：
   - AI 项目：`exp:` 表示实验
   - 数据项目：`data:` 表示数据变更
   - 基础设施：`infra:` 表示基础设施变更
   {如果 git log 中检测到特殊 type: "我在 git 历史中看到你用过 `xxx:`，要加进规范吗？"}
   如果没有特殊需求，回车跳过即可。

2. commit message 用中文还是英文？
   💡 两种都可以，看团队习惯：
   - 中文示例：`feat: 添加用户登录功能`
   - 英文示例：`feat: add user login`
   {如果 git log 中能看出: "你最近的提交用的是 [中文/英文]，继续用这个？"}
   如果团队有外国成员或项目会开源，建议英文。
```

#### `{prefix}-review` 要问的：

```
📋 关于代码审查：

1. 有没有项目特有的审查规则？
   💡 举些常见的例子，看哪些适合你的项目（可多选）：
   a) 数据库相关："所有表必须有 created_at 和 updated_at"
   b) 安全相关："禁止硬编码密钥/密码"
   c) 代码风格："组件必须用函数式写法"、"禁止硬编码颜色/字号"
   d) 性能相关："禁止在循环中做数据库查询"
   e) 目前没有 — 💡 没关系，进化协议会在日常审查中逐步积累规则

2. 审查范围？
   a) 仅变更文件 — 速度快，适合日常提交
   b) 变更文件 + 直接关联文件 — 更全面，能发现连锁影响（推荐）
   c) 不确定 — 💡 建议选 (b)，多看一层关联很有价值
```

#### `{prefix}-digest`：无需提问

知识库固定在 `.claude/knowledge/`，无需用户选择。

#### `{prefix}-todo`：无需提问

待办文件固定在 `.claude/knowledge/todo.md`，无需用户选择。
自我感知提醒默认开启。

#### 其他 skill 的提问同理：给选项、给例子、给推荐、允许跳过。

**核心原则**：
- **尽量从扫描结果中提取答案**，展示给用户确认，而不是让用户从零填写
- **用户回答"不确定"或"没有"时**，使用合理的默认值，不要追问
- **用户回答模糊时**（如"差不多"），根据上下文选最接近的选项，展示选择结果让用户确认
- **用户跳过时**，明确告知"已用默认值，下次 /skill-evo 可以补充"

### 3.2 批量确认

收集完所有答案后，展示即将生成/更新的文件清单：

#### 首次初始化

```
即将锻造以下文件：

1. .claude/CLAUDE.md                       (~120 行)
2. .claude/skills/{prefix}-skill/SKILL.md  (~150 行，含进化引擎)
3. .claude/skills/{prefix}-dev/SKILL.md    (~100 行)
4. .claude/skills/{prefix}-commit/SKILL.md (~60 行)
5. .claude/skills/{prefix}-debug/SKILL.md (~150 行，含经验记录库)
...

是否开始锻造？（Y/直接回车 = 生成全部）
```

#### 优化更新

```
即将执行以下变更：

🔄 更新（仅修改标注的部分，其余不动）：
  1. {prefix}-dev/SKILL.md — 「常用命令速查」章节补充 2 条命令
  2. {prefix}-debug/SKILL.md — 更新踩坑记录路径至知识库

是否执行？（Y/直接回车 = 全部执行）
```

---

## Phase 4: 生成/更新文件

### 4.1 首次初始化的生成顺序

1. **CLAUDE.md**（最先，因为 skills 会引用它）
2. **{prefix}-skill**（元技能，包含目录速查表 + 进化引擎）
3. **{prefix}-digest**（知识沉淀）
4. **其他 skills**（按依赖顺序，每个注入进化协议）
5. **知识库初始化**（创建目录结构 + 空索引）
6. **进化系统配置**（hooks + 脚本 + 目录结构）
7. **.gitignore 更新**（追加，不覆盖）

### 4.1.1 知识库初始化（首次初始化时自动执行）

```bash
mkdir -p .claude/knowledge/{decisions,research,pitfalls,conventions,references,ideas}
```

创建 `.claude/knowledge/index.md`：

```markdown
# {项目名} 知识库索引

## 技术决策

## 调研结论

## 踩坑记录

## 隐式规范

## 外部参考

## 待评估想法
<!-- 列出 ideas/ 下 status: pending 的想法链接 -->
```

**`ideas/` 文件格式**（命名：`YYYY-MM-DD-<slug>.md`）：

    ---
    status: pending
    date: YYYY-MM-DD
    source: <对话中发现 / 用户主动提出 / 调研中产生>
    ---

    # <想法标题>

    **背景**：一句话描述为什么有这个想法

    ## 想法内容

    ...

状态值：`pending`（待评估）/ `to-research` / `to-decision` / `dropped`

### 4.1.2 进化系统配置（首次初始化时自动执行）

创建进化系统的基础设施：

```bash
# 1. 创建目录结构
mkdir -p .claude/evolution/{raw,hooks}

# 2. 写入 capture.sh（统一 hook 入口）
# 3. 写入 digest.py（SessionEnd 预处理）
# 4. 初始化 session-meta.json
echo '{"total_sessions":0,"last_digest_session":0,"pending_signal_count":0}' \
  > .claude/evolution/session-meta.json

# 5. 初始化空 evolution-digest.md
# 6. 合并 hook 配置到 .claude/settings.json（不覆盖已有 hooks）
```

**Hook 注册**（合并到 `.claude/settings.json`）：

```json
{
  "hooks": {
    "SessionStart": [{"hooks": [{"type": "command", "command": "bash .claude/evolution/hooks/capture.sh", "timeout": 10}]}],
    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "bash .claude/evolution/hooks/capture.sh", "timeout": 5}]}],
    "PostToolUse": [{"matcher": "Edit|Write|Bash|Read", "hooks": [{"type": "command", "command": "bash .claude/evolution/hooks/capture.sh", "timeout": 5}]}],
    "Stop": [{"hooks": [{"type": "command", "command": "bash .claude/evolution/hooks/capture.sh", "timeout": 5}]}],
    "SessionEnd": [{"hooks": [{"type": "command", "command": "bash .claude/evolution/hooks/capture.sh", "timeout": 30}]}]
  }
}
```

**.gitignore 追加**：

```
.claude/evolution/raw/
.claude/evolution/pending-signals.jsonl
.claude/evolution/session-meta.json
reference/
```

### 4.2 优化模式的更新规则

| 操作类型 | 规则 |
|---------|------|
| 新建 skill | 完整创建，注入进化协议 |
| 更新 skill | **只修改需要变化的章节**，保留用户已有的自定义内容 |
| 补充内容 | 在现有章节末尾追加，不改动原有内容 |
| 修复过期 | 替换过期内容，清除 `<!-- STALE: -->` 标记 |

**关键**：优化模式下，绝不全量覆盖已有 skill。用 Edit 工具精确修改。

### 4.3 CLAUDE.md 生成模板

```markdown
# {项目名} 开发规范

## 项目概述

{用户提供的一句话描述}

## 技术栈

| 层 | 技术 |
|----|------|
{根据探测和问答填充}

## Skill 体系

所有 skill 使用 `{prefix}-` 前缀，内置自我进化能力。

| Skill | 场景 |
|-------|------|
{遍历所有已确认的 skills}

## 目录结构

```
{根据探测结果生成}
```

## {根据项目类型生成的规范章节}

{比如 Python 项目生成"Python 开发规范"，TypeScript 项目生成"TypeScript 规范"等}

## 安全规范

{根据项目类型生成，如 API Key 管理、环境变量等}

## Git 提交规范

{如果选了 commit skill，在此放简版引用}

## Skill 自我进化

本项目的 skill 体系具备被动进化能力。在日常工作中，如果你发现：
- **skill 内容与项目现状不符**（路径、命令、API 已变）→ 提议更新 skill
- **用户纠正了 skill 中的规范** → 提议将正确做法写入 skill
- **反复出现的操作模式未被 skill 记录** → 提议补充
- **用户明确说"记住"、"以后都这样"** → 提议写入 skill

修改 skill 前必须向用户确认，绝不擅自修改。

## 知识沉淀

对话中出现以下内容时，提议使用 `/{prefix}-digest` 沉淀：
- 做出了技术决策（选型、架构方案）→ 建议记录到 decisions/
- 完成了技术调研或深度分析 → 建议记录到 research/
- 发现了项目的隐式惯例 → 建议记录到 conventions/

## 知识捕获触发器

在对话中识别以下信号，主动建议记录（询问用户，不强制）：

| 信号 | 建议记入 |
|------|---------|
| "这里有个问题"/"感觉不对" | `.claude/knowledge/pitfalls/` |
| "要不要试试"/"可以考虑" | `.claude/knowledge/ideas/` |
| "记住这个"/"以后要做" | `.claude/knowledge/ideas/`（若 todo skill 已安装则优先记入 `todo.md`）|
| 调研结论/技术选型依据 | `.claude/knowledge/research/` |

记录格式：日期 + 一句话背景 + 内容，文件放对应目录。
```

### 4.4 生成规则

#### Skill 格式（`.claude/skills/{prefix}-{name}/SKILL.md`）

```yaml
---
name: {prefix}-{name}
description: >
  {一句话描述}。
  触发词：{逗号分隔的触发关键词}。
version: 1.0.0
source: claude-skill-evo
---
```

#### Command 格式（`.claude/commands/{prefix}-{name}.md`）

```yaml
---
description: {一句话描述，会显示在 /command 菜单中}
argument-hint: {参数提示，如 "可选：--major/--minor 或 @file"}
---
```

Command 比 Skill 更轻量：无需 `name`/`version`/`source` 字段，无需触发词，无需进化协议。

**内容原则**：

| 原则 | 说明 |
|------|------|
| **具体 > 通用** | 填入项目真实的路径、命令、框架名，不用占位符 |
| **精简 > 冗长** | 每个 skill 控制在 60-180 行，核心指令优先 |
| **可操作 > 概念性** | 读完就知道怎么做，避免模糊描述 |
| **有触发词** | description 必须包含多个触发关键词 |
| **有进化协议** | 每个 skill 末尾注入自我进化协议；CLAUDE.md 包含进化提示 |

### 4.5 Debug Skill 与知识库集成

debug skill 的踩坑记录写入 `.claude/knowledge/pitfalls/`，格式由 digest skill 定义。

知识库目录在 Phase 4.1 中统一创建，debug skill 无需单独创建 records 目录。

---

## ★ 自我进化协议（注入到每个生成的 skill 中）

### 设计原则

> 进化通过日常工作被动触发，不依赖显式命令。用户与 Claude 的每次对话都是进化的机会。
> 协议追求最小认知负担：Claude 靠自然语言理解判断"是否值得沉淀"，不依赖无法跨 session 持久化的数值评分。

每个生成的 skill 末尾必须包含以下「自我进化协议」章节。根据 skill 类型调整侧重点描述即可。

### 注入模板

以下内容追加到每个生成的 SKILL.md 末尾：

```markdown
---

## 自我进化协议

> 本 skill 在日常使用中自动进化。无需显式触发，每次对话都可能驱动改进。

### 何时提议进化

在**任何对话**中，发现以下信号时提议更新本 skill：

| 信号 | 示例 | 行为 |
|------|------|------|
| 用户纠正 | "不对，应该用 pnpm 不是 npm" | 提议将正确做法写入 |
| 失败→修复 | 命令失败，排查后找到根因 | 提议写入根因 + 正确做法 |
| 显式指令 | "记住这个"、"以后都这样" | 提议立即写入 |
| 内容过期 | skill 中的路径/命令/API 已失效 | 提议更新过期内容 |
| 规范冲突 | skill 规范与代码实际做法不一致 | 询问以哪个为准，然后提议更新 |

**不需要提议的情况**：一次性的、临时的操作，不代表项目规范的内容。

### 确认流程（绝不擅自修改 skill 文件）

```
🔔 我注意到一个可以写入 skill 的规范：

{描述发现的内容}

建议写入：{prefix}-{skill}/SKILL.md 的「{章节名}」
内容预览：
---
{将写入的具体内容}
---

是否写入？(Y/N)
```

写入后 version patch +1（如 1.0.0 → 1.0.1）。

### Size Guard（体积守护）

**守护线**：每个 SKILL.md ≤ 15KB（约 400 行）

- > 12KB → 写入前警告，建议先压缩（合并相似规则、归档长期未引用的内容）
- > 15KB → 必须先压缩再写入

### 侧重点

> {根据 skill 类型填写，如："新命令发现、环境变量变更、依赖服务变化"}
```

### 各 Skill 的进化侧重

不同 skill 的进化协议侧重点不同：

| Skill 类型 | 侧重点 | 体积上限 |
|-----------|--------|---------|
| `dev` | 新命令、环境变量、依赖服务变化 | 15KB |
| `debug` | 每次调试自动沉淀到 knowledge/pitfalls、更新速查索引 | 15KB |
| `digest` | 新知识类型需求、索引结构优化、模板字段补充 | 15KB |
| `skill`（元技能） | 新 skill 创建时更新目录表、跨 skill 一致性 | 15KB |
| `test` | 新测试模式、覆盖率、断言风格 | 15KB |
| `promote` | 新渠道发现、推广效果反馈、README 优化点 | 15KB |

> Commands（commit/review/research）为轻量过程执行文件，无进化协议。用户仍可手动编辑 `.claude/commands/` 下的文件积累项目规范。

---

## Skill 模板详细设计

### 模板：dev

```markdown
---
name: {prefix}-dev
description: >
  {项目名} 本地开发环境规范。{包管理器}命令速查、依赖服务、
  环境变量配置、常用开发命令。
  触发词：本地开发、启动服务、环境配置、环境变量、.env、开发命令。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} 本地开发规范

## 常用命令速查

```bash
{用户提供的启动命令}
```

## 依赖服务

{Docker/数据库/Redis 等}

## 环境变量

{从 .env.example 或用户输入提取}

## 目录结构

{从自动探测结果生成}

---

## 自我进化协议

{按注入模板生成，侧重点：新命令发现、环境变量变更、依赖服务变化}
```

### 模板：commit

```markdown
---
description: 代码提交工作流。精确暂存、VERSION 管理、生成规范提交信息、自动推送。
argument-hint: 可选：--major/--minor/--patch 强制版本类型
---

# {项目名} 代码提交工作流

**ARGUMENTS**: $ARGUMENTS

```
/{prefix}-commit                   # 默认：提交所有 git 变更
/{prefix}-commit --minor           # 强制 minor 版本
```

> **职责边界**：本 command 只负责提交。代码审查请在提交前单独运行 `/{prefix}-review`。

## 步骤 1：查看当前变更

```bash
git status
git diff HEAD
git diff --cached
```

## 步骤 2：精确暂存

**不使用 `git add -A`**，改为精确暂存：

```bash
git status --short
# 按以下规则暂存文件：
# M（已修改）→ 全部暂存
# ?（新增）→ 排除 .env*、*.log 后暂存
# D（删除）→ 全部暂存
git add <精确列出的文件路径>
git reset HEAD -- .env .env.local .env.* 2>/dev/null || true
git diff --cached --stat  # 确认暂存内容
```

## 步骤 3：VERSION 管理（如果项目有 VERSION 文件）

```bash
current=$(cat VERSION 2>/dev/null)
```

若 VERSION 文件不存在 → 跳过本步骤。

**版本类型判断**（优先以 $ARGUMENTS 参数为准，无参数则自动判断）：

| 触发条件 | 版本类型 | 示例 |
|---------|---------|------|
| `--major` 或破坏性变更 | major | 1.2.3 → 2.0.0 |
| `--minor` 或 `feat` 类提交 | minor | 1.2.3 → 1.3.0 |
| `--patch` 或 fix/docs/chore 等 | patch | 1.2.3 → 1.2.4 |

```bash
new=<计算后的新版本>
echo $new > VERSION
git add VERSION
```

## 步骤 4：生成提交信息

基于 `git diff --cached` 分析变更，按以下规则生成：

| type | 适用场景 |
|------|---------|
| `feat` | 新功能、新页面、新接口 |
| `fix` | 修复 bug |
| `refactor` | 重构（无功能变化） |
| `docs` | 文档、注释更新 |
| `chore` | 依赖、配置、构建脚本 |
{用户自定义 type}

**格式**：
```
<type>: <{中文/英文}描述>（版本号如有 VERSION 文件则附上 vX.Y.Z）

- <细节1>（多文件时列出）
- <细节2>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
```

## 步骤 5：执行提交

```bash
git commit -m "$(cat <<'EOF'
<生成的提交信息>
EOF
)"
git log --oneline -1  # 验证提交
```

## 步骤 6：推送

```bash
git push origin <当前分支>
# 若失败（远程有新提交）：
# git pull --rebase origin <当前分支> && git push origin <当前分支>
```

## 完成输出

```
## {prefix}-commit 完成

暂存文件：N 个，+X -Y 行
VERSION：{old} → {new}（已更新）/ 未变更
提交信息：<type>: <subject>
Commit：<hash>
推送：已推送
```

```

### 模板：debug

```markdown
---
name: {prefix}-debug
description: >
  {项目名} 深度 Debug 工作流。彻底修复，不打补丁，允许破坏性重构。
  触发词：bug、报错、错误、修复、fix、崩溃、TypeError、报错日志、无法启动、debug、调试、{框架特有错误关键词}。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} 深度 Debug

> 踩坑记录库：`.claude/knowledge/pitfalls/`
> 知识库索引：`.claude/knowledge/index.md`

## 核心原则

**彻底修复，不打补丁。** 允许破坏性重构和跨文件大范围改动。宁可花更多时间找到根本原因，也不能用临时方案绕过问题。

---

## 第 0 步：自动预扫描（必须执行，不可跳过）

**拿到错误信息后，第一件事是搜索记录库，再开始调查代码。**

### 关键词提取

从错误信息中提取 2-3 个核心关键词（技术术语、模块名、错误类型）：

\```bash
grep -r "<关键词1>" .claude/knowledge/pitfalls/
grep -r "<关键词2>" .claude/knowledge/pitfalls/
\```

### 命中时的处理

找到匹配记录后：
1. 展示记录摘要（标题 + 根本原因 + 修复要点）
2. 对比当前错误与记录的异同
3. 如果高度一致 → 直接应用记录中的修复方案，无需重新分析
4. 如果部分相似 → 作为参考，结合当前上下文调整

### 无匹配时

继续执行第 1 步深度调查。

---

## 第 0.5 步：主动感知——改代码前先检查

在以下情况，**进入涉及模块前先扫描对应记录**：

{根据项目结构定制模块→扫描范围映射表，格式如下：}

| 进入模块 | 扫描范围 |
|---------|---------|
| {核心模块路径1} | `knowledge/pitfalls/{分类}/` |
| {核心模块路径2} | `knowledge/pitfalls/{分类}/` |
| 依赖升级、配置变更 | `knowledge/pitfalls/` 全部 |

如果该目录有记录，**主动告知用户**：「该区域有 N 条历史 bug 记录，已参考」。

---

## 第 1 步：深度调查

### 只在以下情况才主动问用户

- 有多个修复方向，且选哪个会显著影响架构或数据——先陈述分析结论和候选方案，再让用户选
- 修复需要用户配合做某些操作（如提供密钥、手动配置第三方服务）
- 错误信息不足以定位问题，且读代码也看不出来——明确说「还需要 X 信息才能继续」

### 读代码，不猜测

- 用 `Grep` 和 `Glob` 追踪完整的调用链
- 阅读涉及的所有相关文件（不只是报错行）
- 分析最近的 git 提交，看是否有相关改动引入了 bug

### 合格的根本原因分析

- 明确指出是哪一行代码、哪个配置、哪个设计决策导致了问题
- 解释为什么会出现（机制层面）
- 说明为什么之前没有被发现

**不接受**：「可能是…」「应该是…」「暂时先…」

### 常见 Bug 类型

{根据技术栈定制，格式如下：}

| 类型 | 表现 | 排查方向 |
|------|------|---------|
| {类型1} | {典型错误信息} | {关键排查路径} |
| {类型2} | {典型错误信息} | {关键排查路径} |

---

## 第 2 步：制定修复方案

### 方案评估

| 维度 | 要求 |
|------|------|
| 彻底程度 | 从根本上解决，不绕过 |
| 副作用 | 明确影响哪些模块 |
| 代码质量 | 修完后代码更清晰 |

### 允许破坏性改动

如果根本原因是设计缺陷，**必须重构**：
- 可以删除并重写整个模块
- 可以修改多个文件的接口
- 可以升级或替换依赖库
{如果项目未上线，加入：- 可以变更数据库 schema（无需向后兼容）}

### 方案确认

描述改动范围 + 预期效果 + 可能副作用 → 等待用户批准。

---

## 第 3 步：执行修复

- 分步骤执行，每步说明做了什么
- 修改后检查关联文件
- {根据技术栈加入编译/lint 检查项}

---

## 第 4 步：沉淀经验（必须执行，不可跳过）

修复完成后，将经验写入记录库。

### 记录路径规则

踩坑记录统一写入知识库：

\```
.claude/knowledge/pitfalls/
├── {分类1}/     {分类描述}
├── {分类2}/     {分类描述}
└── {分类3}/     {分类描述}
\```

{如果项目较小，可不分子目录，直接放 pitfalls/ 下。}

文件名格式：`YYYY-MM-DD-kebab-case-描述.md`

记录必须包含：
1. **根本原因**（机制层面，非表面现象）
2. **修复代码**（Before / After 对比）
3. **预防措施**（规范约束 + 检查清单）

### 写入后必须更新

1. 本文件底部「已知 Bug 速查索引」表（添加新条目）
2. `.claude/knowledge/index.md` 的「踩坑记录」章节

### 记录完成后

- 告知用户：「已记录到 `.claude/knowledge/pitfalls/<文件名>.md`」
- 如果 bug 反映了需要写入 `CLAUDE.md` 的规范，提醒用户

---

## 已知 Bug 速查索引

> 每次新增记录后必须同步更新此表。用于第 0 步预扫描的快速匹配。

| 关键词 | 分类 | 文件（在 `.claude/knowledge/pitfalls/` 下） | 一句话摘要 |
|--------|------|------|-----------|

---

## 附：{项目名} 高危 Bug 区域

遇到以下关键词，**必须先查索引再动手**：

{根据项目技术栈列出 5-8 个高频出问题的区域，格式：}
- **{区域名}**：{具体风险描述}

---

## 自我进化协议

{按注入模板生成，侧重点：每次修复自动沉淀记录、更新速查索引}

**Debug 专属进化**：每次调试修复完成后，必须将经验写入 `knowledge/pitfalls/`、更新速查索引表和知识库索引。重复问题模式（≥2 次）提议写入预防规范。
```

### 模板：skill (元技能)

```markdown
---
name: {prefix}-skill
description: >
  {项目名} Skill 管理元技能兼进化引擎。发现、检查、新建、更新所有项目级 skill。
  跨 skill 一致性检查，驱动整个 skill 体系的进化。
  触发词：skill 管理、查看 skill、skill 列表、新建 skill、更新 skill、skill 进化、
  进化、evolve、优化 skill、进化分析。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} Skill 管理元技能

## 当前 Skill 目录速查

| Skill | 触发场景 | 版本 | 分类 |
|-------|---------|------|------|
{遍历所有已生成的 skills，含版本号}

## 功能一：发现

`ls .claude/skills/*/SKILL.md`（扫描所有项目级 skill，不限命名前缀）

## 功能二：健康检查

- 验证每个 skill 的 frontmatter 字段（name, description, version）
- 检查触发词覆盖率（是否有场景没有对应 skill）
- 检查跨 skill 一致性（术语、路径、命令是否统一）
- 检查是否有 `<!-- STALE: -->` 标记未处理

## 功能三：新建

`mkdir -p .claude/skills/{prefix}-<name>` + 填写 SKILL.md（自动注入进化协议）

## 功能四：快速路由

根据任务类型推荐正确的 skill。

## 功能五：进化引擎（元级进化）

作为元技能，负责驱动整个 skill 体系的进化：

### 5.1 主动进化分析

当用户触发 `/{prefix}-skill 进化` 或 `/{prefix}-skill 回顾` 时：

1. 读取所有 `.claude/skills/*/SKILL.md`（包括非 skill-evo 生成的 skill）
2. 扫描项目现状（目录结构、package.json、配置文件等）
3. 对比 skill 内容与项目现状，找出不一致
4. 检查各 skill 体积（>12KB 警告）
5. 检查跨 skill 一致性（术语、路径、命令是否统一）
6. 检查是否有 `<!-- STALE: -->` 标记未处理
7. 生成提议，逐条展示，等待用户确认
8. 确认后写入 skill（version patch +1）

### 5.2 Skill 进化日志

```
.claude/skills/{prefix}-skill/evolution.log
```

记录格式：
```
[YYYY-MM-DD] {skill-name} v{old} → v{new}: {变更摘要}
```

---

## 自我进化协议

{按注入模板生成，侧重点：新 skill 创建时更新目录表、跨 skill 一致性检查}

**元技能专属**：作为元技能，额外关注进化策略本身是否需要调整——进化信号是否噪音太多、好的发现是否被忽略、各 skill 体积增长是否健康。
```

### 模板：digest

```markdown
---
name: {prefix}-digest
description: >
  {项目名} 知识沉淀工作流。将技术决策、调研结论、踩坑记录、隐式惯例、外部参考
  统一归档到项目知识库，跨会话持久化。
  触发词：digest、沉淀、记录、知识、总结、归档、决策记录、经验、笔记。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} 知识沉淀

> 知识库路径：`.claude/knowledge/`

## 知识库结构

```
.claude/knowledge/
├── index.md              # 知识索引（按类型分章节）
├── decisions/            # 技术决策记录
├── research/             # 调研结论
├── pitfalls/             # 踩坑记录（与 debug skill 共享）
├── conventions/          # 发现的隐式规范
└── references/           # 外部知识精炼摘要
```

## 内容类型与模板

所有文件统一命名：`YYYY-MM-DD-{topic}.md`

### decisions/ — 技术决策

```markdown
# 决策：{标题}
**日期**：YYYY-MM-DD
**状态**：✅ 已采纳 / ⏳ 待讨论 / ❌ 已废弃

## 背景
{为什么需要做这个决策}

## 方案对比
| 方案 | 优点 | 缺点 |
|------|------|------|

## 结论
{最终选择及理由}

## 影响范围
{哪些模块/文件受影响}
```

### pitfalls/ — 踩坑记录

```markdown
# 踩坑：{标题}
**日期**：YYYY-MM-DD
**关键词**：{用于检索}

## 错误现象
{描述}

## 根本原因
{机制层面的分析}

## 修复方案
{代码或操作步骤}

## 预防措施
- [ ] {规范约束}
```

### research/ — 调研结论

```markdown
# 调研：{标题}
**日期**：YYYY-MM-DD

## 结论
{一句话结论}

## 关键发现
{要点列表}

## 推荐方案
{推荐什么、为什么}
```

### conventions/ — 隐式规范

```markdown
# 惯例：{标题}
**日期**：YYYY-MM-DD
**来源**：{从哪次对话/代码中发现的}

## 规范内容
{具体规范描述}

## 示例
{正确 vs 错误示例}
```

### references/ — 外部知识摘要

```markdown
# 参考：{标题}
**日期**：YYYY-MM-DD
**原始来源**：{URL 或文档名}

## 摘要
{精炼后的要点}

## 与本项目的关联
{如何应用到项目中}
```

## index.md 格式

```markdown
# {项目名} 知识库索引

## 技术决策
- YYYY-MM-DD [{标题}](decisions/YYYY-MM-DD-{topic}.md) — {一句话摘要}

## 调研结论
- YYYY-MM-DD [{标题}](research/YYYY-MM-DD-{topic}.md) — {一句话摘要}

## 踩坑记录
- YYYY-MM-DD [{标题}](pitfalls/YYYY-MM-DD-{topic}.md) — {一句话摘要}

## 隐式规范
- YYYY-MM-DD [{标题}](conventions/YYYY-MM-DD-{topic}.md) — {一句话摘要}

## 外部参考
- YYYY-MM-DD [{标题}](references/YYYY-MM-DD-{topic}.md) — {一句话摘要}
```

## 操作流程

### 写入知识

1. 判断内容类型（决策/调研/踩坑/惯例/参考）
2. 用对应模板创建 `.claude/knowledge/{type}/YYYY-MM-DD-{topic}.md`
3. 更新 `.claude/knowledge/index.md` 对应章节

### 查看知识

1. 读取 `.claude/knowledge/index.md`
2. 按类型或关键词筛选
3. 读取具体文件展示详情

---

## 自我进化协议

> 本 skill 在日常使用中自动进化。

### 何时提议进化

| 信号 | 行为 |
|------|------|
| 出现新的知识类型 | 提议新增子目录和模板 |
| 索引结构不够清晰 | 提议优化 index.md 格式 |
| 模板字段缺失 | 提议补充模板字段 |
| 用户纠正分类 | 提议调整分类标准 |

### Size Guard — ≤ 15KB

> index.md 体积守护：> 50 条时建议归档旧条目。
```

### 模板：review

```markdown
---
description: 代码审查工作流。多维度并行审查、项目规范检查、迭代修复循环、审查报告。
argument-hint: 可选：@文件路径（审查指定文件）
---

# {项目名} 代码审查工作流

```
/{prefix}-review                   # 默认：审查 git diff（已暂存 + 未暂存）
/{prefix}-review @src/foo.ts       # 审查指定文件（Claude 直接收到内容，无需 git diff）
/{prefix}-review @src/foo.ts @src/bar.ts   # 同时审查多个文件
```

## 审查范围

若 $ARGUMENTS 包含 `@` 文件引用 → 直接使用文件内容作为审查输入，跳过 git diff。
否则：
- 获取变更：`git diff HEAD`（已暂存 + 未暂存）
- 记录变更涉及的功能模块，供 Agent 4 使用

## 多维度并行审查

启动 5 个并行审查 Agent，各司其职：

### Agent 1：逻辑与边界

- 空值/null 处理是否完整
- 边界条件（空数组、超长字符串、并发冲突）
- 条件分支是否覆盖所有情况
- 循环终止条件是否正确

### Agent 2：类型安全与错误处理

- 类型转换是否安全（无 `as any`、无隐式转换）
- 错误是否被正确捕获和传播
- 异步操作是否有超时和错误处理
- 资源（连接、文件句柄）是否正确释放

### Agent 3：并发与资源

- 数据竞争风险
- 死锁可能性
- 内存泄漏（未取消的订阅、未清理的定时器）
- 连接池/资源池使用是否正确

### Agent 4：项目规范

{根据项目已有 skill 生成具体检查项}

- 是否遵循 {prefix}-commit 中的提交规范
- 是否遵循项目 CLAUDE.md 中定义的规范

### Agent 5：代码质量与复用

- 是否有可复用的现有工具函数未使用
- 是否有重复代码可以提取
- 命名是否清晰、一致
- 注释是否有价值（非显而易见的逻辑才加注释）

## 审查流程

```
1. 收集变更文件列表
2. 启动 5 个 Agent 并行审查
3. 汇总发现的问题
4. 按严重程度排序
5. 逐一修复或标记为"接受"
6. 修复后再次审查（最多 3 轮）
7. 生成审查报告
```

## 问题分级

| 级别 | 含义 | 处理 |
|------|------|------|
| 🔴 Critical | 会导致 bug / 安全漏洞 | 必须修复 |
| 🟡 Warning | 可能导致问题 / 不符合规范 | 建议修复 |
| 🔵 Info | 优化建议 / 最佳实践 | 可选 |

## 审查报告模板

```
📋 代码审查报告

变更文件：{N} 个
审查轮次：{轮次}/3

🔴 Critical: {N} 个（已全部修复 ✅ / 待修复 ❌）
🟡 Warning: {N} 个（已修复 {M} 个）
🔵 Info: {N} 个

详细发现：
{逐条列出}
```

```

### 模板：research

```markdown
---
description: 技术调研工作流。并行多源信息采集、技术栈适配评估、源码深度分析、结构化对比报告。
argument-hint: 调研对象名称，如 "zustand vs jotai"
---

# {项目名} 技术调研工作流

**ARGUMENTS**: $ARGUMENTS

---

## Step 1：明确调研目标

从用户问题中提取（缺少则推断）：

- **调研对象**：库/框架/服务名称
- **使用场景**：想解决的具体问题
- **对比候选**：用户未提时，主动找 2-3 个主流竞品
- **决策约束**：必须开源、必须支持 {技术栈}、成本限制等

---

## Step 2：并行信息采集

**同时**执行以下搜索，不要串行等待：

**2A — 官方文档 / GitHub README**
- WebFetch 官网文档或 GitHub README
- 提取：定位/用途、安装方式、最后更新时间、Stars

**2B — 包数据**（npm 包适用）
- 月下载量：`WebFetch https://api.npmjs.org/downloads/point/last-month/<包名>`
- bundle 体积：`WebFetch https://bundlephobia.com/api/size?package=<包名>`（提取 gzip、size）

**2C — 技术栈兼容性搜索**（Web 搜索）：
```
"<库名>" {技术栈关键词} compatibility 2025 OR 2026
"<库名>" issues OR problems OR pitfalls
```

**2D — 社区口碑**（Web 搜索）：
```
"<库名>" vs <竞品> reddit OR hackernews 2025 OR 2026
```

**2E — 竞品对比**（若有多个候选）
对每个竞品重复 2A + 2B 关键数据，填入对比表。

---

## Step 3：源码深度分析（按需）

> 需要理解实现细节时使用，文档级调研可跳过。

```bash
mkdir -p reference
git clone --depth 1 {repo_url} reference/{repo_name}
# 特定版本：git clone --depth 1 --branch {tag} {repo_url} reference/{repo_name}
```

**reference/ 规范**：与项目根目录平级，加入 `.gitignore`，分析完可删除。

优先查看：README → 入口文件 → 目录结构 → 依赖文件（package.json / go.mod 等）

| 项目规模 | 建议深度 |
|---------|---------|
| < 1000 行 | 完整阅读 |
| 1000-10000 行 | 核心模块深读 + 周边浏览 |
| > 10000 行 | 目标模块精读 + 架构概览 |

---

## Step 4：生成调研报告

```markdown
## 技术调研报告：<调研对象>

**调研日期**：YYYY-MM-DD
**使用场景**：[简述想解决的问题]

---

### 一句话结论

> [推荐 / 不推荐 / 建议先 POC]：[核心理由一句话]

---

### 候选方案对比

| 维度 | <方案A> | <方案B> | <当前方案/无> |
|------|---------|---------|-------------|
| Stars / 活跃度 | | | |
| TypeScript 支持 | | | |
| 技术栈兼容性 | ✅/⚠️/❌ | | |
| bundle 体积（gzip） | | | |
| 月下载量 | | | |
| 许可证 | | | |

---

### 风险与权衡

**优点**：
- [优点1]

**缺点/风险**：
- [缺点1]

**与现有技术栈冲突点**：
- [冲突或注意点，无则写"无明显冲突"]

---

### 集成复杂度

- **引入成本**：低 / 中 / 高（说明原因）
- **迁移成本**（若替换现有方案）：低 / 中 / 高

---

### 源码分析（如有）

- 仓库：{URL}，本地：`reference/{repo_name}/`
- 亮点：[值得借鉴的设计]
- 局限：[不适合直接照搬的地方]

---

### 最终建议

**结论**：推荐 / 不推荐 / 建议先 POC 验证

**行动项**（若推荐）：
1. [安装命令]
2. [需要的配置步骤]

**替代方案**（若不推荐）：
- [替代思路]
```

---

## Step 5：后续处理

- 若推荐采用但本次不立即集成，写入 `TODO.md`：
  ```markdown
  - [ ] 集成 <库名>：[使用场景] — 调研日期 YYYY-MM-DD
  ```
- 清理不再需要的 `reference/` 源码（或保留供后续参考）

```

### 模板：todo

```markdown
---
name: {prefix}-todo
description: >
  {项目名} 项目级待办管理。查看/添加/完成/清理待办项，
  持久化到 .claude/knowledge/todo.md，对话中自动感知待办意图。
  触发词：todo、待办、任务、记录todo、查看任务、添加任务、完成任务。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} 项目待办

> 会话级临时 TODO 请使用 Claude Code 内置任务面板（TodoWrite）。
> 本 skill 只管项目级持久化待办：记录、追踪、归档。

## 操作速查

| 指令 | 效果 |
|------|------|
| `/{prefix}-todo` | 展示当前所有待完成项 |
| `/{prefix}-todo 添加 描述` | 追加一条待办到「待完成」区 |
| `/{prefix}-todo 完成 #N` | 将第 N 条移至「已完成」区 |
| `/{prefix}-todo 清理` | 归档已完成项，删除 30 天前的旧记录 |

## 执行流程

### 查看（默认行为）

1. 读取 `.claude/knowledge/todo.md`
2. 若文件不存在，则创建（写入标准模板）
3. 格式化展示「待完成」区所有条目（编号从 1 开始）

### 添加

1. 在「待完成」区末尾追加：`- [ ] {描述} ({今日日期})`
2. 展示追加结果

### 完成

1. 找到第 N 条（按展示顺序）
2. 将 `- [ ]` 改为 `- [x]`，移动到「已完成」区开头
3. 提示：是否将本次完成内容沉淀到知识库？（触发 `/{prefix}-digest`）

### 清理

1. 展示当前「已完成」区所有条目
2. 删除 30 天前的已完成条目（按日期判断）
3. 展示清理结果

## todo.md 标准格式

文件路径：`.claude/knowledge/todo.md`

```markdown
# 项目待办

## 待完成

- [ ] 描述 (YYYY-MM-DD)

## 已完成

- [x] 描述 (YYYY-MM-DD)
```

## 自我感知：被动检测

在任意对话中，若检测到以下信号，主动提议记录：

- 用户说「之后要做」「下次记得」「TODO:」「待办」「先跳过」
- 当前修复了问题但留有后续工作（「暂时先这样，之后要…」）

提议格式（简短，不打断工作流）：
```
📌 检测到待办，要记录到项目 todo 吗？
> {提炼的描述}
```

---

## 自我进化协议

{按注入模板生成，侧重点：待办分类优化、自我感知触发词扩充、与 digest 协作模式改进}
```

### 模板：experiment

```markdown
---
name: {prefix}-experiment
description: >
  {项目名} 实验管理规范。实验设计、执行记录、结果分析、
  对照实验、参数追踪、结论归档。
  触发词：实验、experiment、测试模型、对比实验、A/B测试、调参、{领域关键词}。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} 实验管理规范

## 实验工作流

```
1. 实验设计（假设 + 指标 + 方案）
2. 环境准备（数据 + 配置 + 基线）
3. 执行实验（记录所有参数和中间结果）
4. 结果分析（对比基线 + 统计显著性）
5. 结论归档（写入实验记录）
```

## 实验设计模板

| 字段 | 内容 |
|------|------|
| 实验名称 | {描述性名称} |
| 日期 | YYYY-MM-DD |
| 假设 | {要验证的假设} |
| 自变量 | {改变什么} |
| 因变量 | {测量什么} |
| 控制变量 | {保持不变的} |
| 成功标准 | {达到什么指标算成功} |

## 实验记录模板

```markdown
# 实验记录：{实验名称}

## 基本信息

- 日期：{YYYY-MM-DD}
- 目标：{一句话描述}
- 状态：{进行中 / 完成 / 中止}

## 实验设计

### 假设
{要验证的假设}

### 方案
{具体的实验步骤}

### 基线
{对照基准}

## 参数配置

| 参数 | 值 | 说明 |
|------|---|------|
{列出所有关键参数}

## 执行过程

{按时间顺序记录关键节点}

## 结果

### 定量结果

| 指标 | 基线 | 实验值 | 变化 |
|------|------|--------|------|
{对比数据}

### 定性观察

{非量化的观察发现}

## 结论

{结论 + 下一步}

## 经验教训

{可复用的经验}
```

## 实验目录结构

```
{根据项目类型生成，如：}
experiments/
├── {YYYY-MM}/
│   ├── {实验名}/
│   │   ├── config.yaml     # 参数配置
│   │   ├── results/        # 结果数据
│   │   └── README.md       # 实验记录
│   └── ...
└── _templates/             # 实验模板
```

## 实验命名规范

格式：`{YYYY-MM-DD}-{简短描述}`

示例：`2024-03-15-gpt4-vs-claude-summarization`

---

## 自我进化协议

{按注入模板生成，侧重点：新的实验模式、评估指标扩展、工具链变化}
```

### 模板：admin

```markdown
---
name: {prefix}-admin
description: >
  {项目名} 后台管理开发规范。路由结构、权限管理、
  通用 UI 模式、数据表格、表单、{框架名}规范。
  触发词：后台、管理后台、admin、管理端、运营后台、{框架名}。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} 后台管理开发规范

## 技术栈

- 框架：{前端框架}
- UI 库：{UI 组件库}
- 路由：{路由方案}
- API 调用：{API 客户端}

## 目录结构

```
{根据框架生成，如：}
src/
├── pages/           # 页面组件
│   ├── dashboard/
│   ├── users/
│   └── orders/
├── components/      # 通用组件
├── layouts/         # 布局组件
├── services/        # API 调用
└── utils/           # 工具函数
```

## 路由规范

{根据框架生成路由定义方式}

### 路由结构

| 路径 | 页面 | 权限 |
|------|------|------|
| `/dashboard` | 仪表板 | 所有角色 |
| `/users` | 用户管理 | 管理员 |
| `/settings` | 系统设置 | 超级管理员 |

## 权限管理

### 角色定义

| 角色 | 权限范围 |
|------|---------|
| 超级管理员 | 全部功能 |
| 管理员 | 除系统设置外 |
| 运营 | 内容管理、数据查看 |
| 只读 | 仅查看 |

### 权限控制方式

{根据项目实际情况生成}

## 通用 UI 模式

### 数据表格页

```
┌─────────────────────────────────────┐
│ 页面标题                    [新增] [导出] │
├─────────────────────────────────────┤
│ 搜索栏：[关键词] [状态▼] [日期范围] [搜索] │
├─────────────────────────────────────┤
│ 表格                                │
│ □ | ID | 名称 | 状态 | 操作          │
│ □ | 1  | ...  | ...  | [编辑][删除]  │
├─────────────────────────────────────┤
│ 共 {N} 条  [<] 1 2 3 [>]            │
└─────────────────────────────────────┘
```

### 表单页

```
┌─────────────────────────────────────┐
│ 新增/编辑 {实体}                      │
├─────────────────────────────────────┤
│ 字段名：[输入框]                      │
│ 字段名：[下拉选择]                    │
│ 字段名：[日期选择]                    │
├─────────────────────────────────────┤
│               [取消] [保存]           │
└─────────────────────────────────────┘
```

### 详情页

```
┌─────────────────────────────────────┐
│ {实体} 详情               [编辑] [删除] │
├─────────────────────────────────────┤
│ 基本信息    操作记录    关联数据        │
│ ─────────────────────────           │
│ {Tab 内容}                          │
└─────────────────────────────────────┘
```

## 界面语言

{根据用户回答：中文 / 英文 / 多语言}

## 新页面检查清单

- [ ] 路由已注册
- [ ] 权限检查已配置
- [ ] 表格支持搜索、分页、排序
- [ ] 表单有验证
- [ ] 删除操作有二次确认
- [ ] 加载/空/错误状态完整

---

## 自我进化协议

{按注入模板生成，侧重点：新的 UI 模式、权限角色扩展、通用组件发现}
```

### 模板：migration

```markdown
---
name: {prefix}-migration
description: >
  {项目名} 迁移工作流。架构变更映射、数据迁移、API 迁移、
  渐进式迁移策略、回滚方案、验证检查清单。
  触发词：迁移、migration、架构变更、重构、升级、从...迁移到...。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} 迁移工作流

## 迁移类型

| 类型 | 说明 | 风险等级 |
|------|------|---------|
| API 迁移 | 路由/接口从旧版迁移到新版 | 中 |
| 数据迁移 | 数据库 Schema 变更、数据转换 | 高 |
| 框架迁移 | 更换框架或框架大版本升级 | 高 |
| 架构迁移 | 单体→微服务、模块重组 | 极高 |
| 依赖迁移 | 替换第三方库 | 低-中 |

## 迁移工作流

```
1. 变更映射（旧 → 新的对应关系）
2. 影响评估（涉及的文件、依赖、下游）
3. 迁移计划（分步骤、可回滚）
4. 执行迁移（按计划逐步推进）
5. 验证（每步验证正确性）
6. 清理（删除旧代码、更新文档）
```

## Step 1: 变更映射

### 映射表模板

| 旧 | 新 | 状态 | 备注 |
|----|---|----|------|
| `旧路径/旧API` | `新路径/新API` | 待迁移/已迁移/已验证 | {说明} |

## Step 2: 影响评估

```bash
# 查找所有引用旧模块的文件
grep -r "旧模块名" --include="*.{ext}" -l

# 查找所有导入旧模块的文件
grep -r "import.*旧模块名" --include="*.{ext}" -l
```

### 影响范围

| 影响类型 | 文件数 | 风险 |
|---------|--------|------|
| 直接引用 | {N} | {高/中/低} |
| 间接依赖 | {N} | {高/中/低} |
| 测试文件 | {N} | 低 |
| 文档 | {N} | 低 |

## Step 3: 迁移策略

### 渐进式迁移（推荐）

```
Phase 1: 新旧并存（adapter/facade 模式）
Phase 2: 新代码使用新模块，旧代码保持不变
Phase 3: 逐步迁移旧代码到新模块
Phase 4: 移除旧代码和 adapter
```

### 大爆炸迁移（仅小规模变更）

```
1. 在分支上一次性完成所有变更
2. 全面测试
3. 一次性合并
```

## Step 4: 执行

### 决策确认机制

每一步执行前，展示变更预览：

```
📋 即将执行迁移步骤 {N}/{总步数}：

变更：{描述}
影响文件：{N} 个
不可逆操作：{有/无}

确认执行？(Y/N)
```

## Step 5: 验证检查清单

- [ ] 所有旧引用已更新
- [ ] 编译/构建通过
- [ ] 单元测试全部通过
- [ ] 集成测试通过
- [ ] 手动冒烟测试通过
- [ ] 性能无明显退化
- [ ] 无废弃代码残留

## 回滚方案

| 场景 | 回滚方式 |
|------|---------|
| 数据迁移失败 | 从备份恢复 |
| API 迁移失败 | 切回旧路由 |
| 依赖迁移失败 | 回退版本号 |
| 架构迁移失败 | git revert + 数据恢复 |

---

## 自我进化协议

{按注入模板生成，侧重点：新的迁移模式、回滚经验、验证步骤完善}
```

### 模板：product

```markdown
---
name: {prefix}-product
description: >
  {项目名} 产品设计文档索引。功能模块目录、设计规范、冲突处理、模糊意图处理。
  触发词：产品设计、功能设计、用户流程、业务逻辑、怎么做、该怎么设计。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} 产品设计 Skill

> **子文档索引**
> - 功能模块：`.claude/skills/{prefix}-product/features/`

---

## 文档范围规范（必须遵守）

**{prefix}-product 是产品设计文档，不是技术文档。**

### 应该包含的内容

| 类型 | 示例 |
|------|------|
| 功能描述 | 用户可以执行哪些操作 |
| 业务规则 | 各功能的约束和限制条件 |
| 用户流程 | 操作的步骤顺序 |
| 交互逻辑 | 操作后的反馈和状态变化 |
| 可见性/权限规则 | 不同角色/状态下的功能可见性 |
| 数据的**语义描述** | 实体包含什么信息（不涉及数据库设计） |

### 禁止出现的内容

| 类型 | 示例 |
|------|------|
| ❌ 数据库表结构 | 字段列表、索引定义、外键关系 |
| ❌ 代码片段 | 类型定义、SQL、API 请求格式 |
| ❌ 技术实现细节 | 缓存策略、队列实现、第三方 SDK 用法 |
| ❌ 字段类型和约束 | `UUID`、`text`、`int`、`NOT NULL` |

**判断方法**：这条内容是"产品要做什么"，还是"开发者怎么实现"？后者不属于本 skill。

---

## Skill 维护规则（重要）

**每次产品功能发生变更时，必须同步更新本 skill：**

| 变更类型 | 需要更新的文件 |
|---------|-------------|
| 新增功能模块 | 在 `features/` 下新建对应文件，并在本文件目录中登记 |
| 修改现有功能逻辑 | 直接更新对应的 `features/<module>.md` |
| 新增/修改用户流程 | 在对应 `features/<module>.md` 中添加「完整流程」章节 |
| 调整核心产品定位 | 更新本文件「产品概述」部分 |
| 版本迭代 | 更新本文件 `version` 字段 |

**触发更新的时机**：
- 用户说"我们要加一个功能……"→ 设计完成后写入对应 features 文件
- 用户说"这个功能改成……"→ 修改对应 features 文件
- 代码与文档冲突，且用户明确指定方向 → 按指定执行
- 代码与文档冲突，用户未明确指定 → **先向用户确认**

---

## 产品概述

| 维度 | 定义 |
|------|------|
| 产品定位 | {产品定位} |
| 目标用户 | {目标用户} |
| 差异化 | {差异化} |
| 平台 | {平台} |

---

## 功能模块目录

| 模块 | 文件 | 状态 | 说明 |
|------|------|------|------|
| {模块名} | `features/{module}.md` | 📝 规划中 | {一句话说明} |

> 随产品发展逐步增加。每新增一个功能模块，在此表中登记并在 `features/` 下创建对应文件。

---

## 通用产品原则

### 交互设计原则

{根据产品定位填写，以下为示例：}

1. **低门槛参与**：核心功能 3 步以内可完成
2. **即时反馈**：操作后必须有视觉反馈
3. **一致性**：相同类型的操作使用相同的交互模式

### 数据与隐私

- 用户可控：用户对自己的内容有完整控制权
- 最小采集：只采集业务必需的数据

---

## 代码与设计文档冲突处理（必须遵守）

在检查代码时，若发现**现有代码实现与产品设计文档存在冲突**：

### 判断流程

```
发现代码与文档冲突
        ↓
用户是否在本次对话中明确指定了方向？
        ↓
   是 → 按用户指定执行（修改代码 or 更新文档）
   否 → 停下来，向用户确认
```

### 向用户确认的格式

```
发现代码与设计文档存在冲突，需要确认以哪个为准：

**冲突描述**：
- 设计文档（features/xxx.md）：[描述文档中的设计]
- 现有代码（path/to/file:行号）：[描述代码中的实现]

请确认：
A. 以设计文档为准 → 修改代码
B. 以代码为准 → 更新设计文档
C. 两者都需调整 → 说明新的期望行为
```

### 明确指定的识别规则

| 用户说的 | 视为 |
|---------|------|
| "按文档实现"、"文档说的是对的" | 以文档为准，修改代码 |
| "代码没问题"、"文档写错了" | 以代码为准，更新文档 |
| "帮我把代码改成……" | 修改代码（同时更新文档） |
| "文档里改成……" | 更新文档 |

### 禁止行为

- ❌ 发现冲突后默默选一个方向执行，不告知用户
- ❌ 仅凭"代码已实现"就断定代码优先
- ❌ 仅凭"文档更权威"就断定文档优先

---

## 模糊意图处理规范（必须遵守）

产品设计中的模糊和歧义是常态。**不得自行假设、脑补或凭直觉决定**。

### 何时必须提问

| 情况 | 示例 | 必须确认的问题 |
|------|------|--------------|
| 功能边界不清 | "加一个分享功能" | 分享到哪里？分享什么内容？ |
| 业务规则缺失 | "要有时间限制" | 限制多长时间？到期怎么处理？ |
| 权限逻辑不明 | "管理员可以管理" | 管理包含哪些操作？ |
| 状态/流程有分叉 | "用户取消操作" | 取消后如何恢复？数据如何处理？ |
| 与已有设计有冲突 | 新需求与已记录设计矛盾 | 指出冲突，确认以哪个为准 |

### 提问原则

1. **集中提问**：所有不清楚的点一次性列出
2. **给出选项**：提供 2-3 个候选方案，而非开放性问题
3. **标注影响**：说明不同选择会带来什么后果
4. **区分优先级**：先问核心逻辑，次要细节可暂时搁置

### 禁止行为

- ❌ 凭经验/直觉假设产品逻辑
- ❌ 用"通常来说"、"一般会"等模糊措辞蒙混过关
- ❌ 把多个不确定点拆成多轮对话逐个问

---

## 产品设计问题检查规范（必须遵守）

当用户要求检查产品设计是否有问题时：

### 问题定位要求

每个问题**必须**标注原文所在位置：

```
**问题描述**
位置：`features/xxx.md` > 章节名 > 具体条目
原文：「……」
```

### TODO / 待补充内容的处理

**除非用户明确要求检查 TODO**，否则：
- 标记为「待填写」「待补充」的内容**不作为问题点**列出
- 仅检查**已明确描述的内容**是否存在逻辑漏洞、自相矛盾

### 检查范围

| 检查点 | 说明 |
|--------|------|
| 内容自相矛盾 | 同一文件或跨文件的两处描述互相冲突 |
| 逻辑漏洞 | 某个操作/流程缺少必要的边界情况 |
| 描述不完整 | 某个已描述的功能缺少关键规则 |
| 跨文档不一致 | A 文件引用 B 文件，但两者描述对不上 |

---

## 如何使用本 Skill

1. **查找功能设计**：先看「功能模块目录」，找到对应 `features/xxx.md` 阅读
2. **新功能讨论**：参考产品原则，列出不确定点提问确认，设计完成后写入对应子文件
3. **子文件不存在**：说明该功能尚未设计，通过提问明确方案后再创建文件
4. **跨模块用户流程**：在主要 feature 文档里添加「完整流程」章节

---

## 自我进化协议

{按注入模板生成，侧重点：功能模块增删、设计原则演变、冲突处理经验}

> **注意**：本 skill 主文件保持索引角色，功能细节分散到 `features/` 子文件中。
> 当主文件接近体积上限时，优先将内容拆分到子文件，而非删减。
```

### 模板：promote

```markdown
---
name: {prefix}-promote
description: >
  {项目名} 开源项目推广工作流。README 优化、渠道策略、内容营销、社区建设。
  触发词：推广、promote、宣传、marketing、star、README 优化、写博文、发帖、开源推广。
version: 1.0.0
source: claude-skill-evo
---

# {项目名} 开源推广 Skill

> 项目仓库：{git remote URL}
> 当前阶段：{Phase 3 问答得到的推广阶段}

---

## 项目定位

| 维度 | 内容 |
|------|------|
| 一句话价值主张 | {Phase 3 问答提炼} |
| 目标受众 | {Phase 3 问答确认} |
| 差异化卖点 | {从 README 和代码功能中提取} |
| 所属生态 | {从技术栈推断，如 "Claude Code 生态"、"React 生态"} |

---

## README 优化清单

> README 是最高 ROI 的推广手段。每一项都直接影响路人转化为 star。

### 必备元素检查

| 元素 | 状态 | 说明 |
|------|------|------|
| 首屏一句话价值主张 | {扫描 README 检查} | 打开 10 秒内必须知道解决什么问题 |
| GIF / 截图演示 | {检查是否有图片引用} | 比文字有效 10 倍 |
| Quick Start（30 秒跑通） | {检查是否有安装命令} | 降低试用门槛 |
| Badges（CI / License / Stars） | {检查是否有 badge} | 建立可信度 |
| "Who is this for" 段落 | {检查是否有目标用户描述} | 帮读者自我筛选 |
| 对比表（With / Without） | {检查是否有对比} | 强化价值感知 |

### 优化动作

当用户触发 `/{prefix}-promote README` 时：
1. 读取当前 README.md
2. 逐项检查上表，标注 ✅ 已有 / ❌ 缺失
3. 对缺失项提供具体的补充建议（含示例文本）
4. 用户确认后直接编辑 README

---

## 推广渠道矩阵

### 第一梯队：精准社区（项目创建后 1 周内）

| 渠道 | 行动 | 注意事项 |
|------|------|---------|
| {生态相关的核心社区} | {根据技术栈定制，如 "Anthropic Discord #claude-code 频道"} | 用价值描述而非广告语气 |
| GitHub Discussions | 在 {相关项目} 的 Discussions 分享 | 先贡献再推广，不要冷启动硬推 |
| Awesome Lists | 提 PR 到 {相关的 awesome-xxx 仓库} | 确保项目质量配得上 awesome 标准 |

### 第二梯队：内容平台（1-2 周内）

| 渠道 | 内容类型 | 模板 |
|------|---------|------|
| Hacker News | Show HN 帖 | "Show HN: {项目名} – {一句话描述}" |
| Reddit | 技术分享帖 | 发到 {相关 subreddit} |
| dev.to / Medium | 技术博文 | "Why I Built {项目名}" 或 "{痛点} — Here's How to Fix It" |
| Twitter/X | 技术 Thread | 问题→方案→效果 三段式 |

### 第三梯队：中文社区（同步进行）

| 渠道 | 内容类型 |
|------|---------|
| V2EX（创意工坊/程序员节点） | 项目介绍 + 故事 |
| 掘金 | 技术博文 |
| 知乎 | 回答相关问题时自然引流 |

---

## 内容营销模板

### 博文大纲生成

当用户触发 `/{prefix}-promote 写博文` 时：

1. 确认目标渠道（英文 dev.to / 中文掘金 / 通用）
2. 生成大纲：
   - **标题**：痛点导向，不要产品名导向
   - **开头**：用真实场景描述问题（读者共鸣）
   - **中段**：展示方案（架构图 + 代码示例）
   - **结尾**：CTA（GitHub 链接 + 安装命令）
3. 用户确认大纲后，生成完整草稿

### Social Media 帖文生成

当用户触发 `/{prefix}-promote 发帖` 时：

1. 确认目标平台（Twitter/HN/V2EX/Reddit）
2. 按平台风格生成帖文：
   - **Twitter**：≤280 字，问题→方案→链接
   - **HN**：Show HN 格式，简洁直接
   - **V2EX**：口语化，带故事
   - **Reddit**：社区 tone，先给价值再 mention 项目

---

## 社区建设清单

### 降低贡献门槛

- [ ] 有 CONTRIBUTING.md
- [ ] 有 `good first issue` 标签的 issue
- [ ] Issue 和 PR 模板已配置
- [ ] 回复 issue/PR 的平均时间 < 24h

### 生态集成

- [ ] 在相关工具/框架中提供集成示例
- [ ] 在 README 中展示"谁在用"
- [ ] 被上游项目或 awesome list 收录

---

## 推广节奏（执行计划）

| 时间 | 动作 | 优先级 |
|------|------|--------|
| 本周 | README 优化（GIF + badges + Quick Start） | 🔴 高 |
| 本周 | 核心社区首发（{生态社区}） | 🔴 高 |
| 下周 | 技术博文（英文 + 中文各一篇） | 🟡 中 |
| 下周 | Awesome Lists PR | 🟡 中 |
| 持续 | 每周 1 条 Twitter 展示进展 | 🟢 常规 |
| 月度 | 深度技术博文引流 | 🟢 常规 |

---

## 推广效果追踪

| 指标 | 记录方式 |
|------|---------|
| GitHub Stars | 每次 promote 时自动读取 `gh repo view --json stargazerCount` |
| Forks | 同上 |
| 流量来源 | GitHub Insights（手动记录到此处） |
| 博文/帖子反馈 | 记录各渠道的浏览量和互动 |

---

## 避坑指南

| 陷阱 | 为什么 | 替代方案 |
|------|--------|---------|
| 刷 star（互 star 群） | GitHub 检测 + 虚假 star 不带来真实用户 | 靠内容和社区自然增长 |
| 只发一次就等着 | 推广是持续行为 | 按推广节奏持续执行 |
| 过早追求完美文档 | 先有用户反馈再完善 | README 够用即可，快速上线 |
| 广告语气发帖 | 社区反感 | 分享价值和经验，自然提及项目 |
| 忽略项目名和 description | 搜索引擎依赖元数据 | 确保 GitHub description 精准 |

---

## 自我进化协议

{按注入模板生成，侧重点：新渠道发现、推广效果反馈、README 优化点}

**Promote 专属进化**：每次执行推广动作后，记录渠道、内容类型和效果反馈。有效渠道提升优先级，无效渠道降级或移除。用户发现新的推广机会时，提议写入渠道矩阵。
```

---

## Phase 5: 验证 & 完成

### 5.1 生成后检查

```bash
# 验证所有 skill 文件存在
ls .claude/skills/*/SKILL.md

# 验证 CLAUDE.md 存在
ls .claude/CLAUDE.md

# 验证 frontmatter 格式
grep -h "^name:\|^version:" .claude/skills/*/SKILL.md

# 验证进化协议注入
grep -l "自我进化协议" .claude/skills/*/SKILL.md
```

### 5.2 完成报告

#### 首次初始化

```
✅ Skills 锻造完成！

已生成：
📄 .claude/CLAUDE.md
📂 .claude/skills/{prefix}-skill/SKILL.md    — 元技能（含进化引擎）
📂 .claude/skills/{prefix}-dev/SKILL.md      — 本地开发
📂 .claude/skills/{prefix}-commit/SKILL.md   — Git 提交
📂 .claude/skills/{prefix}-debug/SKILL.md   — Bug 修复（含记录库）
...

🧬 所有 skill 已注入「自我进化协议」（被动进化 + 体积守护）

使用方式：
  /{prefix}-dev         查看本地开发命令
  /{prefix}-commit      提交代码
  /{prefix}-debug      修复 bug
  /{prefix}-skill       管理/进化所有 skills（含进化分析）

💡 随时可以再次执行 /skill-evo 来优化和完善 skills。
```

#### 优化更新

```
✅ Skills 优化完成！

本次变更：
🔄 更新 2 个 skill：{prefix}-dev、{prefix}-debug
📝 version 变更：{prefix}-dev v1.0.0 → v1.0.1

💡 随时可以再次执行 /skill-evo 继续优化。
```

---

## 注意事项

### 多次执行安全

- **首次初始化**：如果 `.claude/CLAUDE.md` 已存在，**询问用户**是合并还是覆盖
- **优化模式**：只精确修改需要变化的部分，绝不全量覆盖
- **版本追踪**：每次更新自动递增 version patch 号，并记录到 evolution.log

### 保持精简

- 初始化生成的 skill 应为**起步版本**（v1.0.0）
- 内容宁少勿多，通过多次 /skill-evo 和进化协议逐步丰富
- 每个 skill 控制在 60-180 行，避免信息过载

### 文件安全

- 生成前先读取目标路径，确认不覆盖重要内容
- `.gitignore` 只追加不覆盖
- 不修改 `~/.claude.json` 或 `~/.claude/settings.json`

### 适配性

- 不假设特定的技术栈——skill 内容完全由扫描结果和问答驱动
- 对于不确定的答案，使用保守的默认值
- 用户说"不需要"的功能，不要强行添加

### 进化协议一致性

- 每个生成的 skill 必须包含「自我进化协议」章节
- 协议结构统一：进化信号表 + 确认流程 + Size Guard
- 侧重点根据 skill 类型调整（参考进化侧重表）
- CLAUDE.md 中必须包含进化提示章节（让所有对话都能触发进化）
登录后下载/点赞/收藏 ❤ 2 | ★ 0
skill-evo

目录结构

SKILL.md

举报内容

提示
