Skill 格式规范

每个 Skill 是一个独立的文件夹，文件夹名即为 Skill 的标识符。平台通过约定的文件结构来识别和加载 Skill。

TIP

如果你关注的是平台是否允许上传、有哪些安全限制、哪些校验会直接阻塞发布，请先阅读 Skill 接入规范。

文件夹结构

my-skill/
├── SKILL.md              # 必须：Skill 描述文件（核心）
├── metadata.openclaw     # 可选：运行时依赖声明
├── .agenthubignore       # 可选：发布时排除的文件
├── tools/                # 可选：工具定义文件
│   └── my-tool.json
├── prompts/              # 可选：提示词模板
│   └── system.md
└── scripts/              # 可选：辅助脚本
    └── setup.sh

SKILL.md 文件

SKILL.md 是每个 Skill 的核心文件，包含 YAML frontmatter 元数据和 Markdown 正文内容。

WARNING

当前上传校验会检查 SKILL.md 是否以 --- 开头，并以 --- 结尾。只写标准 frontmatter 还不够，文件末尾也需要保留结束分隔符。

Frontmatter 字段

---
name: my-skill                    # Skill 唯一标识符（必须）
description: 这是一个示例 Skill    # 简短描述（推荐）
version: 1.0.0                    # 版本号（必须）
author: your-name                 # 作者（可选）
tags:                             # 标签，用于分类和搜索（可选）
  - productivity
  - integration
requires:                         # 依赖的其他 Skill（可选）
  - base-skill
---

当前必需字段

• name
• version

description 目前不是上传强校验必填项，但强烈建议填写。

正文内容

frontmatter 之后的 Markdown 内容会被注入到 Agent 的系统提示词中。这部分内容应该清晰描述：

• 该 Skill 提供的能力
• 可用的工具和命令
• 使用示例和注意事项

完整示例

---
name: weather
description: 查询全球任意城市的实时天气和天气预报
version: 2.1.0
author: winwork-team
tags:
  - weather
  - utility
---

## 天气查询能力

你现在具备查询天气的能力。可以通过以下方式获取天气信息：

### 可用工具

- `get_current_weather(city: string)` - 获取指定城市当前天气
- `get_forecast(city: string, days: number)` - 获取未来 N 天天气预报

### 使用说明

当用户询问天气相关问题时，主动调用天气工具获取实时数据，
不要依赖训练数据中的天气信息。

### 示例

用户："北京今天天气怎么样？"
→ 调用 get_current_weather("北京") 获取实时数据

---

metadata.openclaw 文件

用于声明 Skill 的运行时依赖，格式为 JSON：

{
  "mcp": {
    "servers": {
      "weather-server": {
        "command": "npx",
        "args": ["-y", "/weather-mcp"],
        "env": {
          "API_KEY": "${WEATHER_API_KEY}"
        }
      }
    }
  },
  "env": {
    "required": ["WEATHER_API_KEY"],
    "optional": ["WEATHER_UNITS"]
  }
}

支持的依赖类型

字段	说明
mcp.servers	需要启动的 MCP 服务器
env.required	必须配置的环境变量
env.optional	可选的环境变量
services	需要运行的后台服务

如果你的 Skill 还需要更完整的运行时元数据，例如安装方式、必需命令、主凭据变量、展示图标等，建议参考 Skill 接入规范 中的 metadata.openclaw 约定。

.agenthubignore 文件

类似 .gitignore，指定发布到 Hub 时需要排除的文件：

# 排除开发配置
.env
.env.local
secrets/

# 排除测试文件
tests/
*.test.js

# 排除构建产物
dist/
node_modules/

版本规范

当前上传校验对 version 的要求是：

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

推荐仍遵循语义化版本（SemVer），便于版本管理，例如：

• 1.0.0
• v2.1.3
• 1.0.0-beta
• 2.0.0+build.123

WARNING

SKILL.md 文件是必须的。缺少此文件的文件夹不会被识别为有效的 Skill。

TIP

正文内容会直接注入到 Agent 系统提示词，建议使用清晰的 Markdown 格式，避免过长的内容影响 Agent 性能。