LLM Wiki

OpenClaw-Skills

8分钟阅读

OpenClaw-Skills

一句话定义

OpenClaw-Skills 是 OpenClaw 的”知识/指令包”扩展系统：一个 Skill = 一份 SKILL.md 文件，告诉 Agent 如何做某类事情——它不是可执行代码，而是一份结构化的操作指南。Skill 的菜单（name + description + location）按需注入 system prompt，SKILL.md 全文不预读，Agent 自主决定何时打开哪一份。

摘要

Skills 是 OpenClaw “知识扩展”维度的核心机制。它解决的问题是：同一个 Agent 面对”帮我创建 GitHub PR”和”帮我查今天的天气”需要截然不同的操作知识，如何在不修改核心代码、也不爆掉上下文窗口的前提下灵活注入？

OpenClaw 的答案是 6 源加载 + 优先级覆盖 + 多层过滤 + 菜单注入 + 自主选择，加上”never read more than one skill up front”的关键约束，让 50+ 内置 Skill 协同工作而不爆 token。

详情

Skill 的本质

  • 一份带 frontmatter 的 Markdown 文件，文件名固定为 SKILL.md
  • 描述”如何做某类事情”——例如怎么创建 PR、怎么发邮件、怎么操作浏览器
  • 不是代码，是给 LLM 看的操作指南
  • OpenClaw 项目内置 50+ 个 Skill，覆盖开发工具、知识管理、通信平台等

6 源加载（按优先级，高覆盖低）

由 src/agents/skills/workspace.ts 的 loadSkillEntries() 合并：

  1. project-level skills（最高优先级）—— 项目目录内的 Skill 覆盖同名内置
  2. plugin skills —— 已启用插件提供的 Skill（每个插件通过 openclaw.plugin.json 的 skills 字段声明）
  3. user-level skills —— ~/.openclaw/skills/ 用户级目录
  4. bundled skills —— OpenClaw 内置 Skill 库（约 50+）
  5. external skills —— 通过环境变量等额外路径注入
  6. fallback skills（最低优先级）

内置 Skill 目录解析顺序

src/agents/skills/bundled-dir.ts 按顺序查找：

  1. 环境变量 OPENCLAW_BUNDLED_SKILLS_DIR（最高）
  2. 可执行文件同级的 skills/ 目录（适用 bun --compile）
  3. 从包根向上查找含 SKILL.md 的 skills 目录

多层过滤

shouldIncludeSkill() 的过滤链：

  1. 配置禁用：skillConfig.enabled === false → 排除
  2. 内置白名单：bundled Skill 必须在 allowBundled 列表中
  3. 运行时资格：检查 OS 兼容、必要二进制工具、必要环境变量

数量限制（防膨胀）

SkillsLimitsConfig = {
  maxCandidatesPerRoot?: number;       // 每个来源目录的最大候选数
  maxSkillsLoadedPerSource?: number;   // 每个来源的最大加载数
  maxSkillsInPrompt?: number;          // Prompt 中的最大 Skill 数
  maxSkillsPromptChars?: number;       // Prompt 中 Skill 段的最大字符数
  maxSkillFileBytes?: number;          // 单个 SKILL.md 最大字节数
}

菜单注入（关键设计）

由 src/agents/system-prompt.ts 的 buildSkillsSection() 完成。注入到 system prompt 的 Skills 段只包含每个 Skill 的：

  • name
  • description
  • location

不包含 SKILL.md 的完整内容。Agent 看到的是一份”我有什么 Skill 可选”的菜单，而非全文。这是一个克制但有效的优化——常见反模式是把所有 SKILL.md 全文塞进 prompt，会迅速吃掉上下文窗口。

自主选择 + 关键约束

Skill 的选择由 LLM 自主完成，是”正常的多轮对话”——不是规则匹配。

never read more than one skill up front —— 关键约束：每次最多选择一个 Skill，避免不必要的 token 消耗。

需要细读时再 read SKILL.md，类似”图书馆的目录卡片 vs 书本本身”。

SkillSnapshot 缓存

SkillSnapshot = {
  prompt: string;                    // 已生成的 Skill 菜单 Prompt
  skills: Array<{
    name: string;
    primaryEnv?: string;
    requiredEnv?: string[];
  }>;
  skillFilter?: string[];            // Agent 级过滤
  resolvedSkills?: Skill[];
  version?: number;
};

子 Agent 启动时复用父 Agent 的 SkillSnapshot，避免重复加载。

与 Subagent 的互补

  • Skills = 知识扩展（给 Agent 一本操作手册）
  • Subagent = 并行扩展（派出多个 Agent 分头干活）

二者不是替代关系而是互补——Agent 可以读取 Skill 获得知识后，再创建多个子 Agent 并行执行。

面向 Skills 编程

淘宝企业购实践把 Skill 从”工具使用说明”推进到”研发流水线的能力单元”：SKILL.md 写工作流，references 放领域知识和代码模板，scripts 承担确定性抽取和校验。客户定制对接中的不变量（文档评估、方案设计、代码生成顺序、SPU/SKU 约束、推拉模式判断）被沉淀为 Skill，变化的客户文档作为输入。

这类实践说明，Skill 的质量瓶颈不在模型，而在知识工程：高精度环节要脚本化，长上下文要拆成子 Skill，反复犯错要进入约束和回归验证。Skill 也不是免费的，加载前只有 description 成本很低，但 SKILL.md 一旦进入对话历史，就会成为长期上下文负担。

CLI 实操

openclaw skill install <name>   # 安装
openclaw skill list             # 列出
openclaw skill update           # 更新（建议离线）
openclaw skill sync             # 同步并备份

与其他实体的关系

  • OpenClaw —— 父系统；Skills 是 OpenClaw 16 大模块之一（章节 3.10）
  • OpenClaw-SandBox —— 平行子系统；SandBox 的工具策略可以禁用某些 Skill 触发的工具
  • OpenClaw-双源记忆系统 —— 平行子系统；都用”文件即真相”的设计哲学（一个用 SKILL.md，一个用 MEMORY.md）
  • Harness-Engineering —— Skill 是 Harness 的能力封装层，也是把不确定模型纳入确定流程的载体
  • Spec-Driven-Development —— 领域 Skill 常以结构化 Spec/方案为前置输入
  • Token成本控制 —— Skill 未加载时成本低，加载后需要靠缓存命中降低后续边际成本

参考来源

相关综合

关系图谱

反向链接