先说明一句这篇是给真正想把 WorkBuddy 用成生产力主战装备的人写的不是那种五分钟装完截个图就丢一边的入门水文。我会把技能机制的原理、必装清单、安装流程、自建思路、发布到 ClawHub / SkillHub 的完整链路以及我从实际使用中踩出来的坑一次性讲清楚。不管你是刚听说 Skills 这个概念还是已经在用但想自己开发技能上传分享这篇都能直接照着操作。1. WorkBuddy 的 Skills 机制到底解决的是什么问题先说一个最容易被忽略的点WorkBuddy 本质上不是一个聊天框插件的组合它的核心调度逻辑是围绕任务类型动态加载能力包。这套机制和传统的提示词模板有本质区别我一开始也以为 Skills 只是把 Prompt 变成文件而已实际操作之后才意识到它改变的其实是 Agent 的工作方式。1.1 从 Prompt 到 Skill差的不是格式而是触发逻辑普通自定义指令本质上是静态的。你把一段指令写进去它就一直挂在那里不管当前的任务需不需要这段约束Agent 每次都要把它考虑进去。这就带来两个问题一是指令多了之后互相干扰二是无关指令会稀释 Agent 对当前任务的注意力。Skills 的逻辑完全不同。一个 Skill 本质上是一个独立的目录里面有SKILL.md作为指令入口还可以带上脚本、模板、配置文件。最关键的是每个 Skill 的description字段写的是触发条件Agent 会先根据这个描述判断当前用户的意图是否匹配这个技能匹配了才加载不匹配就不加载。这就像工具箱里的专用扳手——只有用到的时候才拿起来而不是把所有工具都绑在手上干活。我测试过在同一个会话里来回切换文档总结和代码调试这两类任务如果用的是传统自定义指令Agent 经常会把文档总结的规则带到代码调试里去导致输出格式错乱。换成 Skills 之后切换的干净程度明显提升基本能做到各管各的。1.2 WorkBuddy 和 Claude Code / Codex 的 Skills 路线对比目前市面上的 Agent 工具里Claude Code 有类似的原生技能机制Codex 也在往 AGENTS.md 技能目录 的方向演进。WorkBuddy 的差异化在于聚合性WorkBuddy 支持把来自不同生态的技能安装到一个统一目录下管理而 Claude Code 的技能市场相对封闭。外部平台支持WorkBuddy 对接了 ClawHub 和 SkillHub 两个技能分发平台前者主打下载量较高的通用工具型技能后者更偏开发者原创和垂直场景技能。本地优先技能安装后是纯本地文件断网也能用修改和调试都很直观。有一说一在技能生态的成熟度上 Claude Code 还是领先的但 WorkBuddy 后发追赶的速度很快特别是最近一段时间 SkillHub 上的原创技能数量涨得很猛很多之前在 Claude Code 上只能自己魔改的技能现在都能在 WorkBuddy 里直接装。1.3 一个 Skill 的完整文件结构一个标准的 WorkBuddy 技能目录长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── preprocess.py │ └── validate.sh ├── templates/ │ └── output_template.md ├── requirements.txt └── assets/ └── example.pdfSKILL.md是唯一必须的文件其余都是可选增强。我见过很多人只放一个SKILL.md也能跑得很顺但如果技能里要执行外部脚本或者生成复杂模板建议还是把逻辑拆分到scripts/和templates/里职责清楚后续维护也好改。SKILL.md的 frontmatter 至少要有name和description两个字段。name是技能的唯一标识description则是决定这个技能在什么情况下会被唤醒的关键。我后面会在自建章节里详细说 description 的写法这里先记住一句话description 是给 Agent 看的选择依据不是给人看的简介。2. 必装技能清单按工作场景挑别贪多技能这东西不是越多越好。装得太多一是 Agent 在匹配技能描述时会犹豫二是同一类技能描述互相覆盖容易引发错误触发。我根据自己的使用经验和 SkillHub/ClawHub 上的热门数据按场景整理了一份相对克制的清单每个场景装一个主力就够。2.1 编程开发这些技能能直接提升 Agent 的下限前端开发 Skills是热度最高的技能之一尤其是做 React/Vue 项目重构时。这个技能的主要作用不是让 Agent 会写代码而是统一代码风格、自动生成组件结构、在修改时保持现有技术栈的一致性。我实测下来装了它之后生成的组件代码ESLint 通过率从大概 60% 提升到接近 90%省去了大量来回修改的时间。Codex 开发必备 Skills这个标题有蹭热度嫌疑但内容确实实用。它打包了一系列针对多文件项目修改的指令规范核心是教会 Agent 在跨文件改动时先建立索引关系再分步执行。对于用 WorkBuddy 写中大型项目的人来说这个技能值得装。结构图 Skills很多人低估了它的价值。它能把项目目录结构、函数调用关系自动整理成层级图在接手老项目时特别管用。我用它快速生成过一个接手项目的模块依赖说明直接省掉了一下午的人工梳理。2.2 文档与写作论文排版和知识管理的高频刚需LaTeX 排版 Skills是学术党必装。这个技能不是让你告别 LaTeX而是让 Agent 理解你的排版意图正确使用宏包、控制浮体位置、处理参考文献引用。我写论文时经常遇到的一个痛点是中文文档和 LaTeX 的兼容问题——字体、换行、标点压缩这个技能里打包了一套比较成熟的处理方案。SkillHub 上还有针对特定期刊模板的定制版本需要的话可以搜一下。论文写作 Skills和上面那个是搭配使用的论文类技能专注于写作结构比如引言怎么写、相关工作怎么组织、实验部分怎么描述对比结果。它内置了学术写作常用的过渡语句、论证结构和图表说明模板。装了这个之后让 Agent 帮忙润色论文段落的出稿质量会稳定很多。WorkBuddy Obsidian 联动技能是知识管理流的效率神器。它能直接读写 Obsidian 库的 markdown 文件自动为笔记补充双链、维护目录索引、按标签重新组织笔记结构。我之前几百篇散乱笔记就是靠它整理的花了一个下午批量规整完比手动整理快了不知道多少倍。2.3 自动化效率签到、备份和重复操作自动签到技能是最轻松的零成本摸鱼技能会定时帮你执行网页签到类操作比如各类论坛、工具站的每日签到。需要说明的是目前 WorkBuddy 的自动化调度还依赖终端保持运行所以更推荐把它放在常驻服务器的环境里用在纯本地桌面机上使用效果会打折扣。图片生成 Skills 安装包严格来说不是一个技能而是一组技能的合集包括文生图、图生图、局部重绘、统一风格转换等。适合做自媒体配图、设计参考图和电商素材的。需要提醒的是这类技能依赖外部图像生成 API安装之前先确认你手头的 API Key 是哪个平台的——同一套描述词在不同模型上的表现差异很大技能里默认的参数不一定适合你的模型。2.4 选择原则总结我把选技能的经验总结成一条标准描述要窄、依赖要少、输出要稳。描述窄一个技能只干一类事不要装全能型技能因为触发准确率通常不高。依赖少优先选只需要一个脚本或纯指令文本的技能依赖多个外部服务的技能一旦某个服务挂掉就全面失效。输出稳看技能是否定义了明确的输出格式。没有输出模板的技能每次生成结果都像开盲盒。下表是我当前工作环境下保留的技能清单供参考技能名称使用场景来源平台触发关键词示例前端开发 SkillsReact/Vue 组件开发与重构ClawHub前端开发、组件重构、代码规范结构图 Skills生成项目结构/依赖关系图SkillHub目录结构、包依赖、架构图LaTeX 排版 Skills学术论文 LaTeX 写作SkillHubLaTeX、排版、宏包冲突修复论文写作 Skills学术写作结构优化SkillHub论文润色、引言写法、相关工作Obsidian 联动技能笔记库整理与双链维护ClawHubObsidian、笔记整理、双链自动签到技能常驻服务器定时签到ClawHub每日签到、自动打卡3. 技能安装实战目录结构、命令和验证很多人装技能失败不是命令不会敲而是没搞清楚 WorkBuddy 的技能加载机制。这一章我从安装路径讲起把几种安装方式都过一遍附带我应该踩过的坑。3.1 全局目录和项目目录怎么选WorkBuddy 的技能加载目录分两个层级全局目录默认~/.workbuddy/skills/所有项目共享适合通用型技能。项目目录.workbuddy/skills/只对当前项目生效适合项目定制技能。两边的优先级是项目目录更高。也就是说如果同一个技能名在项目目录和全局目录都存在WorkBuddy 会优先加载项目目录的版本。这个机制很实用比如团队里有人对全局技能做了定制但又不想影响其他项目就可以放到项目目录里覆盖。安装策略上我的建议是常用技能装全局项目特定技能装项目目录。一开始我图省事全装全局结果遇到两个项目需要不同技术栈约束的情况全局技能会互相串味改成项目目录后清爽多了。3.2 命令行安装的具体操作WorkBuddy 目前支持几种安装方式以clawhub上的技能为例# 方式一通过命令行从市场安装 workbuddy skills install clawhub:frontend-dev-kit # 方式二从 SkillHub 安装 workbuddy skills install skillhub:academic-latex-suite # 方式三本地源码安装 workbuddy skills install /path/to/local/skill执行完workbuddy skills list检查确认技能出现在列表里。如果列表有名称但显示(disabled)那多半是技能描述格式不合格或者缺少SKILL.md需要手动检查文件内容。还需要说明的是本地源码安装和从市场安装本质是一样的最终都会把技能文件拷贝到技能目录。区别在于从市场安装会带上版本管理和元数据方便后续检查更新本地安装则适合还在调试阶段的技能改完直接在原目录修改即可不用重复安装。3.3 手动安装的适用场景和步骤如果你遇到需要手动安装的情况——比如技能只以压缩包形式分享或者技能文件托管在 Git 仓库里——可以直接手动放置# 克隆技能仓库 git clone https://github.com/yourname/some-skill.git ~/.workbuddy/skills/some-skill # 或者手动解压到技能目录 unzip some-skill.zip -d ~/.workbuddy/skills/手动安装最需要注意的是目录层级问题。很多技能压缩包解压后是some-skill/套着里面又一个some-skill/这样 WorkBuddy 就识别不到了。解压后检查一下确保SKILL.md位于你的技能目录的下一级直接可见而不是藏在两级目录之下。3.4 如何验证技能装好了验证技能是否真正生效不能只看列表。我建议这样测试直接文件检查确认SKILL.md存在并且 frontmatter 中的name和description字段完整且非空。触发测试新建一个会话用和技能描述匹配的自然语言描述你的需求观察 Agent 是否主动加载该技能WorkBuddy 加载技能后会在运行日志中留下记录如果你的终端开启了 verbose 模式会直接看到。行为测试向 Agent 提问一个与技能职责相关的具体问题对比不用该技能时的回答质量和流程规范性。注意修改技能文件后需要在 WorkBuddy 中重新建立会话才能让改动生效。同一个会话内即使修改了SKILL.mdAgent 也不一定会重新读取因为技能在会话开始时就被加载到上下文里了。4. 自建一个技能从零到能用的完整过程会装技能只是入门会自建技能才是真正把 WorkBuddy 用成私人助手的门槛。这一章我带大家完整走一遍自建流程以会议纪要整理这个最经典的场景为例——它够简单不涉及复杂脚本但能跑通技能开发的完整链路。4.1 确定场景、限制范围和输出格式自建技能之前先回答三个问题这个技能帮 Agent 完成了哪些原本不做的事如果只是把一段提示词塞进技能文件那没有意义。技能的边界在哪比如会议纪要整理要明确是只做结构整理还是也包括后续任务分发。输出格式是什么这决定了技能里要不要带模板文件。我见过很多自建技能失败根本原因就是场景过宽。比如帮我写文档这种描述Agent 每次都不知道该加载还是不该加载就算加载了也不知道具体按什么流程执行。反过来从会议录音转写文本中提取决策项、待办事项、风险点生成 markdown 会议纪要这个描述Agent 一下子就知道该做什么。4.2 一步步写出可用的 SKILL.md目录和文件结构如下meeting-notes/ ├── SKILL.md └── templates/ └── notes_template.mdSKILL.md的核心内容是这个样子注意 frontmatter 里的写法--- name: meeting-notes description: 当用户提供会议录音转写文本或会议讨论记录并要求整理会议纪要、提取决策项、待办事项、风险点时使用此技能。 --- # 会议纪要整理 ## 职责范围 - 从原始会议记录中提取关键信息。 - 按统一结构输出会议纪要。 ## 执行步骤 1. 识别参会人员、时间、议题。 2. 提取讨论要点按议题分组。 3. 单独列出决策项、待办事项、风险点。 4. 使用模板生成会议纪要。这里有一个新手常见误区description 不能太抽象也不能太长。太抽象 Agent 判断不了触发时机太长了占用上下文空间而且弱化了关键词权重。我通常控制在三行以内涵盖什么输入场景什么动作。再看模板文件notes_template.md# 会议纪要 - 时间 - 参会人 - 议题 ## 讨论要点 - ## 决策项 - ## 待办事项 - [ ] ## 风险点 -模板的价值在于让 Agent 的输出格式稳定不会这次用 markdown 下次用纯文本。如果技能涉及代码生成同理推荐在模板里定义好代码框架和注释规范。4.3 测试和迭代用真实输入检验技能质量技能写完之后立刻在当前会话测试workbuddy skills enable meeting-notes然后输入一段比较口语化的需求帮我把这段会议内容整理一下看看有什么要跟进的。测试时重点关注触发链路Agent 有没有因为你的描述而加载meeting-notes执行链路Agent 有没有按 SKILL.md 里的步骤走输出链路最终输出的格式是否严格符合模板如果某个环节出了问题不要急着改描述。先把问题定位清楚是没触发、还是触发后步骤跑偏、还是步骤对了但格式不对。每一步对应的修复位置不一样改错地方反而越改越乱。我自己的调试习惯是先拿三段真实度足够高的输入测试看三段输出的稳定性。如果三段输出的格式和内容层面质量都很接近就说明技能基本可用如果三次输出差异很大多半是执行步骤写得不够细。4.4 给技能加上依赖配置如果你的技能要额外调用脚本或者需要指定 Python 环境的依赖就在技能目录下放一个requirements.txtrequests2.31.0 beautifulsoup44.12.0WorkBuddy 目前不会自动帮你安装技能依赖需要你手动执行。我把这个坑写在这里是因为很多人从平台装完技能直接就跑报错ModuleNotFoundError之后才开始排查——其实问题多半是依赖没装。装完技能后第一件事是检查有没有requirements.txt有就手动安装别等报错再处理。5. 发布到 ClawHub / SkillHub上传、审核与更新自己开发的技能只放在本地有点可惜发布到平台能让更多人用到也能沉淀个人作品。这一章讲讲我在 ClawHub 和 SkillHub 上发布技能的完整流程以及平台之间的定位差异。5.1 两个平台怎么选定位决定发布策略从我的使用体验看ClawHub更像是技能应用商店用户群体更广下载量是核心指标适合通用性强、完成度高、文档完善的技能。上传审核相对严格对技能描述格式、脚本安全性都有要求。SkillHub偏开发者社区允许上传实验性技能和针对特定工具链的定制技能更新频率高迭代空间大。适合你在学习和测试阶段的技能也适合带有个人工作流特点的技能。对大多数自建技能我的建议是先在 SkillHub 发布测试版收集反馈和 issue稳定后发布正式版到 ClawHub。不要两个平台都发一样的内容因为用户评价维度不同铺开双发容易分散维护精力。5.2 上传前的检查清单发布前别急着点上传先对照这张清单过一遍检查项要求SKILL.md 格式frontmatter 必须包含name和description字段description 描述需要写出触发场景不要使用推销式语言目录层级SKILL.md必须在技能根目录下一级直接可见脚本安全不能包含下载执行、读取系统敏感目录等操作静态依赖尽量降低外部依赖注明必要的 API Key 或环境变量权限说明如果技能需要读写本地文件需在说明中明确演示效果建议附带一张使用前后对比截图其中description 描述是审核最容易卡的点。平台审核会看这个描述是否能让 Agent 准确触发旁对旁不对的描述会被驳回。我之前被驳回的一次就是因为把 description 写成了 A useful tool for all your tasks这个描述几乎等于没有触发条件平台直接打回让我重写。5.3 实际上传步骤我以 SkillHub 为例说明上传流程准备本地技能包确保技能目录下只有必要文件没有无用缓存和.git目录。打包技能zip -r my-skill.zip my-skill/注意压缩包内第一层应该是技能目录本身。登录 SkillHub在网页端创建新技能填写名称和简介。上传压缩包将my-skill.zip传到平台。填写版本说明v1.0.0下面写清楚这个版本包含的功能和已知限制。提交审核等待结果通常 1-3 个工作日。ClawHub 的上传流程类似但额外要求先通过 CLI 工具做一次本地校验workbuddy skills validate my-skill/这个校验命令会检查格式规范、目录层级、frontmatter 字段完整性。本地通过之后再走网页端提交能省掉不少来回打回的等待时间。5.4 审核被驳回的常见原因和修正方案我见过和经历过的主要驳回原因有这几类SKILL.md 的 description 里带可能、也许这类模糊词——改成确定性的触发描述。技能目录里缺少示例或测试用例——审核希望技能不是一次性产物补上examples/和tests/目录能显著提高过审率。依赖声明不完整——如果你的技能要调用requests库但requirements.txt里没有会被判定为依赖缺失。这个检查尤其严格。脚本里包含网络请求——审核需要你在技能说明中写清楚请求的域名和用途如果不写会被判定为有潜在风险。5.5 发布后如何维护和更新技能发布之后留意一段时间用户的 issue 反馈尤其是环境差异导致的报错。我自己维护技能时有一个固定流程每个季度集中处理一次 issue统一归纳成版本更新。版本号遵循语义化规则修复 bug 升 patch新增功能升 minor不兼容改动升 major。每次更新都在版本说明里标明变化点和影响范围方便用户决定是否升级。这里要给一个特别提醒更新技能时不要在本地原目录里直接改而是复制一份出来改好测试通过后再上传。因为 WorkBuddy 加载技能时直接读原目录如果你在原目录上改了一半Agent 在中途会读取到不完整的文件造成不可预期的行为。6. 实际操作中你大概率会遇到的几个坑这一章写的都是我在实机环境中真正踩过的问题不是从文档里抄出来的注意事项。每个坑我都会给排查思路和解决办法希望你看到的时候能直接避开。6.1 workbuddy 502 write eacces 的权限问题这个报错在 Linux 环境下比较常见尤其是你用非 root 用户安装技能时。报错字面意思是写入权限不足但真正触发场景往往是在技能安装阶段试图向系统级目录写入文件。排查链路先确认报错时的操作是安装技能、加载技能还是运行技能中的脚本。检查技能目录归属ls -la ~/.workbuddy/skills/如果目录归属是 root而你运行 WorkBuddy 的是普通用户执行sudo chown -R $(whoami) ~/.workbuddy/skills/如果用的是系统级安装路径比如/opt/workbuddy建议改成用户级安装避免每次都需要提权。这里有个容易误导人的点这个报错不一定是文件系统权限也可能是npm或pip的全局安装权限问题。如果技能里的脚本依赖npm install -g或pip install --system就会出现类似的 EACCES 报错。解决办法是把依赖安装到用户目录npm config set prefix ~/.npm-global export PATH$HOME/.npm-global/bin:$PATH6.2 技能装了好多但触发率很低这是最多人问我的问题。技能装了一堆但 Agent 好像视而不见。我排查之后发现大多是 description 写得不好原因是你的 description 里写的触发词和用户实际表达的习惯不一致。举个例子你写的是 Latex 排版技能用户实际说的是 帮我改一下参考文献格式——两个文本在语义上相关但字面上没有直接重叠Agent 匹配失败。解决办法是描述里覆盖用户视角的常见表达比如 排版、参考文献格式、公式对齐、LaTex 编译错误修复 这种与具体问题相关的触发词。多写几个用户真实会用的表达而不是一个高高在上的学术化名词。6.3 Skills 和自定义指令的优先级冲突当同一个需求既能被 Skills 触发又命中了自定义指令的内容时WorkBuddy 的默认行为是以自定义指令为基准再叠加技能补充。这个优先级有时候会造成指令覆盖技能的现象——技能里定义的输出规则被自定义指令改写导致技能的实际输出和预期不符。遇到这种情况先检查你的自定义指令里有没有和技能冲突的规则。如果有从自定义指令里删掉对应条目或者把技能的使用说明写进项目目录的指令里做定向约束不要全局默认覆盖。6.4 跨平台迁移技能时的路径坑在 Windows 上写好的技能迁移到 Linux 或 macOS 上跑最常见的坑是路径分隔符和默认 shell 差异。技能里如果写了scripts/xxx.shWindows 上可能没有 bash要改成跨平台的调用方式或者显式声明需要 bash 环境。涉及文件路径的写法不要写死/Users/xxx/这种绝对路径尽量用相对路径让 Agent 基于当前工作目录推导。如果技能脚本里用了 Windows 换行符CRLFLinux 上执行会报\r: command not found迁移后用dos2unix转换一下。这段说出来可能有点低级但真的很多人会中招。我自己的经验是所有自建技能从一开始就用相对路径 可移植脚本Python 优先于 Bash就省掉了绝大多数跨平台问题。6.5 从能跑到稳定迭代时机把握最后一条经验是关于开发节奏的。很多自建技能在能跑通的第二天就被丢进完成任务名单结果换了场景一用就崩。我觉得一个技能真正算稳定至少要经过三个不同场景的实测——不能只拿第一次测试的成功当标准至少要包含一次边界输入比如输入巨长、输入格式混乱、输入包含特殊情况一次正常输入一次接近失效边界的输入。我用一个简单的判断方法如果连续五段不同但相似的输入输出质量都保持稳定就可以发布了如果第二段就崩了调整之后不要急着继续测先把调整逻辑理解清楚再说。7. 写在最后的几条实战补充建议这篇文章的核心内容到这里基本讲完了。最后分享几个我在整个 WorkBuddy 使用过程中沉淀下来的习惯供新参考。第一给技能目录建一个备份机制。~/.workbuddy/skills/这个目录是你花时间积攒出来的资产建议把它纳入一个 Git 仓库管理。我用的方式是建私有仓库每次技能增删或配置修改都提交一次回滚和迁移都非常方便。第二多关注 SkillHub 上的版本更新时间线。同一个技能一个月前和一个月后的版本可能完全不是同一个质量等级。如果觉得某个技能不好用先看一下它最近有没有更新很多问题在最新版已经修复了。第三学会从别人的技能里抄思路。自建技能最快速的上手方式不是从零开始凭空想而是在自己的技能目录里安装三个同场景的技能打开它们的SKILL.md逐行对比。你会发现不同作者的步骤设计、描述写法、模板思路差异很大把这些差异消化掉你对技能应该怎么设计的理解会立刻提升一个层次。这件事比自己从头摸索高效得多。最后补充一句技能生态目前还在快速演进中WorkBuddy 的加载机制和平台规则以后大概率还会调整。但只要理解了触发-加载-执行-输出这条核心链路不管工具怎么升级你都能很快适应。祝都能把自己的 WorkBuddy 调教成真正懂你的助手。
WorkBuddy Skills机制实战：从原理到发布的完整指南
先说明一句这篇是给真正想把 WorkBuddy 用成生产力主战装备的人写的不是那种五分钟装完截个图就丢一边的入门水文。我会把技能机制的原理、必装清单、安装流程、自建思路、发布到 ClawHub / SkillHub 的完整链路以及我从实际使用中踩出来的坑一次性讲清楚。不管你是刚听说 Skills 这个概念还是已经在用但想自己开发技能上传分享这篇都能直接照着操作。1. WorkBuddy 的 Skills 机制到底解决的是什么问题先说一个最容易被忽略的点WorkBuddy 本质上不是一个聊天框插件的组合它的核心调度逻辑是围绕任务类型动态加载能力包。这套机制和传统的提示词模板有本质区别我一开始也以为 Skills 只是把 Prompt 变成文件而已实际操作之后才意识到它改变的其实是 Agent 的工作方式。1.1 从 Prompt 到 Skill差的不是格式而是触发逻辑普通自定义指令本质上是静态的。你把一段指令写进去它就一直挂在那里不管当前的任务需不需要这段约束Agent 每次都要把它考虑进去。这就带来两个问题一是指令多了之后互相干扰二是无关指令会稀释 Agent 对当前任务的注意力。Skills 的逻辑完全不同。一个 Skill 本质上是一个独立的目录里面有SKILL.md作为指令入口还可以带上脚本、模板、配置文件。最关键的是每个 Skill 的description字段写的是触发条件Agent 会先根据这个描述判断当前用户的意图是否匹配这个技能匹配了才加载不匹配就不加载。这就像工具箱里的专用扳手——只有用到的时候才拿起来而不是把所有工具都绑在手上干活。我测试过在同一个会话里来回切换文档总结和代码调试这两类任务如果用的是传统自定义指令Agent 经常会把文档总结的规则带到代码调试里去导致输出格式错乱。换成 Skills 之后切换的干净程度明显提升基本能做到各管各的。1.2 WorkBuddy 和 Claude Code / Codex 的 Skills 路线对比目前市面上的 Agent 工具里Claude Code 有类似的原生技能机制Codex 也在往 AGENTS.md 技能目录 的方向演进。WorkBuddy 的差异化在于聚合性WorkBuddy 支持把来自不同生态的技能安装到一个统一目录下管理而 Claude Code 的技能市场相对封闭。外部平台支持WorkBuddy 对接了 ClawHub 和 SkillHub 两个技能分发平台前者主打下载量较高的通用工具型技能后者更偏开发者原创和垂直场景技能。本地优先技能安装后是纯本地文件断网也能用修改和调试都很直观。有一说一在技能生态的成熟度上 Claude Code 还是领先的但 WorkBuddy 后发追赶的速度很快特别是最近一段时间 SkillHub 上的原创技能数量涨得很猛很多之前在 Claude Code 上只能自己魔改的技能现在都能在 WorkBuddy 里直接装。1.3 一个 Skill 的完整文件结构一个标准的 WorkBuddy 技能目录长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── preprocess.py │ └── validate.sh ├── templates/ │ └── output_template.md ├── requirements.txt └── assets/ └── example.pdfSKILL.md是唯一必须的文件其余都是可选增强。我见过很多人只放一个SKILL.md也能跑得很顺但如果技能里要执行外部脚本或者生成复杂模板建议还是把逻辑拆分到scripts/和templates/里职责清楚后续维护也好改。SKILL.md的 frontmatter 至少要有name和description两个字段。name是技能的唯一标识description则是决定这个技能在什么情况下会被唤醒的关键。我后面会在自建章节里详细说 description 的写法这里先记住一句话description 是给 Agent 看的选择依据不是给人看的简介。2. 必装技能清单按工作场景挑别贪多技能这东西不是越多越好。装得太多一是 Agent 在匹配技能描述时会犹豫二是同一类技能描述互相覆盖容易引发错误触发。我根据自己的使用经验和 SkillHub/ClawHub 上的热门数据按场景整理了一份相对克制的清单每个场景装一个主力就够。2.1 编程开发这些技能能直接提升 Agent 的下限前端开发 Skills是热度最高的技能之一尤其是做 React/Vue 项目重构时。这个技能的主要作用不是让 Agent 会写代码而是统一代码风格、自动生成组件结构、在修改时保持现有技术栈的一致性。我实测下来装了它之后生成的组件代码ESLint 通过率从大概 60% 提升到接近 90%省去了大量来回修改的时间。Codex 开发必备 Skills这个标题有蹭热度嫌疑但内容确实实用。它打包了一系列针对多文件项目修改的指令规范核心是教会 Agent 在跨文件改动时先建立索引关系再分步执行。对于用 WorkBuddy 写中大型项目的人来说这个技能值得装。结构图 Skills很多人低估了它的价值。它能把项目目录结构、函数调用关系自动整理成层级图在接手老项目时特别管用。我用它快速生成过一个接手项目的模块依赖说明直接省掉了一下午的人工梳理。2.2 文档与写作论文排版和知识管理的高频刚需LaTeX 排版 Skills是学术党必装。这个技能不是让你告别 LaTeX而是让 Agent 理解你的排版意图正确使用宏包、控制浮体位置、处理参考文献引用。我写论文时经常遇到的一个痛点是中文文档和 LaTeX 的兼容问题——字体、换行、标点压缩这个技能里打包了一套比较成熟的处理方案。SkillHub 上还有针对特定期刊模板的定制版本需要的话可以搜一下。论文写作 Skills和上面那个是搭配使用的论文类技能专注于写作结构比如引言怎么写、相关工作怎么组织、实验部分怎么描述对比结果。它内置了学术写作常用的过渡语句、论证结构和图表说明模板。装了这个之后让 Agent 帮忙润色论文段落的出稿质量会稳定很多。WorkBuddy Obsidian 联动技能是知识管理流的效率神器。它能直接读写 Obsidian 库的 markdown 文件自动为笔记补充双链、维护目录索引、按标签重新组织笔记结构。我之前几百篇散乱笔记就是靠它整理的花了一个下午批量规整完比手动整理快了不知道多少倍。2.3 自动化效率签到、备份和重复操作自动签到技能是最轻松的零成本摸鱼技能会定时帮你执行网页签到类操作比如各类论坛、工具站的每日签到。需要说明的是目前 WorkBuddy 的自动化调度还依赖终端保持运行所以更推荐把它放在常驻服务器的环境里用在纯本地桌面机上使用效果会打折扣。图片生成 Skills 安装包严格来说不是一个技能而是一组技能的合集包括文生图、图生图、局部重绘、统一风格转换等。适合做自媒体配图、设计参考图和电商素材的。需要提醒的是这类技能依赖外部图像生成 API安装之前先确认你手头的 API Key 是哪个平台的——同一套描述词在不同模型上的表现差异很大技能里默认的参数不一定适合你的模型。2.4 选择原则总结我把选技能的经验总结成一条标准描述要窄、依赖要少、输出要稳。描述窄一个技能只干一类事不要装全能型技能因为触发准确率通常不高。依赖少优先选只需要一个脚本或纯指令文本的技能依赖多个外部服务的技能一旦某个服务挂掉就全面失效。输出稳看技能是否定义了明确的输出格式。没有输出模板的技能每次生成结果都像开盲盒。下表是我当前工作环境下保留的技能清单供参考技能名称使用场景来源平台触发关键词示例前端开发 SkillsReact/Vue 组件开发与重构ClawHub前端开发、组件重构、代码规范结构图 Skills生成项目结构/依赖关系图SkillHub目录结构、包依赖、架构图LaTeX 排版 Skills学术论文 LaTeX 写作SkillHubLaTeX、排版、宏包冲突修复论文写作 Skills学术写作结构优化SkillHub论文润色、引言写法、相关工作Obsidian 联动技能笔记库整理与双链维护ClawHubObsidian、笔记整理、双链自动签到技能常驻服务器定时签到ClawHub每日签到、自动打卡3. 技能安装实战目录结构、命令和验证很多人装技能失败不是命令不会敲而是没搞清楚 WorkBuddy 的技能加载机制。这一章我从安装路径讲起把几种安装方式都过一遍附带我应该踩过的坑。3.1 全局目录和项目目录怎么选WorkBuddy 的技能加载目录分两个层级全局目录默认~/.workbuddy/skills/所有项目共享适合通用型技能。项目目录.workbuddy/skills/只对当前项目生效适合项目定制技能。两边的优先级是项目目录更高。也就是说如果同一个技能名在项目目录和全局目录都存在WorkBuddy 会优先加载项目目录的版本。这个机制很实用比如团队里有人对全局技能做了定制但又不想影响其他项目就可以放到项目目录里覆盖。安装策略上我的建议是常用技能装全局项目特定技能装项目目录。一开始我图省事全装全局结果遇到两个项目需要不同技术栈约束的情况全局技能会互相串味改成项目目录后清爽多了。3.2 命令行安装的具体操作WorkBuddy 目前支持几种安装方式以clawhub上的技能为例# 方式一通过命令行从市场安装 workbuddy skills install clawhub:frontend-dev-kit # 方式二从 SkillHub 安装 workbuddy skills install skillhub:academic-latex-suite # 方式三本地源码安装 workbuddy skills install /path/to/local/skill执行完workbuddy skills list检查确认技能出现在列表里。如果列表有名称但显示(disabled)那多半是技能描述格式不合格或者缺少SKILL.md需要手动检查文件内容。还需要说明的是本地源码安装和从市场安装本质是一样的最终都会把技能文件拷贝到技能目录。区别在于从市场安装会带上版本管理和元数据方便后续检查更新本地安装则适合还在调试阶段的技能改完直接在原目录修改即可不用重复安装。3.3 手动安装的适用场景和步骤如果你遇到需要手动安装的情况——比如技能只以压缩包形式分享或者技能文件托管在 Git 仓库里——可以直接手动放置# 克隆技能仓库 git clone https://github.com/yourname/some-skill.git ~/.workbuddy/skills/some-skill # 或者手动解压到技能目录 unzip some-skill.zip -d ~/.workbuddy/skills/手动安装最需要注意的是目录层级问题。很多技能压缩包解压后是some-skill/套着里面又一个some-skill/这样 WorkBuddy 就识别不到了。解压后检查一下确保SKILL.md位于你的技能目录的下一级直接可见而不是藏在两级目录之下。3.4 如何验证技能装好了验证技能是否真正生效不能只看列表。我建议这样测试直接文件检查确认SKILL.md存在并且 frontmatter 中的name和description字段完整且非空。触发测试新建一个会话用和技能描述匹配的自然语言描述你的需求观察 Agent 是否主动加载该技能WorkBuddy 加载技能后会在运行日志中留下记录如果你的终端开启了 verbose 模式会直接看到。行为测试向 Agent 提问一个与技能职责相关的具体问题对比不用该技能时的回答质量和流程规范性。注意修改技能文件后需要在 WorkBuddy 中重新建立会话才能让改动生效。同一个会话内即使修改了SKILL.mdAgent 也不一定会重新读取因为技能在会话开始时就被加载到上下文里了。4. 自建一个技能从零到能用的完整过程会装技能只是入门会自建技能才是真正把 WorkBuddy 用成私人助手的门槛。这一章我带大家完整走一遍自建流程以会议纪要整理这个最经典的场景为例——它够简单不涉及复杂脚本但能跑通技能开发的完整链路。4.1 确定场景、限制范围和输出格式自建技能之前先回答三个问题这个技能帮 Agent 完成了哪些原本不做的事如果只是把一段提示词塞进技能文件那没有意义。技能的边界在哪比如会议纪要整理要明确是只做结构整理还是也包括后续任务分发。输出格式是什么这决定了技能里要不要带模板文件。我见过很多自建技能失败根本原因就是场景过宽。比如帮我写文档这种描述Agent 每次都不知道该加载还是不该加载就算加载了也不知道具体按什么流程执行。反过来从会议录音转写文本中提取决策项、待办事项、风险点生成 markdown 会议纪要这个描述Agent 一下子就知道该做什么。4.2 一步步写出可用的 SKILL.md目录和文件结构如下meeting-notes/ ├── SKILL.md └── templates/ └── notes_template.mdSKILL.md的核心内容是这个样子注意 frontmatter 里的写法--- name: meeting-notes description: 当用户提供会议录音转写文本或会议讨论记录并要求整理会议纪要、提取决策项、待办事项、风险点时使用此技能。 --- # 会议纪要整理 ## 职责范围 - 从原始会议记录中提取关键信息。 - 按统一结构输出会议纪要。 ## 执行步骤 1. 识别参会人员、时间、议题。 2. 提取讨论要点按议题分组。 3. 单独列出决策项、待办事项、风险点。 4. 使用模板生成会议纪要。这里有一个新手常见误区description 不能太抽象也不能太长。太抽象 Agent 判断不了触发时机太长了占用上下文空间而且弱化了关键词权重。我通常控制在三行以内涵盖什么输入场景什么动作。再看模板文件notes_template.md# 会议纪要 - 时间 - 参会人 - 议题 ## 讨论要点 - ## 决策项 - ## 待办事项 - [ ] ## 风险点 -模板的价值在于让 Agent 的输出格式稳定不会这次用 markdown 下次用纯文本。如果技能涉及代码生成同理推荐在模板里定义好代码框架和注释规范。4.3 测试和迭代用真实输入检验技能质量技能写完之后立刻在当前会话测试workbuddy skills enable meeting-notes然后输入一段比较口语化的需求帮我把这段会议内容整理一下看看有什么要跟进的。测试时重点关注触发链路Agent 有没有因为你的描述而加载meeting-notes执行链路Agent 有没有按 SKILL.md 里的步骤走输出链路最终输出的格式是否严格符合模板如果某个环节出了问题不要急着改描述。先把问题定位清楚是没触发、还是触发后步骤跑偏、还是步骤对了但格式不对。每一步对应的修复位置不一样改错地方反而越改越乱。我自己的调试习惯是先拿三段真实度足够高的输入测试看三段输出的稳定性。如果三段输出的格式和内容层面质量都很接近就说明技能基本可用如果三次输出差异很大多半是执行步骤写得不够细。4.4 给技能加上依赖配置如果你的技能要额外调用脚本或者需要指定 Python 环境的依赖就在技能目录下放一个requirements.txtrequests2.31.0 beautifulsoup44.12.0WorkBuddy 目前不会自动帮你安装技能依赖需要你手动执行。我把这个坑写在这里是因为很多人从平台装完技能直接就跑报错ModuleNotFoundError之后才开始排查——其实问题多半是依赖没装。装完技能后第一件事是检查有没有requirements.txt有就手动安装别等报错再处理。5. 发布到 ClawHub / SkillHub上传、审核与更新自己开发的技能只放在本地有点可惜发布到平台能让更多人用到也能沉淀个人作品。这一章讲讲我在 ClawHub 和 SkillHub 上发布技能的完整流程以及平台之间的定位差异。5.1 两个平台怎么选定位决定发布策略从我的使用体验看ClawHub更像是技能应用商店用户群体更广下载量是核心指标适合通用性强、完成度高、文档完善的技能。上传审核相对严格对技能描述格式、脚本安全性都有要求。SkillHub偏开发者社区允许上传实验性技能和针对特定工具链的定制技能更新频率高迭代空间大。适合你在学习和测试阶段的技能也适合带有个人工作流特点的技能。对大多数自建技能我的建议是先在 SkillHub 发布测试版收集反馈和 issue稳定后发布正式版到 ClawHub。不要两个平台都发一样的内容因为用户评价维度不同铺开双发容易分散维护精力。5.2 上传前的检查清单发布前别急着点上传先对照这张清单过一遍检查项要求SKILL.md 格式frontmatter 必须包含name和description字段description 描述需要写出触发场景不要使用推销式语言目录层级SKILL.md必须在技能根目录下一级直接可见脚本安全不能包含下载执行、读取系统敏感目录等操作静态依赖尽量降低外部依赖注明必要的 API Key 或环境变量权限说明如果技能需要读写本地文件需在说明中明确演示效果建议附带一张使用前后对比截图其中description 描述是审核最容易卡的点。平台审核会看这个描述是否能让 Agent 准确触发旁对旁不对的描述会被驳回。我之前被驳回的一次就是因为把 description 写成了 A useful tool for all your tasks这个描述几乎等于没有触发条件平台直接打回让我重写。5.3 实际上传步骤我以 SkillHub 为例说明上传流程准备本地技能包确保技能目录下只有必要文件没有无用缓存和.git目录。打包技能zip -r my-skill.zip my-skill/注意压缩包内第一层应该是技能目录本身。登录 SkillHub在网页端创建新技能填写名称和简介。上传压缩包将my-skill.zip传到平台。填写版本说明v1.0.0下面写清楚这个版本包含的功能和已知限制。提交审核等待结果通常 1-3 个工作日。ClawHub 的上传流程类似但额外要求先通过 CLI 工具做一次本地校验workbuddy skills validate my-skill/这个校验命令会检查格式规范、目录层级、frontmatter 字段完整性。本地通过之后再走网页端提交能省掉不少来回打回的等待时间。5.4 审核被驳回的常见原因和修正方案我见过和经历过的主要驳回原因有这几类SKILL.md 的 description 里带可能、也许这类模糊词——改成确定性的触发描述。技能目录里缺少示例或测试用例——审核希望技能不是一次性产物补上examples/和tests/目录能显著提高过审率。依赖声明不完整——如果你的技能要调用requests库但requirements.txt里没有会被判定为依赖缺失。这个检查尤其严格。脚本里包含网络请求——审核需要你在技能说明中写清楚请求的域名和用途如果不写会被判定为有潜在风险。5.5 发布后如何维护和更新技能发布之后留意一段时间用户的 issue 反馈尤其是环境差异导致的报错。我自己维护技能时有一个固定流程每个季度集中处理一次 issue统一归纳成版本更新。版本号遵循语义化规则修复 bug 升 patch新增功能升 minor不兼容改动升 major。每次更新都在版本说明里标明变化点和影响范围方便用户决定是否升级。这里要给一个特别提醒更新技能时不要在本地原目录里直接改而是复制一份出来改好测试通过后再上传。因为 WorkBuddy 加载技能时直接读原目录如果你在原目录上改了一半Agent 在中途会读取到不完整的文件造成不可预期的行为。6. 实际操作中你大概率会遇到的几个坑这一章写的都是我在实机环境中真正踩过的问题不是从文档里抄出来的注意事项。每个坑我都会给排查思路和解决办法希望你看到的时候能直接避开。6.1 workbuddy 502 write eacces 的权限问题这个报错在 Linux 环境下比较常见尤其是你用非 root 用户安装技能时。报错字面意思是写入权限不足但真正触发场景往往是在技能安装阶段试图向系统级目录写入文件。排查链路先确认报错时的操作是安装技能、加载技能还是运行技能中的脚本。检查技能目录归属ls -la ~/.workbuddy/skills/如果目录归属是 root而你运行 WorkBuddy 的是普通用户执行sudo chown -R $(whoami) ~/.workbuddy/skills/如果用的是系统级安装路径比如/opt/workbuddy建议改成用户级安装避免每次都需要提权。这里有个容易误导人的点这个报错不一定是文件系统权限也可能是npm或pip的全局安装权限问题。如果技能里的脚本依赖npm install -g或pip install --system就会出现类似的 EACCES 报错。解决办法是把依赖安装到用户目录npm config set prefix ~/.npm-global export PATH$HOME/.npm-global/bin:$PATH6.2 技能装了好多但触发率很低这是最多人问我的问题。技能装了一堆但 Agent 好像视而不见。我排查之后发现大多是 description 写得不好原因是你的 description 里写的触发词和用户实际表达的习惯不一致。举个例子你写的是 Latex 排版技能用户实际说的是 帮我改一下参考文献格式——两个文本在语义上相关但字面上没有直接重叠Agent 匹配失败。解决办法是描述里覆盖用户视角的常见表达比如 排版、参考文献格式、公式对齐、LaTex 编译错误修复 这种与具体问题相关的触发词。多写几个用户真实会用的表达而不是一个高高在上的学术化名词。6.3 Skills 和自定义指令的优先级冲突当同一个需求既能被 Skills 触发又命中了自定义指令的内容时WorkBuddy 的默认行为是以自定义指令为基准再叠加技能补充。这个优先级有时候会造成指令覆盖技能的现象——技能里定义的输出规则被自定义指令改写导致技能的实际输出和预期不符。遇到这种情况先检查你的自定义指令里有没有和技能冲突的规则。如果有从自定义指令里删掉对应条目或者把技能的使用说明写进项目目录的指令里做定向约束不要全局默认覆盖。6.4 跨平台迁移技能时的路径坑在 Windows 上写好的技能迁移到 Linux 或 macOS 上跑最常见的坑是路径分隔符和默认 shell 差异。技能里如果写了scripts/xxx.shWindows 上可能没有 bash要改成跨平台的调用方式或者显式声明需要 bash 环境。涉及文件路径的写法不要写死/Users/xxx/这种绝对路径尽量用相对路径让 Agent 基于当前工作目录推导。如果技能脚本里用了 Windows 换行符CRLFLinux 上执行会报\r: command not found迁移后用dos2unix转换一下。这段说出来可能有点低级但真的很多人会中招。我自己的经验是所有自建技能从一开始就用相对路径 可移植脚本Python 优先于 Bash就省掉了绝大多数跨平台问题。6.5 从能跑到稳定迭代时机把握最后一条经验是关于开发节奏的。很多自建技能在能跑通的第二天就被丢进完成任务名单结果换了场景一用就崩。我觉得一个技能真正算稳定至少要经过三个不同场景的实测——不能只拿第一次测试的成功当标准至少要包含一次边界输入比如输入巨长、输入格式混乱、输入包含特殊情况一次正常输入一次接近失效边界的输入。我用一个简单的判断方法如果连续五段不同但相似的输入输出质量都保持稳定就可以发布了如果第二段就崩了调整之后不要急着继续测先把调整逻辑理解清楚再说。7. 写在最后的几条实战补充建议这篇文章的核心内容到这里基本讲完了。最后分享几个我在整个 WorkBuddy 使用过程中沉淀下来的习惯供新参考。第一给技能目录建一个备份机制。~/.workbuddy/skills/这个目录是你花时间积攒出来的资产建议把它纳入一个 Git 仓库管理。我用的方式是建私有仓库每次技能增删或配置修改都提交一次回滚和迁移都非常方便。第二多关注 SkillHub 上的版本更新时间线。同一个技能一个月前和一个月后的版本可能完全不是同一个质量等级。如果觉得某个技能不好用先看一下它最近有没有更新很多问题在最新版已经修复了。第三学会从别人的技能里抄思路。自建技能最快速的上手方式不是从零开始凭空想而是在自己的技能目录里安装三个同场景的技能打开它们的SKILL.md逐行对比。你会发现不同作者的步骤设计、描述写法、模板思路差异很大把这些差异消化掉你对技能应该怎么设计的理解会立刻提升一个层次。这件事比自己从头摸索高效得多。最后补充一句技能生态目前还在快速演进中WorkBuddy 的加载机制和平台规则以后大概率还会调整。但只要理解了触发-加载-执行-输出这条核心链路不管工具怎么升级你都能很快适应。祝都能把自己的 WorkBuddy 调教成真正懂你的助手。
