3.4 KiB
3.4 KiB
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 保持不变，仅文档结构发生变化