前阵子同事甩给我一句话把WorkBuddy的Skill给我装上我要用那个能自动写巡检报告的技能。我当时觉得这活儿五分钟就能搞定——跟装个普通插件差不多嘛。结果真上手才发现WorkBuddy的Skill安装和“装个插件”完全是两码事。它牵扯到版本差异、目录权限、脚本依赖、SKILL.md编写规范每一步都藏着不起眼的小坑。这篇就把我实际跑通的流程、踩过的坑、以及装上之后不生效的完整排查思路写下来给同样被WorkBuddy Skill折腾过的朋友一个可以直接照做的参考。1. 先搞清楚WorkBuddy的Skill装在“哪个脑子”里1.1 WorkBuddy不是插件商店它是一个Agent工作台先捋清楚WorkBuddy到底是个什么东西。它本质上是一个AI Agent工作台负责把大模型的对话能力、文件系统访问、命令行执行、各种API调用编排在一块。和普通IDE插件不一样WorkBuddy不是单纯给你“加一个按钮”而是让你在对话里指派任务它自己拆解步骤、调用工具、产出结果。所以社区里经常有人把它和CodeBuddy、Codex、Cursor放在一起讨论因为它们都是“AI干活”的思路WorkBuddy更强调把工作台搭建起来Skill就是往这个工作台里塞“可复用的行为包”。理解这一点特别重要因为它决定了你对Skill的预期。很多新手以为安装Skill就是把某个压缩包解压进去点一下“启用”完事。但Skill在WorkBuddy里的运行机制是当模型的对话内容匹配到某个Skill的描述时WorkBuddy会去读对应的SKILL.md文件把里面的指令和步骤作为行为准则再结合Skill自带的脚本去执行任务。换句话说Skill不是一段被调用就完事的代码而是一套“触发条件 操作流程 工具脚本”的组合体。1.2 Skill和普通插件的核心区别指令即行为如果之前用过VS Code插件或JetBrains插件很容易带着旧思路来理解Skill然后就被坑。普通插件是预先编译好的程序功能固定安装后通过界面交互Skill则更多是“写给模型看的行为规范”。SKILL.md里写清楚什么场景触发、按什么步骤做、输出什么格式模型看到这套指令再来执行。所以Skill质量的上下限差异极大写得好的Skill能让模型稳定复现一套复杂流程写不好的Skill哪怕模型再强也会跑偏。这里有个非常有意思的推论社区里那些稀奇古怪的Skill比如“狗头军师Skill”“前任Skill”“去AI味的Skill”本质上都是Prompt工程的作品。它们不是在调用什么黑科技而是把一套经过设计的思考路径和行为约束写进了SKILL.md里。理解了这一点你装任何Skill之前都会有判断力这个Skill到底是真有逻辑还是只是把一堆提示词包装了一下。实际操作中很多号称“神器”的Skill拆开就是一篇结构化指令真正值钱的是指令设计本身。1.3 动手装Skill之前先确认这三件事第一确认你的WorkBuddy版本。国际版和国内版在账号体系、模型路由、Skill市场内容上都有差异后面我会单独讲怎么选。第二确认Skill来源。是官方市场里一键安装还是从GitHub克隆项目还是自己手写不同来源的安装路径和后续维护方式完全不一样。第三确认目标场景。你要这个Skill来做什么是辅助用户写作、整理数据还是调用脚本执行本地任务如果Skill涉及执行外部命令对依赖环境和权限的要求会高很多。这三件事没想清楚就急着装大概率会出现“装上了但用不了”或者“能用但不干活”的尴尬。别问我怎么知道的我一开始就是没确认版本装了一个只适配国际版的Skill结果在国内版上静默失败折腾了两个小时。2. 环境准备版本、目录和依赖一样都不能省2.1 国际版和国内版先选明白别稀里糊涂装一半WorkBuddy国际版和国内版不是换了个服务器那么简单。两者在账号体系上是分开的国内版通常走国内模型服务渠道国际版在模型选择上更多Skill市场的丰富程度也更高。你在选的时候不用纠结“哪个更高级”核心就看你的实际网络环境和使用习惯。能正常访问国际服那就用国际版访问不顺就用国内版两者在Skill目录结构、SKILL.md规范上基本一致换版本的成本没有想象中那么高。这里有个我踩过的教训不同版本对Skill的兼容性并不完全一致。有一部分从CodeBuddy或者旧版WorkBuddy导出的Skill直接放进新版里面会提示“格式不支持”或者干脆不加载。所以装Skill前先看一眼自己的版本号再去看Skill仓库里标注的适配版本不要看到Star多就直接克隆。2.2 依赖环境检查Python、Git、Node和你的目录权限WorkBuddy的Skill分为纯指令型和带脚本型。纯指令型只要读SKILL.md就能跑带脚本型往往需要执行Python或Node脚本。所以我建议无论你现在用不用脚本型Skill先把基础环境补齐否则后面装到一半发现脚本跑不起来非常扫兴。python --version git --version node --version三条命令依次确认Python、Git、Node是否可用。我见过不少报错其实跟WorkBuddy一点关系都没有纯粹是电脑上连Git都没装克隆Skill仓库时卡住还以为是WorkBuddy的问题。另一点容易忽视的是目录权限。在macOS和Linux上如果WorkBuddy的数据目录权限不对Skill文件夹放进去之后可能读不到或者脚本文件没有执行权限。2.3 Skill文件的标准目录结构装之前先看懂家目录不同版本WorkBuddy的Skill目录位置可能略有差异但通常遵循一个约定在用户主目录下创建一个以WorkBuddy相关的隐藏配置目录里面再建skills子目录。常见的路径长这样~/.workbuddy/ skills/ my-skill/ SKILL.md scripts/ assets/核心要点有两个。第一每个Skill必须是一个独立文件夹文件夹的名字尽量用英文小写加连字符比如inspection-report。文件夹名在很多实现里会作为Skill的标识之一乱用中文名或特殊字符容易出问题。第二文件夹里的核心文件是SKILL.md其他scripts、assets都是辅助没有SKILL.md的文件夹不会被识别成一个有效的Skill。新手最常犯的错误是从网上下载Skill压缩包解压后发现里面还套了一层同名文件夹直接把外层文件夹丢进skills目录导致WorkBuddy找不到SKILL.md。正确做法是解压后进入内层确认SKILL.md所在的那一层再移动过去。3. 三种安装Skill的主流路径与实操步骤3.1 路径一从内置Skill市场一键安装适合新手WorkBuddy里一般会有Skill管理面板。打开之后能看到官方市场或者社区市场列表里面按场景分类写作、编程、数据分析、办公自动化都有。搜索你要的Skill名称点安装WorkBuddy会自动拉到本地并完成注册。这是最简单的路径适合刚开始接触WorkBuddy还没搞明白目录结构的人。但一键安装也有个认知陷阱你以为装好了其实可能装的是“市场版本”它更新了你不一定知道。官方市场里的Skill一般有更新提示但如果你改过本地文件更新时可能会覆盖你的修改。所以如果你打算长期使用某个Skill并且想深度定制建议优先走本地路径市场安装适合尝鲜和快速验证。3.2 路径二把本地文件或GitHub项目直接装进Skills目录这是开发者最长用的方式。先到GitHub上找Skill项目克隆下来或者下载Zip包然后放进skills目录。git clone https://github.com/example/awesome-skill.git ~/.workbuddy/skills/awesome-skill如果是下载的Zip解压后一定要确认目录层级。很多仓库为了展示效果会做成外层套内层的结构。你会看到zip解压出来一个文件夹打开里面还有一个同名文件夹SKILL.md在更里面那层。这时候如果直接把外层文件夹放进去等于放了一个空壳。正确做法是把内层那个真正装着SKILL.md的文件夹移动过去或者把整个外层路径在配置里指对。另外从热词里能看到“codex安装”“git安装及配置教程”这些高频搜索说明不少人在安装Skill时连Git这关都没过。如果你也是这种情况别急着克隆仓库先花二十分钟把Git装好配置好user.name和user.email否则某些使用了子模块或关联脚本的Skill会拉取不完整。3.3 路径三通过WorkBuddy自带命令或批量清单安装WorkBuddy如果提供了命令行接口批量安装会非常高效。实际命令以你安装的版本为准思路大致是这样workbuddy skill install example-skill workbuddy skill install --source ./skill-local/对于需要给团队统一安装一批Skill的场景建议维护一份Skill清单把名称、来源、版本都记录清楚然后批量执行。好处是环境可复现新同事入职拉完配置、跑一遍批量安装工作台就齐活了。坏处是一旦某个Skill源失效你会被卡在中间步骤上所以清单里最好保留本地备份的路径。3.4 安装后必须做的验证重启、状态检查与触发测试很多人装完Skill看目录文件都在就以为大功告成结果真正对话里怎么调都调不出来。我强烈建议每次装完Skill后固定做三件事。第一重启WorkBuddy。大部分Skill加载是在启动阶段扫描目录完成的在线热加载的能力不一定稳定别省这一步。第二到Skill管理面板里确认状态看有没有加载失败的提示。第三做一个最简单的触发测试。比如刚装的巡检报告Skill就直接在对话里说“帮我写一个服务器巡检报告”如果它没有按预期输出报告结构说明Skill根本没被触发或者SKILL.md里的描述和你的触发语句匹配不上。4. 手写一个自己的Skill从零到能用的完整案例4.1 SKILL.md就是Skill的说明书兼大脑对Skill来说最核心的文件永远是SKILL.md。它的结构通常由两部分组成开头的元信息区和正文指令区。元信息区用来声明Skill的名字、描述、适用场景正文区域告诉模型具体应该怎么做。模型选择Skill的时候主要靠元信息里的描述来做匹配。所以描述写得是否精准直接决定了Skill能不能在正确的时候被触发。很多人写SKILL.md容易犯一个毛病把描述写得特别空比如“用于各种办公场景”。这种描述毫无区分度模型看了不知道该什么时候调用结果就是你的Skill长期处于“装了等于没装”的状态。正确写法是明确触发边界和输入形式比如“当用户提供Excel销售数据并希望生成月度分析报告时使用”。越具体触发越准。4.2 最小可用Skill案例一个能生成巡检报告的Skill我以一个实际跑通的巡检报告Skill为例演示手写Skill需要哪些东西。目录结构是这样inspection-report/ SKILL.md scripts/generate_report.pySKILL.md的核心内容长这样--- name: inspection-report description: 当用户需要根据系统巡检数据生成结构化报告时使用。输入可以是命令输出文本或日志片段输出为带章节标题、风险等级和处置建议的Markdown报告。 --- 1. 仔细阅读用户提供的巡检数据或日志。 2. 如果数据缺失先输出缺失项清单不要猜测。 3. 按以下结构生成报告 - 巡检概况 - 风险项列表按严重程度排序 - 处置建议 4. 所有严重风险必须单独用警示块标出。scripts/generate_report.py 就是一个纯粹的文本处理脚本负责把原始数据转换成Markdown表格。SKILL.md负责给模型讲清楚流程脚本负责把重复性劳动自动化。手写Skill的核心就是这个思路把“怎么判断”写进SKILL.md把“怎么处理”写进脚本。4.3 “Book to Skill”套路怎么把一份长文档压缩成可用指令社区里高频出现“book to skill”这个词很多人问是什么意思。它其实就是一种把文档知识“翻译”成Skill的方法你手上有一份几十页的规范文档或者内部流程说明希望WorkBuddy能按这套流程来干活这时候就要把文档改写成SKILL.md。我自己的做法分四步。第一步通读文档划出所有“必须做”和“禁止做”的条目。第二步把流程转化为带序号的步骤描述删除所有背景铺垫和抒情段落。第三步把判断条件写成“如果……那么……”的句式方便模型精准执行。第四步把高频出现的表格和模板原样放进SKILL.md作为输出格式参考。经过这四步一份几十页的文档通常能被压缩成几十行指令但执行精度反而比丢给模型去读原文档更高因为你把决策边界都显式写清楚了。4.4 关于“skill编码247、193”这类说法我说句实话热词里出现了“skill编码247”“skill编码193”之类的东西我在不少社区帖里也见到过。根据我看到的资料这类数字实际上是某些资源站或社区内部给预设Skill标的序号或者是在下载页面上用来区分版本的特殊编号跟本地Skill的安装机制没有直接关系。真正决定一个Skill能不能被WorkBuddy识别和加载的是文件夹名、SKILL.md里的name字段以及description写得好不好。所以看到“编码247”、“编码193”这类点进去下载就行不用被名词唬住但下载后记得检查SKILL.md是否存在内容是否是UTF-8编码这比纠结编号有意义得多。5. 踩坑实录我装WorkBuddy Skill时踩过的五类问题5.1 中文路径和空格让Skill直接失效我最初装一个文档处理Skill时图省事放在了“D盘/工作文件/我的Skill”这种带中文和空格的路径下。结果WorkBuddy的Skill列表里始终不显示这个Skill。折腾半天把路径改成全英文重启后立刻就能加载了。原因很简单某些脚本和解析逻辑不能很好处理带空格或非ASCII字符的路径。所以无论装在哪个目录记得确保整个路径上不要出现中文和空格。5.2 Skill名称冲突装了新版旧的还在作怪有一次我从市场装了一个新版的数据清洗Skill名字和之前手动放的旧版一模一样。结果对话里触发的永远是旧版新版怎么都不生效。后来才想到市场安装的Skill和本地skills目录里的Skill如果同名加载优先级可能取决于扫描顺序而旧版文件在本地目录里占着那个名字新版就没办法注册。处理办法是安装前先检查有没有同名项目有的话先把旧的移出去再装新的。5.3 脚本权限不足能看见但跑不起来在macOS和Linux上克隆下来的Skill仓库里的脚本默认可能没有执行权限。表现是WorkBuddy加载了Skill模型也能正常读SKILL.md但是真要执行scripts目录下的脚本时报Permission denied。解决方法是手动给脚本加权限chmod x ~/.workbuddy/skills/my-skill/scripts/*.py这个小问题特别隐蔽因为软件本身运行正常你根本不会想到是操作系统权限在捣乱。5.4 版本不兼容CodeBuddy的Skill拿到WorkBuddy上失灵WorkBuddy和CodeBuddy因为同门关系Skill机制确实很接近但并不意味着互相拷贝一定没问题。我有一次从CodeBuddy那边拿了一个自动化测试Skill装到WorkBuddy上之后SKILL.md能加载但是脚本里调用的某个内部命令路径对不上整个任务执行到一半就中断了。解决办法是装完跨工具来源的Skill后不要只做“加载状态检查”一定要完整跑一个任务检验脚本里的每一步是否真的能落地。5.5 模型能力跟不上Skill写得很完整但模型不执行这是最让人无奈的情况。SKILL.md写得很清楚脚本也没有问题但当前所选模型工具调用能力偏弱导致WorkBuddy把Skill读到了、却执行不完整比如跳过了某一步或者把脚本路径当成文本回复出来。遇到这种情况先别急着怀疑Skill写错了。换个更强模型试试或者把SKILL.md里的指令拆分得再细一些给模型减少决策压力。这也是为什么很多“高质量Skill”会强调零歧义表达因为一来是Prompt工程追求极致二来确实是在给弱模型留活路。6. 装上之后不生效最完整的排查链路6.1 第一步确认Skill是否真的被加载了遇到“装上不生效”的情况先冷静。重启WorkBuddy然后打开Skill管理面板看那个Skill卡片的状态是不是正常的。如果状态是未加载或者有警告图标说明问题出在加载阶段。此时去看日志比瞎猜有价值得多。6.2 第二步翻日志盯准“load”和“error”这两个词WorkBuddy的日志路径以我的版本来看通常在配置目录下的logs文件夹里你可以自己找一下类似~/.workbuddy/logs的位置。打开当天的日志文件搜索Skill名称、load、error这几个关键字。我自己遇到的加载失败日志里大多数时候都会有明确的错误行比如找不到SKILL.md、JSON解析失败、目录不存在。看到具体错误信息之后再回目录结构里排查效率极高。6.3 第三步用最小复现法拆问题如果日志里没有任何报错Skill也显示加载了但对话里就是触发不了这时候用最小复现法来定位。先找官方市场里任意一个最简单的官方示例Skill装上去用同一句触发语测试。如果官方示例能触发说明问题出在你自己装的Skill身上如果官方示例也触发不了说明问题出在对话环境、模型或者WorkBuddy配置上跟你装的Skill无关。这个二分排查法能帮你快速缩小问题范围。6.4 第四步隔离回退找出“带坏”整个列表的Skill还有一种隐蔽情况一个Skill出问题导致整个Skill列表加载异常看起来像所有Skill都失效了。遇到这种情况先把skills目录改名备份让WorkBuddy在无Skill状态下启动确认能正常运行然后新建一个空skills目录把Skill一个一个放回去每放一个重启一次直到复现问题找到那个罪魁祸首。这一步虽然繁琐但对付“全部失灵”的现象非常有效。问题Skill找到后检查它的SKILL.md格式、脚本依赖和名称是否与其他Skill冲突。排查到最后我个人最大的体会是WorkBuddy装Skill这个操作看起来只是复制粘贴实际上每一步都在考验你对“目录结构、版本认知、指令设计”的理解。熟练之后你会发现最顺手的工作台不是拿来直接用的而是自己调出来的。下次不管从社区里下到“狗头军师Skill”还是“AI备课Skill”先看目录、再看SKILL.md、最后做一次触发测试这套节奏走完WorkBuddy基本就不会给你添堵了。
WorkBuddy Skill安装实战：从环境准备到排查不生效
前阵子同事甩给我一句话把WorkBuddy的Skill给我装上我要用那个能自动写巡检报告的技能。我当时觉得这活儿五分钟就能搞定——跟装个普通插件差不多嘛。结果真上手才发现WorkBuddy的Skill安装和“装个插件”完全是两码事。它牵扯到版本差异、目录权限、脚本依赖、SKILL.md编写规范每一步都藏着不起眼的小坑。这篇就把我实际跑通的流程、踩过的坑、以及装上之后不生效的完整排查思路写下来给同样被WorkBuddy Skill折腾过的朋友一个可以直接照做的参考。1. 先搞清楚WorkBuddy的Skill装在“哪个脑子”里1.1 WorkBuddy不是插件商店它是一个Agent工作台先捋清楚WorkBuddy到底是个什么东西。它本质上是一个AI Agent工作台负责把大模型的对话能力、文件系统访问、命令行执行、各种API调用编排在一块。和普通IDE插件不一样WorkBuddy不是单纯给你“加一个按钮”而是让你在对话里指派任务它自己拆解步骤、调用工具、产出结果。所以社区里经常有人把它和CodeBuddy、Codex、Cursor放在一起讨论因为它们都是“AI干活”的思路WorkBuddy更强调把工作台搭建起来Skill就是往这个工作台里塞“可复用的行为包”。理解这一点特别重要因为它决定了你对Skill的预期。很多新手以为安装Skill就是把某个压缩包解压进去点一下“启用”完事。但Skill在WorkBuddy里的运行机制是当模型的对话内容匹配到某个Skill的描述时WorkBuddy会去读对应的SKILL.md文件把里面的指令和步骤作为行为准则再结合Skill自带的脚本去执行任务。换句话说Skill不是一段被调用就完事的代码而是一套“触发条件 操作流程 工具脚本”的组合体。1.2 Skill和普通插件的核心区别指令即行为如果之前用过VS Code插件或JetBrains插件很容易带着旧思路来理解Skill然后就被坑。普通插件是预先编译好的程序功能固定安装后通过界面交互Skill则更多是“写给模型看的行为规范”。SKILL.md里写清楚什么场景触发、按什么步骤做、输出什么格式模型看到这套指令再来执行。所以Skill质量的上下限差异极大写得好的Skill能让模型稳定复现一套复杂流程写不好的Skill哪怕模型再强也会跑偏。这里有个非常有意思的推论社区里那些稀奇古怪的Skill比如“狗头军师Skill”“前任Skill”“去AI味的Skill”本质上都是Prompt工程的作品。它们不是在调用什么黑科技而是把一套经过设计的思考路径和行为约束写进了SKILL.md里。理解了这一点你装任何Skill之前都会有判断力这个Skill到底是真有逻辑还是只是把一堆提示词包装了一下。实际操作中很多号称“神器”的Skill拆开就是一篇结构化指令真正值钱的是指令设计本身。1.3 动手装Skill之前先确认这三件事第一确认你的WorkBuddy版本。国际版和国内版在账号体系、模型路由、Skill市场内容上都有差异后面我会单独讲怎么选。第二确认Skill来源。是官方市场里一键安装还是从GitHub克隆项目还是自己手写不同来源的安装路径和后续维护方式完全不一样。第三确认目标场景。你要这个Skill来做什么是辅助用户写作、整理数据还是调用脚本执行本地任务如果Skill涉及执行外部命令对依赖环境和权限的要求会高很多。这三件事没想清楚就急着装大概率会出现“装上了但用不了”或者“能用但不干活”的尴尬。别问我怎么知道的我一开始就是没确认版本装了一个只适配国际版的Skill结果在国内版上静默失败折腾了两个小时。2. 环境准备版本、目录和依赖一样都不能省2.1 国际版和国内版先选明白别稀里糊涂装一半WorkBuddy国际版和国内版不是换了个服务器那么简单。两者在账号体系上是分开的国内版通常走国内模型服务渠道国际版在模型选择上更多Skill市场的丰富程度也更高。你在选的时候不用纠结“哪个更高级”核心就看你的实际网络环境和使用习惯。能正常访问国际服那就用国际版访问不顺就用国内版两者在Skill目录结构、SKILL.md规范上基本一致换版本的成本没有想象中那么高。这里有个我踩过的教训不同版本对Skill的兼容性并不完全一致。有一部分从CodeBuddy或者旧版WorkBuddy导出的Skill直接放进新版里面会提示“格式不支持”或者干脆不加载。所以装Skill前先看一眼自己的版本号再去看Skill仓库里标注的适配版本不要看到Star多就直接克隆。2.2 依赖环境检查Python、Git、Node和你的目录权限WorkBuddy的Skill分为纯指令型和带脚本型。纯指令型只要读SKILL.md就能跑带脚本型往往需要执行Python或Node脚本。所以我建议无论你现在用不用脚本型Skill先把基础环境补齐否则后面装到一半发现脚本跑不起来非常扫兴。python --version git --version node --version三条命令依次确认Python、Git、Node是否可用。我见过不少报错其实跟WorkBuddy一点关系都没有纯粹是电脑上连Git都没装克隆Skill仓库时卡住还以为是WorkBuddy的问题。另一点容易忽视的是目录权限。在macOS和Linux上如果WorkBuddy的数据目录权限不对Skill文件夹放进去之后可能读不到或者脚本文件没有执行权限。2.3 Skill文件的标准目录结构装之前先看懂家目录不同版本WorkBuddy的Skill目录位置可能略有差异但通常遵循一个约定在用户主目录下创建一个以WorkBuddy相关的隐藏配置目录里面再建skills子目录。常见的路径长这样~/.workbuddy/ skills/ my-skill/ SKILL.md scripts/ assets/核心要点有两个。第一每个Skill必须是一个独立文件夹文件夹的名字尽量用英文小写加连字符比如inspection-report。文件夹名在很多实现里会作为Skill的标识之一乱用中文名或特殊字符容易出问题。第二文件夹里的核心文件是SKILL.md其他scripts、assets都是辅助没有SKILL.md的文件夹不会被识别成一个有效的Skill。新手最常犯的错误是从网上下载Skill压缩包解压后发现里面还套了一层同名文件夹直接把外层文件夹丢进skills目录导致WorkBuddy找不到SKILL.md。正确做法是解压后进入内层确认SKILL.md所在的那一层再移动过去。3. 三种安装Skill的主流路径与实操步骤3.1 路径一从内置Skill市场一键安装适合新手WorkBuddy里一般会有Skill管理面板。打开之后能看到官方市场或者社区市场列表里面按场景分类写作、编程、数据分析、办公自动化都有。搜索你要的Skill名称点安装WorkBuddy会自动拉到本地并完成注册。这是最简单的路径适合刚开始接触WorkBuddy还没搞明白目录结构的人。但一键安装也有个认知陷阱你以为装好了其实可能装的是“市场版本”它更新了你不一定知道。官方市场里的Skill一般有更新提示但如果你改过本地文件更新时可能会覆盖你的修改。所以如果你打算长期使用某个Skill并且想深度定制建议优先走本地路径市场安装适合尝鲜和快速验证。3.2 路径二把本地文件或GitHub项目直接装进Skills目录这是开发者最长用的方式。先到GitHub上找Skill项目克隆下来或者下载Zip包然后放进skills目录。git clone https://github.com/example/awesome-skill.git ~/.workbuddy/skills/awesome-skill如果是下载的Zip解压后一定要确认目录层级。很多仓库为了展示效果会做成外层套内层的结构。你会看到zip解压出来一个文件夹打开里面还有一个同名文件夹SKILL.md在更里面那层。这时候如果直接把外层文件夹放进去等于放了一个空壳。正确做法是把内层那个真正装着SKILL.md的文件夹移动过去或者把整个外层路径在配置里指对。另外从热词里能看到“codex安装”“git安装及配置教程”这些高频搜索说明不少人在安装Skill时连Git这关都没过。如果你也是这种情况别急着克隆仓库先花二十分钟把Git装好配置好user.name和user.email否则某些使用了子模块或关联脚本的Skill会拉取不完整。3.3 路径三通过WorkBuddy自带命令或批量清单安装WorkBuddy如果提供了命令行接口批量安装会非常高效。实际命令以你安装的版本为准思路大致是这样workbuddy skill install example-skill workbuddy skill install --source ./skill-local/对于需要给团队统一安装一批Skill的场景建议维护一份Skill清单把名称、来源、版本都记录清楚然后批量执行。好处是环境可复现新同事入职拉完配置、跑一遍批量安装工作台就齐活了。坏处是一旦某个Skill源失效你会被卡在中间步骤上所以清单里最好保留本地备份的路径。3.4 安装后必须做的验证重启、状态检查与触发测试很多人装完Skill看目录文件都在就以为大功告成结果真正对话里怎么调都调不出来。我强烈建议每次装完Skill后固定做三件事。第一重启WorkBuddy。大部分Skill加载是在启动阶段扫描目录完成的在线热加载的能力不一定稳定别省这一步。第二到Skill管理面板里确认状态看有没有加载失败的提示。第三做一个最简单的触发测试。比如刚装的巡检报告Skill就直接在对话里说“帮我写一个服务器巡检报告”如果它没有按预期输出报告结构说明Skill根本没被触发或者SKILL.md里的描述和你的触发语句匹配不上。4. 手写一个自己的Skill从零到能用的完整案例4.1 SKILL.md就是Skill的说明书兼大脑对Skill来说最核心的文件永远是SKILL.md。它的结构通常由两部分组成开头的元信息区和正文指令区。元信息区用来声明Skill的名字、描述、适用场景正文区域告诉模型具体应该怎么做。模型选择Skill的时候主要靠元信息里的描述来做匹配。所以描述写得是否精准直接决定了Skill能不能在正确的时候被触发。很多人写SKILL.md容易犯一个毛病把描述写得特别空比如“用于各种办公场景”。这种描述毫无区分度模型看了不知道该什么时候调用结果就是你的Skill长期处于“装了等于没装”的状态。正确写法是明确触发边界和输入形式比如“当用户提供Excel销售数据并希望生成月度分析报告时使用”。越具体触发越准。4.2 最小可用Skill案例一个能生成巡检报告的Skill我以一个实际跑通的巡检报告Skill为例演示手写Skill需要哪些东西。目录结构是这样inspection-report/ SKILL.md scripts/generate_report.pySKILL.md的核心内容长这样--- name: inspection-report description: 当用户需要根据系统巡检数据生成结构化报告时使用。输入可以是命令输出文本或日志片段输出为带章节标题、风险等级和处置建议的Markdown报告。 --- 1. 仔细阅读用户提供的巡检数据或日志。 2. 如果数据缺失先输出缺失项清单不要猜测。 3. 按以下结构生成报告 - 巡检概况 - 风险项列表按严重程度排序 - 处置建议 4. 所有严重风险必须单独用警示块标出。scripts/generate_report.py 就是一个纯粹的文本处理脚本负责把原始数据转换成Markdown表格。SKILL.md负责给模型讲清楚流程脚本负责把重复性劳动自动化。手写Skill的核心就是这个思路把“怎么判断”写进SKILL.md把“怎么处理”写进脚本。4.3 “Book to Skill”套路怎么把一份长文档压缩成可用指令社区里高频出现“book to skill”这个词很多人问是什么意思。它其实就是一种把文档知识“翻译”成Skill的方法你手上有一份几十页的规范文档或者内部流程说明希望WorkBuddy能按这套流程来干活这时候就要把文档改写成SKILL.md。我自己的做法分四步。第一步通读文档划出所有“必须做”和“禁止做”的条目。第二步把流程转化为带序号的步骤描述删除所有背景铺垫和抒情段落。第三步把判断条件写成“如果……那么……”的句式方便模型精准执行。第四步把高频出现的表格和模板原样放进SKILL.md作为输出格式参考。经过这四步一份几十页的文档通常能被压缩成几十行指令但执行精度反而比丢给模型去读原文档更高因为你把决策边界都显式写清楚了。4.4 关于“skill编码247、193”这类说法我说句实话热词里出现了“skill编码247”“skill编码193”之类的东西我在不少社区帖里也见到过。根据我看到的资料这类数字实际上是某些资源站或社区内部给预设Skill标的序号或者是在下载页面上用来区分版本的特殊编号跟本地Skill的安装机制没有直接关系。真正决定一个Skill能不能被WorkBuddy识别和加载的是文件夹名、SKILL.md里的name字段以及description写得好不好。所以看到“编码247”、“编码193”这类点进去下载就行不用被名词唬住但下载后记得检查SKILL.md是否存在内容是否是UTF-8编码这比纠结编号有意义得多。5. 踩坑实录我装WorkBuddy Skill时踩过的五类问题5.1 中文路径和空格让Skill直接失效我最初装一个文档处理Skill时图省事放在了“D盘/工作文件/我的Skill”这种带中文和空格的路径下。结果WorkBuddy的Skill列表里始终不显示这个Skill。折腾半天把路径改成全英文重启后立刻就能加载了。原因很简单某些脚本和解析逻辑不能很好处理带空格或非ASCII字符的路径。所以无论装在哪个目录记得确保整个路径上不要出现中文和空格。5.2 Skill名称冲突装了新版旧的还在作怪有一次我从市场装了一个新版的数据清洗Skill名字和之前手动放的旧版一模一样。结果对话里触发的永远是旧版新版怎么都不生效。后来才想到市场安装的Skill和本地skills目录里的Skill如果同名加载优先级可能取决于扫描顺序而旧版文件在本地目录里占着那个名字新版就没办法注册。处理办法是安装前先检查有没有同名项目有的话先把旧的移出去再装新的。5.3 脚本权限不足能看见但跑不起来在macOS和Linux上克隆下来的Skill仓库里的脚本默认可能没有执行权限。表现是WorkBuddy加载了Skill模型也能正常读SKILL.md但是真要执行scripts目录下的脚本时报Permission denied。解决方法是手动给脚本加权限chmod x ~/.workbuddy/skills/my-skill/scripts/*.py这个小问题特别隐蔽因为软件本身运行正常你根本不会想到是操作系统权限在捣乱。5.4 版本不兼容CodeBuddy的Skill拿到WorkBuddy上失灵WorkBuddy和CodeBuddy因为同门关系Skill机制确实很接近但并不意味着互相拷贝一定没问题。我有一次从CodeBuddy那边拿了一个自动化测试Skill装到WorkBuddy上之后SKILL.md能加载但是脚本里调用的某个内部命令路径对不上整个任务执行到一半就中断了。解决办法是装完跨工具来源的Skill后不要只做“加载状态检查”一定要完整跑一个任务检验脚本里的每一步是否真的能落地。5.5 模型能力跟不上Skill写得很完整但模型不执行这是最让人无奈的情况。SKILL.md写得很清楚脚本也没有问题但当前所选模型工具调用能力偏弱导致WorkBuddy把Skill读到了、却执行不完整比如跳过了某一步或者把脚本路径当成文本回复出来。遇到这种情况先别急着怀疑Skill写错了。换个更强模型试试或者把SKILL.md里的指令拆分得再细一些给模型减少决策压力。这也是为什么很多“高质量Skill”会强调零歧义表达因为一来是Prompt工程追求极致二来确实是在给弱模型留活路。6. 装上之后不生效最完整的排查链路6.1 第一步确认Skill是否真的被加载了遇到“装上不生效”的情况先冷静。重启WorkBuddy然后打开Skill管理面板看那个Skill卡片的状态是不是正常的。如果状态是未加载或者有警告图标说明问题出在加载阶段。此时去看日志比瞎猜有价值得多。6.2 第二步翻日志盯准“load”和“error”这两个词WorkBuddy的日志路径以我的版本来看通常在配置目录下的logs文件夹里你可以自己找一下类似~/.workbuddy/logs的位置。打开当天的日志文件搜索Skill名称、load、error这几个关键字。我自己遇到的加载失败日志里大多数时候都会有明确的错误行比如找不到SKILL.md、JSON解析失败、目录不存在。看到具体错误信息之后再回目录结构里排查效率极高。6.3 第三步用最小复现法拆问题如果日志里没有任何报错Skill也显示加载了但对话里就是触发不了这时候用最小复现法来定位。先找官方市场里任意一个最简单的官方示例Skill装上去用同一句触发语测试。如果官方示例能触发说明问题出在你自己装的Skill身上如果官方示例也触发不了说明问题出在对话环境、模型或者WorkBuddy配置上跟你装的Skill无关。这个二分排查法能帮你快速缩小问题范围。6.4 第四步隔离回退找出“带坏”整个列表的Skill还有一种隐蔽情况一个Skill出问题导致整个Skill列表加载异常看起来像所有Skill都失效了。遇到这种情况先把skills目录改名备份让WorkBuddy在无Skill状态下启动确认能正常运行然后新建一个空skills目录把Skill一个一个放回去每放一个重启一次直到复现问题找到那个罪魁祸首。这一步虽然繁琐但对付“全部失灵”的现象非常有效。问题Skill找到后检查它的SKILL.md格式、脚本依赖和名称是否与其他Skill冲突。排查到最后我个人最大的体会是WorkBuddy装Skill这个操作看起来只是复制粘贴实际上每一步都在考验你对“目录结构、版本认知、指令设计”的理解。熟练之后你会发现最顺手的工作台不是拿来直接用的而是自己调出来的。下次不管从社区里下到“狗头军师Skill”还是“AI备课Skill”先看目录、再看SKILL.md、最后做一次触发测试这套节奏走完WorkBuddy基本就不会给你添堵了。