skill optimization guide

Other Community
Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Other
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@openyida · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

# 技能文档优化指南

对技能包的 SKILL.md 进行结构优化,使其符合"导航枢纽"定位:精简、自包含、零冗余。

## 触发条件

- 用户要求优化某个技能包的文档结构、精简行数
- SKILL.md 超过 200 行,需要瘦身
- 多个章节存在重复内容,需要合并或抽取
- 完整代码块需要迁移到 references 或 samples
- 用户提到"技能优化"、"SKILL 瘦身"、"文档精简"

**不适用场景(不要触发)**:
- 技能包的功能开发或 bug 修复 → 直接编辑对应文件
- 静态诊断评分 → `skill-static-diagnosis`
- 运行时测试、接口联调 → 不在本技能范围

## 严格边界

- 本技能只修改文档结构,不修改技能的业务逻辑
- 抽取内容到 references 时,必须同步在 SKILL.md 中添加引用链接
- 不得删除信息,只能迁移——SKILL.md 删除的内容必须在 references 中保留
- 修改前必须先读取目标文件确认内容,避免破坏已有结构

## 优化目标

| 维度 | 目标 | 衡量标准 |
|------|------|---------|
| 精简度 | SKILL.md ≤ 200 行 | 大模型单次读取不超载 |
| 自包含 | 入口文件回答"怎么做"和"什么规则" | 不需跳转即可开始开发 |
| 零冗余 | 同一信息只在一个地方详细展开 | 任意两文件重叠率 ≤ 15% |
| 可验证 | 规则数、规则内容、代码示例三者对齐 | 模拟阅读零矛盾 |

## 执行步骤

### Step 1:现状评估

1. 统计目标 SKILL.md 行数(`wc -l`)
2. 识别重复章节——以下模式是合并信号:
   - "核心约束" + "严格禁止" + "严格要求" + "编码注意事项" → 合并为"核心规则"
   - 同一规则在多个章节出现 → 只保留一处
3. 检查与 references 的内容重叠:
   - SKILL.md 有完整代码示例 → 移到 references 或 samples
   - SKILL.md 有详细规范解释 → 移到 references,SKILL.md 只留摘要+引用

### Step 2:执行优化

按优先级处理:

1. **删除完整代码块**:替换为 `openyida sample` 命令引用或 references 链接
2. **合并重复章节**:多个约束/规则章节合并为统一的"核心规则"
3. **抽取详细内容**:JSON Schema、Prompt 模板、字段类型表等 → `references/*.md`
4. **补全引用链接**:每处抽取都必须在原位添加 `> 📖 详见 [references/xxx.md]` 引用

### Step 3:验证

1. 确认行数 ≤ 200
2. 确认所有 references 链接路径正确
3. 确认无信息丢失(抽取的内容在 references 中完整保留)

## 异常处理

| 异常场景 | 处理方式 |
|---------|----------|
| SKILL.md 已经 ≤ 200 行 | 告知用户无需优化,或仅做结构微调 |
| 无法判断哪些内容应抽取 | 优先抽取完整代码块和 JSON 示例,保留流程步骤和规则摘要 |
| references 目录不存在 | 先创建 `references/` 目录再写入文件 |
| 抽取后 SKILL.md 仍超 200 行 | 进一步合并重复章节,或将使用示例也抽取到 `references/examples.md` |

## SKILL.md 的导航枢纽原则

SKILL.md 是导航枢纽,不是内容倾倒场:

| 内容类型 | SKILL.md 中保留 | 详细内容放在 |
|---------|----------------|-------------|
| 规则 | 名称 + 一句话描述 | `references/*.md` |
| 代码 | `openyida sample` 命令 | `samples/*.js` |
| API | 速查表(方法名+说明+必填参数) | `yida-api.md` |
| 流程 | 完整保留(bash 步骤) | — |
| JSON Schema | 引用链接 | `references/*.md` |
| Prompt 模板 | 引用链接 | `references/*.md` |

## 完成检查清单

- [ ] SKILL.md ≤ 200 行
- [ ] SKILL.md 无完整代码块(只有 bash 命令和速查表)
- [ ] 所有抽取内容在 references 中完整保留
- [ ] 所有引用链接路径正确可达
- [ ] 参考文档导航表完整(含跨 skill 共享文档)

## 参考文档

| 文档 | 覆盖范围 | 何时阅读 |
|------|---------|---------|
| [优化方法论](references/optimization-methodology.md) | 三层职责模型、规则分级标准、代码去重规范、验证方法、反模式案例 | 首次执行优化前必读 |

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.