优化skill提示词

openspec/specs/skill-progressive-disclosure/spec.md

@@ -0,0 +1,83 @@
+# skill-progressive-disclosure
+
+## Purpose
+
+定义 skill 的渐进式披露（Progressive Disclosure）结构规范，将 skill 内容按加载时机分为三层：YAML 前置元数据、SKILL.md 正文、references/ 详细文档。通过分层加载减少 token 消耗，提高 Claude 的响应效率。
+
+## Requirements
+
+### Requirement: 三层渐进式披露结构
+
+每个 skill 目录 SHALL 采用三层渐进式披露结构，按加载时机分为：第一层（YAML 前置元数据）、第二层（SKILL.md 正文）、第三层（references/ 目录）。
+
+#### Scenario: skill 目录包含完整三层结构
+- **WHEN** 检查任意 skill 目录结构
+- **THEN** 目录 SHALL 包含 SKILL.md 文件和 references/ 子目录
+
+#### Scenario: 第一层始终加载
+- **WHEN** Claude 启动会话时
+- **THEN** 所有 skill 的 YAML 前置元数据 SHALL 被加载到系统提示中
+
+### Requirement: YAML 前置元数据内容规范
+
+YAML 前置元数据 SHALL 仅包含触发判断所需的最小信息，使 Claude 能够判断何时使用该 skill。
+
+#### Scenario: 必需字段
+- **WHEN** 编写 SKILL.md 的 YAML 前置元数据
+- **THEN** SHALL 包含 name 和 description 字段
+
+#### Scenario: description 格式
+- **WHEN** 编写 description 字段
+- **THEN** SHALL 同时包含「做什么」和「何时使用」两部分信息
+
+#### Scenario: description 长度限制
+- **WHEN** 检查 description 字段
+- **THEN** 内容 SHALL 少于 1024 个字符
+
+#### Scenario: runner skill 的 description 宽泛性
+- **WHEN** skill 用途为通用脚本执行（如 Python/JavaScript runner）
+- **THEN** description SHALL 保持宽泛，以匹配所有相关处理任务
+
+### Requirement: SKILL.md 正文内容规范
+
+SKILL.md 正文 SHALL 包含核心工作流程和关键指令，保持精简以减少 token 消耗。
+
+#### Scenario: SKILL.md 必需章节
+- **WHEN** 编写 SKILL.md 正文
+- **THEN** SHALL 包含以下章节：Purpose、When to Use、Quick Reference、Workflow、References 链接
+
+#### Scenario: SKILL.md 长度建议
+- **WHEN** 检查 SKILL.md 总字数
+- **THEN** 建议控制在 5000 字以内（含 YAML 前置元数据）
+
+#### Scenario: 详细内容迁移
+- **WHEN** SKILL.md 包含详细示例、完整错误处理、最佳实践等冗长内容
+- **THEN** 这些内容 SHALL 迁移到 references/ 目录，SKILL.md 中保留链接引用
+
+### Requirement: references 目录结构规范
+
+每个 skill SHALL 包含 references/ 子目录，用于存放按需加载的详细文档。
+
+#### Scenario: references 目录存在性
+- **WHEN** 检查 skill 目录结构
+- **THEN** SHALL 存在 references/ 子目录
+
+#### Scenario: references 文件分类
+- **WHEN** 组织 references/ 目录内容
+- **THEN** SHALL 按主题分类为独立的 markdown 文件，如 examples.md、error-handling.md、best-practices.md
+
+#### Scenario: SKILL.md 引用 references
+- **WHEN** SKILL.md 需要引用详细文档
+- **THEN** SHALL 在 SKILL.md 中明确列出 references/ 中的文件并说明用途
+
+### Requirement: 内容迁移完整性
+
+从 SKILL.md 迁移内容到 references/ 时，SHALL 确保所有原有信息被完整保留。
+
+#### Scenario: 迁移前后对比
+- **WHEN** 完成单个 skill 的内容迁移
+- **THEN** references/ 中的文件 SHALL 包含原 SKILL.md 中被移除的所有详细内容
+
+#### Scenario: 功能不变性
+- **WHEN** 完成结构优化后
+- **THEN** skill 的功能逻辑 SHALL 保持不变，仅文档结构发生变化