WorkBuddy 的 Skill 本质上是写给 AI 实例的操作指令集，而非给人看的文档——这个定位决定了它的写法与普通提示词完全不同。本文基于实战教程，拆解SKILL.md 的文件结构、YAML frontmatter 规范、三层资源组织、六步创建流程，以及最常见的七类错误，帮助想把重复对话任务封装成可复用工具的用户少走弯路。
Skill 的完整文件结构
my-skill/
├── SKILL.md ← 唯一必需文件，YAML frontmatter
│ + 操作指令
├── scripts/ ← 可执行脚本（Python/JS），确定性
│ 操作放这里
├── references/ ← AI工作时查阅的参考文档（schema、
│ API文档）
└── assets/ ← 直接复制到产出物的资源（模板、
样板代码）
只有SKILL.md是必须的，其余三个目录按需创建
分层加载机制：决定内容该写在哪里
层级 内容 何时加载 Token成本
L1 name+description 始终在上下文 ~100词
Frontmatter
L2 Body 操作指令正文 触发后加载 <5k词
L3 scripts/references 按需调用 无上限
Resources /assets
这个分层机制直接决定了写作策略——触发条件必须写在 description 里，而不是正文，因为等正文加载时 AI 已经做出了是否触发该 Skill 的决策。
SKILL.md Frontmatter：最小标准
---
name: weekly-report-generator
description: Generates weekly work reports from task
logs. Use when asked to write, create, or summarize
weekly/work reports.
allowed-tools: Read,Write,Bash
---
Frontmatter只允许五个字段：
name、description、license、allowed-tools、metadata
任何其他字段都会被解析器忽略甚至报错
name规范：
- 小写字母+数字+连字符
- ≤64字符
- 不以连字符开头或结尾
- 推荐动词开头的短语（generate-report优于report）
- 目录名必须与name字段完全一致
description 是触发器——AI 用它来判断"该不该调用这个 Skill"，必须写清楚做什么+何时触发。"周报生成技能"这种写法等于没写；改成"Generates weekly work reports from task logs. Use when asked to write, create, or summarize weekly/work reports"才能被稳定触发。
allowed-tools 白名单——显式列出该 Skill 可以使用的工具，常用值包括 Read、Write、Bash、WebFetch。不列出的工具不会被调用，这既是安全边界，也是 SkillHub 安全审查的核心检查项——安全等级 MEDIUM 以上需要人工审查，EXTREME 等级不建议安装。
正文写法：祈使语气，不是描述性语气
## 执行步骤
1. Read task log file from ./logs/week-{YYYYWW}.md
2. Extract completed tasks, blockers, and planned
next steps
3. Format output using template in
assets/report-template.md
4. Write final report to
./output/weekly-report-{DATE}.md
不要写"You should read the task log"，直接写"Read task log"。AI 不需要客气话，需要清晰的操作序列。正文长度控制在 500 行/5000 Token 以内，超出就拆到 references/ 目录，在正文里加一行"Refer to references/detail.md for complete specification"，AI 会在需要时主动读取。
三层资源的分工
scripts/：锁死脆弱操作
任何有格式约束、长度限制、命名规则的操作，都应该
封装成脚本而不是用文字描述——文字描述的"字段长度
不超过60字符"每次输出可能不合规，脚本能保证每次
结果一致。脚本执行时不会被读入上下文，Token成本
为零
references/：按需知识库
存放AI工作时需要查阅但不需要预载的内容：数据库
schema、API文档、领域规范。注意不要让reference
文件互相嵌套引用，会让AI需要多跳才能获取信息，
所有reference应从SKILL.md直接链接
assets/：零修改直接用
存放需要原样复制到产出物的内容：Markdown模板、
样板代码、配置文件
六步创建流程
第一步：用具体例子建立共识
不要从"我想要一个技能"开始，从"用户会说什么话
触发它"开始，写下3-5个真实输入例子
第二步：分析重复单元
把每个例子拆解成：需要什么输入→做什么操作→输出
什么格式，重复出现的操作封装进scripts/，每次不同
的部分是Skill需要接收的参数
第三步：初始化目录
mkdir -p ~/.workbuddy/skills/weekly-report-generator
（或直接告诉WorkBuddy自动调用skill-creator工具
初始化）
第四步：先写资源，再写SKILL.md
优先做好scripts/、references/、assets/里的文件，
SKILL.md正文只需要引用它们——很多人做反了这个
顺序，导致指令和实现频繁不一致
第五步：校验
保存后发送/reload-skills或重启客户端，检查技能
列表是否出现新条目
第六步：真实任务测试+迭代
用真实输入测试，不用精心设计的测试用例，暴露边界
情况后直接改，重新/reload-skills，成本极低
七个最容易踩的坑
错误 症状 修正
触发条件写在正文里 很少被触发 触发词
必须在
description
description只写名称 触发判断模糊 加"Use
when…"
具体场景
正文用描述性语气 AI理解有歧义 改成祈使句
"Do X"
格式约束用文字描述 每次输出格式不一 封装成
scripts/脚本
目录名与name字段不一致 技能列表看不到 两者必须
完全匹配
references互相嵌套引用 AI需多跳获取信息 全部从
SKILL.md
直接链接
frontmatter加非法字段 解析报错或静默忽略 只用规定
的五个字段
发布到 SkillHub
开发完成后可提交到SkillHub（skillhub.tencent.com/
clawhub.ai）供社区使用，提交前需通过skill-vetter
安全审查，核心检查项是allowed-tools的权限范围和
外部网络请求声明
SkillHub目前已有7万多个社区技能、累计下载超3000万
次，覆盖文档处理、开发运维、内容优化、数据分析等
主要场景
实战建议
1. 开始写Skill前，先收集3-5个用户会说的真实触发
语句，避免从空泛的"我想要一个技能"开始设计
2. 严格遵守Frontmatter只用五个合法字段，避免因为
非法字段导致解析报错或静默忽略
3. description必须包含"Use when…"的具体触发场景，
否则Skill很可能几乎不会被自动调用
4. 有严格格式约束的操作（字数限制、命名规则）务必
封装进scripts/脚本，不要依赖文字描述让AI每次
都严格遵守
5. 遵循"先写资源再写SKILL.md"的顺序，避免指令
和实现脱节
总结
写好一个 WorkBuddy Skill 的核心，是理解它"写给AI 看而非人看"的本质定位——分层加载机制、触发条件精确度、格式约束的脚本化封装，这几个原则贯穿整个创建流程。掌握这套方法论后，把重复性对话任务转化为稳定可复用的 Skill，能显著提升WorkBuddy 处理专业场景任务的一致性和效率。
来源：从零写一个 WorkBuddy Skill：七个坑、一个完整示例和 SkillHub 发布指南 — CSDN 技术社区