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