Skills 与 Tools 详解：把你的工作习惯写进 Agent 的说明书

一、为什么你还需要写自己的 Skill

装完 OpenClaw，你会看到 51 个 ready 的内置技能——canvas、github、healthcheck、summarize……这就够用了吗？不够。内置技能解决的是“通用能力”，而你团队里那些真正让效率翻倍的动作，往往写在文档没人看、贴在墙上没人记、口口相传没人稳定执行：每天日报要发到哪个群、周报的固定表头是什么、每次上线前该跑哪几条检查命令。

一位在电商公司做运维的朋友讲过一件真事：他花了半年时间总结了一份“上线前 12 项检查”清单，写在飞书文档里，团队里没一个人认真跑完过——不是不重视，是“打开文档 → 逐条查 → 手工回复群”这个动作太繁琐。后来他把这 12 项写进 OpenClaw 的一个 pre-release-check Skill，改动只有三处：所有检查项脚本化、结果统一 emoji 标注、失败自动 @ 值班同学。上线之后一个季度，团队的“发上线前忘检查某项”事故清零。他说这个 Skill 没写多少代码，“就是把我原来的文档，翻译成了 Agent 能读懂的说明书”。

Skill 就是把这些“部落知识”固化下来的载体。它不是插件、不是工具、也不是提示词——它是 OpenClaw 官方对“给 Agent 一份可复用的操作说明”这件事的答案。写好一次，这个 Agent 每天都记得。

如果把 Agent 类比成一名新入职的员工，Tools 是他手上的键盘和鼠标，Plugins 是他连上公司的 VPN 和内网权限，而 Skills 就是贴在他电脑边的那本“操作手册”。手册写得清楚，员工就能自己按流程做事；手册写得模糊，员工就要天天来问你。这个类比在写 Skill 的过程中会被反复验证——你会发现，让 Agent 表现稳定的秘诀，不是换更强的模型，而是把操作手册写得再清楚一点。

和 Skill 定位最接近的邻居，是 Cursor 的 AGENTS.md（原 .cursor/rules）、Continue.dev 的 .continue/rules、Cline 的自定义指令，思路殊途同归——都是把 prompt 化的工作流写进仓库。OpenClaw 的做法多走了一步：它有中央注册中心（ClawHub），有治理化的提案队列（Skill Workshop），也有开放规范（agentskills.io）。这几层加起来，让 Skill 不只是“我自己用”的私有秘诀，也可以是“整个团队用”的公共资产。

二、Tools、Skills、Plugins：三层结构别搞混

新手最容易在术语上打转。OpenClaw 官方把可扩展面拆成三层，逻辑很清爽：

一句话记住：Tools 是动作，Skills 是说明书，Plugins 是扩展包。本期只讲 Skills，Plugins 与 MCP 我们留到 E08 再深入。三层的分野一旦捋清，你写 Skill 时就不会再纠结“这段功能是不是该做成 tool”、“那段代码是不是该拆成 plugin”——大部分时候，你只需要一份 SKILL.md 加一两个 exec 脚本，就足以让 Agent 稳定完成一件真事。

再往深一步说：Tools 是 Agent 能“做”的事，Skills 是 Agent 该“懂”的事，Plugins 是 Agent 能“接触”的事。这三层加起来，恰好对应人做事的三个环节：具备能力、掌握流程、接入环境。OpenClaw 把它们拆开，好处是每一层都可以独立打磨、独立治理、独立分发。Skills 变了，不用重启；Tools 变了，通常也不用重装 Plugin；Plugin 变了，才要 openclaw restart 一次。这种分层，是“能长期演进”的架构基本功。

三、一个 Skill = 一个文件夹的三件套

Skill 的物理形态朴素得让人意外：一个目录 + 一份 SKILL.md。稍微完整一点，加上脚本与文档，就是标准三件套：

三件套的分工是有讲究的。SKILL.md 放元数据和短提示，加载即进 prompt；scripts/ 放确定性动作，Agent 直接 exec 就行；references/ 放长文档，只有 Agent 明确需要时才加载。这样安排的收益是——你的 SKILL.md 可以保持短、快、准，而不必把所有细节塞进 Agent 的上下文窗口里。

这里面藏着一个很务实的工程判断：确定性脚本永远优于一大段 prompt。凡是能写成脚本的动作——追加文件、格式化数据、字段校验、幂等去重——都塞进 scripts/。Agent 直接 exec 就行，比让它自己临场写 20 行代码可靠得多。这一条经验，AISTOC 内部实测反复印证：能脚本化的动作，永远脚本化。

四、触发词的秘密：description 决定 Skill 是否被用

写 Skill 最常见的踩坑不是“技能坏了”，而是——技能明明在，Agent 就是不用它。九成情况下，是 description 写歪了。

OpenClaw 加载 Skill 时，只把 frontmatter 里的 name 与 description 塞进 Agent 的检索层，正文只有触发后才进上下文。也就是说：description 是给模型看的判据，正文是给人看的说明书。两者位置颠倒是新手最贵的错误。

好触发词的结构公式：动词 + 具体对象 + 关键约束，160 字节内。

判断 description 是否合格，还有个更朴素的办法：读它两秒，你能不能一眼说出“这个技能什么时候会被用”？说不出，就是模糊。

如果 Agent 太“积极”，把无关的闲聊也塞进日志，就在 SKILL.md 的 ## Safety 段加否定约束：“Only use for short factual updates the user explicitly asks to persist. Do NOT auto-log casual chat.” 一句负向指令，胜过十句正向说明。这里也印证了 E02 提到的 Copilot 官方经验：负向约束往往比正向约束更有效。

五、让 skill-creator 起草，跑一次官方校验

写 Skill 最简单的姿势，是让 OpenClaw 自己写。dashboard 里对它说：

Agent 会调用内置 skill-creator 技能起草整套目录。生成完，跑一次官方 quick_validate.py：

一句 Skill is valid! 就意味着 frontmatter 合规、脚本能定位、目录结构过关。这一步在真实工程里很重要——它是 Skill 上到 ClawHub 前的第一道闸门。

六、装进 OpenClaw：用户级 vs 工作区级

OpenClaw 的 Skill 加载有一套六级优先级：workspace skills/ → 项目 agent .agents/skills → 个人 ~/.agents/skills → 用户级 ~/.openclaw/skills → 内置 → 插件。同名会被更高优先级覆盖。对个人开发者，只需记两条：

如果要让全公司都用，把它推到 ClawHub——OpenClaw 的官方 Skills 注册中心。发布走独立的 clawhub CLI，命名沿用 npm 风格 scope（@owner/slug）。别人一句 openclaw skills install @you/daily-note 就能装上，这是“部落知识”变成社区资产的起点。

讲讲实操里的一个关键细节：Agent Allowlist 与 Skill 位置是解耦的。你在 agents.defaults.skills 里写的是共享基线，个别 agent 若在 agents.list[].skills 里非空声明了自己的清单，就会完全替换默认，而不是合并。这意味着如果你想给某个 agent 加一个 skill，要在它自己的清单里连着基线一起写，别期待自动叠加。这个“替换而非合并”的默认行为，是官方为了避免“隐式提权”设的规则——多花两行配置换来的是可预测性。

七、Skill Workshop：Agent 提案，人类拍板

上一节讲的是“你写 Skill”。如果让 Agent 自己发明 Skill呢？OpenClaw 的答案是 Skill Workshop——治理化的提案队列。Agent 不能直接落盘活动 skill，只能先创建一份 PROPOSAL.md，进 pending 队列，等你 apply。

生命周期一图流：create → pending → apply / reject / quarantine。目标变更还会自动降为 stale。这套流程对个人开发者可能显得繁琐，但对企业与团队，是必要的合规底座——你不希望某天 Agent 悄悄给自己加了一个“帮我 rm 全部临时文件”的技能。信任必须是可审计的。

Skill Workshop 的容量参数也顺手记住：单个 proposal 支持文件最多 64 个、单文件不超过 256KB、总体积上限 2MB；proposal body 上限 40,000 字节；pending 队列默认 50 条。这些数字听起来抽象，落到真实场景里就是一句话——Skill 不是给你堆产品文档的地方，它是给你写“操作指引”的地方。写得越紧凑，越好用。业内做 AI 助手的团队普遍反映，写得像论文的 Skill 命中率明显低于写得像便签的 Skill。这条经验，做几个自定义技能就会自己踩明白。

八、安全铁律：第三方 Skill 是 untrusted code

最后一段留给安全。OpenClaw 官方文档里有一句被反复强调的话：

落到日常，就三条铁律：装前读；跑在 sandbox；密钥不进 prompt。据 OpenClaw 官方公告，ClawHub 上传的 Skill 会跑 VirusTotal 与 ClawScan 静态扫描，但这只是外层的过筛，最后一道防线永远是你自己看一眼 SKILL.md 和 scripts。

还有两条常被忽略的安全默认值值得点名：其一，Skill 里通过 entries.<name>.apiKey 注入的秘钥只进 host 进程当次 turn，不会进 sandbox——官方原话是 “Keep secrets out of prompts and logs”；其二，Skill Workshop 里的支持文件仅允许放在五个白名单目录（assets/、examples/、references/、scripts/、templates/），路径穿越、绝对路径、可执行文件都会被拒。这些默认值背后的思路是一致的：信任要显式，越界要拒绝，出错要 fail-closed。这也是 OpenClaw 敢把 Skill 生态摊开给社区的底气。

九、你现在可以做的三件事

读到这里，最好的验证方式不是继续读，而是动手做一个。Skill 这件事很奇特——你写十个不如做一个跑通的。下面三件事，每一件都能在一小时内完成，一起做完你就是从“用 Skill 的人”变成“写 Skill 的人”。

写 Skill 是一件门槛低、天花板高的活。门槛低是因为一份 SKILL.md 就能起步；天花板高是因为你写得越多，你的 Agent 就越像“你自己训练出来的那位”。三个月后回头看，最有价值的往往不是你写的代码，而是你为自己写的这十几个 Skill。

十、下期预告

写好几个自己的 Skill，你会渐渐生出一种奇怪的满足感——不是因为完成了功能，而是因为把自己的工作习惯沉淀成了别人也能读得懂的文件。这一点，是 OpenClaw 相对纯代码补全工具最容易被低估的价值。E03 让你学会“教 Agent 干活”，E04 我们把画面拉阔——让好几个 Agent 一起干活。子会话怎么派单、结果怎么汇总、模型如何差异化分配，多 Agent 协作是 OpenClaw 相对同类产品最独特的一块能力。下期见。

—— AISTOC产品团队