WorkBuddy 的 Skill 是一个带有 SKILL.md 核心文件的文件夹，本质是写给 AI 实例的操作指令集，而非给人看的文档——这个定位决定了它的写法与普通提示词完全不同。本文从文件结构出发，拆解 YAML frontmatter 规范、三层资源组织、触发机制，梳理六步创建流程，并给出最常见的七类错误和对应修正方案，帮助想把重复对话任务封装成可复用工具的开发者少走弯路。SkillHub 技能市场目前已有 7 万多个社区技能、累计下载超 3000 万次，但大多数真正贴合自己业务的场景还是需要自己动手。

---

Skill 是什么：先把模型认清楚

一个 Skill 的完整形态是这样的：

my-skill/
├── SKILL.md        ← 唯一必需文件，YAML frontmatter + 操作指令
├── scripts/        ← 可执行脚本（Python/JS），确定性操作放这里
├── references/     ← AI 工作时查阅的参考文档（schema、API文档）
└── assets/         ← 直接复制到产出物的资源（模板、样板代码）

只有 SKILL.md 是必须的，其余三个目录按需创建。

AI 加载 Skill 的时机是分层的，这直接影响你该把什么写在哪里：

层级	内容	何时加载	Token 成本
L1 Frontmatter	name + description	始终在上下文	~100 词
L2 Body	操作指令正文	触发后加载	< 5k 词
L3 Resources	scripts/references/assets	按需调用	无上限

这意味着触发条件必须写在 description 里，而不是正文——等正文加载时 AI 已经做出触发决策了。

---

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 等级不建议安装。

正文：写给 AI 实例的指令，不是人类文档

正文使用祈使语气/不定式，而非描述性语气：

## 执行步骤

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 字符"每次输出可能不合规；validate_length.py 保证每次结果一致。

# scripts/validate_report.py
import sys
def check_title_length(title: str) -> bool:
    return len(title) <= 60

脚本在执行时不会被读入上下文，Token 成本为零。

references/：按需知识库

存放 AI 工作时需要查阅但不需要预载的内容：数据库 schema、API 文档、领域规范。在 SKILL.md 正文里用相对路径引用：

For field definitions, refer to references/schema.md
For API endpoints, refer to references/api-docs.md

不要让 references 文件互相嵌套引用（A 引用 B，B 引用 C），这会让 AI 需要多跳才能获取信息。所有 reference 从 SKILL.md 直接链接。

assets/：零修改直接用

存放需要原样复制到产出物的内容：Markdown 模板、样板代码、配置文件。比如一个周报模板：

assets/
└── report-template.md   ← AI 读取后直接填充，不改结构

---

六步创建流程

第一步：用具体例子建立共识

不要从"我想要一个技能"开始，从"用户会说什么话触发它"开始。把三到五个真实输入例子写下来，例如：

• “帮我生成本周的工作周报”
• “基于任务日志写一份周总结”
• “整理这周的工作情况”

这些例子直接决定了 description 里的触发词。

第二步：分析重复单元

把每个例子拆解成：需要什么输入 → 做什么操作 → 输出什么格式。重复出现的操作就是需要封装进 scripts/ 的内容，每次不同的部分就是 Skill 需要接收的参数。

第三步：初始化目录

在 ~/.workbuddy/skills/ 下创建目录，目录名即 Skill name：

mkdir -p ~/.workbuddy/skills/weekly-report-generator
cd ~/.workbuddy/skills/weekly-report-generator
touch SKILL.md
mkdir scripts references assets

或者直接告诉 WorkBuddy：“帮我创建一个叫 weekly-report-generator 的 Skill，功能是……”——WorkBuddy 会自动调用 skill-creator 工具初始化目录结构并生成 SKILL.md 草稿。

第四步：先写资源，再写 SKILL.md

优先把 scripts/、references/、assets/ 里的文件做好，SKILL.md 正文只需要引用它们。这是很多人做反的顺序——先写 SKILL.md 再写脚本，导致指令和实现频繁不一致。

第五步：校验

保存后在 WorkBuddy 里发送 /reload-skills 或重启客户端，检查技能列表是否出现新条目。看不到新条目的首要原因：SKILL.md frontmatter 格式错误，或目录名与 name 字段不一致。

第六步：真实任务测试 + 迭代

用真实输入测试，不用精心设计的测试用例。真实使用会暴露边界情况：输入为空时怎么处理、文件路径带空格时怎么处理、脚本执行失败时返回什么。每次发现问题直接改，重新 /reload-skills，成本极低。

---

七个最容易踩的坑

错误	症状	修正
触发条件写在正文里	Skill 很少被触发	触发词必须在 description
description 只写名称	触发判断模糊	加"Use when…"具体场景
正文用描述性语气	AI 理解有歧义	改成祈使句 “Do X”
格式约束用文字描述	每次输出格式不一	封装成 scripts/ 脚本
目录名与 name 字段不一致	技能列表看不到	两者必须完全匹配
references 互相嵌套引用	AI 需多跳获取信息	全部从 SKILL.md 直接链接
frontmatter 加了非法字段	解析报错或静默忽略	只用 name / description / license / allowed-tools / metadata

---

发布到 SkillHub

Skill 开发完成后，可以提交到 SkillHub（skillhub.tencent.com / clawhub.ai）供社区使用。提交前需通过 skill-vetter 安全审查，审查核心检查项是 allowed-tools 的权限范围和外部网络请求声明。

SkillHub 目前已有 7 万多个社区技能、累计下载超 3000 万次，覆盖文档处理、开发运维、内容优化、数据分析等主要场景。提交审查通过后，技能会在市场按下载量、更新频率、用户评价排序展示。

如果你想先找现成 Skill 参考或直接复用，LinSkills（linskills.qiniu.com）收录了 Summarize（网页/PDF/音视频摘要，81.8k 下载）、自我改进代理（119.4k 下载）、Tavily 网络搜索（100.6k 下载）等精选 Skills，格式与 WorkBuddy Agent Skills 标准兼容，下载 ZIP 解压放入 ~/.workbuddy/skills/ 目录即可激活。

---

一个完整示例：会议纪要 Skill

meeting-notes/
├── SKILL.md
├── scripts/
│   └── format_action_items.py
├── references/
│   └── format-spec.md
└── assets/
    └── notes-template.md

---
name: meeting-notes
description: Generates structured meeting notes from transcripts or voice recordings. Use when asked to write meeting minutes, summarize meetings, or extract action items from meeting content.
allowed-tools: Read,Write,Bash
---

## Workflow

1. Read input (transcript file path or pasted text)
2. Extract: attendees, agenda items, decisions, action items
3. Format action items using scripts/format_action_items.py
4. Fill assets/notes-template.md with extracted content
5. Write output to ./meeting-notes-{YYYYMMDD}.md

## Constraints

- Action items must include owner and deadline; if missing, mark as [TBD]
- Decisions must be clearly distinguished from discussions
- Refer to references/format-spec.md for output formatting details

这个示例覆盖了三层资源的使用模式：脚本处理格式约束、模板保证输出一致、reference 存放详细规范，SKILL.md 只做主流程编排，控制在 50 行内。

---

延伸阅读

• WorkBuddy Skill 开发文档：cloud.tencent.com/developer/article/2659721
• Agent Skills 规范（datawhalechina）：github.com/datawhalechina/hello-agents
• LinSkills 精选技能包下载：linskills.qiniu.com/