# skill 技能
本质是一个‌模块化、可复用的能力单元或“任务说明书”‌。
它通常包含目标描述、执行步骤、所需工具和资源（如脚本、配置文件），将完成一项特定任务（如发送周报、查询天气）的最佳实践封装起来，供AI模型按需调用。‌‌


## 📁 一、结构规范：遵循 Agent Skills 开放标准

一个规范的 Skill 本质上是一个精心命名的文件夹，必须遵循官方的目录结构和 Frontmatter 定义。

### 1. 标准目录结构

```text
my-awesome-skill/
├── SKILL.md              # 【必需】核心指令文件
├── scripts/              # 【可选】可执行脚本 (Python/Bash等)
├── references/           # 【可选】参考文档，按需加载
└── assets/               # 【可选】模板、图片等静态资源
```

### 2. `SKILL.md` 的 Frontmatter 规范

SKILL.md 必须包含 YAML Frontmatter，这是模型判断是否调用该技能的唯一路由信息。

```yaml
---
name: bug-triage-workflow        # 必需：仅小写字母、数字、连字符，不超过64字符
description: 技能描述...           # 必需：清晰说明用途和触发场景，不超过1024字符
license: Apache-2.0               # 可选
allowed-tools: Bash(git:*) Read   # 可选：预授权工具列表
metadata:                         # 可选：自定义元数据
  author: your-name
  version: "1.0"
---

# 以下是具体的 Markdown 指令内容...
```

> **注意**：模型在启动时只会加载 `name` 和 `description`（约100 tokens），只有当判断任务相关时，才会加载完整的 `SKILL.md` 内容（建议不超过5000 tokens），从而实现“渐进式披露”，避免上下文膨胀。


## ✍️ 二、内容规范：OpenAI 官方最佳实践

这是确保技能**能被正确触发**且**高效执行**的关键。根据 OpenAI 内部（Codex）和 Glean 的生产实践，以下是核心规范：

### 1. 将 `description` 写成“路由逻辑”

不要写空泛的描述（如“用于生成报告”），应明确回答三个问题：**何时用？何时不用？输出什么？**

- **推荐格式**：`Use when... Don't use when... Output...`
- **实例对比**：
    - ❌ **错误**：`name: code-helper`；`description: Helps with code.`
    - ✅ **正确**：
      ```yaml
      name: code-review-checklist
      description: Use this skill when reviewing a PR, diff, or patch. 
                   Don't use for general coding questions. 
                   Output findings grouped by severity (Critical, Warning, Suggestion).
      ```

### 2. 加入“负面例子”防止误触发

Glean 的教训表明，当技能之间太相似时，模型正确触发率会下降 20%。**必须**在描述或指令中明确排除易混淆的场景。

> *“Don't use this skill for fixing the bug directly. If the user asks for a quick fix, use the `hotfix-apply` skill instead.”*

### 3. 模板和长文本塞进 Skill Body

不要在 System Prompt 中塞入大段的输出模板或格式要求。把它们放进 `SKILL.md` 里，只有在调用该技能时才会消耗 Token，这是优化延迟和成本的主要手段。

### 4. 需要确定性时，直接下指令

虽然模型可以自主决定是否调用技能，但在关键流程（如 CI/CD、发布）中，建议在 Prompt 里直接强制指定：

> *“Use the `data-report` skill to generate the final output.”*

### 5. 安全规范：防止数据泄露

OpenAI 明确警告：**Skills + 开放网络访问 = 高危组合**。因为技能包中可能包含内部业务逻辑。

- **网络隔离**：若技能需要联网，应限制在最小化的白名单域名内。
- **凭证管理**：**绝对不要**在 `SKILL.md` 或脚本中硬编码 API Key。必须使用 `domain_secrets` 机制（如 `$API_KEY` 占位符），由系统在运行时注入。


## 🧠 三、决策框架：何时使用 Skill vs. Rules vs. Commands？

很多开发者分不清这三者的区别。根据官方逻辑，你可以这样区分：

| 概念 | 触发者 | 最佳场景 | 上下文成本 |
| :--- | :--- | :--- | :--- |
| **Rules** | 系统自动 | 硬性约束（如“禁止提交 .env”）、命名规范、安全基线 | 始终占用 |
| **Skills** | **模型自主判断** | 特定任务的“操作手册”（如代码审查流程、Bug 分类标准） | **按需加载** |
| **Commands** | **用户手动** | 用户主动触发的快捷方式（如 `/deploy`） | 使用时占用 |

**判断逻辑**：如果一个指令是你**希望 AI 每次对话都默认遵守**的，写成 **Rule**。如果一个指令是**AI 遇到特定场景时才需要查阅**的，写成 **Skill**。


## 📝 四、快速自检清单

在完成一个 Skill 后，可以用这个清单来验证其规范性：

1.  **命名合规**：文件夹名和 `name` 字段是否只包含小写字母、数字和连字符？
2.  **描述精准**：`description` 是否包含明确的“Use when”条件？
3.  **无硬编码**：是否检查了所有脚本和文档，确保没有明文密钥？
4.  **结构清晰**：指令是否分步骤列出（Step 1, Step 2），输出格式是否明确？
5.  **体积控制**：`SKILL.md` 是否超过了 500 行？若超过，建议拆分解构到 `references/` 文件夹中。

如果你觉得手动编写比较麻烦，可以直接把需求发给 AI（如 Claude Code 或 Codex 自带的 `$skill-creator` 技能），让它帮你生成规范的初始版本。