注意：说明：
注意：本平台遵循业界广泛采纳的 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-name version: 1.0.0—# PDF Processing这里开始写 Markdown 正文，说明 Skills 的具体使用方式……
上例中，license、metadata 为可选字段。
五、2.3 name 字段（必填）
| 约束 | 说明 |
| 长度 | 3～64 个字符。 |
| 字符集 | 仅允许小写字母（a-z）、数字（0-9）和连字符（-）。不允许大写字母、下划线、空格、中文或其他特殊字符。 |
| 首尾限制 | 不能以连字符开头，不能以连字符结尾。 |
| 连续连字符 | 不允许出现连续连字符（–）。 |
| 唯一性 | name 需在企业内唯一，与已安装 Skills 重名时导入将失败。 |
合法示例：
·pdf-processing
·data-analysis
·code-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。 | 减少文件数量后重新上传。 |
十六、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 个字符，超长会被截断。
20、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 配置目录。 |
21、5.6 版本号有什么要求？
·必须符合 SemVer 格式：主版本.次版本.修订号（如 1.0.0）。
·修改技能时，新版本号必须严格高于当前版本。
·不支持 v1.0、1.0、latest 等非标准格式。
22、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 文件损坏，需要重新打包
23、5.8 文件数量限制 300 是否包含系统文件？
不包含。被自动过滤的系统垃圾文件（.DS_Store、__MACOSX/ 等）不计入文件数量。300 个限制只计算有效文件。
24、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