详细介绍如何从零构建符合规范的 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