Skill 构建指南：AI 智能体扩展包开发

SKILL.md 文件详解

前言区（YAML）

SKILL.md 以 YAML 前言区开始，包含以下字段：

---
name: skill-name # 必需：Skill 名称（小写字母 + 连字符）
description: Skill 的核心能力与触发场景描述 # 必需：100-150 字符
dependency:
  python:
    - package-name==version
    - another-package>=1.2.0
  system:
    - mkdir -p some-path
---

name 字段（必需）

• 格式：英文小写字母和连字符拼接
• 示例：exam-grading、pdf-parser、data-cleaner

description 字段（必需）

• 格式：单行文本，清晰说明"能做什么"与"何时触发"
• 内容要求：
  • 包含 Skill 核心价值
  • 列举几个典型的互不耦合的场景或意图
• 长度：100-150 字符

示例：

description: 支持批量评分与反馈生成；处理多种题型（选择题/简答题/论述题）；可自定义评分标准；支持导出成绩报告

dependency 字段（可选）

python 子字段：

• 直接列出包名和版本
• 禁止写安装命令

示例：

dependency:
  python:
    - requests==2.28.0
    - pandas>=1.5.0

system 子字段：

• 前置需要执行的命令行命令
• 当前路径视为相对于 Skill 目录的父目录
• 仅用于系统级命令（mkdir、chmod 等）
• 禁止包含 Python 包安装命令

示例：

dependency:
  system:
    - mkdir -p extra-files/input
    - chmod +x scripts/*.sh

正文区（Markdown）

正文部分使用 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 个典型使用场景

正文体量要求

• 不超过 500 行
• 参考链接均为一层链接
• 避免与参考重复

实现方式选择指南

理解智能体已有能力

在编写 Skill 之前，首先要明确：智能体已经具备强大的能力：

已有能力清单：

• 语言理解与推理：深度理解复杂指令，进行逻辑推理与决策
• 内容创作：文案撰写、报告生成、文档编写、创意产出
• 多模态能力：
  • 图像识别：理解和分析图片内容
  • 图像生成：根据文本描述生成图片
• 知识问答：领域知识解答、实践建议
• 结构化思维：问题拆解、流程规划、框架设计

实现方式决策树

第一步：问自己"智能体能做吗？"

如果任务属于以下类型 → 使用自然语言指导（在 SKILL.md 中描述）：

• ✅ 内容创作：文案、报告、文档生成
• ✅ 知识咨询：概念解释、最佳实践建议
• ✅ 分析推理：文本分析、情感分析、决策建议
• ✅ 结构化引导：问题拆解、流程规划
• ✅ 多模态任务：图像识别、图像生成
• ✅ 灵活输出：根据上下文动态调整格式

如果任务属于以下类型 → 使用脚本（在 scripts/ 中实现）：

• 🔧 文件格式处理：docx/pdf/Excel 转换、图片压缩、二进制操作
• 🔧 外部 API 调用：需要鉴权的第三方服务、复杂 API 工作流
• 🔧 复杂数据计算：数学统计、算法实现、大规模数据处理
• 🔧 系统级操作：批量文件操作、进程管理、网络爬虫

对比示例

scripts/ 目录详解

脚本设计原则

1. 纯函数式工具：脚本应为接收参数 → 处理数据 → 返回结果的函数
2. 无交互逻辑：不应包含主动循环、服务监听、用户交互逻辑
3. 直接可执行：无需修改即可直接调用执行
4. 参数化设计：所有动态变量必须通过参数传入，禁止硬编码

脚本调用第三方服务

当脚本需要调用第三方 API 时，必须遵循以下四步流程：

第一步：确定实现调用方式

按照优先级顺序查找实现方案：

1. 优先级 1：用户提供的文档
2. 优先级 2：网络搜索
3. 优先级 3：基于已有知识确定调用方式

第二步：分析授权类型

判断是否需要授权以及授权类型：

第三步：调用凭证工具

根据授权类型调用凭证工具让用户填写凭证信息。

第四步：生成代码

必须使用 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()

脚本调试与修复

• 全景调试：报错时必须读取报错位置前后各 150-200 行代码
• 阻断式重写：同一 Bug 修复失败 3 次时，直接使用 write_file 全量重写

references/ 目录详解

参考文档结构

超过 100 行的文件需含目录（TOC）：

# <Topic>
## 目录
列出主要章节
## 概览
一句话定义与适用范围
## 核心内容
- 数据结构/格式定义（含完整示例）
- 验证规则
- 常见操作（输入→处理→输出）
- 约束与注意事项
## 示例
2-3 个可复制执行的标准示例

格式规范要求

若被脚本依赖，必须提供：

• 明确的格式定义
• 完整示例
• 验证规则

文件模板要求

对于 Skill 使用过程中需要生成的文件，必须在此处提供格式模板。

assets/ 目录详解

用途

存放最终输出需要直接引用的文件：

• 模板文件
• 图标
• 样板文件

使用原则

• 在输出中可直接引用
• 路径与格式正确
• 避免在脚本中硬编码长文本（超过 50 行的 HTML/CSS/JSON 必须剥离为独立文件）

打包与清理

打包前清理（必须完成）

清理范围：

• Skill 目录内：仅保留 SKILL.md 及有内容的 scripts/、references/、assets/
• Skill 同级目录：移除所有临时文件及文件夹

清理目标：

• 脚本试运行产生的临时输出文件或日志
• 测试生成的临时数据文件夹
• 系统缓存（__pycache__、.DS_Store）
• 空目录（检查并删除没有任何文件的目录）

打包执行

1. 调用打包工具：package_skill(skill_dir_name="your-skill-name")
2. 验证打包结果：确认 .skill 文件已生成且大小合理

注意：必须使用 package_skill 工具进行打包，严禁使用 zip 命令手动打包。

质量门槛与校验清单

前言区检查

• name 符合命名规范（小写字母 + 连字符）
• description 采用单行文本格式
• description 内容包含核心能力与触发场景
• description 长度在 100-150 字符之间
• 触发场景具体明确，包含典型用户表达

正文检查

• 不超过 500 行
• 参考均为一层链接
• 使用祈使语气
• 避免与参考重复

目录结构检查

• 目录规范
• 无多余文档
• 引用路径正确
• 长参考含 TOC
• 无空目录

实现方式合理性检查

• 脚本使用符合"实现方式决策树"
• 内容创作、知识咨询、分析推理类任务未使用脚本
• 文件处理、API 调用、复杂计算等使用了脚本
• 每个脚本都有明确的技术性理由
• SKILL.md 中清晰说明智能体和脚本的职责分工

资源质量检查

脚本：

• 通过语法校验
• 自行试运行通过
• 架构合规性：脚本为纯函数式工具
• 依赖清晰
• 参数规范
• 直接可执行
• 格式一致性：脚本输入解析逻辑与 references 中定义的格式规范完全一致
• 涉及第三方 API 时已完整执行"脚本调用第三方服务"流程

参考：

• 无深层嵌套引用
• 超过 100 行含目录
• 命名清晰
• 若被其他资源依赖，需提供明确的格式、结构或模板

资产：

• 在输出中可直接引用
• 路径与格式正确

打包检查

• .skill 为 Zip
• 包含所有必要文件
• 相对路径一致
• 产物仅包含 Skill 相关文件
• 不含临时文件、生成脚本、缓存与日志

依赖元数据检查

• 格式符合 YAML 规范
• python 字段遵循 requirement.txt 格式
• system 字段为有效的命令行命令列表

常见误区与纠正

误区 1：为简单任务过度工程化

❌ 错误：为"生成文章大纲"编写 Python 脚本
✅ 正确：在 SKILL.md 中写："根据主题生成包含 3-5 个章节的大纲"

误区 2：重复建设智能体能力

❌ 错误：编写脚本调用图像生成 API
✅ 正确：直接在 SKILL.md 中描述图像需求

误区 3：脚本缺乏必要性

❌ 错误：为"格式化文本列表"写脚本
✅ 正确：在 SKILL.md 中说明格式要求

误区 4：把 Skill 当成独立应用（严重错误）

❌ 错误：在 scripts/ 中实现 Flask/FastAPI web server
❌ 错误：编写 while True 循环等待用户输入
❌ 错误：实现完整的命令行交互菜单
✅ 正确：所有用户交互由智能体在对话中完成

误区 5：为创作类任务编写"生成器"脚本

典型场景：小说创作、角色设计、情节构思、文案生成等

❌ 错误做法：

• 编写 character_builder.py 随机生成角色名和属性
• 编写 plot_suggester.py 从预设列表中随机选择情节

✅ 正确做法：

• 在 SKILL.md 中描述角色设计要点
• 在 references/ 中提供参考素材
• 让智能体根据用户需求和上下文创造性地完成

核心原则：智能体擅长创造，脚本擅长计算

核心法则总结

1. 流程强制性：严格按"创建→编辑→打包→交付"顺序执行，不允许跳过打包
2. 防卡死推进：严格按流程推进，不在任何步骤停留
3. 错误恢复强制性：工具调用失败后禁止盲目重试，必须先诊断再修复
4. 状态追踪强制性：持续追踪当前 Skill 目录名和完整路径
5. 简洁为王：上下文窗口是共享资源，只放必要信息
6. 避免重复建设：智能体已有的能力不要用脚本重新实现
7. 避免过度工程化：不要为简单任务引入脚本

结语

构建一个优质的 Skill 需要遵循清晰的规范和最佳实践。通过合理选择实现方式、精心设计目录结构、严格遵循质量门槛，你可以创造出真正有价值的智能体扩展包。

记住核心原则：扩展而非重复。充分利用智能体已有能力，仅在必要时引入额外工具。这样你的 Skill 才能既强大又高效。