跳转到主要内容
千问AI平台 home page
文档

创建自定义 Skill

当官方 Skill 无法满足业务需求时，可通过上传 ZIP 技能包创建自定义 Skill。本文说明 ZIP 包的要求和 SKILL.md 的编写规范。

当官方 Skill 无法满足业务需求时，可通过上传 ZIP 技能包创建自定义 Skill。
上传的控制台操作步骤和 API 调用方式见 Agent Skill，本文只讲 ZIP 包该怎么准备。

ZIP 技能包要求

要求说明
必须包含 SKILL.mdZIP 包根目录下必须有 SKILL.md 文件，用于定义 Skill 元信息。
大小限制整个 ZIP 包不超过 10 MB。
名称唯一SKILL.md 中的 name 字段不可与当前账号下已有 Skill 重名。

SKILL.md 编写规范

SKILL.md 使用 YAML 格式定义 Skill 的名称和描述。格式如下： 
name: my-custom-skill
description: "Skill 的功能描述，包含触发条件、适用场景和不适用场景。"
字段说明
字段必填说明
name是Skill 的唯一标识名称。建议使用小写英文和连字符，如 data-cleaner、invoice-parser。
description是描述 Skill 的触发条件和处理能力。智能体根据此描述判断是否调用该 Skill，因此描述的质量直接影响 Skill 的调用准确率。
description 编写建议 description 的质量决定了智能体调用 Skill 的准确性。建议包含以下信息：
  1. 适用的输入类型：明确 Skill 处理的文件格式或数据类型。
  2. 支持的操作：列出 Skill 可以执行的具体操作。
  3. 触发关键词：用户对话中可能出现的、应触发该 Skill 的关键词或表达方式。
  4. 不适用的场景：标注不应触发该 Skill 的场景，避免误调用。
完整示例 以下是官方 xlsx Skill 的 SKILL.md 示例： 
name: xlsx
description: "Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path - even casually (like \"the xlsx in my downloads\") - and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved."
该示例中：
  • 明确了支持的文件格式（.xlsx、.xlsm、.csv、.tsv）。
  • 列出了适用操作（读取、编辑、创建、格式转换、数据清洗等）。
  • 包含了触发场景描述（用户提到文件名或路径时也应触发）。
  • 标注了不适用的场景（产出物为 Word、HTML、Python 脚本等情况）。

提交后的审查

提交后系统会自动审查 Skill 内容，预计耗时约 2 分钟，期间状态为 checking。
  • 审查通过：状态变为 active，Skill 出现在自定义标签页中，可挂载到智能体。
  • 审查未通过：状态变为 rejected，不能挂载。请根据提示修改 SKILL.md 内容后重新上传。

更新自定义 Skill

重新上传同名 Skill 的 ZIP 包时，系统会创建新版本，流程与首次创建一致：
  1. 修改本地 ZIP 包中的内容（如更新 SKILL.md 中的 description）。
  2. 在自定义标签页中重新上传 ZIP 包。
  3. 审查通过后生成新版本号。
挂载到智能体时必须指定具体版本号，上传新版本不会自动改变已挂载智能体使用的版本。如需让智能体用上新版本，要在智能体配置里把版本改过去。

下一步

  • Agent Skill：上传、挂载、版本管理与删除的完整操作。
  • Skill 简介：Skill 的定位与调用机制。