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」，而是「怎么在不把上下文撑爆的前提下，让模型知道自己有技能可用」。

它背后的思路：

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

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

以上。

当 Agent 做到一定复杂度，问题往往不在模型能力本身，而在上下文怎么给、工具怎么给、流程怎么控。同一套模型，有的团队能把它用成「能稳定交付的执行系统」，有的团队只能得到「偶尔灵光一现的聊天机器人」，差距就在架构。

早期提示词工程里，上下文基本是静态的：一次性把提示词写好，然后让 LLM 自己发挥。随着架构的演化，，上下文变成动态的，它会「收」和「放」：

收（Contract）：渐进式披露。屏蔽无关信息，减少 Token 消耗，聚焦注意力。（解决“准确性”）
放（Expand）：动态注入。根据交互状态，主动引入外部话题、记忆片段或世界观设定。（解决“丰富性”与“持续性”）

这是一种系统架构策略：用有限 Token 去管理无限信息，用非确定性模型去执行标准化流程。

1. 三个典型瓶颈：Context、工具、SOP

复杂 Agent 基本都会遇到三个主要的问题：

1. 上下文爆炸（Context Explosion）
   文档、代码、历史对话、用户画像、任务状态……你不可能全塞进 Prompt。硬塞进去也会出现“Lost in the Middle”，关键信息被淹没。

2. 工具过载（Tool Overload）
   工具越多，定义越长，Token 越贵；更严重的问题是：工具选项越多，模型选择正确工具的概率越低，尤其是多个工具功能相近时。

3. 执行不可控
   当我们希望它按 SOP 做事（先检查、再验证、最后提交），它却容易跳步、漏步，或者为了“把话说圆”而瞎编执行结果。

「渐进式披露 + 动态上下文管理」就是对这三件事的统一解法：不要一次把世界交给模型，而是让模型在每一步只看到它此刻需要看到的东西。

2. 渐进式披露

渐进式披露不是少给信息，是分阶段给信息

有人把渐进式披露理解成省 Token。省 Token 是结果，不是核心。

核心是：把一次性的大上下文，拆成多轮的决策—反馈—再决策。每一步只给与当前决策相关的最小信息面，减少噪音，让模型的注意力更集中，也让系统更可控。

一个直观的工程化表述：

• 不是构建一个「全量 Context」
• 而是维护一个「可增长的 Context」，并且增长受控

你会看到两个动作交替出现：

• Contract（收缩）：隐藏、裁剪、摘要、替换为索引
• Expand（扩张）：按需加载片段、工具子集、记忆、世界观、流程状态

3. 数据层

传统做法，使用 RAG 很容易走向粗暴：检索到的内容直接拼进 Prompt，能拼多少拼多少（可以配置）。结果通常是两种：

• Token 变贵，延迟变长
• 模型注意力被稀释，反而更不准

渐进式披露在数据层的落地方式，是把「获取信息」做成连续的动作序列，而不是一次性拉满。

参考 AI Conding 很贴近工程实际的步骤：

• 初始 Prompt 只有任务描述
• AI 发现信息不足，发起 ls 或 grep 请求
• 系统只返回 ls 的结果（文件名列表），而不是文件内容
• AI 选中目标，发起 read_file
• 系统这时才披露文件内容

这里关键点不是 ls/grep/read_file 这些名字，而是信息披露粒度：

• 先给目录/索引（低成本，低噪音）
• 再给片段（命中后才扩大）
• 最后给全文（只在确认需要时才给）

3.1 披露层级建议：L0 到 L3

可以把上下文分成几层，这里定义的层级不是标准答案，但思路是这么个思路：

• L0：任务和约束
  用户需求、输出格式、禁止事项、成功标准。L0 必须稳定，尽量短，长期驻留。

• L1：证据索引
  文件列表、章节目录、数据库表名、日志摘要、搜索结果标题。只给“在哪里”。

• L2：证据片段
  命中的段落、代码片段、表结构、关键日志区间。只给“相关部分”。

• L3：证据全量
  全文档、完整文件、长对话历史。尽量少用，只在确实需要通读时开放。

系统要做的事是：让模型先用 L1 做定位，再用 L2 做判断，最后才允许 L3 进场。这样不仅省 Token，还可以减少模型在噪音里自我发挥的空间。

3.2 动态注入

动态注入常见误区：用户问 A，你检索 A；用户又问 B，你把 A+B 都塞进去；几轮后上下文就乱了，且不可控了。

比较常用的做法是引入「上下文预算」和「淘汰策略」：

• 每轮允许注入的 Token 上限（硬预算）
• 驻留区（长期有效，例如用户身份、偏好、当前任务）
• 工作区（当前步骤的证据片段）
• 冷存区（旧证据移出，保留索引或摘要）

淘汰的对象通常是“旧证据全文”，不是“任务状态”。任务状态丢了，模型就会重复问、重复做；证据全文丢了，大不了重新检索。

4. 工具层

工具越多越强这件事，在 Agent 里是反的：工具越多，模型越容易犹豫、选错，甚至编造「我已经调用了某某 工具」。

渐进式披露在工具层的做法是：分层路由，按需可见。

参考一个很实用的层级披露思路：

• Root 层只披露 5 个大类工具：代码类、文档类、部署类、数据库类、通知类
• 模型先选大类，例如“我要查数据”-> 数据库类
• 下一轮 Prompt 才披露数据库相关的具体工具，例如 sql_query, get_table_schema

我们可以把它当成「工具菜单」：

• 第一屏：只显示一级菜单
• 点进去：才显示二级菜单
• 系统控制可见性，而不是让模型在 100 个工具里裸选

4.1 工具披露带来的三个工程收益

1. Token 控制更直接
   大量工具的 schema 描述会花费大量的 Token。层级分发能把「工具定义成本」分摊到多轮，而且只在需要时支付。

2. 工具选择准确率提升
   选项少，模型更容易做对；更重要的是，减少「近义工具」同时出现。

3. 安全策略更好落地
   不该给的能力，默认不可见。你不需要在 Prompt 里反复警告“不要调用某某工具”，直接让它看不见。

4.2 「工具可见性」本质是一种权限系统

很多团队权限做在网关、做在后端鉴权，但 Agent 的权限还应该做在“可见性”上：

• 看不见：降低误用概率
• 看得见但不可用：模型会反复尝试，浪费回合
• 可用但有条件：需要把条件变成流程状态的一部分（下一节讲 SOP）

5. SOP 层

SOP 层就是当前很火热的 Skills，且不仅仅是 Skills，它是把流程写进披露逻辑，而不是写在提示词里

企业场景里，最怕的是「看似完成、实际没做」，而这在大模型的输出中很常见。让模型「请遵循 SO」”意义不大，它会漏步骤，而且它很擅长把漏掉的步骤用语言补上。

渐进式披露在 SOP 上的落地方式，是在我们的系统里做“流程锁”：上一步没通过，下一步的工具就不出现。

参考一段很清晰的流程控制（关键点直接引用）：

1. 阶段一（Lint）：系统只披露 Lint 工具和当前 Diff，隐藏 Commit 工具
2. 阶段二（Test）：Lint 返回 Success 后，系统才披露 Test 工具
3. 阶段三（Commit）：只有测试通过，系统才披露 git_commit

这套逻辑解决的是“话术不可信”的问题：模型可以说“我已经测试通过”，但系统的状态机不会因为它一句话就放行。放行只能来自可验证的工具回执。

5.1 SOP 控制要点

把「检查点」设计成机器可判定

SOP 最容易失败的地方是检查点含糊，比如“确保无问题”“确认完成”。Agent 体系里要改成：

• 有工具回执的：以回执为准
• 没有工具回执的：以人工确认或外部系统状态为准
• 不能验证的：不要当作放行条件

能自动化判定，就不要让模型自评。

6. 为什么要引入 Agent Skill

这里本质是一种是工程分层，当然也是概念包装。

很多人会问：这些用代码控制不就行了，为什么还要提 Agent Skill？

把 Skill 当成一个架构抽象，会更容易把系统做稳：它解决的是解耦、复用、状态感知。

这里把关键逻辑说透：

6.1 Skill 是「上下文的容器」，用完即走

没有 Skill 时，你往往会得到一个越来越大的系统提示词：把所有话题、所有工具、所有规则都塞进去。结果就是注意力迷失、指令冲突、Token 爆炸。

有 Skill 后，你把「某一类任务需要的提示词 + 可用工具 + 知识入口」封装到一起：

• 需要时加载
• 不需要时卸载
• 上下文保持干净

这和「渐进式披露」是同一件事：Skill 是披露的载体。

6.2 Skill 是「动态注入」的边界

动态注入真正难的是边界：注入多少、注入什么、何时撤回。

Skill 让边界清晰：

• 注入不是“往 Prompt 拼字符串”
• 注入是“激活某个 Skill”，让它把需要的最小信息面带进来

系统因此更容易做预算、做审计、做回放。

6.3 Skill 让路由变成可维护的系统，而不是靠直觉写 prompt

复杂 Agent 一定会路由：用户一句话可能触发“查资料 / 写代码 / 安抚情绪 / 改流程 / 发通知”。

Skill 体系下，路由的输出是“激活哪些 Skill”，而不是“写一段更长的提示词”。这会直接改善维护体验：

• 你能统计每个 Skill 的触发率、成功率、平均 Token
• 你能对某个 Skill 单独迭代，而不牵一发动全身
• 你能为不同用户、不同权限加载不同 Skill 组合

7. 动态上下文管理

动态上下文管理要管理「状态 + 证据 + 权限」。

把上下文当成一段文本来拼接，迟早失控。更合理的视角是：上下文是系统状态在模型侧的投影。

建议把上下文拆成四类对象，每一类有不同的生命周期：

1. 任务状态
   当前处于哪个阶段、已完成哪些检查点、下一步允许做什么。它要短、稳定、结构化，尽量每轮都带。

2. 证据
   检索片段、工具输出、外部信息。它要可引用、可追溯、可淘汰。

3. 偏好与长期记忆
   能影响输出风格或长期策略的东西。它不该频繁变化，变化要可控，最好有写入门槛。

4. 能力与权限
   工具可见性、工具可用性、流程放行条件。它是约束，不是参考建议。

8. 可执行的架构清单

按“先做什么更值”排：

1. 先做工具可见性控制
   工具分层，默认只给 Root 类目；按分支披露具体工具。

2. 把 SOP 变成状态机放行
   上一步成功回执出现，下一步工具才可见。失败就停在当前阶段，不要让模型口头放行。

3. 把上下文分区：驻留区 / 工作区 / 冷存区
   驻留区短且稳定；工作区有预算；冷存区只保留索引/摘要。

4. 先索引后片段的披露策略
   任何大文本资源都先给目录、标题、命中位置，再给片段，不要一上来就全文。

5. Skill 化你的上下文与工具组合
   让“动态注入”从拼 Prompt 变成“加载/卸载 Skill”。一开始不需要 100 个 Skill，把高频的 5–10 个先做稳。

6. 把观测补齐
   记录每轮：披露了哪些证据、开放了哪些工具、触发了哪些 Skill、用了多少 Token、是否命中检查点。没有这些数据，后面很难迭代。

9. 小结

一个成熟的 Agent 系统，外观上像在聊天，内部其实在跑一套受控的执行架构：

• 信息不是一次塞满，而是按步骤披露
• 工具不是全量开放，而是按层级开放
• 流程不是靠自觉，而是靠状态机约束
• 记忆不是越多越好，而是可写入、可淘汰、可追溯

把这四件事做好，Agent 会越来越像一个靠谱的执行系统：该问的问清楚，该查的查到证据，该做的按流程做完，做不到就停下来，不会硬编。

这就是「渐进式披露 + 动态上下文管理」的价值：不是让 Agent 说得更像，而是让它做得更稳。

以上。