Skill 定义#
Skill 是一种给 AI agent 用的“小插件”或“工作说明书”。它会教大模型 如何稳定地完成某类特定任务，尤其适合重复、固定流程、需要遵循格式或团队规范的工作。简单概括：专业知识 + 操作流程 + 工具调用
和 MCP 及 Prompt 的区别#
System Prompt 是一次性指令，MCP 是给 AI 装新手臂，Skill 是给 AI 装行为准则。
| 维度 | System Prompt | MCP | Skill |
|---|
| 本质 | 一次性角色设定 | 工具/能力扩展协议 | 可复用行为约束 |
| 解决什么问题 | 临时调整 AI 风格 | AI 连不到外部系统 | AI 不按规范工作 |
| 需要写代码 | 否 | 是（Server/Client） | 非必须（纯 Markdown就可以，scripts为可选） |
| 持久性 | 仅当前对话 | 持久（服务常驻） | 持久（文件存储） |
| 面向人群 | 所有人 | 开发者 | 所有人 |
| 典型例子 | “你是一个翻译助手” | 连接数据库、调用 API | 强制 TDD、规范 Git 提交 |
Skill 构成#
1
2
3
4
5
6
| my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
|
一个技能就是一个包含 SKILL.md 文件的文件夹。该文件包含元数据（至少包括 name 和 description ）以及指导代理如何执行特定任务的指令。技能还可以捆绑脚本、参考资料、模板和其他资源。
SKILL.md = 触发说明 + 任务目标 + 输入要求 + 执行流程 + 输出格式 + 质量标准 + 限制规则 + 示例 + 外部资源说明
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
| ---
name: skill-unique-name （必须）
description （必须）: |
触发场景描述。说明这个 Skill 做什么、什么时候应该使用。
AI 会优先根据这里判断是否启用该 Skill。
license(可选): Apache-2.0
metadata(可选) :
author: Luenci
version: "1.0"
---
# Skill 名称
`SKILL.md` 是 Skill 的入口文件，用来告诉 AI：这个 Skill 的用途、触发条件、输入要求、执行步骤、输出格式和限制规则。
## 1. Skill 做什么
说明 Skill 的核心能力和目标，例如：用于整理会议纪要、分析客户反馈、生成周报、处理文件等。
## 2. 什么时候使用
说明 Skill 的触发场景。用户提出哪些任务、提供哪些材料或使用哪些关键词时，AI 应该调用该 Skill。
## 3. 需要什么输入
说明用户需要提供的内容，例如文本、文件、表格、链接、模板、字段信息或其他上下文。
## 4. 具体执行步骤
说明 AI 应该按照什么流程完成任务，通常用 1、2、3 的步骤列出。
## 5. 输出格式
规定最终结果的结构，例如 Markdown、表格、JSON、邮件、报告模板或固定标题层级。
## 6. 质量标准
说明结果应满足的要求，例如准确、完整、简洁、结构化、可执行、不遗漏关键信息。
## 7. 特殊规则或限制
说明必须遵守的边界，例如不要编造、不要跳过校验、不要改变格式、缺失信息要标注“待确认”。
## 8. 示例
提供一个简短的用户输入和期望输出，帮助 AI 理解正确的处理方式和输出风格。
## 9. 需要调用的脚本、模板、参考资料
说明是否需要使用 `scripts/`、`references/`、`assets/` 中的脚本、模板、规范或示例文件。
|
三类可选资源详解#
scripts/ 确定性脚本#
用途： 把反复编写的代码固化成可直接执行的脚本。Skill 执行过程中可调用的脚本
适合场景：
- 旋转 PDF：
scripts/rotate_pdf.py - 解密音频：
scripts/decrypt_ncm.py - 分析日志：
scripts/parse_log.py
优势： 不需要读入上下文就能执行，节省 token。
references/ 参考文档#
用途： 存储 AI 需要参考但不必一直占用上下文的知识。给 AI 提供背景知识和参考规范
适合场景：
- 数据库表结构：
references/schema.md - API 文档：
references/api_docs.md - 公司政策：
references/policies.md
设计原则： 按领域拆分成独立文件，用户问销售数据时只加载 sales.md，不加载 finance.md。
assets/ 静态资源#
用途： 存储输出中会用到的文件，不需要读入上下文。模板、静态文件
适合场景：
- 前端模板：
assets/frontend-template/ - PPT 模板：
assets/slides.pptx - 品牌 Logo：
assets/logo.png - checklist 模板：
checklist.md
使用参考#
1
2
3
4
5
6
| ## 参考规范 请在审查前阅读 reference/style-guide.md 中的编码规范。
## 执行流程
1. 运行 scripts/validate.sh 做静态检查
2. 按照 assets/checklist.md 逐项审查
3. 使用 assets/templates/report.md 格式输出结果
|
Skill 工作流程#
- Discovery（发现）: agent 启动时，智能体仅加载每个可用技能的名称和描述，加载技能介绍。后续按需调用技能
- Activation（加载）：当任务与技能的描述匹配时，agent 会将完整的
SKILL.md 指令读入上下文。 - Execution（执行）：agent 遵循指令，根据需要可选地执行捆绑的代码或加载引用的文件。
三级加载机制#
Skill 采用"按需加载"的设计，避免浪费上下文窗口：
| 级别 | 内容 | 何时加载 | 大小 |
|---|
| 第一级 | name + description | 始终在上下文中 | ~100 词 |
| 第二级 | SKILL.md 正文 | Skill 被触发后 | < 5000 词 |
| 第三级 | scripts/ references/ assets/ | AI 判断需要时 | 无限制 |
实际效果： AI 随时知道有哪些 Skill，但只有真正需要时才"打开"它。
Skill 编写实践#
核心设计原则#
原则 1：精简优先#
上下文窗口是公共资源。每加一段文字都问自己：
“这是 AI 不知道的信息吗？删掉会有什么后果？”
不要写： “在开始之前，你需要理解这个任务的重要性…”
要写： 直接给出操作步骤。
原则 2：自由度要匹配任务#
| 任务特性 | 自由度 | 写法 |
|---|
| 步骤固定、易出错 | 低 | 具体脚本 + 严格参数 |
| 有首选方案、允许变化 | 中 | 伪代码 + 可配置参数 |
| 多种方案均可、依赖上下文 | 高 | 文字指导 + 启发式原则 |
原则 3：渐进式披露#
SKILL.md 只放核心工作流，细节通过引用指向 references/ 文件：
1
2
3
4
5
6
7
8
| ## 高级功能
- **表单填写**：详见 [FORMS.md](references/FORMS.md)
- **API 参考**：详见 [API.md](references/API.md)
## 日志格式
详见 [references/log-format.md](references/log-format.md)
|
常见误区#
| 误区 | 正确做法 |
|---|
| 在 SKILL.md 正文写"何时使用" | 应写在 description 字段（正文触发后才加载，写了也没用） |
| 创建 README.md、CHANGELOG.md | 只保留任务必需的文件 |
| 把所有细节塞进 SKILL.md | 细节放 references/，SKILL.md 只放核心流程 |
| 跳过脚本测试 | 脚本必须实际运行验证 |
| 深层嵌套引用 | 所有 references 文件直接从 SKILL.md 一层引用 |
SKill 示例#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
| ---
name: meeting-notes-summarizer
description: |
Use when the user provides Chinese meeting notes, call transcripts, chat logs, or project discussions and asks to generate a structured meeting summary, action items, owners, deadlines, risks, and open questions.
---
# 会议纪要整理助手
## 核心原则
- 只基于用户提供的内容总结，不编造信息。
- 区分“已确认结论”“讨论中事项”和“待确认问题”。
- 输出必须结构化、简洁、可执行。
- 缺失信息明确标注“未提及”或“待确认”。
## 适用输入
用户可能提供以下内容：
- 原始会议转写文本
- 零散会议笔记
- 项目讨论记录
- Slack、飞书、微信等聊天记录
- 多人评审或复盘材料
## 执行流程
1. 阅读用户提供的全部内容。
2. 识别会议主题、背景和核心讨论点。
3. 提取明确达成一致的关键结论。
4. 提取行动项，包括任务、负责人、截止时间和状态。
5. 标记风险、阻塞点和待确认问题。
6. 按指定输出格式生成会议纪要。
7. 输出前检查是否存在编造、遗漏或格式错误。
## 输出格式
请按以下格式输出：
# 会议纪要
## 一、会议主题
...
## 二、会议背景
...
## 三、关键结论
1. ...
2. ...
## 四、行动项
| 任务 | 负责人 | 截止时间 | 状态 |
|---|---|---|---|
| ... | ... | ... | ... |
## 五、风险与阻塞
- ...
## 六、待确认问题
- ...
## 七、简短总结
...
## 禁止行为
- 不要编造参会人、负责人、截止时间或结论。
- 不要把未确认的讨论写成已决定事项。
- 不要逐字复述原文。
- 不要省略风险、阻塞和待确认问题。
- 不要改变输出结构，除非用户明确要求。
## 质量检查
输出前确认：
- 关键结论是否都能从原文找到依据。
- 行动项是否包含任务、负责人、截止时间和状态。
- 缺失信息是否已标注“未提及”或“待确认”。
- 是否区分了结论、风险和待确认问题。
|
参考链接#
- 岛雨AI：https://juejin.cn/post/7620262637797408808
- agentskills：https://agentskills.io/specification