77 lines
3.4 KiB
Markdown
77 lines
3.4 KiB
Markdown
## 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 消耗 |
|