适用范围： 本规范适用于用户在 Skills 广场创建自定义 Skills 时，本地组装并打包 ZIP 文件的要求。内置 Skills 和企业共享 Skills 无需自行打包。
说明：
本平台遵循业界广泛采纳的 Agent Skills 开放规范，作为统一的 Skills 格式标准。以下要求均为该规范的硬性校验项，不满足将直接导致上传失败。
一、ZIP 包基础约束
要求项 | 说明 |
文件格式 | 仅支持 .zip 格式。 |
文件大小 | 最大 10 MB。 |
文件数量 | ZIP 包内文件总数不超过 300 个。 |
文件类型 | 不允许在 ZIP 包任意位置包含二进制文件，包括但不限于： 可执行文件：.exe、.dll、.so、.dylib 等。 图片/媒体文件：.png、.jpg、.gif、.mp4 等。 压缩/归档文件：.zip、.tar、.gz 等。 ZIP 包内只允许包含纯文本格式文件（例如： .md、.py、.js、.txt、.json、.yaml 等）。 |
根目录结构 | ZIP 包根目录下必须直接包含 SKILL.md 文件，不可嵌套在子文件夹中。 |
文件正确结构： 解压后
SKILL.md 直接位于根目录，无外层包裹文件夹：my-skill.zip├── SKILL.md├── scripts/│ └── main.py├── references/│ └── api-docs.md└── assets/└── config.json
文件错误结构：
SKILL.md 被嵌套在子文件夹里：my-skill.zip└── my-skill/ ← 多余的包裹层，SKILL.md 未在根目录├── SKILL.md├── scripts/└── references/
二、SKILL.md 硬性规范
SKILL.md 是 Skills 的入口文件，由两部分组成，必须同时满足本节所有规范，缺一不可：YAML Frontmatter（元数据区）：位于文件开头，用一对
--- 包裹，包含 Skills 的标识、描述、许可证等元信息，供平台识别和校验。其中 name 和 description 为必填字段。Markdown 正文：紧跟 Frontmatter 闭合的
--- 之后，说明 Skills 的具体使用方式、调用逻辑、注意事项等，供 LLM 在运行时理解并执行。2.1 文件名
文件名大小写精确：必须是
SKILL.md，不能是 skill.md、Skill.md 或其他变体。2.2 YAML Frontmatter 基础格式
元数据区只需一对
--- 包裹（开头开始、闭合结束），闭合后直接写正文，中间不要再插入额外的 --- 分隔线。格式示范（
SKILL.md 文件开头）：---name: pdf-processingdescription: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF 文件。当用户提到 PDF、表单填写、文档提取或需要处理 .pdf 文件时使用此技能。license: MITmetadata:author: your-nameversion: 1.0.0---# PDF Processing这里开始写 Markdown 正文，说明 Skills 的具体使用方式……
上例中，
license、metadata 为可选字段。2.3 name 字段（必填）
约束 | 说明 |
长度 | 3～64 个字符。 |
字符集 | 仅允许小写字母（a-z）、数字（0-9）和连字符（ -）。不允许大写字母、下划线、空格、中文或其他特殊字符。 |
首尾限制 | 不能以连字符开头，不能以连字符结尾。 |
连续连字符 | 不允许出现连续连字符（ --）。 |
唯一性 | name 需在企业内唯一，与已安装 Skills 重名时导入将失败。 |
合法示例：
pdf-processingdata-analysiscode-review非法示例：
PDF-Processing（含大写字母）。-pdf（以连字符开头）。pdf_processing（含下划线）。2.4 description 字段（必填）
约束 | 说明 |
长度 | 1～1024 个字符，不能为空。 |
内容要求 | description 是 LLM 选择是否调用该 Skills 的关键依据，建议同时包含 Skills 功能（做什么）和触发场景（什么时候用），以便平台更准确地识别和调用该 Skills。 |
建议参考的示例：
description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF 文件。当用户提到 PDF、表单填写、文档提取或需要处理 .pdf 文件时使用此技能。不建议的写法（可能影响 Skills 触发效果）：
description: 处理 PDF。（过于模糊，缺少触发场景）。description: 帮助处理文档（没有说明具体功能和触发条件）。留空（上传将失败）。
2.5 可选字段
字段 | 说明 |
license | 许可证标识，可以是 SPDX 许可证标识（如 MIT、Apache-2.0），也可以是 ZIP 包内附带的许可证文件名（如 LICENSE.txt）。 |
compatibility | 环境兼容约束，最多 500 字符，标注运行 Skills 所需平台、依赖、网络等条件（例： Python 3.10+）。无特殊环境限制的常规 Skills，可省略该字段不填。 |
metadata | 自定义键值对扩展信息，使用 YAML 嵌套对象格式（如 author: your-name、version: 1.0.0）。其中 version 建议遵循语义化版本规范（SemVer，如 1.0.0），更新时新版本号必须高于当前最新版本。 |
2.6 Markdown 正文
正文建议控制在 500 行以内，内容过多时拆分为
references/ 目录下的独立文件。引用其他文件时使用相对于 Skills 根目录的路径，如
references/api-docs.md、scripts/main.py。三、标准目录结构
（ZIP 根目录）├── SKILL.md ← 必填：YAML 元数据 + Markdown 指令正文，须直接位于根目录├── scripts/ ← 可选：可执行脚本（Python/Bash/JS 等）├── references/ ← 可选：按需加载的参考文档└── assets/ ← 可选：模板文件、图标等静态资源
3.1 scripts/ 目录
存放 Skills 运行时可执行脚本，支持 Python、Bash、JavaScript 等语言。
3.2 references/ 目录
存放按需加载的参考文档（Markdown 格式）。LLM 在执行任务时，会根据 Skills 正文中的引用自主决定是否加载对应参考文档，未引用的文件不会预加载。
3.3 assets/ 目录
存放文本格式的模板文件、配置文件等静态资源。注意：ZIP 包内任意位置均不允许放置二进制文件（图片、可执行文件等）。
3.4 打包方式
进入 Skills 文件夹内执行
zip -r ../skill.zip .，确保 SKILL.md 位于 ZIP 根目录。打包时排除 __pycache__、.DS_Store、.git 等无关文件。四、平台主要错误码及相关说明
错误码 | 说明 | 解决方案 |
450019 | 技能包缺少 SKILL.md 文件，请确认压缩包解压后 SKILL.md 直接位于根目录。 | 检查 ZIP 内是否有 SKILL.md，且不在过深的嵌套目录中。 |
450020 | SKILL.md 缺少必填信息，请补全 name 和 description。 | 在 SKILL.md 开头的元数据区填写 name 和 description 字段。 |
450033 | 技能包中包含不支持的文件。 | 删除 .exe/.png/.mp4 等二进制文件后重新上传。 |
450034 | 技能包内文件数量超过上限 300。 | 减少文件数量后重新上传。 |
五、FAQ
5.1 我的压缩包解压后明明有 SKILL.md，为什么还报 450019？
原因有以下几种：
1. 同一层级有多个 SKILL.md：如
dir1/SKILL.md 和 dir2/SKILL.md，平台无法确定哪个是根目录，会拒绝。不同层级的多个 SKILL.md 不会报错（如 a/SKILL.md 和 a/b/SKILL.md，平台取最浅的 a/ 作为根目录）。2. ZIP 文件损坏：压缩包本身格式有问题。
排查方法：
# 查看 ZIP 内文件列表unzip -l my-skill.zip# 确认 SKILL.md 位置unzip -l my-skill.zip | grep SKILL.md
5.2 Windows 打的 ZIP 包上传后中文文件名乱码怎么办？
平台已做兼容处理（GBK → UTF-8 自动转换），正常情况下不会出现乱码。若仍有问题，建议使用以下工具重新打包：
7-Zip：选择 UTF-8 编码。
PowerShell：
Compress-Archive -Path .\\my-skill -DestinationPath my-skill.zip。Git Bash：
zip -r my-skill.zip my-skill/。5.3 技能标识 name 的命名有什么规则？
仅允许小写字母、数字、连字符（
-）。不能以连字符开头或结尾。
长度 3-64 个字符。
同一企业内唯一。
name | 是否合法 | 原因 |
pdf-tool | ✅ | - |
weather123 | ✅ | - |
My-Skill | ❌ | 包含大写字母 |
my_skill | ❌ | 包含下划线 |
-weather | ❌ | 以连字符开头 |
weather- | ❌ | 以连字符结尾 |
ab | ❌ | 少于 3 字符 |
5.4 SKILL.md 的 description 支持多行吗？
支持。可以使用 YAML 块标量语法：
---name: my-skilldescription: |这是一个多行描述。第二行内容。第三行内容。---
也支持折叠块标量
>：description: >这是一段很长的描述，会被折叠成一行。
description 最多 1024 个字符，超长会被截断。
5.5 哪些文件会被自动过滤？
以下文件不会上传到运行环境，也不计入文件数量：
类型 | 文件/目录 | 说明 |
macOS 元数据 | __MACOSX/ | macOS 压缩工具自动生成。 |
macOS 扩展属性 | ._* | 如 ._SKILL.md。 |
macOS Finder | .DS_Store | 目录显示设置文件。 |
Windows 缩略图 | Thumbs.db | Windows 资源管理器缩略图缓存。 |
Windows 配置 | desktop.ini | Windows 文件夹配置文件。 |
Python 缓存 | __pycache__/ | Python 字节码缓存目录。 |
Python 字节码 | *.pyc、*.pyo | Python 编译产物。 |
Git 元数据 | .git/ | Git 版本控制目录。 |
IDE 配置 | .idea/、.vscode/ | JetBrains / VS Code 配置目录。 |
5.6 版本号有什么要求？
必须符合 SemVer 格式：
主版本.次版本.修订号（如 1.0.0）。修改技能时，新版本号必须严格高于当前版本。
不支持
v1.0、1.0、latest 等非标准格式。5.7 如何排查"技能包不可用"（450019）错误？
按以下步骤排查：
1. 检查 SKILL.md 是否存在：
unzip -l my-skill.zip | grep SKILL.md
2. 检查是否有多个 SKILL.md：
unzip -l my-skill.zip | grep -c SKILL.md# 输出 > 1 则需要删掉多余的
3. 检查路径安全性：
unzip -l my-skill.zip# 确认没有异常路径（如绝对路径、特殊字符等）
4. 检查 ZIP 是否损坏：
unzip -t my-skill.zip# 报错说明 ZIP 文件损坏，需要重新打包
5.8 文件数量限制 300 是否包含系统文件？
不包含。被自动过滤的系统垃圾文件（
.DS_Store、__MACOSX/ 等）不计入文件数量。300 个限制只计算有效文件。5.9 不同系统推荐的打包建议
推荐使用以下方式打包，避免编码和路径问题：
macOS：
cd my-skillzip -r ../my-skill.zip . -X
-X 参数排除 macOS 扩展属性。Linux：
cd my-skillzip -r ../my-skill.zip .
Windows (PowerShell)：
Compress-Archive -Path .\\my-skill\\* -DestinationPath my-skill.zip
