4fe53197c4
- 5 agent frameworks: Qoder, Claude Code, Codex, OpenClaw, Hermes Agent - 9 lifecycle skills: lifecycle router, discover, create, test, audit, debug, update, publish, retire - 5 framework-specific meta-skills with specs and guides - OpenClaw meta-skill enriched with ClawHub official ecosystem data - Per-framework directories with skills/, versions/, publish/, docs/
113 lines
3.3 KiB
Markdown
113 lines
3.3 KiB
Markdown
# OpenClaw 技能规范摘要
|
||
|
||
> 基于 ClawHub 官方生态和多个高人气参考技能整理。完整规范请参阅 [ClawHub](https://clawhub.ai)。
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
<skill-name>/
|
||
├── SKILL.md # 核心指令文件（必填）
|
||
├── _meta.json # 元数据文件（必填）
|
||
├── references/ # 按需加载的参考文档（可选）
|
||
├── scripts/ # 辅助脚本（可选）
|
||
├── examples/ # 使用示例（可选）
|
||
└── CHANGELOG.md # 版本变更记录（推荐）
|
||
```
|
||
|
||
## SKILL.md 规范
|
||
|
||
### YAML 前置信息（Frontmatter）
|
||
|
||
```yaml
|
||
---
|
||
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 规范
|
||
|
||
```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. **文件操作审查**：修改工作区前需用户明确批准
|
||
|
||
## 发布流程
|
||
|
||
```bash
|
||
# 认证（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` |
|