SkillSpace/meta-skills/create-openclaw-skill/spec.md

OpenClaw 技能规范摘要

基于 ClawHub 官方生态和多个高人气参考技能整理。完整规范请参阅 ClawHub。

文件结构

<skill-name>/
├── SKILL.md          # 核心指令文件（必填）
├── _meta.json        # 元数据文件（必填）
├── references/       # 按需加载的参考文档（可选）
├── scripts/          # 辅助脚本（可选）
├── examples/         # 使用示例（可选）
└── CHANGELOG.md      # 版本变更记录（推荐）

SKILL.md 规范

YAML 前置信息（Frontmatter）

---
name: my-skill-name          # 小写 + 连字符，全局唯一
description: 15-25 词描述     # 上限 160 字符（ClawHub 搜索摘要）
---

注意：YAML 前置信息仅需 name 和 description 两个字段，不要添加多余字段。

核心章节结构

章节	说明
## When to Use	定义激活触发条件（关键词、场景）
## Core Rules	3-7 条编号规则，约束技能行为
## Quick Start	最小可行示例
## Workflow	复杂任务的步骤清单
## Advanced	链接至独立参考文件（渐进式披露）

编写原则

• 核心文件控制在 30-50 行，上限 80 行
• 超过 20 行的内容拆分至独立文件
• 信息仅存一处，通过引用避免重复
• 以全新代理视角审查指令是否清晰且必要

_meta.json 规范

{
  "name": "my-skill-name",
  "version": "1.0.0",
  "description": "Process, merge, and extract PDF content",
  "tags": ["pdf", "extraction", "utility"]
}

字段	类型	必填	说明
name	string	是	小写 + 连字符，与 YAML 一致
version	string	是	语义化版本号
description	string	是	与 YAML 一致
tags	array	否	搜索关键词

Description 编写规范

描述是代理识别并加载技能的唯一依据：

• 上限 1024 字符
• 第三人称
• 首句：15-25 词，以动作动词开头，描述能力
• 次句：触发条件，包含 "Use when..."

渐进式披露（三层加载机制）

层级	内容	加载时机
L1 元数据	name、description	始终加载
L2 核心主体	SKILL.md 正文	触发时加载
L3 辅助文件	references/、scripts/	按需加载

安全验证标准

发布时技能需通过：

1. 静态扫描：YAML 格式、字段完整性、文件结构
2. LLM 分析：用途匹配度、安装机制、权限需求
3. 触发词审查：范围不能过宽，防止意外激活
4. 文件操作审查：修改工作区前需用户明确批准

发布流程

# 认证（GitHub 账号，注册满 2 周）
openclaw auth login

# 发布
openclaw skills publish <local-path> \
  --slug <skill-slug> \
  --name <skill-name> \
  --version 1.0.0 \
  --tags "tag1,tag2"

常见问题

问题	原因	解决方案
无效目录路径	使用了相对路径	使用绝对路径
认证失败	GitHub 账号不满 2 周	等待或换账号
技能不可见	YAML 前置信息字段过多	只保留 name 和 description
技能未被识别	网关未重启	执行 openclaw gateway restart