企业官网建设流程全解析

先说明一句：这篇是给真正想把 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.pdf

SKILL.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 选择原则总结

我把选技能的经验总结成一条标准：描述要窄、依赖要少、输出要稳。

• 描述窄：一个技能只干一类事，不要装"全能型"技能，因为触发准确率通常不高。
• 依赖少：优先选只需要一个脚本或纯指令文本的技能，依赖多个外部服务的技能一旦某个服务挂掉就全面失效。
• 输出稳：看技能是否定义了明确的输出格式。没有输出模板的技能，每次生成结果都像开盲盒。

下表是我当前工作环境下保留的技能清单，供参考：

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 如何验证技能装好了

验证技能是否真正生效，不能只看列表。我建议这样测试：

1. 直接文件检查：确认SKILL.md存在，并且 frontmatter 中的name和description字段完整且非空。
2. 触发测试：新建一个会话，用和技能描述匹配的自然语言描述你的需求，观察 Agent 是否主动加载该技能（WorkBuddy 加载技能后会在运行日志中留下记录，如果你的终端开启了 verbose 模式会直接看到）。
3. 行为测试：向 Agent 提问一个与技能职责相关的具体问题，对比不用该技能时的回答质量和流程规范性。

注意：修改技能文件后，需要在 WorkBuddy 中重新建立会话才能让改动生效。同一个会话内即使修改了SKILL.md，Agent 也不一定会重新读取，因为技能在会话开始时就被加载到上下文里了。

4. 自建一个技能：从零到能用的完整过程

会装技能只是入门，会自建技能才是真正把 WorkBuddy 用成私人助手的门槛。这一章我带大家完整走一遍自建流程，以"会议纪要整理"这个最经典的场景为例——它够简单，不涉及复杂脚本，但能跑通技能开发的完整链路。

4.1 确定场景、限制范围和输出格式

自建技能之前，先回答三个问题：

1. 这个技能帮 Agent 完成了哪些原本不做的事？如果只是把一段提示词塞进技能文件，那没有意义。
2. 技能的边界在哪？比如"会议纪要整理"要明确是只做结构整理，还是也包括后续任务分发。
3. 输出格式是什么？这决定了技能里要不要带模板文件。

我见过很多自建技能失败，根本原因就是场景过宽。比如"帮我写文档"这种描述，Agent 每次都不知道该加载还是不该加载，就算加载了也不知道具体按什么流程执行。反过来，"从会议录音转写文本中提取决策项、待办事项、风险点，生成 markdown 会议纪要"这个描述，Agent 一下子就知道该做什么。

4.2 一步步写出可用的 SKILL.md

目录和文件结构如下：

meeting-notes/ ├── SKILL.md └── templates/ └── notes_template.md

SKILL.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.txt：

requests==2.31.0 beautifulsoup4==4.12.0

WorkBuddy 目前不会自动帮你安装技能依赖，需要你手动执行。我把这个坑写在这里，是因为很多人从平台装完技能直接就跑，报错ModuleNotFoundError之后才开始排查——其实问题多半是依赖没装。装完技能后第一件事是检查有没有requirements.txt，有就手动安装，别等报错再处理。

5. 发布到 ClawHub / SkillHub：上传、审核与更新

自己开发的技能只放在本地有点可惜，发布到平台能让更多人用到，也能沉淀个人作品。这一章讲讲我在 ClawHub 和 SkillHub 上发布技能的完整流程，以及平台之间的定位差异。

5.1 两个平台怎么选：定位决定发布策略

从我的使用体验看：

• ClawHub：更像是"技能应用商店"，用户群体更广，下载量是核心指标，适合通用性强、完成度高、文档完善的技能。上传审核相对严格，对技能描述格式、脚本安全性都有要求。
• SkillHub：偏开发者社区，允许上传实验性技能和针对特定工具链的定制技能，更新频率高，迭代空间大。适合你在学习和测试阶段的技能，也适合带有个人工作流特点的技能。

对大多数自建技能，我的建议是：先在 SkillHub 发布测试版收集反馈和 issue，稳定后发布正式版到 ClawHub。不要两个平台都发一样的内容，因为用户评价维度不同，铺开双发容易分散维护精力。

5.2 上传前的检查清单

发布前别急着点上传，先对照这张清单过一遍：

其中description 描述是审核最容易卡的点。平台审核会看这个描述是否能让 Agent 准确触发，旁对旁不对的描述会被驳回。我之前被驳回的一次就是因为把 description 写成了 "A useful tool for all your tasks"，这个描述几乎等于没有触发条件，平台直接打回让我重写。

5.3 实际上传步骤

我以 SkillHub 为例说明上传流程：

1. 准备本地技能包：确保技能目录下只有必要文件，没有无用缓存和.git目录。
2. 打包技能：zip -r my-skill.zip my-skill/，注意压缩包内第一层应该是技能目录本身。
3. 登录 SkillHub：在网页端创建新技能，填写名称和简介。
4. 上传压缩包：将my-skill.zip传到平台。
5. 填写版本说明：v1.0.0，下面写清楚这个版本包含的功能和已知限制。
6. 提交审核：等待结果，通常 1-3 个工作日。

ClawHub 的上传流程类似，但额外要求先通过 CLI 工具做一次本地校验：

workbuddy skills validate my-skill/

这个校验命令会检查格式规范、目录层级、frontmatter 字段完整性。本地通过之后再走网页端提交，能省掉不少来回打回的等待时间。

5.4 审核被驳回的常见原因和修正方案

我见过和经历过的主要驳回原因有这几类：

1. SKILL.md 的 description 里带"可能"、"也许"这类模糊词——改成确定性的触发描述。
2. 技能目录里缺少示例或测试用例——审核希望技能不是一次性产物，补上examples/和tests/目录，能显著提高过审率。
3. 依赖声明不完整——如果你的技能要调用requests库但requirements.txt里没有，会被判定为"依赖缺失"。这个检查尤其严格。
4. 脚本里包含网络请求——审核需要你在技能说明中写清楚请求的域名和用途，如果不写会被判定为有潜在风险。

5.5 发布后如何维护和更新

技能发布之后，留意一段时间用户的 issue 反馈，尤其是环境差异导致的报错。我自己维护技能时有一个固定流程：

• 每个季度集中处理一次 issue，统一归纳成版本更新。
• 版本号遵循语义化规则：修复 bug 升 patch，新增功能升 minor，不兼容改动升 major。
• 每次更新都在版本说明里标明"变化点"和"影响范围"，方便用户决定是否升级。

这里要给一个特别提醒：更新技能时不要在本地原目录里直接改，而是复制一份出来改好测试通过后再上传。因为 WorkBuddy 加载技能时直接读原目录，如果你在原目录上改了一半，Agent 在中途会读取到不完整的文件，造成不可预期的行为。

6. 实际操作中你大概率会遇到的几个坑

这一章写的都是我在实机环境中真正踩过的问题，不是从文档里抄出来的注意事项。每个坑我都会给排查思路和解决办法，希望你看到的时候能直接避开。

6.1 workbuddy 502 write eacces 的权限问题

这个报错在 Linux 环境下比较常见，尤其是你用非 root 用户安装技能时。报错字面意思是写入权限不足，但真正触发场景往往是在技能安装阶段试图向系统级目录写入文件。

排查链路：

1. 先确认报错时的操作是安装技能、加载技能还是运行技能中的脚本。
2. 检查技能目录归属：ls -la ~/.workbuddy/skills/
3. 如果目录归属是 root，而你运行 WorkBuddy 的是普通用户，执行：

   sudo chown -R $(whoami) ~/.workbuddy/skills/

4. 如果用的是系统级安装路径（比如/opt/workbuddy），建议改成用户级安装，避免每次都需要提权。

这里有个容易误导人的点：这个报错不一定是文件系统权限，也可能是npm或pip的全局安装权限问题。如果技能里的脚本依赖npm install -g或pip install --system，就会出现类似的 EACCES 报错。解决办法是把依赖安装到用户目录：

npm config set prefix ~/.npm-global export PATH="$HOME/.npm-global/bin:$PATH"

6.2 技能装了好多，但触发率很低

这是最多人问我的问题。技能装了一堆，但 Agent 好像视而不见。我排查之后发现大多是 description 写得不好，原因是你的 description 里写的触发词和用户实际表达的习惯不一致。

举个例子，你写的是 "Latex 排版技能"，用户实际说的是 "帮我改一下参考文献格式"——两个文本在语义上相关，但字面上没有直接重叠，Agent 匹配失败。

解决办法是描述里覆盖用户视角的常见表达，比如 "排版、参考文献格式、公式对齐、LaTex 编译错误修复" 这种与具体问题相关的触发词。多写几个用户真实会用的表达，而不是一个高高在上的学术化名词。

6.3 Skills 和自定义指令的优先级冲突

当同一个需求既能被 Skills 触发，又命中了自定义指令的内容时，WorkBuddy 的默认行为是以自定义指令为基准，再叠加技能补充。这个优先级有时候会造成指令覆盖技能的现象——技能里定义的输出规则被自定义指令改写，导致技能的实际输出和预期不符。

遇到这种情况，先检查你的自定义指令里有没有和技能冲突的规则。如果有，从自定义指令里删掉对应条目，或者把技能的使用说明写进项目目录的指令里做定向约束，不要全局默认覆盖。

6.4 跨平台迁移技能时的路径坑

在 Windows 上写好的技能，迁移到 Linux 或 macOS 上跑，最常见的坑是路径分隔符和默认 shell 差异。

• 技能里如果写了scripts/xxx.sh，Windows 上可能没有 bash，要改成跨平台的调用方式或者显式声明需要 bash 环境。
• 涉及文件路径的写法不要写死/Users/xxx/这种绝对路径，尽量用相对路径，让 Agent 基于当前工作目录推导。
• 如果技能脚本里用了 Windows 换行符（CRLF），Linux 上执行会报\r: command not found，迁移后用dos2unix转换一下。

这段说出来可能有点低级，但真的很多人会中招。我自己的经验是，所有自建技能从一开始就用相对路径 + 可移植脚本（Python 优先于 Bash），就省掉了绝大多数跨平台问题。

6.5 从"能跑"到"稳定"：迭代时机把握

最后一条经验是关于开发节奏的。很多自建技能在能跑通的第二天就被丢进"完成任务"名单，结果换了场景一用就崩。我觉得一个技能真正算稳定，至少要经过三个不同场景的实测——不能只拿第一次测试的成功当标准，至少要包含一次边界输入（比如输入巨长、输入格式混乱、输入包含特殊情况），一次正常输入，一次接近失效边界的输入。

我用一个简单的判断方法：如果连续五段不同但相似的输入，输出质量都保持稳定，就可以发布了；如果第二段就崩了，调整之后不要急着继续测，先把调整逻辑理解清楚再说。

7. 写在最后的几条实战补充建议

这篇文章的核心内容到这里基本讲完了。最后分享几个我在整个 WorkBuddy 使用过程中沉淀下来的习惯，供新参考。

第一，给技能目录建一个备份机制。~/.workbuddy/skills/这个目录是你花时间积攒出来的资产，建议把它纳入一个 Git 仓库管理。我用的方式是建私有仓库，每次技能增删或配置修改都提交一次，回滚和迁移都非常方便。

第二，多关注 SkillHub 上的版本更新时间线。同一个技能，一个月前和一个月后的版本可能完全不是同一个质量等级。如果觉得某个技能不好用，先看一下它最近有没有更新，很多问题在最新版已经修复了。

第三，学会从别人的技能里抄思路。自建技能最快速的上手方式，不是从零开始凭空想，而是在自己的技能目录里安装三个同场景的技能，打开它们的SKILL.md逐行对比。你会发现不同作者的步骤设计、描述写法、模板思路差异很大，把这些差异消化掉，你对"技能应该怎么设计"的理解会立刻提升一个层次。这件事比自己从头摸索高效得多。

最后补充一句：技能生态目前还在快速演进中，WorkBuddy 的加载机制和平台规则以后大概率还会调整。但只要理解了"触发-加载-执行-输出"这条核心链路，不管工具怎么升级，你都能很快适应。祝都能把自己的 WorkBuddy 调教成真正懂你的助手。