Agent Skills 完全指南：从概念到自定义实践

最近，OpenClaw 这类开源 AI Agent 框架持续升温，公司也基于这类框架快速推出了自己的企业版产品。在这段时间的探索中，我接触了多款 AI Agent 平台------有开源框架、企业级助理、低代码开发平台等，开始逐步学习和实践 Skill 的开发。

初期我曾有不少困惑：各类平台之间究竟是什么关系？Skill 又在其中扮演什么角色？

随着实践才逐渐理解：如果把 AI 智能体比作一个"数字员工"，那么 Skill 就是它的岗位交接文档------告诉它具体怎么做你那份工作，而不是每次都手把手教。

这篇文章就是这段时间学习心得的系统整理，希望能帮你少走弯路。

摘要：在 AI Agent 时代，Skills 正在成为扩展大模型能力的核心机制。如何理解 Skill？想象你要把一项工作交给新同事------不准口口相传，只靠文档交接，而且你想一次性交接完成、以后不被打扰。 这份"交接文档"就是 Skill。本文将深入解析 Agent Skills 的本质、与 MCP 的区别，并提供完整的自定义技能开发指南，帮助你打造专属的 AI 能力扩展包。

关键词：Agent Skills、MCP、大模型、自定义技能、AI 工程化

一、什么是 Agent Skills？

1.1 一个绝佳的比喻

💡 如何理解 Skill？

想象你要把一项工作交给新同事：

❌ 不准口口相传（不能每次手把手教）

✅ 只靠文档交接（所有知识写下来）

✅ 一次性交接完成（以后不被打扰）

这份"交接文档"就是 Skill。
📦 更完整的比喻：工作交接 SOP 大礼包

你会给新同事准备什么？

📝 任务执行 SOP 与必要背景知识（这件事大致怎么做）

🛠️ 工具使用说明（用什么软件、怎么操作）

📋 模板与素材（历史案例、格式规范、Logo 资源）

❓ 常见问题解决方案（可能遇到的问题、规范、避坑指南）

Skill 就是这个"交接大礼包"的数字化版本------AI 拿到它，就能独立完成任务，不再打扰你。

1.2 核心定义

**Agent Skills（智能体技能）**是模块化、自包含的功能包，用于扩展 AI 助手的能力边界。它们为通用大模型提供特定领域的专业知识、工作流和工具集成，将通用型 AI 转变为专业型 AI 助手。

可以把 Skills 理解为AI 的"岗位交接文档" ------就像新员工入职需要学习特定岗位的操作流程一样，Skills 为大模型提供它无法从训练数据中完全掌握的程序性知识 和领域专有知识。

关键洞察 ：Skill 的终极目标是让 AI 独立完成任务，无需人类反复指导。

1.3 Skills 提供什么？

一个完整的 Skill 通常包含以下四类核心内容：

类型	说明	示例
专业工作流	多步骤领域特定流程	会议室预订流程、文档审批流程
工具集成	特定文件格式或 API 的操作指令	PDF 处理、Excel 公式计算、数据库查询
领域专业知识	公司特定知识、Schema、业务逻辑	数据库表结构、财务报销规则、API 文档
捆绑资源	脚本、参考文档、模板资产	Python 脚本、PPT 模板、品牌资产

1.4 为什么需要 Skills？

大模型虽然强大，但存在天然局限：

知识时效性：训练数据截止后新知识无法获取
私有知识缺失：企业内部系统、数据库、业务流程不在训练数据中
精确性要求：某些操作需要确定性执行，不能依赖模型"猜测"
上下文效率：将常用知识打包成 Skill，避免每次重复说明

Skills 的本质：通过"按需加载"的模块化设计，在不占用过多上下文窗口的前提下，为大模型提供它需要的特定知识。

1.4.1 Skills 的三大核心优势（相比其他 AI 应用开发方式）

💡 洞察来源：smartcity.team《Agent Skills 终极指南》

Skills 与 Workflow、传统程序化 AI 应用相比，有底层机制的不同：

优势	说明	对比案例
✅ 零代码、自然语言编写	非技术人员可用自然语言创建真·智能 Agent，入门门槛极低，智能上限极高	Coze/Dify 等 Workflow 平台仍需理解节点配置、条件分支，本质还是"编程"
✅ 突破预设限制，灵活应对	不像 Workflow 那样遇到边缘情况就卡住，能利用 LLM 推理智能弥合各类意外问题	Workflow 假设所有情况都能预设，遇到意外格式/字段不符就报错或要求用户自行修正
✅ 多 Skills 自由联用	一次任务可调用多个 Skill，极其灵活，本质是 Context 工程的优雅实现	传统 AI 应用往往是孤岛，难以组合使用

关键洞察：

"人给出专业知识与工具方法，通用 Agent 提供智能，自主理解，主动执行。"

"通用 Agent 提供智能上限，Skills 决定垂直领域深度。"

1.5 什么时候应该使用 Skills？（判断标准）

这是最常被问到的问题。以下是明确的判断标准：

🎯 三个关键信号（来自 smartcity.team）

如果你发现以下情况，就是创建 Skill 的最佳时机：

信号 1：发现自己在向 AI 反复解释同一件事

"最典型的信号是：为了完成某个任务，在多轮对话中，需要不断向 AI 解释一件事应该怎么做。"

信号 2：某些任务需要特定知识、模板、材料才能做好

"AI 的通用能力够了，但缺'特定场景的知识材料'。"

信号 3：发现一个任务要多个流程协同完成

"有些任务更加复杂，往往需要'组合多个流程'才能完成。"

✅ 应该使用 Skills 的场景

场景	说明	示例
重复性任务	同一类任务反复出现，每次都重新解释成本高	PDF 处理、会议纪要生成、代码审查
需要精确执行	操作不能出错，需要确定性流程	财务报销、数据库迁移、API 调用
私有知识	涉及企业内部系统、流程、规范	公司内部 API、数据库 Schema、审批流程
多步骤工作流	任务需要按特定顺序执行多个步骤	会议室预订→通知参会人→创建日历事件
工具集成	需要调用外部工具/API	调用钉钉 API、查询内部系统、操作 Git
团队协作	多人需要 AI 以相同方式处理同类任务	代码规范检查、文档格式要求、品牌规范

❌ 不需要 Skills 的场景

场景	原因
一次性任务	任务只做一次，不需要复用
简单查询	大模型已有足够知识（如"Python 怎么写循环"）
创意性工作	需要灵活发挥，不应被流程束缚
探索性问题	答案不唯一，需要多轮对话探索

🔑 核心判断法则

问自己这个问题：

"如果我要把这个任务交给一个聪明的实习生，我是否需要写一份详细文档，让他/她以后能独立完成，不再打扰我？"

YES → 应该创建 Skill

NO → 直接用对话即可

实际案例对比：

任务	需要 Skill 吗？	原因
"帮我写个 Python 脚本读取 Excel"	❌ 不需要	大模型已经会，一次性任务
"每次新员工入职时，按公司流程创建账号、分配权限、发送欢迎邮件"	✅ 需要	重复性、多步骤、涉及内部流程
"翻译这段话"	❌ 不需要	简单任务，大模型原生能力
"按公司品牌规范生成 PPT，使用指定模板、字体、配色"	✅ 需要	涉及私有资产和规范，需要精确执行

二、Skills vs MCP：有什么区别？

这是最容易混淆的两个概念。让我们从多个维度进行对比：

2.1 一个生活化比喻

想象你要装修房子：

角色	对应概念	说明
装修手册	Skill	告诉你"先拆旧→改水电→铺瓷砖→刷漆"的流程和注意事项
电动工具	MCP	提供电钻、电锯等具体工具来执行操作

💡 没有手册 ：有工具但不知道怎么有序使用

💡 没有工具 ：知道流程但无法执行

✅ 两者配合：按手册流程，使用工具高效完成装修

2.2 概念层级

复制代码

┌─────────────────────────────────────┐
│         Agent Skills                │  ← 概念层：能力定义
│  "什么场景下，AI 应该做什么事"        │
└─────────────────────────────────────┘
              ↓ 使用
┌─────────────────────────────────────┐
│           MCP Servers               │  ← 实现层：工具提供
│  "提供具体的 API 工具供 AI 调用"       │
└─────────────────────────────────────┘

2.3 详细对比

维度	Agent Skills	MCP (Model Context Protocol)
本质	知识包 + 行为指南	工具协议 + 服务器标准
内容	Markdown 指令、脚本、参考文档、资产	JSON-RPC API、工具定义、资源端点
作用	告诉 AI"什么时候做、怎么做"	给 AI 提供"可以调用的工具"
触发	基于用户查询语义自动触发	需要 Skill 指令调用
上下文	元数据常驻，正文触发后加载	工具定义常驻，调用时传参
示例	`meeting-room` 技能：指导 AI 如何查询/预订会议室	`mcp.ant.homi.claw`：提供 `queryMeetingRooms`、`bookMeetingRoom` 等 API

2.4 实际案例：会议室预订

MCP Server 提供工具：

复制代码

{
  "tools": [
    { "name": "queryMeetingRooms", "description": "查询空闲会议室" },
    { "name": "bookMeetingRoom", "description": "预订会议室" },
    { "name": "queryMyBookings", "description": "查询我的预订记录" }
  ]
}

Skill 指导 AI 如何使用：

复制代码

# 会议室管理技能

## 触发条件
当用户提到以下短语时使用此技能：
- "帮我订个会议室"
- "下午有空的会议室"
- "查看我的会议室预订"

## 使用流程
1. 确认需求：时间、人数、设备要求
2. 调用 `queryMeetingRooms` 查询可用会议室
3. 展示选项供用户选择
4. 调用 `bookMeetingRoom` 完成预订
5. 返回预订确认信息

## 注意事项
- 预订前必须确认参会人数
- 避免重复预订（先调用 queryMyBookings 检查）

关键洞察：

MCP 是"手和脚"：提供执行能力
Skill 是"大脑和知识库"：提供决策逻辑和领域知识
两者配合：Skill 指导 AI 何时、如何调用 MCP 工具

2.5 依赖关系

复制代码

用户查询 → Skill 触发 → 读取 Skill 指令 → 调用 MCP 工具 → 返回结果
           ↑                                    ↑
      决策逻辑                              执行能力

不是所有 Skills 都需要 MCP（有些 Skill 只是知识库），但 MCP 工具通常需要 Skill 来指导 AI 有效使用。

三、实战案例：某蚁官方【日/周报生成】Skill 拆解 ⭐

导语：在深入讲解 Skill 的开发方法之前，我们通过一个实际案例 ------ 某蚁官方的【日/周报生成】Skill，来直观理解一个成熟的生产级 Skill 是如何组织的。

这个 Skill 能够从语雀、蚂蚁钉、Dima 三个平台自动整合数据，生成标准化日报/周报并归档至语雀。它的 SKILL.md 采用了5 层内容结构设计：

层级	作用	核心内容	关键价值
🆔 技能定义层	告诉 AI 什么时候该用这个技能	Frontmatter 元数据（name + description）	AI 识别器：description 决定何时触发技能
🧑‍🏫 角色定义层	让 AI 在调用技能时严格扮演角色设定	角色定位、核心职责、触发场景/不触发场景	岗位说明书：明确职责边界，避免误触发
⚙️ 引导 + 配置层	让 AI 知道你的习惯和需求	日报/周报判断逻辑、用户偏好配置	个人配置文件：记住用户习惯，如汇报时间、称呼
📉 数据源 + 处理层	让 AI 知道数据、会收集& 处理数据	多源数据采集（语雀/钉钉/Dima）、处理流程、状态追踪	工具说明书：接口规范、待办 4 色法、变化追踪
💻 输出&操作层	让 AI 按模版、按风格完成输出，并执行后续动作	标准化汇报模板、语雀归档、定时任务、钉钉推送	标准化输出：格式固化、自动化执行、多端同步

💡 关键洞察 ：这 5 层结构是一个SKILL.md 文件内部的内容组织方式，它确保了 AI 能够：

正确触发（技能定义层）

进入角色（角色定义层）

了解用户偏好（引导配置层）

获取和处理数据（数据源 + 处理层）

规范输出并执行后续动作（输出&操作层）
📋 重要说明：5 层结构 vs 三级加载

5 层结构 ：SKILL.md 文件内部的内容组织方式（本文案例采用）

三级加载 ：Skill 系统的加载机制（L1 元数据始终加载/L2 body 触发后加载/L3 资源按需加载）

两者是不同维度的概念：5 层结构讲"内容怎么写"，三级加载讲"系统怎么读"

四、如何自定义一个 Skill？

📚 学习路径建议

零基础新手：按顺序阅读 4.1→4.4→4.5→4.6

已有想法 ：直接看 4.4 六步法，边做边查

需要参考模板 ：跳到 4.6 完整示例

遇到具体问题 ：查看 4.5 最佳实践清单 或 第六章调试与优化

4.1 技能结构解剖

一个标准 Skill 的目录结构如下：

复制代码

skill-name/
├── SKILL.md                  # [必需] 入口文件：frontmatter + body
├── agents/
│   └── openai.yaml           # [推荐] 技能的"名片"
├── scripts/                  # [可选] 可执行脚本
├── references/               # [可选] 参考文档
└── assets/                   # [可选] 产出物模板

逐个说明：

文件/目录	必要性	用途	示例
SKILL.md	必需	技能入口文件，包含 frontmatter 元数据和 body 操作指令	唯一必需的文件
scripts/	可选	写好的程序，AI 执行而不读入	`scripts/rotate_pdf.py` --- AI 只需调用 `python rotate_pdf.py input.pdf 90`，不用每次重写旋转逻辑
references/	可选	AI 在工作过程中需要查阅的参考资料	`references/schema.md` --- BigQuery 表结构，AI 需要时读取
assets/	可选	直接用在意最终产出里的文件，AI 不需要读懂它	`assets/frontend-template/` --- HTML/React 样板代码，AI 直接拷贝修改；`assets/logo.png` --- 公司 logo，AI 生成网页时直接引用
agents/openai.yaml	推荐	技能的"名片"，给产品界面用，不影响 AI 行为	显示在技能列表中的名称、简介、图标等，通过脚本 `generate_openai_yaml.py` 确定性生成

关键区别：

references vs scripts ：references 是给 AI 读的，scripts 是给 AI 执行的
assets vs references：assets 是用在最终输出里的，references 是给 AI 查阅的
agents/openai.yaml：纯粹给产品界面用，AI 不读它

4.2 核心文件：SKILL.md ------ 官方 5 层结构解剖

💡 与第三章的关系

第三章展示了某蚁官方日报 Skill 的 5 层结构全貌概览 ，本节将逐层深入讲解具体写法 。

建议：先快速浏览第三章的案例表格建立直觉，再回到本节学习具体实现细节。

基于官方【日/周报生成】Skill 的最佳实践，一个成熟的生产级 Skill 应包含5 个层次：

复制代码

┌─────────────────────────────────────────┐
│ 🆔 技能定义层（Frontmatter 元数据）      │  ← 始终在上下文
├─────────────────────────────────────────┤
│ 🧑‍🏫 角色定义层（技能定位与边界）         │  ← 触发后加载
├─────────────────────────────────────────┤
│ ⚙️ 引导 + 配置层（触发条件与个性化）      │  ← 触发后加载
├─────────────────────────────────────────┤
│ 📉 数据源 + 处理层（MCP 工具与数据处理）  │  ← 按需读取
├─────────────────────────────────────────┤
│ 💻 输出 & 操作层（生成模板与外部动作）   │  ← 按需读取
└─────────────────────────────────────────┘

第 1 层：🆔 技能定义层（Frontmatter 元数据）

复制代码

---
name: daily-weekly-report
description: 跨平台工作汇报自动化技能。从语雀、蚂蚁钉、Dima 三源整合数据，自动生成标准化日报/周报并归档至语雀，具备完整的待办追踪闭环和个性化配置能力。
             当用户提到"写日报"、"生成周报"、"本周工作总结"、"同步工作进展"时触发。
---

核心要素：

name：技能标识符（小写 + 连字符，如 daily-weekly-report）
description：最重要的触发机制 ，需包含：
- WHAT：技能做什么（1 句话 summary）
- WHEN：何时使用（触发条件/场景）
- Trigger Phrases：用户会说的具体短语（中英文都包含）

⚠️ 常见错误：

❌ 描述过于抽象："帮助处理工作汇报事务"
✅ 正确做法：包含具体触发词，如"写日报"、"生成周报"

第 2 层：🧑‍🏫 角色定义层（技能定位与边界）

内容示例（SKILL.md 正文）：

Daily-Weekly-Report - 跨平台工作汇报自动化

Version : v2.1.0
Last Updated: 2026-03-26

✅ 触发场景：

"帮我写今天的日报"

"生成这周的工作总结"

"把本周工作进展同步到语雀"

"上周完成哪些事？整理成周报"

❌ 不触发：

单一文档总结（无汇报上下文）

临时性记录（如"记一下今天要做什么"）
目的：让 AI 明确理解自己在什么场景下扮演什么角色，避免误触发。

第 3 层：⚙️ 引导 + 配置层（触发条件与个性化）

内容示例（SKILL.md 正文）：

日报 vs 周报 vs 月报判断

类型判断依据

日报用户提到"今天"、"今日"，或时间范围≤1 天

周报用户提到"本周"、"这周"，或时间范围 3-7 天

月报用户提到"本月"、"这个月"，或时间范围>7 天

个性化配置（可选）：

"只总结 Dima 工作项" → 仅查询 Dima 数据源

"包含会议记录" → 额外查询 Homi 会议记录

"发送到钉钉群" → 生成后调用钉钉机器人发送
目的：明确决策逻辑，支持灵活配置。

类型	判断依据
日报	用户提到"今天"、"今日"，或时间范围≤1 天
周报	用户提到"本周"、"这周"，或时间范围 3-7 天
月报	用户提到"本月"、"这个月"，或时间范围>7 天

第 4 层：📉 数据源 + 处理层（MCP 工具与数据处理）

内容示例（SKILL.md 正文）：

多源数据获取

数据源 MCP Server 获取内容工具示例

语雀 mcp.ant.faas.skylarkmcpserver 文档编辑记录 skylark_user_recent

蚂蚁钉 mcp.ant.antdingopenapi 日程、待办 queryScheduleList

Dima mcp.ant.arkai.dimamcpserver 工作项更新 queryUserWorkItemList

数据处理流程：

时间过滤: 根据用户指定范围过滤

去重: 同一工作项在不同数据源出现时去重

分类: 按"已完成"、"进行中"、"新增"分类

优先级排序: 高优先级排在前面

调用示例：
复制代码
# 获取 Dima 工作项
ant_mcp call --server mcp.ant.arkai.dimamcpserver \
  --tool queryUserWorkItemList \
  --args '{"startDate": "20260320", "endDate": "20260326"}'

# 获取语雀最近编辑
ant_mcp call --server mcp.ant.faas.skylarkmcpserver \
  --tool skylark_user_recent \
  --args '{"type": "doc", "limit": 20}'
⚠️ 注意事项：

先宽后窄：先用时间范围获取较大集合，再用关键词过滤

多关键词：如果单次搜索结果少，尝试多个关键词分别搜索

人工确认：展示搜索结果，让用户确认是否关联正确
目的：定义数据从哪里来、如何处理。

数据源	MCP Server	获取内容	工具示例
语雀	`mcp.ant.faas.skylarkmcpserver`	文档编辑记录	`skylark_user_recent`
蚂蚁钉	`mcp.ant.antdingopenapi`	日程、待办	`queryScheduleList`
Dima	`mcp.ant.arkai.dimamcpserver`	工作项更新	`queryUserWorkItemList`

第 5 层：💻 输出 & 操作层（生成模板与外部动作）

内容概述：

输出模板：定义日报/周报的标准格式
后续操作：定义可选的额外动作（如语雀归档、钉钉通知等）

说明：后续操作是可选的------用户可以在创建 Skill 时决定是否支持，也可以在使用时通过指令选择是否执行。

用户说"生成周报并发送到钉钉群"→ 执行钉钉通知

用户说"生成周报就好"→ 只生成文本，不执行额外操作

标准日报格式（SKILL.md 正文中应包含的模板）：

📅 日报 - {日期}

✅ 今日完成

$Dima-W20260326001\] 完成 Skill 开发指南初稿$

Review 代码 PR #128

📌 进行中

功能 A 开发（进度 70%）

文档 B 更新（等待 Review）

📋 明日计划

继续开发功能 A

参加 14:00 的技术分享会

🔗 相关文档

Skill 开发指南

标准周报格式：

📊 周报 - 第 X 周 (3.20-3.26)

🎯 本周重点

完成 Skill 开发指南初稿，修复 gateway 重启问题，推进功能 A 开发。

✅ 已完成

工作项 ID 标题类型状态

W20260326001 Skill 开发指南需求已完成

W20260325002 Gateway 重启修复缺陷已完成

🔄 进行中

工作项 ID 标题进度风险

W20260320003 功能 A 开发 70% 无

📈 关键指标

完成工作项：2 个

修复缺陷：1 个

文档产出：1 篇

📝 下周计划

完成功能 A 开发（优先级 P0）

启动功能 B 设计（优先级 P1）

工作项 ID	标题	类型	状态
W20260326001	Skill 开发指南	需求	已完成
W20260325002	Gateway 重启修复	缺陷	已完成

工作项 ID	标题	进度	风险
W20260320003	功能 A 开发	70%	无

语雀归档（可选）：

复制代码

ant_mcp call --server mcp.ant.faas.skylarkmcpserver \
  --tool skylark_doc_create \
  --args '{"book_id": 12345, "title": "周报 -2026-W13", "body": "{内容}"}'

钉钉通知（可选）：当用户要求"发送到钉钉"时执行。

💡 说明 ：这类后续操作是可选的------Skill 可以定义多种输出方式（如仅生成文本、语雀归档、钉钉通知等），用户在使用时通过指令选择是否执行。
目的：定义输出格式和可选的后续动作。

5 层结构的优势

优势	说明
结构清晰	AI 明确知道每部分的作用，不易混淆
按需加载	只有需要的层次才会被详细读取，节省上下文
可维护性	修改某一层不影响其他层
可扩展性	新增数据源或输出格式只需扩展对应层次

4.3 渐进式披露设计

核心原则：上下文窗口是稀缺资源，按需加载。

复制代码

Level 1: Frontmatter（元数据）
  └─ 始终在上下文中（~100 词）
       ↓ 触发匹配
Level 2: SKILL.md 正文
  └─ 触发后加载（<5000 词）
       ↓ 按需读取
Level 3: 捆绑资源（scripts/references/assets）
  └─ AI 判断需要时加载（无限制）

实践技巧：

SKILL.md 正文控制在 500 行以内
详细 Schema、API 文档、示例放入 references/
重复执行的代码放入 scripts/（可执行无需加载）
模板、图片等放入 assets/

4.4 开发六步法

步骤 1：明确使用场景

在动手之前，先回答：

用户会说什么来触发这个技能？
这个技能要完成什么任务？
需要哪些工具/知识？

示例问题：

"用户会说'帮我旋转这个 PDF'还是'把这个 PDF 转 90 度'？"

"是否需要调用外部 API，还是本地脚本就能完成？"

步骤 2：规划可复用内容

分析任务，确定需要打包什么：

任务类型	推荐资源
重复性代码	`scripts/`（Python/Bash 脚本）
领域知识	`references/`（Schema、API 文档）
输出模板	`assets/`（PPT、Word 模板）

步骤 3：初始化技能

使用官方脚本创建模板：

复制代码

# 基本用法
python scripts/init_skill.py my-skill --path skills/public

# 带资源目录
python scripts/init_skill.py my-skill --path skills/public --resources scripts,references

# 带示例文件
python scripts/init_skill.py my-skill --path skills/public --resources scripts --examples

脚本会自动：

创建技能目录结构
生成带 TODO 占位符的 SKILL.md 模板
可选创建 scripts/、references/、assets/ 子目录

步骤 4：编写技能

分两个阶段进行：

阶段一：实现可复用资源

从步骤 2 规划的 выпадающие内容开始
实现 scripts/、references/、assets/ 文件
测试脚本：新增的脚本必须通过实际运行来测试

阶段二：更新 SKILL.md

Frontmatter 写法：

复制代码

---
name: skill-name
description: >-
  描述技能做什么 + 具体什么时候用。
  把所有 "when to use" 信息放这里，不要放在 body 里。
---

Body 写法：

写给另一个 AI 实例的操作指令
统一使用祈使语气/不定式
包含对 AI 有帮助但不显而易见的信息
采用 5 层结构：技能定义→角色定义→引导配置→数据源处理→输出操作

关键原则：

用命令式语气："调用 createEvent"，而不是"你应该调用 createEvent"
简洁示例优于冗长解释
分支逻辑用决策树明确表达

步骤 5：打包技能

复制代码

python scripts/package_skill.py path/to/skill-folder

打包脚本会自动：

验证 YAML 格式、命名规范、描述完整性
生成 .skill 文件（带签名的 ZIP 文件）

步骤 6：迭代优化

好的 Skill 不是一次写成的。迭代工作流：

在真实任务上使用技能
发现吃力或低效的地方
更新 SKILL.md 或捆绑资源
重新打包并测试

实际案例 ：官方 laotou-thought-style 技能在第一次生成后就迭代了 openai.yaml 的 short_description 和 default_prompt，从泛泛的描述变为更精确的操作指令。

4.5 最佳实践清单

✅ 应该做的

名称使用 kebab-case（meeting-room 不是 MeetingRoom）
描述包含中英文触发词
SKILL.md 正文 < 500 行
用命令式语气写指令
为分支逻辑提供决策树
包含错误处理指南
采用 5 层结构组织内容
脚本需要实际运行测试
Frontmatter 只包含 name 和 description
所有 references/ 文件从 SKILL.md 直接链接

❌ 不应该做的

在技能目录放 README.md、CHANGELOG.md、INSTALLATION_GUIDE.md
描述只写"处理 XX 相关事务"（太模糊）
把 API 文档全塞进 SKILL.md（应放入 references/）
使用 <skill> 等 XML 标签（安全风险）
留下 TODO 注释
在 body 中写"何时使用此技能"（应放在 description）
SKILL.md 和 references 内容重复
references 文件互相引用（应都从 SKILL.md 直接链接）

4.6 完整示例：日报/周报生成 Skill

基于官方最佳实践，以下展示一个完整的生产级 Skill 的 Frontmatter 和结构概览：

复制代码

---
name: daily-weekly-report
description: 跨平台工作汇报自动化技能。从语雀、蚂蚁钉、Dima 三源整合数据，自动生成标准化日报/周报并归档至语雀。当用户提到"写日报"、"生成周报"、"本周工作总结"、"同步工作进展"时触发。
---

完整的 SKILL.md 5 层结构：

层级	内容	说明
🆔 技能定义层	Frontmatter（name + description）	触发机制
🧑‍🏫 角色定义层	何时使用/不触发	技能定位与边界
⚙️ 引导 + 配置层	日报/周报/月报判断逻辑、个性化配置	决策规则
📉 数据源 + 处理层	语雀/钉钉/Dima 数据获取、处理流程	MCP 工具调用
💻 输出 & 操作层	日报/周报模板、语雀归档、钉钉通知（可选）	输出格式与后续动作

完整的 SKILL.md 正文示例 请参考本文 4.2 节 的 5 层结构逐层详解（包含每层的完整代码示例和写法说明）。

目录结构：

复制代码

daily-weekly-report/
├── SKILL.md                  # 5 层结构完整指令
├── agents/
│   └── openai.yaml           # 技能名片（UI 元数据）
├── scripts/
│   └── aggregate_reports.py  # 周报聚合脚本
├── references/
│   └── output-template.md    # 输出模板详细规范
└── assets/
    └── weekly-report.pptx    # 周报 PPT 模板

五、Skill 设计模式

5.1 模式一：高层指南 + 参考文件

适用场景：技能支持多种变体或框架

复制代码

# 文档处理

## 创建文档
使用 docx-js 创建新文档。详见 `references/docx-js.md`

## 编辑文档
简单编辑直接修改 XML。

**跟踪修订**：见 `references/redlining.md`
**OOXML 细节**：见 `references/ooxml.md`

5.2 模式二：按领域组织

适用场景：技能覆盖多个业务域

复制代码

bigquery-skill/
├── SKILL.md（概览和导航）
└── references/
    ├── finance.md（收入、账单指标）
    ├── sales.md（销售机会、管线）
    ├── product.md（API 使用、功能）
    └── marketing.md（营销活动、归因）

5.3 模式三：按提供商组织

适用场景：支持多个云平台/服务提供商

复制代码

cloud-deploy/
├── SKILL.md（工作流 + 提供商选择）
└── references/
    ├── aws.md（AWS 部署模式）
    ├── gcp.md（GCP 部署模式）
    └── azure.md（Azure 部署模式）

六、调试与优化

6.1 常见问题诊断

问题	可能原因	解决方案
技能不触发	描述太模糊	添加具体触发词到 description
触发错误技能	描述重叠	区分各自专属场景
AI 乱调用工具	指令不清晰	添加决策树和参数示例
上下文溢出	SKILL.md 太长	移到 `references/`

6.2 性能优化

减少常驻上下文：只保留必要元数据
延迟加载：参考文件按需读取
脚本化 ：重复代码放入 scripts/ 可执行无需加载
去重：信息只在一个地方维护

七、总结与展望

核心要点回顾

Skills 是什么：AI 的"岗位交接文档"，让 AI 独立完成任务
与 MCP 的区别：MCP 是工具，Skill 是使用指南
5 层结构：技能定义→角色定义→引导配置→数据源处理→输出操作
开发流程：明确场景 → 规划内容 → 初始化 → 编写 → 打包 → 迭代

最佳实践金句

"上下文窗口是公共资源。每个词都要证明它存在的价值。"

--- Skill-creator 核心原则
"大模型已经很聪明了。只添加它真正不知道的知识。"

--- Skill-creator 默认假设
"好的 Skill 设计：让 AI 像 trained employee 一样独立工作。"
"写约束时，'不做什么'比'做什么'更精确。"

--- 反模式清单比正面描述更有效
"脆弱操作脚本锁死，创造性工作文字引导。"

--- 自由度光谱原则

核心洞察：三个关键设计思想

基于 skill-creator 的设计哲学，写好 Skill 需要理解三个核心思想：

思想一：信息熵管理系统

Skill 的本质是在有限的上下文窗口内，给 AI 最有效的指令。skill-creator 设计了三级分层架构：

层级	内容	何时在上下文中	Token 成本	作用
L1	Frontmatter（name + description）	始终	~100 词	过滤器：AI 靠它判断是否激活技能
L2	SKILL.md body	触发后加载	<5k 词	操作手册：告诉 AI 怎么做
L3	scripts/references/assets	按需加载	无上限	工具箱：其中 scripts 执行而不读入，零 token 成本

关键推论：

description 不精确 → 误触发或漏触发
body 太长 → 注意力被稀释
scripts 最高效 → 执行而不读入

思想二：自由度光谱

不是所有任务都适合让 AI 自由发挥。skill-creator 用三个档位处理：

复制代码

高自由度（文字指令）←→ 中自由度（伪代码/带参数脚本）←→ 低自由度（具体脚本）
   多种方法都可行                有最佳实践但允许变通            脆弱操作，一致性至关重要
   创造性工作                    配置影响行为                   精确格式/长度约束

判断标准：

做错了后果多严重？ → 越严重 → 越低自由度
有多少种"正确"的做法？ → 越多 → 越高自由度

实际应用：

任务	自由度	实现方式
理解用户需求并提问	高	SKILL.md 文字指导
规划技能内容结构	中	模板 + 选择题式模式推荐
初始化目录结构	低	`init_skill.py` 脚本
生成 openai.yaml	低	`generate_openai_yaml.py` 脚本
编写 SKILL.md 内容	高	原则指导 + 写作建议
校验最终结果	低	`quick_validate.py` 脚本

思想三：质量保障链

skill-creator 用三个脚本形成确定性保障链，夹住中间的创造性步骤：

复制代码

init_skill.py（输入保障）
  命名标准化 + 目录结构创建 + 模板生成
  → 确保起点正确
       ↓
  AI 创造性编写（高自由度）
  → SKILL.md 内容、references、自定义 scripts
       ↓
quick_validate.py（输出保障）
  frontmatter 格式 + 命名规范 + 长度约束校验
  → 确保终点合规

关键洞察 ：脚本是"执行而不读入"的 → 零 token 成本。你可以把任意复杂的确定性逻辑封装进脚本，而不用担心占用上下文。

什么该封装成脚本？

复制代码

✅ 封装成脚本：
- 每次执行结果必须一样
- 涉及精确格式/长度约束
- 涉及命名规范转换
- 需要校验规则匹配
- 同样的代码每次都要重新写

✅ 用文字指令：
- 需要理解上下文
- 有多种合理做法
- 需要创造性判断

常见错误对照表

错误	后果	修正
触发条件放在 body 里	body 是触发后才加载的，晚了	放 frontmatter description
"When to Use This Skill" 写在 body	同上，Codex 已经决定用了才看到	移到 description
参考细节塞进 SKILL.md	body 膨胀，信息密度下降	拆到 references/，body 只放引用链接
确定性操作写成文字指令	AI 每次重新理解，可能出错	封装成 scripts/，执行不读入
references 互相引用	AI 需要多跳获取信息	所有 references 从 SKILL.md 直接链接
SKILL.md 和 references 内容重复	浪费 token，更新时可能不一致	信息只在一处存在
给人写指令而不是给 AI 写	背景、原则、版本记录对 AI 无意义	只写 AI 需要的操作指令
使用模糊的正面描述	"保持专业语气"对 AI 是无限大的可行域	改用反模式清单："不要角色堆砌"

未来趋势

随着 AI Agent 生态发展，Skills 将呈现以下趋势：

标准化：统一的 Skill 描述语言和分发机制
可组合：多个 Skill 协同完成复杂任务
自学习：根据使用反馈自动优化 Skill 内容
Marketplace：第三方技能市场，即插即用
脚本化：更多确定性操作封装成脚本，零 token 成本

附录：资源链接

官方文档

Anthropic Skill 概念文档
Hello-Agents 技能编写指南 - datawhalechina 翻译整理
Agent Skills 终极指南 - smartcity.team（1.2 万字长文，强烈推荐）
HomiClaw 技能开发完整指南 - 内部语雀文档

工具脚本

init_skill.py：技能初始化脚本
package_skill.py：技能打包脚本
generate_openai_yaml.py：生成技能名片（UI 元数据）
quick_validate.py：技能校验工具

附录：核心概念对比速查表

对比维度	Skills	MCP	Workflow（Coze/Dify）	传统 AI 应用
本质	知识包 + 行为指南	工具协议 + 服务器标准	可视化流程编排	程序代码
内容	Markdown 指令、脚本、参考文档、资产	JSON-RPC API、工具定义	节点、条件分支、API 连接器	Python/Java 等代码
作用	告诉 AI"什么时候做、怎么做"	给 AI 提供"可以调用的工具"	按预设流程执行任务	执行预设逻辑
触发	基于用户查询语义自动触发	需要 Skill 指令调用	手动触发或事件触发	函数调用/API 请求
灵活性	⭐⭐⭐⭐⭐ 利用 LLM 智能灵活应对边缘情况	⭐⭐⭐⭐ 依赖 Skill 指导	⭐⭐ 遇到预设外情况易卡住	⭐ 完全按代码执行
开发门槛	⭐⭐⭐⭐⭐ 自然语言编写，零代码	⭐⭐⭐ 需要技术知识	⭐⭐⭐ 需理解节点配置逻辑	⭐ 需要编程能力
可组合性	⭐⭐⭐⭐⭐ 多 Skill 可自由联用	⭐⭐⭐⭐ 可被多个 Skill 调用	⭐⭐⭐ 可调用外部 API	⭐⭐ 需手动集成
典型场景	重复性任务、私有知识、多步骤工作流	工具集成、数据查询	固定流程自动化	确定性业务逻辑
示例	`daily-weekly-report`：日报/周报生成	`mcp.ant.homi.claw`：会议室 API	审批流、客服机器人	订单系统、支付系统

附录：常见问题 FAQ

Q1：Skill 和 MCP 到底有什么区别？

答：用最简单的话说------

MCP 是"手和脚"：提供执行能力（工具）
Skill 是"大脑和知识库"：提供决策逻辑和领域知识

举例：mcp.ant.homi.claw 提供了 queryMeetingRooms 工具（MCP），但 AI 不知道什么时候用、怎么用。meeting-room Skill 告诉 AI："当用户说'帮我订个会议室'时，先问时间人数，再调用 queryMeetingRooms，然后展示选项"。

Q2：我什么时候应该用 Skill，什么时候直接用对话？

答：记住三个信号：

你发现自己在反复向 AI 解释同一件事
任务需要特定知识/模板/材料才能做好
一个任务需要多个流程协同完成

如果只是一次性任务或简单查询，直接用对话即可。

Q3：Skill 开发难吗？需要编程能力吗？

答：Skill 开发门槛极低------

最简单的 Skill ：只需要一个 SKILL.md 文件，纯自然语言编写
复杂的 Skill：可以加入 Python 脚本（但也可以让 AI 帮你写）
核心能力：把你的专业经验和工作流程用文档写清楚

非技术出身的领域专家，离自己做专业 Agent 只隔一层窗户纸。

Q4：Skill 会影响 AI 响应速度吗？

答：合理设计的 Skill 不会显著影响速度------

Frontmatter 元数据：始终加载（~100 词），影响极小
SKILL.md body：只在触发后加载（<5k 词）
Scripts ：执行而不读入，零 token 成本
References/Assets：按需加载

关键在于渐进式披露设计，避免把所有内容都塞进 SKILL.md body。

Q5：多个 Skill 会冲突吗？

答：不会。Skill 采用基于语义的触发机制------

AI 会根据你的 query 和每个 Skill 的 description 判断是否相关
多个相关 Skill 可以同时激活、协同工作
例如：brand-guidelines + pptx 可以联用，自动生成符合品牌规范的 PPT

但要注意：Skill 越多，元数据占用的上下文也越多，建议只启用真正需要的 Skill。

作者简介：hz的文档整理专家蒜蓉🦐～，专注于 AI 工程化与 Agent 技能开发，探索大模型与企业系统的最佳集成实践。

欢迎交流：如有问题或建议，欢迎在评论区留言讨论！

🚀 下一步行动

现在你已经掌握了 Skill 开发的核心方法，建议：

动手实践：从一个小技能开始（如 PDF 旋转、日报生成）

参考模板：查看 4.6 节的完整示例，复制你的第一个 Skill 框架

检查清单 ：用 4.5 节的最佳实践清单验证你的 Skill

遇到问题 ：查看第六章调试与优化 或附录 FAQ

加入社区：分享你的 Skill 开发经验，共同成长

记住：好的 Skill 不是一次写成的------迭代优化才是关键！

本文基于 Anthropic 官方 Skill 设计指南、官方【日/周报生成】Skill 最佳实践和实际开发经验编写，内容持续更新。