Skill 构建指南:从零打造 AI 智能体扩展包
引言
在人工智能时代,如何让智能体具备更强的专业能力和更丰富的工作流程?答案就是 Skill——一种为智能体设计的能力扩展包。本文将详细介绍如何从零开始构建符合规范的 Skill,让你的创意变成可分发的工具。
什么是 Skill?
核心定位
Skill 是被智能体加载和执行的能力扩展包,而非独立运行的应用程序。
详细介绍如何从零构建符合规范的 Skill(AI 智能体扩展包)。内容包括目录结构、命名规范、SKILL.md 文件编写(YAML 前言区与正文区)、实现方式选择(脚本与自然语言指导的决策树)、资源目录(scripts/references/assets)详解、打包与清理流程以及质量校验清单。文章强调避免过度工程化,充分利用智能体已有能力,仅在必要时引入脚本工具,确保技能包高效、合规地分发与执行。
在人工智能时代,如何让智能体具备更强的专业能力和更丰富的工作流程?答案就是 Skill——一种为智能体设计的能力扩展包。本文将详细介绍如何从零开始构建符合规范的 Skill,让你的创意变成可分发的工具。
Skill 是被智能体加载和执行的能力扩展包,而非独立运行的应用程序。
/workspace/projects/ └── <skill-name>/ # Skill 根目录
├── SKILL.md # 必需:入口与指南
├── scripts/ # 可选:可执行代码
├── references/ # 可选:参考文档
└── assets/ # 可选:静态资源
严格统一使用以下结构,Skill 不允许包含任何额外的文件或文件夹:
| 路径 | 必需性 | 说明 |
|---|---|---|
<skill-name>/SKILL.md | 必需 | 入口与指南,含 YAML 前言区 |
<skill-name>/scripts/ | 可选 | 可执行代码(Python/Bash 等) |
<skill-name>/references/ | 可选 | 长参考与细节文档 |
<skill-name>/assets/ | 可选 | 资源文件(模板/图标等) |
<skill-name>(必须使用英文小写字母和连字符拼接,例如:exam-grading、pdf-parser)-skill 后缀:目录名不应以 -skill 结尾<skill-name>.skill(目录名 + .skill 扩展名)exam-grading/ → 打包为 exam-grading.skillSKILL.md 以 YAML 前言区开始,包含以下字段:
---
name: skill-name # 必需:Skill 名称(小写字母 + 连字符)
description: Skill 的核心能力与触发场景描述 # 必需:100-150 字符
dependency:
# 可选:依赖管理
python:
# Python 依赖包
- package-name==version
- another-package>=1.2.0
system:
# 系统级命令
- mkdir -p some-path
---
exam-grading、pdf-parser、data-cleaner示例:
description: 支持批量评分与反馈生成;处理多种题型(选择题/简答题/论述题);可自定义评分标准;支持导出成绩报告
python 子字段:
示例:
dependency:
python:
- requests==2.28.0
- pandas>=1.5.0
system 子字段:
示例:
dependency:
system:
- mkdir -p extra-files/input
- chmod +x scripts/*.sh
正文部分使用 Markdown 编写,遵循以下原则:
references/ 并在正文一层链接# Skill 标题
## 任务目标
- 本 Skill 用于:一句话场景
- 能力包含:核心能力要点
- 触发条件:典型用户表达或上下文信号
## 前置准备
- 依赖说明:scripts 脚本所需的依赖包及版本
- 非标准文件/文件夹准备:需要前置创建的文件或文件夹
## 操作步骤
- 标准流程:
1. 步骤 1:输入/准备
- 如果涉及脚本执行,说明:调用 `scripts/<script-name>.py` 处理...
- 如果由智能体处理,说明:根据参考文档中的指导...
2. 步骤 2:执行/处理
3. 步骤 3:输出/校验
- 可选分支:
- 当 条件 A:执行 分支 A
- 当 条件 B:执行 分支 B
## 资源索引
- 必要脚本:见 [scripts/<script-name>.py](scripts/<script-name>.py)
- 领域参考:见 [references/<topic>.md](references/<topic>.md)
- 输出资产:见 [assets/<template-dir>/](assets/<template-dir>/)
## 注意事项
- 仅在需要时读取参考,保持上下文简洁
- 当操作脆弱或需强一致性时,优先调用脚本执行
- 充分利用智能体的语言理解和生成能力
## 使用示例(可选)
根据实际功能提供 2-3 个典型使用场景
在编写 Skill 之前,首先要明确:智能体已经具备强大的能力:
已有能力清单:
第一步:问自己"智能体能做吗?"
如果任务属于以下类型 → 使用自然语言指导(在 SKILL.md 中描述):
如果任务属于以下类型 → 使用脚本(在 scripts/ 中实现):
| 任务 | ❌ 错误做法 | ✅ 正确做法 |
|---|---|---|
| 图像生成 | 在 scripts/ 中编写脚本调用图像生成 API | 在 SKILL.md 中描述图像需求 |
| 文档分析 | 编写 Python 脚本提取关键信息 | 在 SKILL.md 中指导:阅读文档并提取关键信息 |
| API 鉴权调用 | 在 SKILL.md 中写:'请调用 XX API' | 在 scripts/ 中实现完整的 API 调用脚本 |
| PDF 格式转换 | 在 SKILL.md 中写:'请转换 PDF' | 在 scripts/ 中使用 pypdf 等库实现转换 |
当脚本需要调用第三方 API 时,必须遵循以下四步流程:
按照优先级顺序查找实现方案:
判断是否需要授权以及授权类型:
| 授权类型 | auth_type 值 | 适用场景 | 凭证字段要求 |
|---|---|---|---|
| ApiKey | 1 | 使用 API 密钥认证 | ["API_KEY"] 或 ["ACCESS_TOKEN"] 等 |
| WeChatOfficialAccount | 2 | 微信公众号相关请求 | ["APP_ID", "APP_SECRET"] |
| OAuth | ❌ 不支持 | OAuth2.0 授权流程 | 暂不支持 |
根据授权类型调用凭证工具让用户填写凭证信息。
必须使用 coze-workload-identity 包中的 requests 或 httpx,不要使用标准库。
示例代码结构:
import os
from coze_workload_identity import requests
def call_api():
# 1. 获取凭证
skill_id = "7603377970841174059"
credential = os.getenv("COZE_<CREDENTIAL_NAME>_<SKILL_ID>")
# 2. 构建请求
url = "<API_URL>"
headers = {
"Content-Type": "application/json",
}
# 3. 发起请求
response = requests.post(url, headers=headers, json={}, timeout=30)
response.raise_for_status()
return response.json()
write_file 全量重写超过 100 行的文件需含目录(TOC):
# <Topic>
## 目录
列出主要章节
## 概览
一句话定义与适用范围
## 核心内容
- 数据结构/格式定义(含完整示例)
- 验证规则
- 常见操作(输入→处理→输出)
- 约束与注意事项
## 示例
2-3 个可复制执行的标准示例
若被脚本依赖,必须提供:
对于 Skill 使用过程中需要生成的文件,必须在此处提供格式模板。
存放最终输出需要直接引用的文件:
清理范围:
清理目标:
__pycache__、.DS_Store)package_skill(skill_dir_name="your-skill-name").skill 文件已生成且大小合理注意:必须使用 package_skill 工具进行打包,严禁使用 zip 命令手动打包。
name 符合命名规范(小写字母 + 连字符)description 采用单行文本格式description 内容包含核心能力与触发场景description 长度在 100-150 字符之间脚本:
参考:
资产:
.skill 为 Zip❌ 错误:为"生成文章大纲"编写 Python 脚本
✅ 正确:在 SKILL.md 中写:"根据主题生成包含 3-5 个章节的大纲"
❌ 错误:编写脚本调用图像生成 API
✅ 正确:直接在 SKILL.md 中描述图像需求
❌ 错误:为"格式化文本列表"写脚本
✅ 正确:在 SKILL.md 中说明格式要求
❌ 错误:在 scripts/ 中实现 Flask/FastAPI web server
❌ 错误:编写 while True 循环等待用户输入
❌ 错误:实现完整的命令行交互菜单
✅ 正确:所有用户交互由智能体在对话中完成
典型场景:小说创作、角色设计、情节构思、文案生成等
❌ 错误做法:
✅ 正确做法:
核心原则:智能体擅长创造,脚本擅长计算
构建一个优质的 Skill 需要遵循清晰的规范和最佳实践。通过合理选择实现方式、精心设计目录结构、严格遵循质量门槛,你可以创造出真正有价值的智能体扩展包。
记住核心原则:扩展而非重复。充分利用智能体已有能力,仅在必要时引入额外工具。这样你的 Skill 才能既强大又高效。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
使用加密算法(如AES、TripleDES、Rabbit或RC4)加密和解密文本明文。 在线工具,加密/解密文本在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online