快速开始
技能格式
技能格式
磁盘结构
技能是一个文件夹。
必需：
SKILL.md（或skill.md；也接受旧版skills.md）
可选：
- 任何常规支持文件（参见“技能文件”）
.clawhubignore（发布时使用的忽略模式，旧版为.clawdhubignore）.gitignore（同样会采用）
GitHub 导入
Web 端 GitHub 导入器比本地发布/同步更严格。它仅发现
已登录 GitHub 账户所拥有的公开、非复刻仓库中的 SKILL.md 或旧版
skills.md 文件。它不会导入私有仓库、复刻仓库、
已归档/已禁用仓库或第三方公开仓库。
本地安装元数据（由 CLI 写入）：
<skill>/.clawhub/origin.json（旧版为.clawdhub）
工作目录安装状态（由 CLI 写入）：
<workdir>/.clawhub/lock.json（旧版为.clawdhub）
SKILL.md
- 带有可选 YAML frontmatter 的 Markdown。
- 服务器在发布期间从 frontmatter 中提取元数据。
description用作 UI/搜索中的技能摘要。
对于可移植的 Agent Skills，name 应与父目录名称一致，并使用
1–64 个小写字母、数字或连字符。ClawHub 将可路由的 slug 与
目录显示名称分开保存，因此来自其他客户端的现有名称仍可
发布，且不会被静默改写。目录列表可能会在视觉上缩短过长的名称，
但不会更改存储的名称。
Frontmatter 元数据
技能元数据在 SKILL.md 顶部的 YAML frontmatter 中声明。它会告知注册表（以及安全分析）技能运行时需要哪些条件。
基本 frontmatter
---name: my-skilldescription: 此技能功能的简短摘要。version: 1.0.0---运行时元数据（metadata.openclaw）
在 metadata.openclaw 下声明技能的运行时要求（别名：metadata.clawdbot、metadata.clawdis）。
---name: my-skilldescription: 通过 Todoist API 管理任务。metadata: openclaw: requires: env: - TODOIST_API_KEY bins: - curl primaryEnv: TODOIST_API_KEY---使用 requires.env 声明技能运行前必须存在的环境变量。当需要各变量的元数据（包括通过 required: false 声明的可选变量）时，请使用 envVars。
完整字段参考
| 字段 | 类型 | 描述 |
|---|---|---|
requires.env |
string[] |
技能所需的环境变量。 |
requires.bins |
string[] |
必须全部安装的 CLI 二进制文件。 |
requires.anyBins |
string[] |
至少必须存在一个的 CLI 二进制文件。 |
requires.config |
string[] |
技能读取的配置文件路径。 |
primaryEnv |
string |
技能的主要凭据环境变量。 |
envVars |
array |
带有 name、可选 required 和可选 description 的环境变量声明。对于可选环境变量，请设置 required: false。 |
always |
boolean |
如果为 true，技能将始终处于活动状态（无需显式安装）。 |
skillKey |
string |
覆盖技能的调用键。 |
emoji |
string |
技能的显示表情符号。 |
homepage |
string |
技能主页或文档的 URL。 |
os |
string[] |
操作系统限制（例如 ["macos"]、["linux"]）。 |
install |
array |
依赖项的安装规范（见下文）。 |
nix |
object |
Nix 插件规范（参见 README）。 |
config |
object |
Clawdbot 配置规范（参见 README）。 |
安装规范
如果技能需要安装依赖项，请在 install 数组中声明：
metadata: openclaw: install: - kind: brew formula: jq bins: [jq] - kind: node package: typescript bins: [tsc]支持的安装类型：brew、node、go、uv。
可选环境变量
在 metadata.openclaw.envVars 下声明可选环境变量，并设置 required: false。不要将可选条目添加到 requires.env，因为 requires.env 表示缺少这些变量时技能无法运行。
metadata: openclaw: primaryEnv: TODOIST_API_KEY envVars: - name: TODOIST_API_KEY required: true description: 用于已认证请求的 Todoist API 令牌。 - name: TODOIST_PROJECT_ID required: false description: 用户未指定项目 ID 时使用的可选默认项目 ID。这为何重要
ClawHub 的安全分析会检查技能声明的内容是否与其实际行为一致。如果代码引用了 TODOIST_API_KEY，但 frontmatter 未在 requires.env、primaryEnv 或 envVars 下声明它，分析将标记元数据不匹配。保持声明准确有助于技能通过审查，也有助于用户了解他们正在安装的内容。
示例：完整的 frontmatter
---name: todoist-clidescription: 从命令行管理 Todoist 任务、项目和标签。version: 1.2.0metadata: openclaw: requires: env: - TODOIST_API_KEY bins: - curl primaryEnv: TODOIST_API_KEY envVars: - name: TODOIST_API_KEY required: true description: Todoist API 令牌。 - name: TODOIST_PROJECT_ID required: false description: 可选的默认项目 ID。 emoji: "\u2705" homepage: https://github.com/example/todoist-cli---技能文件
发布功能接受技能文件夹中的所有常规文件，无论扩展名为何。忽略文件、 隐藏路径、符号链接、macOS 元数据和服务器端大小限制仍然适用。
- 包含有效 UTF-8 的有限大小文件可预览为经过转义的纯文本，并会纳入 有限文本分析。
- 其他文件会保留其精确字节，并可供下载。
- 安全扫描程序会接收完整的已存储工件；文本检测是渲染和 分析方面的事项，而不是上传允许列表。
限制（服务器端）：
- 捆绑包总大小：50MB。
- 嵌入文本包括
SKILL.md+ 最多约 40 个有限大小的 UTF-8 文件（尽力而为的上限）。
Slug
- 默认从文件夹名称派生。
- 包作用域必须与 ClawHub 发布者用户名完全匹配。发布者用户名可以使用小写字母、数字、连字符、点和下划线；必须以小写字母或数字开头和结尾。
- 包 slug 必须为小写且符合 npm 安全规范，例如
@example.tools/demo-plugin或demo-plugin。
版本控制 + 标签
- 每次发布都会创建一个新版本（semver）。
- 标签是指向某个版本的字符串指针；通常使用
latest。
许可证
- ClawHub 上发布的所有技能均采用
MIT-0许可。 - 任何人都可以使用、修改和重新分发已发布的技能，包括用于商业用途。
- 无需署名。
- 不要在
SKILL.md中添加冲突的许可条款；ClawHub 不支持按技能覆盖许可证。
付费技能
- ClawHub 不支持付费技能、按技能定价、付费墙或收入分成。
- 不要向
SKILL.md添加定价元数据；它不属于技能格式，也不会使已发布的技能变为付费技能。 - 如果技能与付费第三方服务集成，请在技能说明和环境变量声明中清楚说明外部费用和所需账户（必需变量使用
requires.env，可选变量使用envVars并设置required: false）。
