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 Frontmattername description始终在上下文~100 词L2 Body操作指令正文触发后加载 5k 词L3 Resourcesscripts/references/assets按需调用无上限这意味着触发条件必须写在 description 里而不是正文——等正文加载时 AI 已经做出触发决策了。SKILL.md 写法精要Frontmatter最小标准---name:weekly-report-generatordescription: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.pyimportsysdefcheck_title_length(title:str)-bool:returnlen(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 引用 BB 引用 C这会让 AI 需要多跳才能获取信息。所有 reference 从 SKILL.md 直接链接。assets/零修改直接用存放需要原样复制到产出物的内容Markdown 模板、样板代码、配置文件。比如一个周报模板assets/ └── report-template.md ← AI 读取后直接填充不改结构六步创建流程第一步用具体例子建立共识不要从我想要一个技能开始从用户会说什么话触发它开始。把三到五个真实输入例子写下来例如“帮我生成本周的工作周报”“基于任务日志写一份周总结”“整理这周的工作情况”这些例子直接决定了 description 里的触发词。第二步分析重复单元把每个例子拆解成需要什么输入 → 做什么操作 → 输出什么格式。重复出现的操作就是需要封装进 scripts/ 的内容每次不同的部分就是 Skill 需要接收的参数。第三步初始化目录在~/.workbuddy/skills/下创建目录目录名即 Skill namemkdir-p~/.workbuddy/skills/weekly-report-generatorcd~/.workbuddy/skills/weekly-report-generatortouchSKILL.mdmkdirscripts 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 很少被触发触发词必须在 descriptiondescription 只写名称触发判断模糊加Use when…具体场景正文用描述性语气AI 理解有歧义改成祈使句 “Do X”格式约束用文字描述每次输出格式不一封装成 scripts/ 脚本目录名与 name 字段不一致技能列表看不到两者必须完全匹配references 互相嵌套引用AI 需多跳获取信息全部从 SKILL.md 直接链接frontmatter 加了非法字段解析报错或静默忽略只用 name / description / license / allowed-tools / metadata发布到 SkillHubSkill 开发完成后可以提交到 SkillHubskillhub.tencent.com / clawhub.ai供社区使用。提交前需通过skill-vetter安全审查审查核心检查项是allowed-tools的权限范围和外部网络请求声明。SkillHub 目前已有 7 万多个社区技能、累计下载超 3000 万次覆盖文档处理、开发运维、内容优化、数据分析等主要场景。提交审查通过后技能会在市场按下载量、更新频率、用户评价排序展示。如果你想先找现成 Skill 参考或直接复用LinSkillslinskills.qiniu.com收录了 Summarize网页/PDF/音视频摘要81.8k 下载、自我改进代理119.4k 下载、Tavily 网络搜索100.6k 下载等精选 Skills格式与 WorkBuddy Agent Skills 标准兼容下载 ZIP 解压放入~/.workbuddy/skills/目录即可激活。一个完整示例会议纪要 Skillmeeting-notes/ ├── SKILL.md ├── scripts/ │ └── format_action_items.py ├── references/ │ └── format-spec.md └── assets/ └── notes-template.md---name:meeting-notesdescription: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---## Workflow1. 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/2659721Agent Skills 规范datawhalechinagithub.com/datawhalechina/hello-agentsLinSkills 精选技能包下载linskills.qiniu.com/
、@Transaction、@TransactionRollback)
)
