优化skill提示词
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-25
|
||||
@@ -0,0 +1,76 @@
|
||||
## Context
|
||||
|
||||
当前项目包含 4 个 skills（lyxy-runner-python、lyxy-runner-js、lyxy-reader-office、lyxy-kb），每个 SKILL.md 文件内容在 200-300 行之间。根据 `document/the-complete-guide-to-building-skill.md` 中的渐进式披露原则，SKILL.md 应保持精简（建议 5000 字以内），详细文档应放在 `references/` 目录中。
|
||||
|
||||
**当前状态**：
|
||||
- SKILL.md 包含完整的工作流程、示例、错误处理、最佳实践等所有内容
|
||||
- 无 references/ 目录结构
|
||||
- 每次 Claude 加载 skill 时需要处理全部内容
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 遵循三层渐进式披露结构：YAML 前置元数据 → SKILL.md 核心指令 → references/ 详细文档
|
||||
- 减少 skill 加载时的 token 消耗
|
||||
- 保持 lyxy-runner-python 和 lyxy-runner-js 的 description 宽泛性
|
||||
- 为 4 个现有 skills 创建 references/ 目录并迁移内容
|
||||
|
||||
**Non-Goals:**
|
||||
- 不修改 skill 的功能逻辑
|
||||
- 不修改 scripts/ 目录中的可执行代码
|
||||
- 不新增 skill 或删除现有 skill
|
||||
|
||||
## Decisions
|
||||
|
||||
### 决策 1：三层结构内容划分
|
||||
|
||||
| 层级 | 位置 | 内容 | 加载时机 |
|
||||
|-----|------|------|---------|
|
||||
| 第一层 | YAML 前置元数据 | name、description、compatibility | 始终加载到系统提示 |
|
||||
| 第二层 | SKILL.md 正文 | 核心工作流、关键命令、快速参考 | Claude 判断相关时加载 |
|
||||
| 第三层 | references/*.md | 详细示例、错误处理、最佳实践、API 参考 | 按需导航和发现 |
|
||||
|
||||
**理由**：遵循官方指南的渐进式披露原则，最小化 token 消耗的同时保持完整能力。
|
||||
|
||||
### 决策 2：SKILL.md 保留内容
|
||||
|
||||
每个 SKILL.md 正文保留以下核心部分：
|
||||
1. **Purpose**：简要说明用途和关键依赖
|
||||
2. **When to Use**：适用/不适用场景（简化版）
|
||||
3. **Quick Reference**：核心命令表格或流程图
|
||||
4. **Workflow**：简化的执行步骤
|
||||
5. **References 链接**：指向 references/ 中详细文档的链接
|
||||
|
||||
**理由**：保留足够信息让 Claude 完成任务，详细内容按需加载。
|
||||
|
||||
### 决策 3：references/ 目录结构
|
||||
|
||||
```
|
||||
references/
|
||||
├── examples.md # 详细示例
|
||||
├── error-handling.md # 错误处理和故障排除
|
||||
├── best-practices.md # 最佳实践和注意事项
|
||||
└── api-reference.md # API/命令参数详细说明（可选）
|
||||
```
|
||||
|
||||
**理由**：按主题分类，便于 Claude 按需定位和加载。
|
||||
|
||||
### 决策 4：Description 格式
|
||||
|
||||
采用统一格式：`[做什么] + [何时使用] + [关键能力]`
|
||||
|
||||
- lyxy-runner-python：保持 "Any task that requires Python processing should use this skill."（宽泛）
|
||||
- lyxy-runner-js：保持 "Any task that requires Javascript/Typescript processing should use this skill."（宽泛）
|
||||
- lyxy-reader-office：保持当前描述，已包含具体文件类型和操作
|
||||
- lyxy-kb：可优化添加用户触发短语
|
||||
|
||||
**理由**：runner skills 需要宽泛以匹配所有相关任务，reader/kb skills 可以更具体以精准触发。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
| 风险 | 缓解措施 |
|
||||
|-----|---------|
|
||||
| references/ 文件未被 Claude 发现 | 在 SKILL.md 中明确列出 references/ 文件并说明用途 |
|
||||
| 拆分后信息不完整 | 核心工作流程保留在 SKILL.md，确保基本任务可完成 |
|
||||
| 迁移过程中遗漏内容 | 逐个 skill 处理，对比前后内容确保完整性 |
|
||||
| 文件数量增加 | references/ 文件按需加载，不影响初始 token 消耗 |
|
||||
@@ -0,0 +1,30 @@
|
||||
## Why
|
||||
|
||||
当前 skills 的 SKILL.md 文件内容较长（200-300 行），未遵循渐进式披露（Progressive Disclosure）原则。根据 skill 编写指南，应采用三层结构：YAML 前置元数据（触发判断）→ SKILL.md 正文（核心指令）→ references/（详细文档）。这样可以减少 token 消耗，提高 Claude 的响应效率。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **结构优化**：为每个 skill 创建 `references/` 目录，将详细文档、示例、错误处理等内容从 SKILL.md 正文移至 references/
|
||||
- **SKILL.md 精简**：保留核心工作流程和关键指令，将详细说明改为链接到 references/ 中的文档
|
||||
- **Description 优化**：确保 description 同时包含「做什么」和「何时使用」两部分，便于 Claude 判断是否加载
|
||||
- **lyxy-runner-python/js 保持宽泛**：这两个 runner skill 的 description 需要保持宽泛，以便匹配所有 Python/JS 处理任务
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `skill-progressive-disclosure`: 定义 skill 渐进式披露的三层结构规范，包括 YAML 前置元数据、SKILL.md 正文、references/ 目录的职责划分和内容组织方式
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
（无现有 spec 需要修改）
|
||||
|
||||
## Impact
|
||||
|
||||
- **文件结构变更**：每个 skill 目录新增 `references/` 子目录
|
||||
- **SKILL.md 重构**：4 个 skills 的 SKILL.md 文件需要精简，详细内容迁移到 references/
|
||||
- `skills/lyxy-runner-python/SKILL.md`
|
||||
- `skills/lyxy-runner-js/SKILL.md`
|
||||
- `skills/lyxy-reader-office/SKILL.md`
|
||||
- `skills/lyxy-kb/SKILL.md`
|
||||
- **向后兼容**：功能不变，仅优化文档结构，**无破坏性变更**
|
||||
@@ -0,0 +1,77 @@
|
||||
## ADDED 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 保持不变，仅文档结构发生变化
|
||||
@@ -0,0 +1,45 @@
|
||||
## 1. lyxy-runner-python 结构优化
|
||||
|
||||
- [x] 1.1 创建 `skills/lyxy-runner-python/references/` 目录
|
||||
- [x] 1.2 提取示例代码到 `references/examples.md`
|
||||
- [x] 1.3 提取错误处理内容到 `references/error-handling.md`
|
||||
- [x] 1.4 提取最佳实践和注意事项到 `references/best-practices.md`
|
||||
- [x] 1.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
|
||||
- [x] 1.6 在 SKILL.md 末尾添加 References 链接章节
|
||||
- [x] 1.7 验证 description 保持宽泛（"Any task that requires Python processing..."）
|
||||
|
||||
## 2. lyxy-runner-js 结构优化
|
||||
|
||||
- [x] 2.1 创建 `skills/lyxy-runner-js/references/` 目录
|
||||
- [x] 2.2 提取示例代码到 `references/examples.md`
|
||||
- [x] 2.3 提取错误处理内容到 `references/error-handling.md`
|
||||
- [x] 2.4 提取最佳实践和输出处理到 `references/best-practices.md`
|
||||
- [x] 2.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
|
||||
- [x] 2.6 在 SKILL.md 末尾添加 References 链接章节
|
||||
- [x] 2.7 验证 description 保持宽泛（"Any task that requires Javascript/Typescript processing..."）
|
||||
|
||||
## 3. lyxy-reader-office 结构优化
|
||||
|
||||
- [x] 3.1 创建 `skills/lyxy-reader-office/references/` 目录
|
||||
- [x] 3.2 提取详细示例到 `references/examples.md`
|
||||
- [x] 3.3 提取解析器说明和依赖安装到 `references/parsers.md`
|
||||
- [x] 3.4 提取错误处理和限制说明到 `references/error-handling.md`
|
||||
- [x] 3.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
|
||||
- [x] 3.6 在 SKILL.md 末尾添加 References 链接章节
|
||||
|
||||
## 4. lyxy-kb 结构优化
|
||||
|
||||
- [x] 4.1 创建 `skills/lyxy-kb/references/` 目录
|
||||
- [x] 4.2 提取目录结构和文件格式详细说明到 `references/structure.md`
|
||||
- [x] 4.3 提取文档生命周期和处理策略到 `references/workflow.md`
|
||||
- [x] 4.4 提取渐进式查询策略到 `references/query-strategy.md`
|
||||
- [x] 4.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
|
||||
- [x] 4.6 在 SKILL.md 末尾添加 References 链接章节
|
||||
- [x] 4.7 优化 description 添加用户触发短语
|
||||
|
||||
## 5. 验证与收尾
|
||||
|
||||
- [x] 5.1 对比每个 skill 的原始 SKILL.md 和重构后内容，确保信息完整
|
||||
- [x] 5.2 验证每个 skill 的 references/ 目录包含必要文件
|
||||
- [x] 5.3 验证每个 SKILL.md 的 References 章节正确链接到 references/ 文件
|
||||
- [x] 5.4 验证所有 description 符合格式要求（<1024 字符）
|
||||
83
openspec/specs/skill-progressive-disclosure/spec.md
Normal file
83
openspec/specs/skill-progressive-disclosure/spec.md
Normal file
@@ -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 保持不变，仅文档结构发生变化
|
||||
Reference in New Issue
Block a user