liaoxin-skills/references/skill-creator-guide.md

Skill 创建指南

基于 OpenClaw 官方 skill-creator 提炼的核心要点。

目录结构

skill-name/
├── SKILL.md              # 必需：frontmatter + markdown 指令
├── scripts/              # 可选：可执行脚本（Python/Bash）
├── references/           # 可选：参考文档，按需加载
└── assets/               # 可选：输出用资源（模板、图片、字体等）

SKILL.md 核心结构

Frontmatter（必需）

---
name: skill-name
description: 详细描述技能做什么，以及何时触发。这是唯一决定 skill 是否被加载的字段。
  必须包含所有"何时使用"的信息——不要放在正文里。正文只在触发后才加载。
---

• 仅需 name 和 description 两个字段
• name 要求：小写字母 + 数字 + 连字符，不超过 64 字符

正文原则

1. 简洁至上：上下文窗口是公共资源，只写 AI 不知道的信息
2. 指令式：用祈使句写，不是描述
3. 选择自由度：脆弱操作给低自由度（精确脚本），灵活操作给高自由度（文字指引）
4. 渐进式加载：正文 < 500 行，详细内容放 references，按需加载

三层次加载

1. 元数据（name + description）— 始终在上下文中（~100 词）
2. SKILL.md 正文 — 触发后加载（< 5000 词）
3. bundled resources — 按需加载（无限制）

资源目录

目录	用途	示例
scripts/	可执行代码，可不经加载直接执行	rotate_pdf.py
references/	参考文档，加载到上下文中阅读	api_docs.md, schema.md
assets/	输出用资源，不加载到上下文	模板、图标、字体

常见正文结构

1. 工作流型：适合有序步骤 → ## Overview → ## Workflow → ## Step 1 → ## Step 2...
2. 任务型：适合工具集 → ## Overview → ## Quick Start → ## Task A → ## Task B...
3. 参考/指南型：适合规范标准 → ## Overview → ## Guidelines → ## Specifications...
4. 能力型：适合集成系统 → ## Overview → ## Core Capabilities → ### 1. ...

创建流程

1. 明确使用场景（从具体例子出发）
2. 规划可复用资源（scripts/references/assets）
3. ./scripts/init_skill.py <name> --path skills/ --resources scripts,references,assets
4. 编辑 SKILL.md 和资源文件，删除不需要的
5. ./scripts/package_skill.py skills/<name> 打包验证

命名规范

• 小写字母 + 数字 + 连字符
• 优先动词开头的短语，描述动作
• 有明确的工具命名空间时加上前缀（如 gh-address-comments）
• 文件夹名等于技能名

禁止事项

• ❌ 不创建 README、CHANGELOG 等附加文档
• ❌ 不含构建过程、测试步骤、用户文档
• ❌ 不嵌套引用（references 之间不要互相引用）
• ❌ 信息不重复（不在 SKILL.md 和 references 里各写一遍）