1. 先搞清楚WorkBuddy和Skill到底是什么1.1 WorkBuddy不是又一个效率软件而是一个“带手带脑”的工作台说实话我第一次看到WorkBuddy这个名字的时候以为是又一款待办清单或者笔记工具。真正用下来才发现它更像是一个“AI工作台”——把对话模型、本地脚本、外部工具和你日常用的应用有人拿它配合Obsidian也有人拿它管理自动签到任务全部串在一个界面里。你可以把它理解成一个总控台左边是模型右边是工具中间是你给AI布置的任务流。WorkBuddy最核心的机制是Skill。Skill这个概念如果你接触过Claude的Skills或者Codex的自定义指令应该不陌生——它就是给AI预置的一组“技能包”。装一个Skill等于告诉AI“遇到这类任务时先用这套思路、这套脚本、这套输出格式去处理”。WorkBuddy把这种能力做了标准化Skill不只是一段提示词而是一个包含说明文件、可执行脚本、依赖清单、示例数据的完整目录。安装Skill的过程本质就是让AI从“只会聊天”变成“会干活”。这篇文章写给谁两类人。一类是刚下载WorkBuddy、看着界面不知道从哪儿下手的新手另一类是已经在用Codex或其他终端AI工具、想搞懂Skill到底怎么搬运、怎么调试的老手。我会从环境准备讲到三种安装方式再讲验证和排查全程用我实际踩坑的经验来讲不是抄文档那种干巴巴的步骤。1.2 Skill和“插件”“Agent”之间到底是什么关系在动手之前必须把Skill这个概念的边界划清楚不然后面会遇到很多困惑。网上有人把Skill、Plugin、Agent混着叫其实它们在WorkBuddy里的分工完全不同。Skill是最小执行单元它是一个静态目录里面放着“AI做这件事需要的所有知识和方法”。比如一个“网页爬虫Skill”包含SKILL.md说明文件告诉模型先分析页面结构再写脚本、一个Python脚本实际抓取逻辑、一份requirements.txt。Skill本身不主动启动只有当AI判断当前任务匹配这个Skill的描述时它才会被加载进上下文。Plugin侧重系统集成通常带生命周期比如WorkBuddy启动时自动加载、监听某个事件、提供API接口。你可以把Plugin理解为“给WorkBuddy本体动手术”而Skill只是“给AI递工具”。Agent则是有自主决策能力的闭环它内部会调用多个Skill和Plugin自己拆分任务、循环执行、直到目标完成。在WorkBuddy里Agent负责调度Skill负责干脏活累活。打个比方Plugin是工作台上的电源插座Skill是插在插座上的电钻、电锯、螺丝刀Agent是那个拿着工具、看着图纸施工的工人。你问“WorkerBuddy里怎么装Skill”本质上就是研究“给工人往工具架上放什么工具、怎么放、放完怎么确认工具好使”。2. 安装前的环境准备先把地基打牢2.1 基础依赖Git、Node.js、Python一个都不能少WorkBuddy的Skill安装高度依赖三个底层工具。先说Git因为绝大多数Skill都托管在GitHub仓库workbuddy安装Skill最常见的方式就是“从仓库拉取”如果没有Git你连第一步都迈不出去。Windows用户在官网下载Git安装包后一直Next就行安装完打开终端输入git --version能输出版本号说明装好了。Node.js和Python需要重点说。WorkBuddy本身基于Node.js生态构建所以Node.js是必装的而很多Skill的实现脚本是Python写的所以Python环境也得备好。我见过太多人在这一步翻车装了Node.js 14然后发现WorkBuddy要求至少18或者系统里有两个Python版本WorkBuddy调用的python3命令指到了一个古老版本。建议统一用最新LTS版本Node.js直接去官网下载LTS版目前是20.x或22.xPython至少3.10以上。装完分别执行node -v python3 --version git --version三个命令都能正常输出再继续往下走。这一步不是浪费时间我后面排查问题时发现至少三分之一的问题出在环境不干净上。2.2 配置好模型服务WorkBuddy的底层大脑装Skill之前WorkBuddy必须能连上一个大模型服务。WorkBuddy本身不内置模型它像是一个“遥控器”需要你给它指定后端。目前最常用的方式是配置Codex或兼容OpenAI接口的服务。如果你选择Codex这条路线需要先装好Codex CLI然后在WorkBuddy的设置里填入Codex的API Key和工作目录。这里有个容易踩的坑Codex有多个配置项包括model、temperature、system_prompt。我最初安装完成后Skill能识别但执行脚本时总是报权限错查了半天发现是WorkBuddy调用Codex时没有用对配置文件。建议在工作目录下建一个.codex文件夹手动写一份配置把模型名、API Key、允许的目录范围填清楚。如果你不想用Codex只要你的模型服务提供OpenAI兼容的/v1/chat/completions接口WorkBuddy也能接。这类服务的通用配置是base_url: http://127.0.0.1:8000/v1 api_key: 你的密钥没有就填not-needed model: 模型名称配置完先不急着装Skill直接在WorkBuddy的对话窗口问一句“你好能看到这条消息吗”确认模型通了再继续。这一步能排查掉一大半“Skill装了没反应”的问题。2.3 找到WorkBuddy的配置目录和数据目录很多人卡在“Skill到底该放到哪里”这个问题上。不同操作系统的路径不一样WorkBuddy遵循常见的配置文件规范Linux:~/.config/workbuddy/macOS:~/Library/Application Support/workbuddy/Windows:%APPDATA%\workbuddy\实际操作中不用死记路径。你打开WorkBuddy的设置界面找到“Advanced”或“数据目录”一栏里面会显示当前数据目录。我的习惯是直接在终端里定位# Linux/macOS echo ~/.config/workbuddy # 查看当前数据目录内容 ls -la ~/.config/workbuddy正常情况下你会看到skills、config.json、logs这几个主要目录。如果还没有skills目录可以自己创建一个WorkBuddy会识别。搞清楚数据目录后安装Skill就变得很直观了——无论哪种安装方式最终目标都是让Skill目录出现在skills文件夹下面。3. 三种安装Skill的方式按场景选3.1 方式一通过WorkBuddy内建的Skill市场直接安装这是最简单的方式适合不想碰命令行的朋友。在WorkBuddy界面左侧或顶部菜单里找到“Skill Market”有的版本叫“插件市场”或“技能商店”里面会列出一批官方维护的Skill。鼠标悬停可以看到简介、版本号、更新时间点击“Install”按钮就能装好。内建市场的优势在于依赖自动处理。比如你装一个“PDF解析Skill”它需要的pypdf库会被自动安装装完即用。我从实际经验里总结出一个选择技巧不要只看下载量要看“Last updated”时间。Skill这东西和模型迭代速度强相关一个半年没更新的Skill很可能还在用旧模型的调用范式装上去后AI反而表现变差。市场安装还有个细节安装完成后有些Skill需要重启WorkBuddy才能生效。我建议每次装完Skill后都做一次彻底重启退出进程再重新打开而不是用界面里的“Reload”因为某些缓存不会完全清除。另外一个Skill的版本更新后市场里通常会显示“Update”按钮。我的建议是不要盲目点更新——如果当前版本用着顺手先看一眼更新日志确认没有重大配置变更再升。有一次我点了一个Skill的更新结果它的配置文件格式改了之前自定义过的参数全部失效又花时间重新调。3.2 方式二从GitHub仓库手动安装灵活度最高当你在GitHub上看到一个别人分享的Skill仓库就需要动手手动安装了。这个方法本质上是“把远程仓库里的Skill目录拉下来放到本地的skills目录”。第一步找到远程仓库地址。以一台Linux服务器为例假设这个Skill仓库地址是https://github.com/someone/workbuddy-skill-awesome我通常这么操作# 进入WorkBuddy的skills目录 cd ~/.config/workbuddy/skills # 克隆整个仓库 git clone https://github.com/someone/workbuddy-skill-awesome.git但这里有个新手常见问题一个仓库里往往不止一个Skill而是包含多个子目录直接clone整个仓库会把多余文件也拉进来。更规范的做法是先git clone到临时目录然后挑选需要的Skill目录复制进skills目录# 克隆到临时目录 git clone https://github.com/someone/workbuddy-skill-awesome.git /tmp/wb-skill-src # 看看里面有哪些Skill ls -la /tmp/wb-skill-src # 把需要的Skill复制到WorkBuddy数据目录 cp -r /tmp/wb-skill-src/skills/awesome /home/你的用户名/.config/workbuddy/skills/为什么要复制而不是整个仓库放进去因为WorkBuddy扫描skills目录时会读取每个子目录下的SKILL.md文件来注册技能。如果整个仓库目录结构不对WorkBuddy可能识别不到任何Skill。手动复制的好处就是你可以精确控制哪些Skill生效。第三步检查Skill目录结构是否合法。一个标准的WorkBuddy Skill目录应该有这些内容skill-name/ ├── SKILL.md ├── scripts/ ├── assets/ ├── requirements.txt可选 └── config.json可选其中SKILL.md是必须的它是AI理解这个Skill的入口。有的Skill还需要安装Python依赖复制完成后别忘了cd ~/.config/workbuddy/skills/某个skill pip install -r requirements.txt这里有个重要经验看清楚requirements.txt里有没有指定版本。有些老Skill会指定numpy1.24这种旧版本直接安装可能和系统里其他库冲突。遇到这种情况我一般会把版本号去掉或改到当前兼容的版本以能运行为准。3.3 方式三自己动手写一个Skill彻底掌控一切当现成的Skill满足不了需求时自己写一个并不难。WorkBuddy的Skill机制设计得很清晰核心就是写好SKILL.md再配上必要的脚本和数据文件。SKILL.md用的是带YAML frontmatter的Markdown格式最基本的结构长这样--- name: my-weather-skill description: 查询任意城市的实时天气支持中文城市名。 version: 1.0.0 allowed-tools: - python - requests --- # 天气查询Skill 当用户询问“今天天气怎么样”或“查询某个城市天气”时使用此技能。 ## 使用步骤 1. 从用户消息中提取城市名。 2. 运行 python scripts/weather.py 城市名。 3. 将输出结果整理成通俗的一句话播报按照“城市天气温度建议”的格式返回。 ## 注意事项 - 城市名为空时默认查询北京。 - 接口超时时间设为10秒。这个文件的关键不是格式多漂亮而是description字段要写得精确。AI决定是否调用Skill时主要靠匹配这个description和用户输入的相关性。我写第一个Skill时description写得太笼统写“执行天气查询”结果用户问“今天适合穿什么”时模型没能联想到这个Skill。后来改成“查询天气并给出穿衣建议”命中率瞬间提升。脚本部分按规范放到scripts/目录比如我那个天气Skill的weather.pyimport sys, json, urllib.request city sys.argv[1] if len(sys.argv) 1 else 北京 url fhttps://api.example.com/weather?city{city} with urllib.request.urlopen(url, timeout10) as resp: data json.loads(resp.read().decode()) print(json.dumps({city: city, weather: data[weather], temp: data[temp]}, ensure_asciiFalse))写好后把整个目录放到skills/下。WorkBuddy会在下次启动时自动扫描并注册这个Skill。自己写Skill的最大好处是你完全清楚它内部怎么工作出了问题一眼就能定位。4. 装完之后怎么验证、怎么调优4.1 三步验证法确认Skill真的生效了每次装完Skill只看到提示“安装成功”是远远不够的。环境不同、模型不同Skill装好但调用失败的情况很常见。我建议用一套三步验证法第一步在WorkBuddy的对话界面输入“查看所有已安装的技能”或“列出可用Skill”。WorkBuddy一般会返回当前已加载的Skill列表。如果列表里看不到刚装的Skill说明注册没成功去检查目录结构和SKILL.md格式。第二步用一句和Skill描述高度匹配的指令来触发它。比如刚装了“天气查询Skill”就直接问“查询一下上海的天气”。在WorkBuddy的日志里你可以看到模型是否选择了这个Skill来回答。第三步直接运行Skill依赖的脚本确认脚本本身能跑通。比如cd ~/.config/workbuddy/skills/my-weather-skill python scripts/weather.py 上海如果脚本自己都报错就别指望AI能帮你跑成功。这个“隔离测试”的思路能帮助你快速分清问题是出在Skill本身还是出在模型调用Skill的环节上。我自己做验证时发现至少有四成的情况是脚本在纯命令行下能跑通但在WorkBuddy环境里报错原因通常是环境变量或PATH不一致。4.2 给一个Skill换模型或调参的进阶操作有些Skill默认按某一种模型的能力来设计提示词当你换了更强的模型或更弱的模型时Skill表现会有明显差异。WorkBuddy允许在Skill的config.json里覆盖模型相关参数。举个例子我的一个“会议纪要Skill”在弱模型下需要把每个步骤拆得非常细分五步走换了强模型后只保留两步就够了效果反而更好。所以建议你在Skill的配置里加上这类参数{ model_override: false, use_cot: false, max_steps: 5 }这里有个经验如果使用的模型工具调用能力很强不太会出错那use_cot思维链开不开其实影响不大如果模型经常“偷工减料”跳跃步骤那打开use_cot并加上“请列出步骤再执行”的提示词会更稳。调参的时候不要一次性改太多一次只改一个变量然后跑两次真实任务对比能更清楚地看出每个参数的影响。4.3 几个我常用的Skill配置和自定义指令推荐结合热词里大家常搜的“workbuddy自定义指令推荐”我分享几个经过验证的配置思路。一个是“每日自动签到”Skill。很多人问WorkBuddy能不能做自动签到我的答案是“能但要谨慎”。具体做法是写一个Python脚本用requests库模拟登录、发送签到请求然后用WorkBuddy的定时能力每天触发一次。这里必须重点提醒自动签到涉及账户凭证存储一定不要把账号密码明文写在Skill的配置里。我踩过这个坑后来改用环境变量或WorkBuddy自带的安全存储字段。另外签到逻辑里要加错误重试和通知机制否则某天网站改版了你都不知道签没签上。另一个是“代码审查”Skill。我配合Codex用的场景是把一段代码贴给WorkBuddy它会按照SKILL.md里定义的规范逐条审查从安全漏洞到性能问题给出列表。这个Skill的description我写得比较宽“审查输入代码输出问题列表、对应行号及修复建议”。因为代码审查的触发往往不是某个固定句式description写得宽一些命中率更高。还有一个“Obsidian笔记整理”Skill。这个需要和Obsidian的本地目录打通本质就是文件操作脚本加提示词约束。我最常用它来做“把今日临时笔记按标签归入对应文件夹”和“为笔记标题生成统一命名格式”这两件事。这些配置没有标准答案关键是理解SKILL.md中的description和使用步骤是AI的“操作手册”写得越具体执行结果越稳定。5. 常见问题与排查实录5.1 为什么安装成功但Skill没有出现在列表里这是我自己第一次装Skill就遇到的问题。装完一个仓库里的SkillWorkBuddy界面里却看不到。排查了一圈发现出在目录结构上。WorkBuddy扫描skills目录时要求每个Skill子目录必须是顶层目录直接包含SKILL.md。而我把整个仓库克隆进了skills目录仓库下面还套着二级子目录等于WorkBuddy扫描时看到的是一个没有SKILL.md的“仓库目录”。解决办法很简单进入skills目录把Skill对应的文件夹放到顶层。另外还要看SKILL.md有没有语法错误。frontmatter格式要求严格name和description必填如果记得version写错了或allowed-tools格式不对注册就会失败。你可以用任何在线的YAML校验工具把SKILL.md开头那段frontmatter粘贴进去检查一下。5.2 Skill能识别但执行脚本时报错这种情况最折磨人AI成功选择了这个Skill结果每次执行都说“脚本报错”。常见的原因有三类。第一类是环境变量问题。WorkBuddy作为GUI应用启动时读取的PATH可能和终端里不一样。你在终端里能用的python命令WorkBuddy不一定能找到。排查方法是在报错信息里看具体的命令路径然后把WorkBuddy的启动方式改成从终端启动或者修改Skill里的SKILL.md让它总是使用绝对路径调用解释器比如#!/usr/bin/env python3。第二类是依赖缺失。Skill的README里写了要装依赖你没装或者装到了错误的环境。WorkBuddy可能用的是独立的Python虚拟环境你在终端里pip install装的是全局Python。这种情况要在WorkBuddy的设置里找到“Python解释器路径”或者在Skill启动脚本中先激活对应的虚拟环境。第三类是运行目录错误。脚本里用了相对路径比如./data/xxx.json但Skill执行时的工作目录和Skill所在目录不是同一个。解决办法是任何文件路径都基于__file__来构造写成绝对路径不要用相对路径。5.3 同一个Skill在Linux和Windows上表现不一样热词里既有“workbuddy linux”也有Windows相关的搜索这确实是个真实痛点。WorkBuddy跨平台支持但Skill不一定跨平台。很多Python脚本在Windows下跑不通最常见的是路径分隔符和第三方库的兼容问题。如果主要在Linux服务器上用建议优先使用Linux环境彻底避免这类跨平台兼容问题。如果条件限制必须在Windows用那么安装Skill时多留意三件事一是看README里有没有写明平台支持范围二是scripts目录里的文件如果是Shell脚本在Windows上大概率跑不了三是打开Skill的PY脚本检查有没有用os.system(rm -rf ...)这种Unix特性命令。我自己的经验是生产环境跑重型Skill一律放到Linux服务器或容器里Windows本机只装那些纯提示词类的“轻量Skill”比如格式整理、文案改写、代码片段生成。5.4 排查工具和日志查看WorkBuddy带有一套日志系统出问题时首先要想到看日志而不是瞎猜。Linux下日志一般在~/.config/workbuddy/logs/里面会有多个日期命名的.log文件。查看最近日志tail -f ~/.config/workbuddy/logs/最新日志.log常见的关键词包括skill_load_failedSkill加载失败、skill_execute_error执行出错、tool_call_timeout工具调用超时、model_response_error模型返回异常。看到这类关键词直接去搜索引擎搜“WorkBuddy 关键词”会比从头翻日志效率高很多。还有一个非常实用的排查手段在WorkBuddy的对话里输入“调试模式显示当前Skill的加载状态”让它以文本形式汇报每个Skill的加载情况。这比打开日志看半天的效率高得多。写在最后的几个心得WorkBuddy装Skill这件事说难不难说简单也不简单。它真正难的地方不在于“把文件放到文件夹里”这一步而在于理解Skill、模型、工具三者之间的协作逻辑。我刚开始用的时候以为Skill装得越多越厉害结果装了二三十个很多都在配置里互相冲突模型反而不知道该调哪个。后来我做了一次“减负”只保留十个核心Skill每个都是精挑细选、反复验证过的整体效率反而上来了。还有一个心得是Skill不是“装完就完”它需要持续维护。模型一更新可能某个Skill的prompt就该改了某个外部API一变对应的Skill脚本就要修。我现在每次升级WorkBuddy或者Codex之后都会顺手把最常用的几个Skill跑一遍验证命令确保没有引入回归。最后如果你刚接触WorkBuddy不要一上来就折腾各种花哨Skill。先用最简单的方式装一个官方市场的Skill跑通整个流程再逐步尝试从GitHub安装最后再考虑自己写。这个过程会让你对Skill的机制有更直观的认识。等你熟悉了自然会形成一套属于自己的Skill管理和定制方法论。