CLAUDE.md · diff
git:20260124.b073d29 to git:20260125.8410184
17 added, 664 removed. Audit A to A.
# 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 # 项目变更记录（强制性）
- ```
+ @./AGENTS.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/)`
+ - **文件**：`[filename.md](路径/filename.md)`
+ - **特定行**：`[filename.md:42](路径/filename.md#L42)`
+ - **行范围**：`[filename.md:42-51](路径/filename.md#L42-L51)`
+ - **目录**：`[目录名/](路径/目录名/)`
### 任务管理
- 使用 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` 检查一致性
+ ### 与 AGENTS.md 的关系
- ---
+ - **AGENTS.md**：跨平台通用项目指令（Single Source of Truth）
+ - **CLAUDE.md**：通过 `@./AGENTS.md` 自动引用 + Claude Code 特定适配
+ - **维护流程**：
+ 1. 修改 AGENTS.md（唯一需要手动维护的项目指令文件）
+ 2. CLAUDE.md 会自动读取最新的 AGENTS.md 内容
+ 3. 无需运行任何同步命令
+ - **参考文档**：
+ - AGENTS.md 标准：https://agents.md/
+ - Claude Code @ 引用语法：https://github.com/anthropics/claude-code/issues/990
- **提示**：修改本文档后，请立即在 [CHANGELOG.md](CHANGELOG.md) 中记录变更。这是项目管理的强制性要求，不是可选项。
+ **提示**：修改 AGENTS.md 后，请立即在 [CHANGELOG.md](CHANGELOG.md) 中记录变更。这是项目管理的强制性要求，不是可选项。