SKILLS 和 渐进式披露 是 A 家最早提出来的方案，也是 OpenClaw 火了后大家一直讨论的哪个技能好用很核心的强依赖的实现逻辑。

如果把 Claude Code 的 skills 理解成一堆 prompt 文件，后面的很多设计都解释不通。

从其源码实现来看，会发现它在解决的核心问题是：怎么让模型保留足够强的技能召回能力，同时又不把常驻上下文撑爆。

这件事说穿了就是五个字：渐进式披露。

大概的逻辑是：

• 先告诉模型「系统里存在 skills 机制」。
• 再告诉它「当前有哪些 skill 名称和简短说明」。
• 等它真的决定调用某个 skill 时，再把正文、权限、hooks、模型覆盖、附加工具权限这些重内容展开。
• 如果某些 skill 还和路径、目录、文件类型绑定，那就继续往后拖，拖到模型真的碰到对应文件时再激活。

这是一个优雅且干净的工程化设计。它没有发明一套复杂到难以维护的 skill runtime，也没有把所谓智能寄托在黑盒检索器上，而是先把「披露成本」这件事控制住。

我们按工程实现往下拆：

• skill 在系统里到底被建模成什么
• 多来源 skill 是怎么统一装配的
• 渐进式披露具体分了哪几层
• 条件激活和动态发现是怎么接进文件操作链路的
• inline 和 fork 两条执行路径分别解决什么问题
• 这套设计真正适合什么场景，代价又是什么
• 如果要在自己的 Agent 里复刻，最短落地路径应该怎么走

一、先看 skills 在系统里被建模成什么

Claude Code 里，skill 最终会被统一建模成 Command，而且类型是 prompt。

最核心的构造函数是 createSkillCommand：

return {
type: 'prompt',
  name: skillName,
  description,
  hasUserSpecifiedDescription,
  allowedTools,
  argumentHint,
  argNames: argumentNames.length > 0 ? argumentNames : undefined,
  whenToUse,
  version,
  model,
  disableModelInvocation,
  userInvocable,
  context: executionContext,
  agent,
  effort,
  paths,
  contentLength: markdownContent.length,
  isHidden: !userInvocable,
  progressMessage: 'running',
  userFacingName(): string {
    return displayName || skillName
  },
  source,
  loadedFrom,
  hooks,
  skillRoot: baseDir,
async getPromptForCommand(args, toolUseContext) {
    ...
    return [{ type: 'text', text: finalContent }]
  },
}

这段代码说明有几个关键点：

• skill 不是特殊 runtime object，而是 prompt command
• skill 本体是 getPromptForCommand() 生成的一组文本 block
• skill 可以带：
  • allowedTools
  • model
  • effort
  • paths
  • hooks
  • context: inline | fork
• skill 的调用结果，不是「执行一段脚本」，而是把 skill 展开成后续对话消息，或者 fork 成子代理执行

如果我们自己做 Agent，建议参考。skill 不要单独发明一套 DSL runtime，直接把它抽象成「可延迟展开的 prompt 命令」就够了。

二、skills 的来源有哪几类

skills 并不只来自一个目录。getSkills() 会把多个来源统一聚合。[commands.ts] commands.ts#L353-L398

const [skillDirCommands, pluginSkills] = await Promise.all([
  getSkillDirCommands(cwd)...
  getPluginSkills()...
])
const bundledSkills = getBundledSkills()
const builtinPluginSkills = getBuiltinPluginSkillCommands()

然后 loadAllCommands() 再把这些东西和 workflow/plugin/内建命令一起合并。[commands.ts] commands.ts#L445-L469

也就是说，skills 的来源至少有：

• bundled skills
• 磁盘上的 /skills/
• plugin skills
• builtin plugin skills
• 兼容旧 /commands/ 目录加载进来的 prompt commands

SkillTool 根本不需要知道 skill 来自哪里。只要最后是 prompt command，就能走统一调用路径。

三、skills 的「渐进式披露」分 5 层

1）第一层：系统提示只声明「技能机制存在」

系统提示里不会把所有 skill 正文直接塞进去。它只给一个能力声明，告诉模型：

• 用户说 /<skill-name>，其实是在指 skill
• 可以用 SkillTool 去执行
• 不要乱猜，只能调用列出来的那些

这段在 [prompts.ts] prompts.ts#L353-L401：

hasSkills
  ? `/<skill-name> (e.g., /commit) is shorthand for users to invoke a user-invocable skill. When executed, the skill gets expanded to a full prompt. Use the ${SKILL_TOOL_NAME} tool to execute them. IMPORTANT: Only use ${SKILL_TOOL_NAME} for skills listed in its user-invocable skills section - do not guess or use built-in CLI commands.`
  : null

这一步只暴露了机制，没有暴露内容。

2）第二层：只披露 skill 名称和短描述

真正给模型看的 skill 列表，是通过 getSkillToolCommands() 过滤出来的。[commands.ts] commands.ts#L561-L580

return allCommands.filter(
  cmd =>
    cmd.type === 'prompt' &&
    !cmd.disableModelInvocation &&
    cmd.source !== 'builtin' &&
    (
      cmd.loadedFrom === 'bundled' ||
      cmd.loadedFrom === 'skills' ||
      cmd.loadedFrom === 'commands_DEPRECATED' ||
      cmd.hasUserSpecifiedDescription ||
      cmd.whenToUse
    ),
)

这段有两个要点：

• 只有 prompt 命令才能进 skill 列表
• 并不是所有 prompt command 都自动暴露，至少得满足可描述性要求

也就是说，可执行集合和对模型披露集合不是完全相同的。
Claude Code 在这里收了一刀，避免模型看到一堆没有描述、无法判断用途的技能。

3）第三层：列表本身还要走预算裁剪

skill 列表不是全量原文塞进 prompt，而是按预算压缩过的。核心逻辑在 [prompt.ts] tools/SkillTool/prompt.ts#L20-L171。

最关键的常量：

export const SKILL_BUDGET_CONTEXT_PERCENT = 0.01
export const DEFAULT_CHAR_BUDGET = 8_000
export const MAX_LISTING_DESC_CHARS = 250

以及格式化逻辑：

return `- ${cmd.name}: ${getCommandDescription(cmd)}`

和预算裁剪：

if (fullTotal <= budget) {
  return fullEntries.map(e => e.full).join('\n')
}

如果超预算，就会：

• bundled skills 尽量保留完整描述
• 其它 skills 截断 description
• 极端情况下退化成只发 - skill-name

这就是很典型的渐进式披露：先给最小可用索引，不给正文。

4）第四层：列表还是增量下发，不是每轮全量重发

技能列表通过 skill_listing attachment 发给模型。发送逻辑在 [attachments.ts] utils/attachments.ts#L2669-L2752。

核心逻辑：

const newSkills = allCommands.filter(cmd => !sent.has(cmd.name))
...
for (const cmd of newSkills) {
  sent.add(cmd.name)
}
...
return [
  {
    type: 'skill_listing',
    content,
    skillCount: newSkills.length,
    isInitial,
  },
]

这个 sentSkillNames 机制说明：

• 第一次发的是初始批次
• 后面只发新增的 skill
• resume 之后还会 suppress，避免重复污染上下文

然后 messages.ts 会把它包成系统提醒。[messages.ts] utils/messages.ts#L3763-L3772

return wrapMessagesInSystemReminder([
  createUserMessage({
    content: `The following skills are available for use with the Skill tool:\n\n${attachment.content}`,
    isMeta: true,
  }),
])

很多 Agent 会每轮把所有 tools / skills 全量重发，Claude Code 显然在认真控 token。 当然，如果技能不多，也可以直接全量发，不要过早优化。

5）第五层：真正的 skill 内容延迟到调用时才展开

直到调用 SkillTool，skill 的真实正文才会通过 command.getPromptForCommand() 生成。[SkillTool.ts] utils/processUserInput/processSlashCommand.tsx#L869-L920

这里才会发生：

• $ARGUMENTS 替换
• ${CLAUDE_SKILL_DIR} 替换
• ${CLAUDE_SESSION_ID} 替换
• markdown 内嵌 shell 执行
• hooks 注册
• 附加权限 attachment 注入
• invoked skill 记录

换句话说，skill 的重内容、重权限、重上下文副作用，都是按需加载。

四、除了延迟加载，它还做了「条件激活」

这也是渐进式披露的重要一层，而且很多人会漏掉。

1）带 paths frontmatter 的 skill，不会启动即暴露

getSkillDirCommands() 里会把 skill 分成两类：[loadSkillsDir.ts] loadSkillsDir.ts#L771-L803

if (
  skill.type === 'prompt' &&
  skill.paths &&
  skill.paths.length > 0 &&
  !activatedConditionalSkillNames.has(skill.name)
) {
  newConditionalSkills.push(skill)
} else {
  unconditionalSkills.push(skill)
}

然后 conditional skills 被先放进 conditionalSkills map，而不是直接进入模型可见集合。

这意味着：

• 你定义了某个 skill 只适用于 *.tsx
• 它不会在项目启动时就干扰所有任务
• 只有模型真的碰到匹配文件时，这个 skill 才会被激活

2）激活时机挂在文件操作上

FileRead / FileWrite / FileEdit 三个工具里，都有两步副作用：

• 发现上层目录里的 .claude/skills
• 激活匹配当前文件路径的 conditional skills

比如 FileReadTool：[FileReadTool.ts] /tools/FileReadTool/FileReadTool.ts#L575-L591

const newSkillDirs = await discoverSkillDirsForPaths([fullFilePath], cwd)
...
addSkillDirectories(newSkillDirs).catch(() => {})
...
activateConditionalSkillsForPaths([fullFilePath], cwd)

对应的激活实现是 [activateConditionalSkillsForPaths] skills/loadSkillsDir.ts#L997-L1058：

const skillIgnore = ignore().add(skill.paths)
...
if (skillIgnore.ignores(relativePath)) {
  dynamicSkills.set(name, skill)
  conditionalSkills.delete(name)
  activatedConditionalSkillNames.add(name)
}

这一步非常像条件规则系统，而不是纯静态注册。
效果就是：技能集合会随着你读写哪些文件而变化。

五、动态发现本身也是渐进式披露的一部分

除了 path-conditional activation，Claude Code 还支持目录级动态发现。

1）启动时只加载一部分 skill 目录

getSkillDirCommands() 启动时会加载：

• managed
• user
• project dirs
• additional dirs
• legacy commands

但它不会把所有嵌套目录里的 .claude/skills 一次性全扫出来。[loadSkillsDir.ts] skills/loadSkillsDir.ts#L638-L804

2）当模型碰到某个文件时，再向上走目录树找嵌套 skill

discoverSkillDirsForPaths() 会从当前文件的父目录开始，一路往上走到 cwd，查找 .claude/skills。[loadSkillsDir.ts] skills/loadSkillsDir.ts#L861-L915

while (currentDir.startsWith(resolvedCwd + pathSep)) {
  const skillDir = join(currentDir, '.claude', 'skills')
  ...
  await fs.stat(skillDir)
  ...
  newDirs.push(skillDir)
}

而且还做了两个非常实用的约束：

• 已检查过的目录不会重复 stat
• gitignored 目录里的 skills 不会静默加载

这个设计让：
技能跟着你进入子目录而出现，不跟整个仓库一起一次性曝光。

六、SkillTool 的调用链，实际上分 inline 和 fork 两条路

这是技能系统和普通 slash command 最大的不同之一。

1）调用前校验

SkillTool.validateInput() 会做：

• 去掉前导 /
• 检查 skill 是否存在
• 检查是否 disableModelInvocation
• 检查是否为 prompt 类型
  见 [SkillTool.ts] tools/SkillTool/SkillTool.ts#L355-L430

关键逻辑：

const commands = await getAllCommands(context)
const foundCommand = findCommand(normalizedCommandName, commands)
...
if (foundCommand.type !== 'prompt') {
  return {
    result: false,
    message: `Skill ${normalizedCommandName} is not a prompt-based skill`,
  }
}

2）权限检查

SkillTool.checkPermissions() 很细，除了 allow / deny 规则，还会对「只有安全属性的 skill」自动放行。[SkillTool.ts] /tools/SkillTool/SkillTool.ts#L433-L579

这个设计的意义是：

• 简单 declarative skill 不必每次都弹权限
• 带额外风险属性的 skill 要 ask user

3）inline skill：展开成后续对话消息

默认分支会走 processPromptSlashCommand()。[SkillTool.ts] tools/SkillTool/SkillTool.ts#L635-L644

getMessagesForPromptSlashCommand() 干的事情很丰富：[processSlashCommand.tsx] utils/processUserInput/processSlashCommand.tsx#L827-L920

• command.getPromptForCommand(args, context) 得到真正 skill 正文
• 注册 hooks
• addInvokedSkill() 记录 skill 内容，供 compact 时恢复
• 从 skill 文本里再抽 attachment
• 增加 command_permissions attachment
• 生成一批 messages

返回结构里最关键的是：

return {
  messages,
  shouldQuery: true,
  allowedTools: additionalAllowedTools,
  model: command.model,
  effort: command.effort,
  command
}

也就是说，inline skill 的本质是：
把 skill 变成一段新的上下文和权限修饰，然后让主对话继续跑。

4）fork skill：交给子代理跑，再把结果归还

如果 skill frontmatter 里声明 context === 'fork'，就走 executeForkedSkill()。[SkillTool.ts] tools/SkillTool/SkillTool.ts#L622-L633

它会：

• 构造子代理上下文
• runAgent()
• 收集 agent messages
• 抽取结果文本
• 最终返回 { status: 'forked', agentId, result }
  见 [executeForkedSkill] /tools/SkillTool/SkillTool.ts#L122-L290

这一步说明 Claude Code 已经把 skill 分成两类：

• 知识/流程模板型 skill：inline 展开
• 工作委派型 skill：fork 子代理执行

这个值得学一下。不是所有 skill 都应该展开在主上下文里。

七、结果返回逻辑

为什么它也算渐进式披露的一部分？

1）inline skill 的 tool_result

很轻

mapToolResultToToolResultBlockParam() 对 inline skill 的返回只是：

content: `Launching skill: ${result.commandName}`

见 [SkillTool.ts] tools/SkillTool/SkillTool.ts#L857-L862

也就是说，tool_result 本身不承载 skill 的全部结果。
真正有价值的内容在 newMessages 里，已经被送回主会话继续推理。

2）fork skill 的 tool_result

直接带最终结果

fork skill 返回的是：

content: `Skill "${result.commandName}" completed (forked execution).\n\nResult:\n${result.result}`

见 [SkillTool.ts] tools/SkillTool/SkillTool.ts#L848-L855

这是因为 fork skill 已经在独立上下文里把工作做完了，主线程要拿的是总结结果。

所以在 Claude Code 里，skill 结果返回不是单一模式，而是：

• inline：返回「已加载 skill」，真正内容进主对话
• fork：返回「子代理执行结果」

这也是一种披露控制。
不同执行语义，对结果暴露方式也不同。

八、如何简要实现

一个新 Agent，如何简要实现 skills 的发现、召回、调用、结果返回？

一个够用、够短、能落地的最小设计，不追求和 Claude Code 一模一样，但核心思路一致。

1）第一步：统一 skill 数据结构

最小结构建议这样：

type Skill = {
  name: string
  description: string
  whenToUse?: string
  contentLoader: (args: string, ctx: AgentContext) => Promise<string>
  allowedTools?: string[]
  model?: string
  effort?: 'low' | 'medium' | 'high'
  context?: 'inline' | 'fork'
  paths?: string[]
}

• contentLoader 允许延迟展开
• context 决定 inline/fork
• paths 支持条件激活
• allowedTools/model/effort 支持 skill 级上下文修饰

这和 Claude Code 的 createSkillCommand() 思路是一致的。[loadSkillsDir.ts] skills/loadSkillsDir.ts#L270-L401

2）第二步：启动时只加载「索引」，不要加载正文

最简做法：

• 扫描 skills 目录
• 解析 frontmatter
• 只把 name / description / whenToUse / paths / context 放进 registry
• skill 正文不要此时进 prompt

示意：

async function loadSkillIndex(skillDirs: string[]): Promise<Skill[]> {
const skills: Skill[] = []
for (const dir of skillDirs) {
    for (const skillFile of await listSkillFiles(dir)) {
      const raw = await readFile(skillFile, 'utf8')
      const { frontmatter, content } = parseFrontmatter(raw)
      skills.push({
        name: basename(dirname(skillFile)),
        description: String(frontmatter.description ?? ''),
        whenToUse: frontmatter.when_to_use ? String(frontmatter.when_to_use) : undefined,
        paths: Array.isArray(frontmatter.paths) ? frontmatter.paths : undefined,
        context: frontmatter.context === 'fork' ? 'fork' : 'inline',
        contentLoader: async () => content,
      })
    }
  }
return skills
}

这个阶段要学 Claude Code 的不是目录细节，而是索引和正文分离。

3）第三步：做一个「未发送 skill 集合」

这是渐进式披露的核心。

维护一个 session 级状态：

type SkillDisclosureState = {
  sentSkillNames: Set<string>
}

每轮只发送新的：

function getNewSkillListings(skills: Skill[], sent: Set<string>): Skill[] {
  const fresh = skills.filter(s => !sent.has(s.name))
  for (const s of fresh) sent.add(s.name)
  return fresh
}

然后把它格式化成短列表，而不是全文：

function formatSkillListing(skills: Skill[]): string {
  return skills.map(s => `- ${s.name}: ${s.description}`).join('\n')
}

这对应 Claude Code 的 sentSkillNames + skill_listing attachment 方案。

4）第四步：把文件操作接成动态发现触发器

如果你也想要「技能跟着目录出现」，最小版本就是：

• 用户或模型读/写/改文件时
• 从文件父目录往上走到 cwd
• 看有没有 .agent/skills 或 .claude/skills
• 找到新目录就加载 skill index

示意：

async function discoverSkillDirsForFile(filePath: string, cwd: string): Promise<string[]> {
const dirs: string[] = []
let current = dirname(filePath)
while (current.startsWith(cwd + sep)) {
    const candidate = join(current, '.agent', 'skills')
    if (await exists(candidate)) dirs.push(candidate)
    const parent = dirname(current)
    if (parent === current) break
    current = parent
  }
return dirs
}

Claude Code 的现成参考是 [discoverSkillDirsForPaths] skills/loadSkillsDir.ts#L861-L915。

5）第五步：做条件激活，而不是启动时全暴露

如果 skill 定义里有 paths，就不要一开始暴露。
等碰到匹配文件时再激活：

function activatePathScopedSkills(
  pending: Skill[],
  touchedFiles: string[],
): { active: Skill[]; remaining: Skill[] } {
const active: Skill[] = []
const remaining: Skill[] = []
for (const skill of pending) {
    if (!skill.paths || skill.paths.length === 0) {
      active.push(skill)
      continue
    }
    const matched = touchedFiles.some(file => matchAny(file, skill.paths!))
    if (matched) active.push(skill)
    else remaining.push(skill)
  }
return { active, remaining }
}

这就是 Claude Code conditionalSkills -> activateConditionalSkillsForPaths() 的最小复刻。

6）第六步：调用 skill 时才真正加载正文

不要提前把 skill 正文塞到 prompt。
调用时再做：

async function invokeSkill(
  skill: Skill,
  args: string,
  ctx: AgentContext,
): Promise<SkillInvocationResult> {
const prompt = await skill.contentLoader(args, ctx)

if (skill.context === 'fork') {
    const result = await runSubAgent({
      prompt,
      allowedTools: skill.allowedTools,
      model: skill.model,
      effort: skill.effort,
    })
    return { mode: 'fork', result }
  }

return {
    mode: 'inline',
    newMessages: [
      { role: 'user', content: `[SKILL:${skill.name}]` },
      { role: 'user', content: prompt, meta: true },
    ],
    allowedTools: skill.allowedTools,
    model: skill.model,
    effort: skill.effort,
  }
}

这就是 Claude Code SkillTool.call() 的最小骨架。[SkillTool.ts] tools/SkillTool/SkillTool.ts#L581-L863

7）第七步：结果返回必须分 inline 和 fork

直接照 Claude Code 的语义分两种：

inline

• 返回一个轻 tool_result：Launching skill: xxx
• 真正内容通过 newMessages 回到主对话继续推理

fork

• 返回最终结果摘要
• 子代理对话不污染主上下文

示意：

type SkillInvocationResult =
  | {
      mode: 'inline'
      newMessages: Message[]
      allowedTools?: string[]
      model?: string
      effort?: string
    }
  | {
      mode: 'fork'
      result: string
    }

这一步是很多新 Agent 最容易偷懒的地方。
要么所有 skill 都 inline，主上下文爆炸；要么所有 skill 都 fork，失去细粒度引导。

九、小结

「skills 的渐进式披露」其实就是 Claude Code 在控制 prompt 成本和能力密度时最典型的设计之一。它真正解决的问题不是「怎么找到一个 skill」，而是「怎么在不把上下文撑爆的前提下，让模型知道自己有技能可用」。

它背后的思路：

• 先给索引
• 再给局部集合
• 再给真实正文
• 最后才给执行结果

这是一个很像搜索引擎的设计：摘要、点击、展开、消费，而不是把整本书扔给你。

以上。

OpenClaw 的 Skills，本质上不是一个「可调用工具」，它更像一套经过约束的运行手册：启动时把技能目录扫描出来，压成一份 <available_skills> 清单塞进 system prompt，模型自己判断要不要选一个 skill，然后再通过 Read 工具去读这个 skill 的 SKILL.md。读完以后，没有任何独立执行器接管，还是在当前这条 session 的 tool-loop 里继续跑。

Claude Code 走的是另一条路。它把 skill 做成了 tool，工具里负责校验、加载、执行，甚至可以放进一个新上下文里跑完，再把结果回传主对话。

这两个实现方向，表面上都叫 skills，工程含义完全不一样。

如果你是做 Agent 平台、企业内 Copilot、代码助手、任务执行器，这个差异不只是架构图上的审美问题。它会直接影响：

• prompt 预算怎么花
• 权限边界放在哪里
• skill 的治理成本有多高
• 运行链路是可控还是失控
• 你后面想不想做隔离执行、审计、回放、灰度发布

1. OpenClaw 的 Skills，到底是怎么被「召回」的

很多人一看到 skills，第一反应是：是不是和 memory 一样，先走 embedding 检索，再把相关技能召回进上下文。

不是。

OpenClaw 的 skills 召回机制非常直接，甚至可以说有点「朴素」：扫描目录，生成目录清单，注入提示词，让模型自己选。整条链路分三段：

1. 发现
2. 注入
3. 读取

OpenClaw 反过来做了一件更工程化的事：先把 skill 列表显式给模型，再用 system prompt 约束它怎么选。

这个机制的起点在 src/agents/skills/workspace.ts 的 loadSkillEntries()。

1.1 技能发现：先扫目录，再谈调用

OpenClaw 会从多个 root 目录扫描 SKILL.md，然后合并成最终技能集。这里是有明确的覆盖优先级的：

extra < bundled < managed < agents-personal < agents-project < workspace

它的逻辑是：越靠近当前工作空间、越贴近用户项目的 skill，优先级越高。平台预置的 bundled skill 可以兜底，但项目级 skill 要能覆盖它。否则你做企业落地时会很难受，团队定制流程永远被平台内置逻辑压着打。

从目录结构看，OpenClaw 支持两种 skill 形态：

• root 本身就是一个 skill，目录下直接有 SKILL.md
• root 下的子目录分别是 skill，每个子目录里有自己的 SKILL.md

这样，团队在实际维护 skill 时，有两种典型组织方式：

• 单一 skill 仓库，根目录就是技能内容
• skills 集合仓库，每个子目录一个技能

都支持，落地阻力会小很多。

它对 SKILL.md 做了体积限制，默认超过 256KB 就直接跳过。

SKILL.md 本来就应该是高密度操作指南，不应该演变成一个什么都往里塞的大文档。你一旦允许 skill 文件无限变大，后面一定会有人把 SOP、FAQ、设计文档、事故复盘全扔进去，最后技能选择和加载成本一起爆炸。OpenClaw 在扫描阶段直接卡体积，其实是在替平台维护纪律。

1.2 frontmatter 解析

给 skill 增加最小限度的结构化元信息

扫描到 SKILL.md 后，OpenClaw 会读原文并解析 frontmatter。坏掉或者缺失的 frontmatter 会被忽略。

这个决策也很对。

OpenClaw 这里更像是「有就用，没有拉倒」。它承认 markdown 本体才是 skill 的核心，frontmatter 只是辅助控制面。这个姿态很适合 skills 这种增长很快、来源很多的资产类型。

但这里也埋了一个工程 trade-off：frontmatter 被弱约束，意味着后续治理和平台能力扩展会受限。你今天只做 discovery 和 basic gating，这么玩没问题；你明天如果要做 skill 分类、依赖分析、版本兼容、批量审计，元信息松散会让成本陡增。

OpenClaw 当前站在了「先把系统跑起来」的一边，没有走「先把规范做重」的路子。

这意味着它更适合中小规模 skill 生态，或者说更适合个人助手这类工具，而不是一个强治理的企业级 skill marketplace。

2. 不是所有 skill 都会进 <available_skills>

扫描出来只是候选集，不等于模型能看到。

OpenClaw 在注入 system prompt 之前会做一轮 gating。这个步骤比很多人想象得重要，因为它决定了模型到底暴露给了哪些能力。

过滤逻辑里有几类条件。

2.1 配置开关

最基础的 enable/disable

如果某个 skill 在配置里被标成 skills.entries.<skillKey>.enabled === false，它就会被剔除。

这是最基础的 kill switch。工程上没什么可争议的，必须有。不然你没法快速止血。某个 skill 写坏了、依赖环境挂了、被发现会引导模型做危险操作，没有一键下线能力，平台就不配上线。

2.2 bundled allowlist

对内置技能单独管控

skills.allowBundled 只约束 bundled 来源。

这个细节很有意思。它说明 OpenClaw 把 bundled skills 当成一类特殊资产处理：平台自带，但不默认无条件信任。

为什么这事重要？因为内置 skill 经常是平台演进中最容易「偷偷变多」的那部分。你今天打包 5 个，明天为了演示方便塞到 20 个，后天 prompt 里一大坨 descriptions，模型选 skill 的噪声越来越大。allowlist 的存在，本质上是在给平台预装能力上保险栓。

2.3 eligibility 判断

按运行环境判断 skill 是否可用

OpenClaw 会根据 metadata.requires 去判断 skill 能不能用，条件包括：

• 二进制依赖是否存在
• 环境变量是否满足
• 配置是否具备
• 操作系统是否匹配
• remote 平台是否匹配

这个设计非常工程化。因为 skill 如果涉及真实操作，它一定和环境耦合。比如某个 skill 依赖特定 cli，或者要求某个 API token，或者只能在 Linux 跑。你如果不在注入前做 eligibility，而是让模型先看到 skill，再在执行时失败，用户体验会很差，模型行为也会变形：它会看到一个貌似可用的方案，实际一调就炸。

OpenClaw 选择「先过滤，再暴露」，这是我非常认同的策略。因为对模型来说，看得见就等于潜在可用。你让它看见无效 skill，本质上是在制造认知噪声。

2.4 disable-model-invocation

系统内部保留，模型不可见

如果某个 skill 标记了 disable-model-invocation，它不会进入 prompt 的 <available_skills>，但仍然存在于系统内部，可用于管理或校验。

因为技能资产不只有「给模型用」这一种角色。你可能有些 skill 需要：

• 用于测试
• 用于审核
• 用于运维校验
• 用于内部 pipeline
• 用于未来发布但暂不开放

OpenClaw 没把「存在」和「可被模型调用」绑死，这样 skill registry 才像个平台能力，而不是一个 prompt 拼装器。

3. <available_skills> 才是 OpenClaw 的真正召回入口

很多人说 skills 被召回，其实这句话在 OpenClaw 语境里容易让人误解。

真正被放进上下文里的第一层，不是 SKILL.md 内容，而是 <available_skills> 这个目录清单。它由 buildWorkspaceSkillsPrompt() 生成，注入到 system prompt。

也就是说，模型最先看到的是技能目录，不是技能正文。

这个做法也算是渐进式披露的一种实现。先给模型足够决定是否要读 skill 的最小信息，避免一开始就把所有技能全文灌进去。

3.1 system prompt 里的强规则，决定了技能选择流程

OpenClaw 在 system prompt 里有一段明确的 Skills mandatory 规则，大意是：

• 先扫描 <available_skills> 里的 <description>
• 只有明确匹配一个 skill 时，才去读对应的 SKILL.md
• 最多只读一个 skill

这三条里，最重要的是后两条。

3.1.1 只有明确匹配一个才读

这是在压制模型的泛化冲动。模型很喜欢「我觉得这个也相关，那个也相关」，然后多读几个，最后把自己卷进上下文泥潭。OpenClaw 用提示词硬性要求「明确匹配一个」才允许进入下一步，这本质上是在给模型加稀疏化约束。

效果未必 100% 可控，但方向是对的。

3.1.2 最多只读一个 skill

如果你做过基于 prompt 的 tool orchestration，就会知道一个常见死法：模型在一堆说明里来回跳，读完 A 觉得 B 也有用，再读 B，顺手 C 也看看，最后 token 花了不少，任务还没干。

OpenClaw 这里直接规定 upfront 只能读一个 skill。我个人判断，这不是因为理论上最优，而是因为工程上最稳。

它牺牲了一部分组合式技能能力，换来了几个非常实际的好处：

• token 消耗更可控
• 模型决策路径更短
• skill 选择失败更容易定位
• 调试和回放更容易做

代价也很明确：如果任务天然需要多个 skill 协同，OpenClaw 当前机制会显得笨。模型要么自己在单个 skill 指导下绕着做，要么根本选不准。

这也是它和 Claude Code 一个很大的分歧。Claude Code 把 skill 视作 tool，更容易天然支持复杂编排；OpenClaw 把 skill 视作可读说明，天然倾向于单次聚焦。

3.2 技能过多时的降级策略：compact 和 truncated

<available_skills> 不是无上限注入的。技能太多时，OpenClaw 会降级成 compact 格式，甚至截断，并提示 skills truncated。

这个点看起来像 prompt 小技巧，其实是很重要的预算治理。

因为技能系统一旦跑起来，数量几乎只会越来越多。最初十几个 skill，description 全量塞进去还行；到几十上百个 skill，再这么搞，system prompt 很快会变成垃圾堆。OpenClaw 至少意识到了这个问题，所以做了两级退化：

• compact：保留更少信息
• truncated：截断并明确提示

这说明它把 prompt 当成有限资源，而不是无限容器。

但实话实说，这个策略只是在「延缓爆炸」，不是根治。skill 数量继续增长以后，靠 compact/truncate 顶不住。因为问题不只是 token 多了，而是模型在目录里做决策的辨识难度会越来越高。description 再压缩，skill 之间的区分度也会变差。

所以我对这块的判断是：OpenClaw 的 catalog 注入机制适合中等规模 skill 集，不适合无限扩张。
如果你团队未来真要做上百个 skill 的企业级平台，迟早要引入更分层的 catalog、分类路由、或者显式 selector，而不是靠一坨 <available_skills> 让模型裸选。

4. 真正的 SKILL.md 是怎么进入上下文的

OpenClaw 的第二层加载是按需读取。模型先看到目录清单，选中 skill 以后，才通过 Read 工具去读对应路径的 SKILL.md。

4.1 技能正文不是 system prompt 的一部分

system prompt 里只有规则和技能目录。真正的 SKILL.md 内容，是在模型发起一次 read tool call 后，作为 toolResult 追加进当前消息流。

也就是说，skill 正文进入上下文的方式，和你用工具读一个普通文件没有本质区别。差别只是 system prompt 先规定了什么时候允许这样读。

这个设计的好处非常明确：

• 大幅降低初始上下文体积
• 让技能正文成为按需成本，而不是固定成本
• skill 更新后无需改 system prompt 模板，只影响运行时读到的内容
• 便于把 skill 当文件资产管理，而不是 prompt 模板片段

坏处也很明确：

• skill 的执行效果更依赖模型有没有正确触发 read
• skill 的权威性被弱化成一条 toolResult，而不是顶层指令
• 如果 toolResult 很长，后续上下文里它和普通读文件结果没什么层级差异

从实现角度看，OpenClaw 这里是很克制的。它没有发明一个 Skill Runtime，没有做一套专门的 skill 调度协议，就是借已有的 read 工具完成正文加载。

这让系统保持简单，但也让 skill 更像「读到的一份说明书」，而不是「被激活的执行单元」。

5. OpenClaw 的安全边界

既然 skill 是文件，模型要去读 SKILL.md，安全问题马上就来了：路径能不能逃逸？symbolic link 能不能把 skill 指到 root 外？模型能不能顺着 location 读到不该读的内容？

OpenClaw 这里做了两层保护。

5.1 第一层：扫描阶段的 containment 检查

在技能发现阶段，它会对 realpath 做 containment 检查，防止 symlink 把 skill 指到 root 外面。

这是典型的「尽早失败」策略。我一直觉得文件系统相关的安全问题，能在发现阶段拦的，不要拖到执行阶段。因为一旦把异常路径放进 skill registry，后面每个环节都得假设它可能有问题，整个系统会变得很难推理。

扫描时就把越界项挡掉，registry 内部的数据至少是干净的。

5.2 第二层：Read 工具的 workspace root guard

模型真正发起读取时，Read 工具还会做 sandbox root 校验，禁止 .. 或绝对路径逃逸 workspace root。

也就是说，即使 discovery 阶段没出问题，真正读取文件时还有一层运行时防线。

文件边界这事，单点防护永远不够。扫描阶段挡的是「注册进来的 skill 本身」，读取阶段挡的是「模型实际提出的路径参数」。二者保护的对象不一样。

工程上要是只做第一层，你会被运行时路径拼接坑；只做第二层，你会把很多脏数据带进 registry，影响可观测性和调试。

OpenClaw 在这块虽然不算复杂，但做法是标准的。

6. Skills 的渐进式披露

OpenClaw 的 skills 机制，如果只看「枚举目录 -> 注入 prompt -> read 文件」，会有人觉得太朴素。真正值得注意的是，它和 memory 一样，贯彻了一套很明确的渐进式披露思路。

这是上下文预算治理的逻辑。

原则就两条：

1. 先给最小可用信息
2. 确认需要后再扩大读取范围

在 OpenClaw 里，memory 和 skills 都是这么干的，只是路径不同。

6.1 Memory 是先搜 snippet，再精读指定行段

memory_search 先返回短片段，带 path 和 line range，不是全文注入。底层还有 SNIPPET_MAX_CHARS = 700 的硬上限。如果后端预算紧，还会继续裁结果。

之后再通过 memory_get 按 path + from/lines 去拉具体行段。

这个流程是非常标准的 progressive disclosure：先定位，再精读。

6.2 Skills 是先给目录，再只读一个 SKILL.md

skills 这边没有向量召回，而是目录清单。模型先看 <available_skills>，只在明确匹配一个时才读正文，并且 upfront 最多一个。

两条链路表面不同，本质一样：都在防止大块文本无脑灌进上下文。

我为什么说这点值钱？因为很多团队做 Agent 系统时，最大的问题不是模型不会做事，而是上下文管理太粗糙。什么都想喂进去，最后 token 烧得飞快，模型还因为噪声太高做不准。

OpenClaw 至少在架构层面承认了一件事实：上下文是预算，不是仓库。

这件事说起来简单，真正落实到工具语义、提示词规则、底层裁剪，很多系统做不到。

7. OpenClaw 没有「独立 Skill 执行器」

在 OpenClaw 里，skill 读完之后，并没有一个单独的执行环境接管它。没有所谓「Skill Runtime」去解释 SKILL.md，也没有「新上下文执行 skill」这回事。它还是在同一个 activeSession.prompt(...) 的 tool-loop 里继续跑。

链路大概是这样：

1. system prompt 里给出 <available_skills> 和选择规则
2. 模型决定某个 skill 匹配当前请求
3. 模型调用 read 工具读取对应 SKILL.md
4. toolResult 里带回 SKILL.md 文本
5. 这个 toolResult 被追加到当前 session 的 messages
6. 模型再次被调用，看到刚才读到的 skill 内容
7. 模型按 skill 指导，继续发起后续 toolCall，比如 exec、write、edit
8. 直到输出最终回答

关键点：skill 内容只是同一消息流里多了一条 toolResult。

这意味着什么？

意味着 OpenClaw 的 skill 执行，本质上是「模型读了一份流程说明，然后继续在原对话里行动」。它没有新的边界，没有新的记忆隔离，没有新的权限域。真正的隔离，来自工具列表裁剪和文件读写沙箱，不来自上下文切换。

这和 Claude Code 很不一样。

8. Claude Code 的 skills，更像「可调用子程序」

Claude Code 的 skill 流程有几个特征：

• skill 是 tools 列表里的一个明确工具
• 模型会调用 Skill tool，而不是自己去 read 某个 markdown
• skill prompt 的加载是 tool 内部动作
• 权限校验也主要发生在 tool 内
• skill 可以在新上下文执行，执行完再把结果带回主对话

从工程抽象上看，Claude Code 的 skill 更像一个「子程序入口」。它有名字、有调用接口、有内部装载逻辑，甚至有上下文隔离能力。

OpenClaw 没有走这条路。它把 skill 设计成「模型可读的文件」，由模型自己决定是否展开，并在原上下文里继续操作。

这两个方向，没有谁天然高级，但适用面不同

如果你要的是：

• 更强的执行隔离
• 更容易做权限封装
• 更容易做结果回传和子任务边界
• 更适合复杂、多步骤、可复用的任务单元

Claude Code 那种 tool 化 skill 更合适。

如果你要的是：

• 实现简单
• skill 作者门槛低
• 把 skill 当 markdown 资产管理
• 快速把流程知识接进现有 ReAct tool-loop

OpenClaw 这种文件化 skill 更实用。

工程上不看理念，看代价结构。

9. OpenClaw 为什么会做成这样

我猜它的设计动机是：尽量复用现有 agent runtime，而不是为 skills 单独发明一层执行框架。

你看它的做法就知道了：

• discovery 复用文件系统扫描
• selection 复用 system prompt
• loading 复用 read 工具
• execution 复用原有 tool-loop
• safety 复用 sandbox path guard 和 tool policy

这是一套很节制的架构思路。好处是：

实现成本低 ：不用造新协议，不用加新消息类型，不用多一层 runtime。对一个正在演进中的 agent 系统来说，这非常现实。 Skill 作者认知负担小：本质上写一个 SKILL.md 就行。对于组织内部推广，这是巨大优势。因为真正阻碍 skill 规模化的，从来不是模型能力，而是作者生态能不能起来。 运行链路可观测性还不错：所有事情都发生在同一 session 里。read 了什么、接着调了什么工具、toolResult 长什么样，回放起来相对直观。

但它的代价也有。

代价 1：skill 缺少强执行边界

skill 本身不是 tool，没有独立权限面。你没法像封装一个函数那样，给 skill 绑定专属 schema、专属校验、专属 side effect 边界。最终还是模型在拿到 skill 文本后，自由地调用后续工具。

这就意味着 skill 的约束力主要来自提示词，不来自执行器。

代价 2：组合式编排能力弱

system prompt 里要求 upfront 最多读一个 skill，这对预算控制很好，对复杂任务不友好。多 skill 协同在这个体系里不是一等公民。

代价 3：skill 的结果不可天然封装

Claude Code 那种「在新上下文执行 skill，再返回结果」，天然有个输入输出边界。OpenClaw 这里没有。skill 一旦展开，后续动作直接混进主会话消息流。你很难把它当作一个独立执行单元来治理。

代价 4：对模型的选择质量要求高

因为没有独立 selector，也没有 tool-level dispatcher，skill 能不能选对，主要靠 <available_skills> 的 descriptions 和 system prompt 规则。这对 skill 描述质量要求很高。写得不清楚，模型就选歪。数量一多，问题更明显。

10. 权限控制

OpenClaw 的思路是「先裁剪能力，再让模型行动」

这一点我很喜欢，因为它比「调用时再临时拦截」更稳。

OpenClaw 的权限控制，不是把所有工具都亮给模型，然后在调用某个危险工具时说不行。它更像是：

1. 先根据 policy pipeline 把不允许的工具从列表里移掉
2. 再把剩下的工具暴露给模型
3. 模型根本看不到被禁的能力

skills 这边也一样：

• 不合格的 skill 不进入 <available_skills>
• disable-model-invocation 的 skill 对模型不可见
• Read 路径有 workspace root guard

这种「先裁剪，再推理」的方式有个很大的好处：模型认知空间更干净。它不会围着一堆不可用能力打转，也不会生成大量被拒调用的无效动作。

如果你做企业场景，这比事后 deny 好得多。因为用户只会看到 agent 做合理尝试，而不是不停撞墙。

当然，它的代价是灵活性差一点。你没法在非常细粒度的时刻做动态放行，除非重新构建 tool list 或 skill list。但我认为这笔账是划算的。Agent 系统的第一优先级不是灵活，是可控。

11. 从平台设计角度看呢

觉得比较好的点：

第一，简单。
这个简单不是简陋，是尽量不新增系统概念。skill 就是文件，加载靠 read，执行靠原有 tool-loop。对演进中的 agent 框架来说，这是非常健康的选择。

第二，预算意识强。
<available_skills> 目录注入、最多只读一个 skill、compact/truncated 降级，这些都说明它把 context 当稀缺资源处理。

第三，权限思路对。
先过滤 skill 和 tool，再让模型行动。可见性先于可调用性，这很工程化。

第四，适合知识流程化。
很多团队真正需要的，不是一个会自己发明流程的 agent，而是把组织内已有 SOP 结构化地喂给模型。OpenClaw 这套很适合干这个。

一些局限：

第一，规模扩展性一般。
catalog 注入机制天然不适合 skill 数量无限增长。它适合几十级别，不适合大规模 marketplace。

第二，组合能力弱。
「最多只读一个 skill」对稳态有帮助，对复杂任务编排是限制。

第三，skill 缺少运行时身份。
它不是 tool，没有明确的输入输出边界，也没有独立权限与审计单元。后续做深治理会比较难。

第四，过度依赖模型选择。
一旦 descriptions 写得不好，或者目录过大，skill 选择质量会变成系统上限。

12. 适用场景

在系统架构选型时，如果有以下的条件，可以优先选择 OpenClaw 的设计逻辑：

• 团队已经有一套成熟的 tool-loop，想低成本引入 skills
• 主要目标是把流程知识、操作手册、领域步骤注入 agent
• skill 作者很多，技术水平参差不齐，需要低门槛 markdown 入口
• 更看重实现速度和治理可落地，而不是复杂编排能力
• skill 数量在可控范围内，不会迅速膨胀到几百个

有如下的情况时，就不太适用使用这种方案：

• skill 本质上是可执行业务子任务，需要独立生命周期
• 需要强隔离执行、单独审计、结果回传和失败恢复
• 任务天然需要多个 skill 协同编排
• 技能库规模会非常大，必须做复杂路由
• 权限模型要求细到「某个 skill 可以做 A 但不能做 B」

这些场景下，我更倾向 Claude Code 那种 tool 化 skill，或者更进一步，直接走 subagent / workflow node / task runtime。

13. 小结

如果只用一句话概括两者区别：

Claude Code 的 skill 更像可调用子程序，OpenClaw 的 skill 更像按需展开的运行手册。

前者强调执行单元，后者强调上下文注入。
前者天然适合隔离和编排，后者天然适合轻量接入和流程沉淀。
前者的复杂度在 runtime，后者的复杂度在 prompt 和内容治理。

OpenClaw 用极其精简的 Prompt 规则和现成的 Read 工具，低成本实现了 Agent Skills 标准。它够用，但也把长文本管理的压力，原封不动地推给了底层大模型的 Context Window。

我个人对 OpenClaw 这套实现是认可的，前提是别把它想象成一个万能技能平台。它解决的是「如何在不重写 agent runtime 的前提下，把结构化流程知识接进模型执行链路」这个问题。这个问题它解得挺干净。

但如果你要的是 Claude Code 那种「新上下文执行 skill、像子程序一样调用、跑完把结果带回来」，你该找的是子会话、subagent、任务编排层，而不是继续往 SKILL.md 上堆规则。

以上。