Skills:三层渐进式披露

更新于 · 在 sijie.xyz 查看原条目 ↗

一个 skill 不是每个脚本配一个工具的做法(那样会让工具列表爆炸,把系统提示词撑得臃肿)——skill 也不是一种 capability:它是骑在 capability 之上的一个被创作出来的产物(confusables)。取而代之的是三个层级:

  • L1 —— 系统提示词里只放该 skill 的名称 + 描述
  • L2 —— 一个 skill_use(name) 工具按需揭示完整的 SKILL.md,由 agent 自行判断是否相关
  • L3 —— 一个 skill_run_script(name, script, args) 工具在沙箱里运行它

于是 agent 先看到的是 capability 的名字,只有感兴趣时才去读细节,只有真正需要时才执行(backend/internal/routes/capload/capreg_skill_runner.go)。SKILL.md 是面向 agent 的权威合约,数据库那一行只是管理层的存储——marketplace 解析的正是同一份 SKILL.md 格式。

类图

classDiagram
  class skillRunnerCapability {
    -deps skillRunnerDeps
    ONE capability, TWO generic tools
    SystemPromptFragment() = empty - L1 rides the persona
    per-skill ACL checked INSIDE each tool
  }
  class skillRunnerDeps {
    Skills conversation.SkillGetter
    Sandbox sandbox.Runner
  }
  class parseSkillName {
    <<func>>
    parses the skill_use args: {name}
  }
  class runScriptArgs {
    Name string
    Script string
    Args json.RawMessage
  }
  class renderSkillMD {
    <<func>>
    takes *domain.Skill, returns string
    YAML frontmatter + body + scripts section
  }
  class skillRunPayload {
    Stdout, Stderr string
    ExitCode int
    TimedOut bool
  }
  skillRunnerCapability *-- skillRunnerDeps
  skillRunnerCapability ..> parseSkillName : skill_use (L2)
  skillRunnerCapability ..> renderSkillMD : L2 output
  skillRunnerCapability ..> runScriptArgs : skill_run_script (L3)
  skillRunnerCapability --> skillRunPayload : L3 output

这个类图形状就是这套披露设计本身:两个通用工具取代了"每脚本一个工具"——工具列表的数量相对 skill 的数量保持 O(1)。

相关笔记