3.4 Skill System¶
本节摘要
从State Management角度看，OpenClaw Skill 系统回答的核心问题是：Skill 元数据何时注入、提供哪些、怎么控制预算？ 本节按「是什么 → 从哪来 → LLM 看到什么 → 何时激活 → 怎么执行」展开。
一、Skill 是什么¶
每个 Skill 是一个 SKILL.md 文件（Markdown + YAML frontmatter），格式与 Claude Code 的 AgentSkills 兼容：
| 信息 | LLM 可见？ | 说明 |
|---|---|---|
name + description |
✅ 注入 prompt | LLM 据此判断是否需要该 Skill |
fullPath |
✅ 注入 prompt | LLM 通过 Read 工具加载全文 |
| 正文内容 | ❌ 按需加载 | LLM Read 后才可见 |
invocation / exposure / command-dispatch |
❌ 框架内部 | 控制触发方式和暴露级别 |
延迟加载：LLM 只看到「菜单」（name + description + path），需要时才 Read 全文。
二、Skill 从哪来¶
5 个来源，高优先级同名覆盖低优先级：
| 优先级 | 来源 | 谁来写 |
|---|---|---|
| 1（最高） | workspace 根目录 skills/ |
团队共享 |
| 2 | agents-skills .agents/skills/ |
Agent 专用 |
| 3 | managed 插件管理 | 插件自动 |
| 4 | extra 配置 + 插件声明 | 管理员配置 |
| 5（最低） | bundled 内置 | 安装包自带 |
此外 ClawHub（clawhub.ai）提供远程 Skill 注册中心（类似 npm），但运行时列表仍来自本地扫描——ClawHub 只是分发/安装渠道，不参与运行时。
三、LLM 看到什么：Prompt 注入与预算¶
注入格式¶
所有入选 Skill 以 <available_skills> XML 注入系统提示的 Skills 段：
<available_skills description="Skills the agent can use.
Use the Read tool with the provided absolute path to fetch full contents.">
<agent_skill fullPath="/workspace/skills/github/SKILL.md">
GitHub operations: create PR, review code, manage issues.
</agent_skill>
</available_skills>
预算控制¶
| 参数 | 默认值 | 说明 |
|---|---|---|
maxSkillsInPrompt |
50 | 最大 Skill 数量 |
maxSkillsPromptChars |
8,000 | 最大字符数 |
formatSkillsCompact |
自动 | 超预算时每个 Skill 压缩为一行 |
与 Claude Code 的预算对比
Claude Code 用窗口的 1% 做预算（自适应不同窗口大小）；OpenClaw 用绝对数量 + 字符数（管理员明确知道展示多少）。
三层过滤¶
| 层级 | 机制 |
|---|---|
| 1 | 配置白名单：agents.list[].skills（非空时替换默认列表） |
| 2 | 资格检查：shouldIncludeSkill 判断 exposure / invocation |
| 3 | LLM 自选择：通过 Read 主动加载 |
四、Skill 何时激活¶
| 方式 | 说明 |
|---|---|
| LLM 主动选择 | 根据 prompt 中的列表判断，通过 Read 加载 |
| 用户手动 | /skill-name 命令 |
与 Claude Code 的差异
OpenClaw 没有路径触发（Claude Code 的 paths glob 自动激活）和向上遍历动态发现。Skill 在启动时加载，通过 cron 刷新快照。
五、Skill-Tool 桥接¶
当 frontmatter 声明 command-dispatch: tool 时，Skill 被桥接为可调用工具——LLM 可以像调用工具一样触发 Skill，无需先 Read 全文。这模糊了 Skill 和 Tool 的边界。
OpenClaw 的 Skill 只有 inline 执行（无 Claude Code 的 Fork 隔离模式），因此 Skill 的所有输出都留在主对话 Context中。
关键文件索引¶
| 文件 | 职责 |
|---|---|
src/agents/skills/loader.ts |
loadSkillEntries 多目录扫描 |
src/agents/skills/types.ts |
SkillEntry 类型 |
src/agents/skills/clawhub.ts |
ClawHub 远程注册表 |