Skill Design Guide

---
name: skill-design-guide
description: Skill 设计指南。在创建新 Skill、优化现有 Skill、或评审 Skill 质量时使用。包含核心设计原则、常见陷阱、最佳实践。
---

# Skill 设计指南

> 核心思想：**Skills 的本质不是提示词增强，而是 Workflow 的迁移**

## Skill 是什么

Skill 是一个工程化的能力单元，不是高级 Prompt：

```
skill-name/
├── SKILL.md      # 核心：告诉 Agent "怎么做" 的调度入口
├── references/   # 知识层：API 文档、业务规则、历史案例
├── assets/       # 模板层：输出骨架、固定格式
├── scripts/      # 执行层：确定性任务的代码
└── hooks/        # 约束与观测：记录调用、控制权限
```

## Skill 解决的三大痛点

1. **提示词臃肿** — 复杂任务需要几百上千字 Prompt，难维护，模型注意力分散
2. **上下文窗口限制** — 完美 Prompt 也要占用宝贵上下文
3. **能力复用困难** — 调教好的能力难以分享、难以保证执行一致

## 核心设计原则

### 1. 元数据要精准

`name` 和 `description` 是模型判断何时调用的唯一窗口。

❌ 差的写法：
```
description: 用于审查代码质量的 Skill
```

✅ 好的写法：
```
description: 在用户提交 Pull Request 后自动触发，对新增代码进行安全审查，输出审查报告并标注高风险问题
```

**要点**：告诉模型什么时候触发、干什么事、输出什么。

### 2. 约束强度适中

- **管太死**：每一步都写死 → 模型遇到超出预期的情况就乱来
- **放太松**：只说目标 → 每次结果不一样

✅ 正确做法：
- 明确告诉模型"要做什么"
- 给它留足推理空间
- 明确告诉它"不要做什么"
- 配上关键场景的例子

### 3. 一事一 Skill

单一职责原则。Skill 越简单，触发越精准，执行越稳定。

### 4. 持续迭代

发现问题 → 加评测用例 → 改 Skill → 继续观察

## Skill 开发流程

### Step 1: 先用裸模型跑一遍

看它哪里出错，这些就是 Skill 要填的坑。

### Step 2: 定标准

什么算好？什么算不好？定义及格线。

示例：
- 输入：一段关于项目进度讨论的会议记录
- 期望：明确列出"下一步行动"，包含负责人和时间节点
- 及格线：漏掉任何一个行动项就算失败

### Step 3: 先有再优

写最小可用版本，别一上来就大而全。

评测里暴露什么问题，就先解决什么问题，别的先别管。

### Step 4: 补边界

最小版本能用了，再慢慢往里加东西：

- 把边界情况写清楚：能处理什么、不能处理什么
- 定好输入输出格式
- 每个关键场景配一个例子

### Step 5: 持续观察

上线后监控，迭代改进。

## 脚本编写原则

如果 Skill 需要跑脚本：

- **错误要说人话**：别抛异常，告诉模型"为什么错"和"怎么办"
- **输出要解释清楚**：不光说"干了什么"，还要说"为什么"和"接下来可以干什么"
- **别用魔法数字**：`TIMEOUT_SECONDS = 30  # 服务启动一般 10-20 秒`

## 常见陷阱

### 陷阱 1：写成说明书了

Skill 是给模型下的指令，不是给人看的文档。

❌ 不要写：
```
本 Skill 基于敏捷开发方法论
旨在通过结构化思维提升会议纪要的质量...
```

✅ 要写：
```
什么情况用我、怎么执行、做成什么样
```

### 陷阱 2：越写越复杂

功能越多越不稳定，模型也有注意力限制。

**Skill 越简单，触发越精准，执行越稳定。**

## 优先级覆盖机制

同名 Skill 按优先级覆盖：

```
工作区 > 项目 Agent > 个人 Agent > 用户 managed > 内置 > 额外目录
```

用途：官方提供默认版本，个人有常用版本，项目可覆盖成专属版本，彼此不冲突。

## 三级预算降级

防止上下文爆炸：

1. **完整格式** — name + description + instructions
2. **紧凑格式** — name + location only
3. **二分截断** — 找最大可行前缀

## 渐进式披露

模型启动时只加载元数据（name + description），触发时才加载完整指令，按需加载脚本和资源。

这平衡了灵活性和效率：
- 元数据始终在上下文中 → 模型知道自己能做什么
- 指令按需加载 → 节省上下文
- 资源按需调用 → 无限扩展可能