Skill 接入规范

本文面向 Skill 开发者，定义 Skill 发布到 AgentHub、接入 WinWork 平台以及被 Agent 安装使用时的最小交付要求。

适用范围

本文覆盖两类约束：

平台当前强校验：文件结构、包名、大小、安全扫描、协议校验等，会直接影响 Skill 是否能通过入库审核
团队推荐约定：帮助 Skill 在 WinWork 的 Agent 生态中更易复用、更易维护、更易排障

字段语法和目录参考见 Skill 格式规范。

当前上传强校验

以下规则来自当前平台实际上传校验，命中后会直接上传失败。

上传文件类型

上传内容必须是有效的 .zip 压缩包，或单个 SKILL.md 文件
文件大小不能超过 50MB
如果上传的是 ZIP，压缩包根目录必须直接包含 SKILL.md

ZIP 包名规则

只能包含小写字母、数字、点号 .、下划线 _、连字符 -
必须以小写字母或数字开头
长度为 1-128 个字符

示例：

pdf-to-word.zip
daily-todo-collector.zip
personality-match.zip

`SKILL.md` 基础校验

文件必须以 --- 开头，并以 --- 结尾
必须包含 name 字段
必须包含 version 字段

最小可上传示例：

markdown

---
name: pdf-to-word
version: 1.0.0
description: 将 PDF 转换为可编辑 Word 文档
---

# PDF 转 Word

这里填写技能说明、触发场景、使用步骤和注意事项。

---

`version` 字段规则

可包含字母、数字、点号 .、下划线 _、加号 +、连字符 -
必须以字母或数字开头
长度为 1-64 个字符

示例：

1.0.0
v2.1.3
1.0.0-beta
2.0.0+build.123
V1.2.3

TIP

如果你希望 Skill 在列表页和搜索结果中更易理解，仍然建议补充 description，但当前上传强校验至少要求 name 和 version。

最小目录结构

Skill 以文件夹为基本交付单元，根目录至少包含一个 SKILL.md。

text

my-skill/
├── SKILL.md           # 必需：Skill 元数据和功能说明
├── README.md          # 推荐：给维护者和使用者看的说明
├── api.yaml           # 可选：OpenAPI 规范（如有 API 接口）
├── metadata.openclaw  # 可选：运行时依赖与安装说明
├── .agenthubignore    # 可选：发布排除规则
├── config/            # 可选：配置文件
├── examples/          # 可选：示例输入输出
├── tools/             # 可选：工具定义
├── prompts/           # 可选：提示词模板
└── scripts/           # 可选：辅助脚本

必需文件

`SKILL.md`

平台会将 SKILL.md 识别为 Skill 的入口文件，并从 frontmatter 中提取元数据。

最小示例：

markdown

---
name: my-skill
description: 通过外部服务为 Agent 提供任务管理能力
version: 1.0.0
---

## 能力说明

该 Skill 为 Agent 提供任务查询、创建和更新能力。

### 使用提示

- 优先调用实时接口，不要依赖历史知识
- 出错时返回明确的失败原因和下一步建议

---

文件	作用	建议程度
`README.md`	说明使用场景、限制和示例	推荐
`api.yaml`	声明外部 API 结构和参数	有 API 时推荐
`metadata.openclaw`	声明运行时依赖、安装要求、环境变量	推荐
`examples/`	存放调用示例、输入输出样例	推荐
`.agenthubignore`	排除本地配置、测试和构建产物	推荐

`SKILL.md` 元数据

基础 frontmatter

字段	类型	必需	说明
`name`	string	是	Skill 唯一标识符
`description`	string	否	强烈建议填写，用于 UI 和搜索
`version`	string	是	版本号
`author`	string	否	作者或维护团队
`tags`	string[]	否	分类和搜索标签
`requires`	string[]	否	依赖的其他 Skill

`metadata.openclaw` 运行时元数据

当 Skill 需要外部依赖、环境变量、CLI 工具或 MCP 服务时，建议通过 metadata.openclaw 明确声明。

常用字段

字段	说明
`install`	依赖安装说明，例如 brew、npm、pip
`requires.env`	运行该 Skill 所需的环境变量
`requires.bins`	运行该 Skill 所需的本地命令
`primaryEnv`	最关键的凭据环境变量
`emoji`	在 UI 中展示的图标
`homepage`	Skill 主页或说明地址

命名与版本规则

`name`

格式：^[a-z0-9][a-z0-9._-]{0,127}$
必须以小写字母或数字开头
只允许小写字母、数字、点、下划线、连字符
长度限制为 1 到 128 个字符

有效示例：

git-helper
code.analyzer
data_processor_v2

无效示例：

GitHelper
-my-skill

`version`

当前上传强校验采用宽松字符串规则：

可包含字母、数字、点号、下划线、加号、连字符
必须以字母或数字开头
长度为 1-64 个字符

推荐仍按 SemVer 维护版本，便于发布和排障，例如：

1.0.0
1.2.3-beta
2.0.0+build.123

API 与协议要求

如果 Skill 暴露 API 或依赖外部接口，建议遵循以下要求：

有 HTTP 接口时提供 api.yaml
所有外部 Base URL 必须使用 HTTPS
不允许在文档、配置或示例中直接出现内网地址
对关键入参、出参和错误码提供清晰描述

平台重点关注的风险

非 HTTPS 的 API Base URL
内网 IP，例如 127.x、10.x、192.168.x、172.16-31.x
未声明但运行时必须存在的环境变量或命令

文件编码与大小

所有文本文件必须使用 UTF-8
不支持 UTF-16、GBK 等其他编码
上传文件大小应不超过 50MB
解压后建议不超过 100MB

安全要求

禁止内容

硬编码的 API Key、Token、密码
路径穿越内容，例如 ../../../etc/passwd
恶意代码、病毒、木马
内网 IP 地址
不安全的 HTTP 接口地址

平台会重点检测的模式

AWS Key：AKIA[A-Z0-9]{16}
OpenAI Key：sk-...
明文密码
内网地址

WARNING

敏感信息只能通过环境变量或安全配置注入，并在 requires.env 中声明，不应直接写入仓库、压缩包或示例文件。

忽略文件

.agenthubignore 与 .gitignore 语法一致，可用于排除本地调试文件、构建产物和测试数据。

text

.env
.env.local
secrets/
node_modules/
dist/
build/
tests/
*.log

旧版 .clawdhubignore 如仍存在，建议尽快迁移到 .agenthubignore。

打包与上传

打包

bash

cd my-skill/
zip -r my-skill.zip .

上传流程

登录 AgentHub 平台
进入 Skill 管理
上传 ZIP 压缩包，或直接上传单个 SKILL.md
等待同步预检
通过后进入异步深检

两阶段校验

阶段	目标	典型检查项
同步预检	秒级快速拒绝	文件类型、大小、ZIP 根目录是否包含 `SKILL.md`、包名、frontmatter、`name`、`version`、路径穿透、OpenAPI 校验、敏感信息初检
异步深检	分钟级安全校验	病毒扫描、LLM 安全分析

常见错误

问题	表现	解决方式
上传文件类型错误	上传直接失败	仅上传有效 `.zip` 或单个 `SKILL.md`
ZIP 根目录缺少 `SKILL.md`	上传失败	确保 `SKILL.md` 位于压缩包根目录，而不是子目录中
`SKILL.md` 结构不合法	上传失败	确保文件以 `---` 开头并以 `---` 结尾
缺少 `name` 或 `version`	上传失败	在 frontmatter 中补齐必需字段
包名不合法	上传失败	仅使用小写字母、数字、点、下划线、连字符，且以字母或数字开头
Base URL 非 HTTPS	平台拒绝入库	使用 `https://` 开头的接口地址
版本号冲突	已存在同版本	升级版本号后重新发布
依赖未声明	运行时失败	在 `metadata.openclaw` 中补齐 `requires.env` 和 `requires.bins`

发布前检查清单

[ ] 根目录包含 SKILL.md
[ ] frontmatter 至少包含 name、version
[ ] 文件以 --- 开头并以 --- 结尾
[ ] ZIP 包名符合上传规则
[ ] 文本文件全部为 UTF-8
[ ] 敏感信息已移除
[ ] 如有 API，已提供 api.yaml 或等价说明
[ ] 如有依赖，已声明 requires.env 和 requires.bins
[ ] 对外接口全部使用 HTTPS
[ ] .agenthubignore 已排除构建产物和本地配置
[ ] README、示例和 SKILL.md 中的行为描述一致

面向 WinWork 的补充建议

为了让 Skill 更容易被 Agent 正确使用，建议进一步满足以下约定：

在 SKILL.md 中明确“该 Skill 解决什么问题”
提供至少一个成功示例和一个失败示例
明确边界，例如“只读查询”“允许写入”“需要人工确认”
如果 Skill 面向特定域，例如 SRE、资产、FinOps，请标清适用 Agent
如果 Skill 依赖外部额度、频控或付费接口，请写清限制条件

相关语法参考见 Skill 格式规范。

Skill 接入规范

适用范围

当前上传强校验

上传文件类型

ZIP 包名规则

`SKILL.md` 基础校验

`version` 字段规则

最小目录结构

必需文件

`SKILL.md`

推荐补充文件

`SKILL.md` 元数据

基础 frontmatter

推荐的完整示例

`metadata.openclaw` 运行时元数据

常用字段

推荐结构

命名与版本规则

`name`

`version`

API 与协议要求

平台重点关注的风险

文件编码与大小

安全要求

禁止内容

平台会重点检测的模式

忽略文件

打包与上传

打包

上传流程

两阶段校验

常见错误

发布前检查清单

面向 WinWork 的补充建议

Skill 接入规范 ​

适用范围 ​

当前上传强校验 ​

上传文件类型 ​

ZIP 包名规则 ​

SKILL.md 基础校验 ​

version 字段规则 ​

最小目录结构 ​

必需文件 ​

SKILL.md ​

推荐补充文件 ​

SKILL.md 元数据 ​

基础 frontmatter ​

推荐的完整示例 ​

metadata.openclaw 运行时元数据 ​

常用字段 ​

推荐结构 ​

命名与版本规则 ​

name ​

version ​

API 与协议要求 ​

平台重点关注的风险 ​

文件编码与大小 ​

安全要求 ​

禁止内容 ​

平台会重点检测的模式 ​

忽略文件 ​

打包与上传 ​

打包 ​

上传流程 ​

两阶段校验 ​

常见错误 ​

发布前检查清单 ​

面向 WinWork 的补充建议 ​

Skill 接入规范

适用范围

当前上传强校验

上传文件类型

ZIP 包名规则

`SKILL.md` 基础校验

`version` 字段规则

最小目录结构

必需文件

`SKILL.md`

推荐补充文件

`SKILL.md` 元数据

基础 frontmatter

推荐的完整示例

`metadata.openclaw` 运行时元数据

常用字段

推荐结构

命名与版本规则

`name`

`version`

API 与协议要求

平台重点关注的风险

文件编码与大小

安全要求

禁止内容

平台会重点检测的模式

忽略文件

打包与上传

打包

上传流程

两阶段校验

常见错误

发布前检查清单

面向 WinWork 的补充建议