# Skills 开发流水线 - Claude Code 项目指令

你正在 `/Users/bensz/Nutstore Files/PythonCloud/Agents/pipelines/skills` 中工作：该目录用于开发与维护一组"可复用 Agent Skills"。

## 项目目标

本项目是 **Agent Skills 开发流水线**：用于创建、优化和维护高质量、可复用的 AI Agent Skills。所有技能遵循 [Agent Skills 开放标准](https://agentskills.io)，确保在 Claude Code、OpenAI Codex、Cursor 等多个平台间"编写一次，随处使用"。

**核心价值**：
- 提供标准化的技能开发框架和工作流
- 确保技能质量（安全性、可靠性、通用性）
- 支持有机迭代和持续优化

## 核心工作流

当用户提出 Skills 开发相关需求时，按以下流程执行：

### 1. 任务理解

- 理解用户的真实需求：新建技能 / 优化现有技能 / 修复问题
- 确认任务范围和预期输出
- 识别可能的依赖和约束

### 2. 执行流程

**新建技能**：
```
需求确认 → 创建结构 → 编写 SKILL.md → 添加配置/脚本 → 质量检查 → 测试验证 → 系统安装
```

**优化技能**：
```
分析现状 → 规划改进 → 有机更新 → 自检验证 → 轻量测试 → 记录变更
```

### 3. 交付验证

- 通过有机更新检查清单
- 通过技能质量六大原则验证
- 记录所有变更到 [CHANGELOG.md](CHANGELOG.md)

## 工程原则

本项目遵循以下工程原则：

| 原则 | 核心思想 | 在本项目中的体现 |
|------|----------|------------------|
| **KISS** | Keep It Simple, Stupid | 追求极致简洁，避免过度设计 |
| **YAGNI** | You Aren't Gonna Need It | 只实现当前需要的功能 |
| **DRY** | Don't Repeat Yourself | 相似逻辑应抽象复用 |
| **SOLID** | 面向对象设计五大原则 | 单一职责、开闭原则等 |
| **关注点分离** | Separation of Concerns | 不同层次逻辑应分离 |
| **奥卡姆剃刀** | 如无必要，勿增实体 | 优先选择最简单的解决方案 |
| **最小惊讶原则** | Principle of Least Astonishment | API 行为应符合用户直觉 |
| **早期返回原则** | Early Return | 尽早返回，减少嵌套 |

**原则冲突时的决策优先级**：
1. **正确性 > 一切**
2. **简洁性 > 灵活性**
3. **清晰性 > 性能**
4. **扩展性 > 紧凑性**

## 高质量技能开发原则

基于实战经验总结，开发高质量 Agent Skills 需遵循以下六大原则：

### 1. 硬编码/AI 功能规划

**核心思想**：合理划分确定性与灵活性的边界

| 层级 | 处理方式 | 典型场景 |
|------|----------|----------|
| **确定性操作** | 硬编码到 scripts/ | 文件解析、数据验证、格式转换 |
| **启发式判断** | AI 动态处理 | 需求理解、方案设计、内容生成 |
| **可配置参数** | 提取到 config.yaml | 阈值、路径、模板、选项 |

**实践要点**：
- ❌ 避免：让 AI 反复编写相同的代码逻辑
- ✅ 推荐：将重复性、确定性操作脚本化
- ❌ 避免：硬编码会变化的业务逻辑
- ✅ 推荐：将可配置参数集中到 config.yaml

**Skill 脚本路径感知机制**：

当 skill 被安装到 `~/.claude/skills/` 或 `~/.codex/skills/` 后，其脚本需要能够正确识别自身的绝对路径，以便访问同 skill 内的 `config.yaml`、`assets/`、`references/` 等资源。

**标准实现模式**：

```python
# 在脚本文件中获取 skill 根目录
# 假设脚本位于 {skill_name}/scripts/script.py

# 模式1：使用 parent 索引（推荐）
skill_root = Path(__file__).resolve().parents[1]  # 向上两级到 skill 根目录

# 模式2：显式使用 parent.parent
skill_root = Path(__file__).resolve().parent.parent

# 访问 skill 内资源
config_path = skill_root / "config.yaml"
assets_dir = skill_root / "assets"
references_dir = skill_root / "references"
```

**关键原则**：
- ✅ **始终使用 `Path(__file__).resolve()`**：获取脚本文件的绝对路径，自动解析符号链接
- ✅ **基于 `__file__` 计算相对路径**：无论 skill 安装到何处，都能正确定位资源
- ❌ **禁止使用 `Path.cwd()` 或 `os.getcwd()`**：这会返回用户当前工作目录，而非 skill 目录
- ❌ **禁止硬编码绝对路径**：如 `/Users/xxx/skills/xxx`，这会在安装后失效

**实践示例**：

```python
# ✅ 正确：基于 __file__ 的相对路径
from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parents[1]
CONFIG_PATH = SKILL_ROOT / "config.yaml"
ASSETS_DIR = SKILL_ROOT / "assets"

def load_config():
    return yaml.safe_load(CONFIG_PATH.read_text(encoding="utf-8"))

# ❌ 错误：使用当前工作目录
SKILL_ROOT = Path.cwd()  # 这会返回用户的工作目录，而非 skill 目录

# ❌ 错误：硬编码绝对路径
SKILL_ROOT = Path("/Users/xxx/pipelines/skills/xxx")
```

**跨平台兼容性**：
- 使用 `Path` 对象而非字符串拼接，自动处理路径分隔符（`/` vs `\`）
- 使用 `.resolve()` 规范化路径，解析 `..` 和符号链接
- 使用 `encoding="utf-8"` 显式指定文件编码，避免平台差异

### 2. 多轮 AI 自检 + 人类监督 + 时刻轻量测试

**核心思想**：建立可重复的优化循环，确保每次变更都可验证

```
┌─────────────────────────────────────────────────────────┐
│  优化循环（Repeatable Optimization Loop）                │
├─────────────────────────────────────────────────────────┤
│  1. AI 自检：静态分析（代码-文档一致性、逻辑推演）         │
│  2. 人类监督：审查关键决策和变更范围                      │
│  3. 轻量测试：验证核心功能（非全面测试）                   │
│  4. 记录结果：在 CHANGELOG.md 中记录变更                  │
│  5. 迭代优化：根据测试结果调整（回到步骤1）                │
└─────────────────────────────────────────────────────────┘
```

**实践要点**：
- 每次变更后，在 `tests/{test_name}/` 目录下进行轻量测试
- 测试目录必须包含：规划文档（PLAN.md）和测试报告（REPORT.md）
- 所有中间文件保存在测试目录，不污染项目主目录

### 3. 冗余残留错误检查

**核心思想**：每次更新时主动清理冗余和残留

**检查清单**：
- [ ] **冗余检查**：是否存在重复逻辑或可合并的相似代码？
- [ ] **残留检查**：删除功能后，相关引用是否全部清理？
- [ ] **一致性检查**：YAML frontmatter、SKILL.md、config.yaml 三者是否一致？
- [ ] **版本号检查**：确认版本号仅在 config.yaml 中记录，SKILL.md 和 README.md 中是否存在冗余的版本号记录？
- [ ] **僵尸检查**：是否存在未被引用的文件或定义？

**实践要点**：
- 删除功能时，使用 Grep 工具全局搜索引用，确保彻底清理
- 定期检查 `references/` 目录，移除过时的参考文档
- 合并相似功能时，主动重构而非简单追加

### 4. 安全性检查

**核心思想**：预防常见安全漏洞和风险

**检查维度**：

| 维度 | 检查内容 | 典型风险 |
|------|----------|----------|
| **输入验证** | 用户输入是否充分验证 | 注入攻击、路径遍历 |
| **路径处理** | 文件路径是否规范化 | 路径遍历、任意文件写入 |
| **敏感信息** | 是否泄露密钥/凭证 | 凭证泄露 |
| **权限控制** | 文件操作权限是否合理 | 权限提升 |
| **外部调用** | 网络/系统调用是否安全 | SSRF、命令注入 |

**实践要点**：
- 文件路径始终使用正斜杠（跨平台兼容）
- 用户提供的路径需验证其在项目范围内的合法性
- 避免在日志或错误消息中泄露敏感信息
- 脚本错误处理要明确，不推诿给 AI 猜测

### 5. 过度设计检查

**核心思想**：用奥卡姆剃刀原则审视每个设计决策

**自问清单**：
- "这个功能当前是否真的需要？"（YAGNI）
- "是否有更简单的实现方式？"（KISS）
- "这个抽象是否增加了不必要的复杂性？"（奥卡姆剃刀）
- "用户是否会理解这个设计？"（最小惊讶原则）

**典型反模式**：
- ❌ 为"未来可能用到"的场景预留扩展点
- ❌ 引入多层抽象解决简单问题
- ❌ 提供过多可选配置，增加理解成本
- ❌ 过度泛化，导致代码难以理解

**推荐做法**：
- ✅ 只实现当前明确需要的功能
- ✅ 优先选择最直观的解决方案
- ✅ 提供合理的默认值，减少配置负担
- ✅ 当真正需要时再重构，而非提前过度设计

### 6. 通用性检查

**核心思想**：避免不必要的场景和年份限制，提高技能复用性

**检查清单**：
- [ ] **时间敏感性**：是否包含具体年份、日期等会过时的信息？
- [ ] **场景限制**：是否过度限定使用场景？
- [ ] **平台依赖**：是否不必要地依赖特定平台或工具？
- [ ] **语言假设**：是否假设特定语言或文化背景？

**实践要点**：
- 使用相对时间描述（如"当前版本"而非"2025年版"）
- 描述功能时使用通用术语，避免特定品牌或产品
- 如需限定场景，在 YAML `description` 中说明，而非硬编码到工作流
- 提供扩展机制（如 config.yaml），而非写死配置

## 默认语言

除非用户明确要求其他语言，始终使用简体中文与用户对话与撰写文档/说明。

## 联网与搜索

默认优先使用项目内文件与本地上下文；确需联网获取信息时，优先使用本地 SearXNG（如已通过 MCP 配置）。仅当 SearXNG 不足以满足需求时再使用其它联网手段，并说明原因与保留关键链接。

### 文件访问边界

- **Prompts.md**：开发者私有的 Prompt 库，包含常用工作流和模板。AI 不应主动读入此文件，除非用户明确要求。
  - 理由：Prompts.md 是开发者的"个人笔记"，用于手动调用特定流程，不是 AI 自动执行的规范
  - 正确做法：优先根据项目指令（AGENTS.md）和上下文理解需求；仅在用户明确引用 Prompts.md 内容时才读入

## 目录结构

```
skills/
├── {skill_name}/           # 每个 skill 一个子目录
│   ├── SKILL.md            # 必需：技能定义（YAML frontmatter + Markdown）
│   ├── README.md           # 推荐：用户使用指南
│   ├── config.yaml         # 推荐：技能参数配置
│   ├── scripts/            # 可选：可执行脚本
│   ├── references/         # 可选：参考文档
│   ├── assets/             # 可选：模板/资源文件
│   └── test/               # 可选：测试目录
├── AGENTS.md               # 本文档：项目指令
├── CLAUDE.md               # Claude Code 特定指令
├── Prompts.md              # 工作流与定义（优先级最高）
└── CHANGELOG.md            # 项目变更记录（强制性）
```

## Claude Code 特定说明

### 文件引用规范

在 Claude Code 中引用文件时，使用 markdown 链接语法：
- 文件：`[filename.md](path/to/filename.md)`
- 特定行：`[filename.md:42](path/to/filename.md#L42)`
- 行范围：`[filename.md:42-51](path/to/filename.md#L42-L51)`
- 目录：`[目录名/](path/to/directory/)`

### 任务管理

- 使用 TodoWrite 工具跟踪复杂任务的进度
- 完成任务后及时标记为 completed
- 拆分大任务为可管理的小步骤

### 代码变更规范

- 修改代码前先使用 Read 工具阅读文件
- 优先使用 Edit 工具进行精确修改
- 避免不必要的格式化或重构

### 语义发现机制

Claude Code 使用**语义匹配**触发技能，因此：

**YAML `description` 的特殊地位**：
- 它是技能的"语义入口"——决定了技能何时被触发
- 更新 `description` 时，必须考虑其对发现机制的影响

**更新实践**：
- 新增触发场景 → 补充 `metadata.keywords`
- 工作流变化 → 同步更新 `description`
- 技能定位变化 → 更新 `name` 和 `metadata.short-description`

### Progressive Disclosure 体现

Claude Code 的加载机制天然支持三层渐进披露：

| 层级 | 加载时机 | 有机更新要点 |
|------|----------|--------------|
| **YAML frontmatter** | 会话启动时 | 确保 `name` 和 `description` 准确反映核心价值 |
| **SKILL.md 正文** | 技能触发时 | 保持简洁，只包含 AI 执行所需的核心信息 |
| **references/** | 按需加载 | 将详细策略、标准、参考文档独立存放 |

## 有机整体更新原则

本项目的技能迭代遵循**有机整体更新**原则，而非简单的补丁式修补。

### 核心理念

**❌ 补丁式更新**（避免）：
```
用户："加一条规则：输出文件要按日期命名"
AI：在文档末尾添加："2025-12-29 更新：文件按日期命名"
```

**✅ 有机更新**（倡导）：
```
用户："加一条规则：输出文件要按日期命名"
AI：理解意图 → 定位文件命名规则在工作流中的位置 →
    整合到相关章节（如"输出规范"） →
    检查是否与其他规则冲突 →
    重构该章节以保持内聚性 →
    更新相关示例以保持一致性
```

### 操作原则

1. **理解而非记录**：在更新前，先理解用户需求背后的意图
2. **定位生态位**：每条规则都应找到其在文档结构中的位置
3. **协调生长**：更新一个部分时，检查并同步更新相关部分
4. **保持呼吸感**：文档应像生物体一样有逻辑流动，而非割裂的清单
5. **定期修剪整合**：当章节臃肿时，主动重构

### 表头-正文一致性原则

**YAML frontmatter 不是静态元数据，而是技能的"活语义接口"**：

| 工作逻辑变更 | 表头同步更新 |
|-------------|-------------|
| 新增工作流步骤 | 更新 `description` 中的功能描述 |
| 修改输入参数 | 更新 `description` 中的参数说明 |
| 新增输出格式 | 更新 `description` 中的输出描述 |
| 扩展使用场景 | 补充 `metadata.keywords` |
| 调整技能定位 | 更新 `name` 和 `metadata.short-description` |

### 更新自检清单

在响应任何"更新/优化/修改"请求时，问自己：

- [ ] **意图理解**：我真正理解了用户想要解决什么问题吗？
- [ ] **生态位定位**：这个更新应该放在文档的哪个位置？
- [ ] **影响范围**：这个更新会影响其他哪些章节？
- [ ] **冲突检查**：新内容是否与现有规则冲突？
- [ ] **术语一致性**：我是否使用了与文档其他部分一致的术语？
- [ ] **示例同步**：相关示例是否反映了新的规则？
- [ ] **内聚性保持**：更新后，该章节是否仍然围绕一个清晰的核心主题？
- [ ] **表头一致性**：我是否检查并更新了 YAML frontmatter？

## 技能开发流程

### 新建技能流程

1. **需求确认**：
   - 阅读 [Prompts.md](Prompts.md)，确认是否属于"创建/优化 skill"
   - 获取 `skill_name`（用户指定或自取 1-3 个候选）

2. **创建结构**：
   - 创建 `{skill_name}/` 目录
   - 生成 `SKILL.md`（包含 YAML frontmatter）
   - 按需添加 `config.yaml`、`scripts/`、`references/`、`assets/`

3. **质量检查**：
   - 通过"六大质量原则"验证
   - 运行静态自检清单

4. **生成用户文档**：
   - 使用 **write-skill-readme** skill 生成用户友好的 README.md
   - README.md 面向使用者，说明如何触发和使用技能
   - SKILL.md 面向 AI，定义执行规范和工作流

5. **测试验证**：
   - 在 `tests/{test_name}/` 进行轻量测试
   - 生成测试报告

6. **系统安装**：
   - 运行 `python3 install-bensz-skills/scripts/install.py`
   - 验证技能在任意项目中可被发现

### 优化技能流程

1. **分析现状**：
   - 使用 auto-test-skill 分析问题
   - 将问题记录到 `{skill_name}/suggestions/Problems_from_xxx.md`

2. **规划改进**：
   - 制定优化计划（plans/v{timestamp}.md）
   - 明确 P0-P2 优先级

3. **有机更新**：
   - 按照有机整体更新原则修改
   - 同步更新相关文件和示例

4. **更新用户文档（强制）**：
   - **每次优化 skill 后，如有功能变化或新增，必须使用 write-skill-readme skill 重新优化 README.md**
   - 确保 README.md 与 SKILL.md、config.yaml 保持一致
   - 这是保证用户文档与技能实现同步的关键步骤

5. **自检验证**：
   - 运行静态自检清单
   - 检查六大质量原则

6. **轻量测试**：
   - 在测试目录验证核心功能
   - 记录测试结果

7. **记录变更**：
   - 更新 `{skill_name}/CHANGELOG.md`
   - 同步更新项目级 [CHANGELOG.md](CHANGELOG.md)

## Agent Skills 标准规范

### 必需结构

每个 skill 必须包含 `SKILL.md` 文件，格式如下：

```yaml
---
name: skill-name
description: Brief description of what this Skill does and when to use it
---

# Skill Title（Markdown body）

[技能说明、工作流程、使用指南等]
```

### 技能触发条件设计原则

**核心问题**：技能触发条件过于宽泛会导致 AI 在不恰当的场景下误触发技能，影响用户体验和开发效率。

**设计原则**：

| 原则 | 说明 | 示例 |
|------|------|------|
| **精确边界** | `description` 应明确界定触发条件，而非列举所有可能场景 | ✅ "用户明确要求'测试技能'时使用"<br>❌ "用于技能/项目迭代时" |
| **精简关键词** | `keywords` 只保留核心关键词，移除同义词和变体 | ✅ 保留 3-5 个核心术语<br>❌ 列举 10+ 个同义词 |
| **负向约束** | 明确说明不适用场景，避免误触发 | ✅ "以下情况不适用：用户只是想优化功能"<br>❌ 无边界说明 |
| **避免"等场景"** | "等场景"暗示更多未列举场景，扩大触发范围 | ✅ 明确列举适用场景<br>❌ "适用于XXX等场景" |

**实践要点**：

1. **`description` 应使用"当用户明确要求"句式**
   - ✅ "当用户明确要求'提交 Git 改动'时使用"
   - ❌ "当用户要提交 Git 改动时使用"

2. **`keywords` 应控制在 3-5 个核心术语**
   - ✅ 保留：`git commit`, `conventional commit`, `commit message`
   - ❌ 删除：`提交代码`, `提交改动`, `自动提交`, `拆分提交`（同义词）

3. **添加负向约束明确边界**
   ```yaml
   description: |
     当用户明确要求"测试技能"或"运行 auto-test"时使用。

     ⚠️ 以下情况不适用：
     - 用户只是想优化/改进某个功能（应直接修改）
     - 用户只是询问技能问题（应直接回答）
     - 没有明确"测试"意图的一般性开发
   ```

4. **避免"适用于XXX等场景"句式**
   - ✅ "用于以下场景：场景A、场景B、场景C"
   - ❌ "适用于场景A、场景B、场景C等场景"

### YAML frontmatter 规范

| 字段 | 必需性 | 规范 |
|------|-------|------|
| `name` | 必需 | 小写字母、数字、连字符；最大 64 字符；推荐动名词形式 |
| `description` | 必需 | 最大 1024 字符；使用"当用户明确要求"句式；可包含负向约束 |
| `metadata.short-description` | 可选 | 单行概览（用于 UI 显示） |
| `metadata.keywords` | 可选 | 3-5 个核心关键词；避免同义词和变体 |

### 推荐文件结构

| 文件 | 必需性 | 面向对象 | 核心作用 |
|------|-------|---------|---------|
| **SKILL.md** | 必需 | AI | 定义工作流、输入输出、验证标准 |
| **README.md** | 推荐 | 用户 | 教用户如何触发和使用技能 |
| **config.yaml** | 推荐 | 维护者 | 集中管理可配置参数和版本号 |
| **scripts/** | 可选 | 执行引擎 | 需要确定性可靠性的自动化任务 |
| **references/** | 可选 | AI（按需） | 详细策略、标准、领域知识 |
| **assets/** | 可选 | 输出生成 | 模板、图标、字体等资源 |

### SKILL.md 格式约束原则

**核心思想**：SKILL.md 是 AI 执行时的核心输入，必须保持简洁、聚焦、高效，避免信息过载和认知负荷。

| 约束项 | 限制 | 理由 |
|--------|------|------|
| **主体长度** | ≤ 500 行 | 控制上下文窗口占用，确保 AI 能完整理解 |
| **Frontmatter 字段** | name ≤ 64 字符<br>description ≤ 1024 字符 | 符合 Agent Skills 开放标准，避免触发失败 |
| **Token 预算** | ≤ 5,000 tokens（约 500 行） | 确保技能加载时不会占用过多上下文 |
| **引用层级** | 仅一层深度 | 避免 SKILL.md → advanced.md → details.md 的深层嵌套 |
| **冗余内容** | 版本历史移至 CHANGELOG.md<br>宣传性内容移至 README.md | 保持 SKILL.md 聚焦功能规范，减少噪声 |

**实践要点**：
- ❌ 避免：在 SKILL.md 中添加"版本历史"章节
- ❌ 避免：用多层引用分散内容（应保持扁平化或集中到 references/）
- ❌ 避免：添加宣传性标记（如"新增"、"v2.x.0 新增"）
- ✅ 推荐：当 SKILL.md 接近 500 行时，主动拆分详细内容到 references/
- ✅ 推荐：使用 Progressive Disclosure 策略——核心逻辑在 SKILL.md，细节在 references/

**与用户私有指令的一致性**：
本项目遵循 `/Users/bensz/.claude/CLAUDE.md` 中定义的"文档编写设计哲学"：
- 移除版本标记和宣传性内容，聚焦功能本身
- 标题不使用序号前缀（用 `##` 而非 `## 1)`）
- CHANGELOG.md 作为唯一版本真理来源

## 技能版本号管理规范

**核心原则**：所有技能的版本号统一通过 config.yaml 管理（Single Source of Truth），确保版本信息的一致性和可追溯性。

### 技能配置文件结构

每个技能的 `config.yaml` 应包含以下结构：

```yaml
# 技能基本信息
skill_info:
  name: skill-name          # 技能名称（与 SKILL.md 的 name 字段一致）
  version: 1.0.0            # 版本号（遵循语义化版本规范）
  description: "技能简短描述"  # 与 SKILL.md 的 description 保持一致
  category: "技能分类"       # 如：数据处理、文档生成、测试等

# 可配置参数
# ... 其他配置项 ...
```

### 版本号命名规则

遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范：

| 版本类型 | 格式 | 使用场景 |
|---------|------|----------|
| **稳定版** | `v1.0.0` 及以上 | 技能已稳定可用 |
| **开发中** | `v0.x.x` | 功能开发中，可能有较大变更 |
| **实验性** | `v0.0.x` | 早期实验阶段，API 不稳定 |

版本号格式：`主版本号.次版本号.修订号`
- **主版本号**：不兼容的 API 修改
- **次版本号**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正

### 版本同步机制

**核心规则**：版本号仅在 `config.yaml` 中记录（Single Source of Truth），其他任何地方**不得直接记录版本号**，只能通过引用 config.yaml 获取。

| 文件 | 版本号处理方式 | 说明 |
|------|--------------|------|
| **config.yaml** | **唯一记录处** | 版本号的唯一来源，遵循语义化版本规范 |
| **SKILL.md** | ❌ **禁止直接记录** | 不得在 YAML frontmatter 或正文中直接记录版本号 |
| **README.md** | 仅引用 | 在文档中说明"版本号见 config.yaml:skill_info.version" |
| **CHANGELOG.md** | 仅引用 | 在版本条目标题中使用，但本质是记录变更历史，非版本号存储 |

**实践要点**：
- ❌ **禁止**：在 SKILL.md 的 YAML frontmatter 中添加 `metadata.version` 字段
- ❌ **禁止**：在 SKILL.md 正文中直接写明"当前版本：v1.0.0"
- ❌ **禁止**：在 README.md 中硬编码版本号（如"最新版本 v1.0.0"）
- ✅ **推荐**：在 README.md 中写明"版本信息见 config.yaml:skill_info.version"
- ✅ **推荐**：使用脚本或构建工具动态读取 config.yaml 中的版本号（如需要）

### 新建技能时的版本号初始化

创建新技能时：

1. **初始化 config.yaml**，设置版本为 `v0.1.0`（开发中版本）
2. **在 CHANGELOG.md 添加初始版本**：

```markdown
## [0.1.0] - YYYY-MM-DD

### Added（新增）
- 初始化技能，实现核心功能
```

### 版本号更新时机

| 变更类型 | 版本更新示例 | 说明 |
|---------|-------------|------|
| Bug 修复 | `1.0.0` → `1.0.1` | 修复问题，不改变功能 |
| 新增功能 | `1.0.0` → `1.1.0` | 向下兼容的新功能 |
| 破坏性变更 | `1.0.0` → `2.0.0` | 不兼容的 API 变更 |

**实践要点**：
- 每次更新技能时，首先评估变更类型
- 根据变更类型更新 config.yaml 中的版本号
- 立即在 CHANGELOG.md 中记录变更内容
- ❌ 不要在其他文件中记录或同步版本号（保持 config.yaml 为唯一来源）

### 版本号检查命令

快速检查技能版本号：

```bash
# 查看 config.yaml 中的版本号
grep -A 3 "skill_info:" {skill_name}/config.yaml | grep "version"

# 检查所有技能的版本号
find . -name "config.yaml" -exec grep -l "skill_info" {} \; | while read f; do echo "$f:"; grep -A 3 "skill_info" "$f" | grep "version"; done
```

### 与有机更新原则的集成

版本号管理是**有机整体更新**的一部分：

- **理解意图**：版本变更的目的是什么？（修复/增强/重构）
- **定位生态位**：变更属于哪个版本类型？（修订/次版本/主版本）
- **协调生长**：版本号更新后，同步更新 CHANGELOG.md 和相关文档
- **记录变更**：在 CHANGELOG.md 中详细记录每个版本的具体变更

## 变更边界

- 只修改 `pipelines/skills/` 内文件，除非用户明确授权扩展到其它目录
- 不批量重写与当前任务无关的文档与结构；保持最小可用、可迭代
- 修改技能时，优先优化而非重写，保留用户自定义内容

## 变更记录规范

**重要原则**：凡是项目的更新，都要统一在 `CHANGELOG.md` 文件里记录。

### 记录范围

每次修改以下内容时，必须更新 [CHANGELOG.md](CHANGELOG.md)：
- **项目指令文件**：[CLAUDE.md](CLAUDE.md)、[AGENTS.md](AGENTS.md) 的任何修改
- **技能核心文件**：SKILL.md、config.yaml 的修改
- **项目结构变更**：新增/删除/重命名目录或关键文件
- **工作流变更**：核心工作流程的调整
- **工程原则变更**：新增、修改或删除工程原则
- **重要配置变更**：影响项目行为的配置文件修改

### 记录格式

遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 格式：

```markdown
## [版本号] - YYYY-MM-DD

### Added（新增）
- 新增了 XXX 功能/章节：用途是 YYY

### Changed（变更）
- 修改了 XXX 章节：原因是 YYY，具体变更内容是 ZZZ

### Fixed（修复）
- 修复了 XXX 问题：表现是 YYY，修复方式是 ZZZ
```

### 记录时机

- **修改前**：先在 [CHANGELOG.md](CHANGELOG.md) 的 `[Unreleased]` 部分草拟变更内容
- **修改后**：完善变更描述，添加具体细节和影响范围
- **发布时**：将 `[Unreleased]` 内容移至具体版本号下

## 技能加载路径

Claude Code 从以下路径加载技能（按优先级）：

1. **项目级技能**：`{项目根目录}/.claude/skills/`
2. **用户级技能**：`~/.claude/skills/`

## 与 AGENTS.md 的关系

- **[AGENTS.md](AGENTS.md)**：OpenAI Codex CLI 项目指令（主文件）
- **[CLAUDE.md](CLAUDE.md)**：基于 AGENTS.md 适配的 Claude Code 版本（本文件）
- 两个文件的核心内容保持一致，仅平台特定说明有差异

**同步机制**：
- 运行 `python3 init-project/scripts/generate.py --sync-from agents` 从 AGENTS.md 同步到 CLAUDE.md
- 运行 `python3 init-project/scripts/generate.py --check-consistency` 检查一致性

---

**提示**：修改本文档后，请立即在 [CHANGELOG.md](CHANGELOG.md) 中记录变更。这是项目管理的强制性要求，不是可选项。