Agent Skill 按需加载：架构设计与实现解析

┌──────────────────────────────────────────────────────────────┐
│                        Agent Runtime                         │
│                                                              │
│   ┌──────────┐    ┌────────────────────┐    ┌─────────────┐  │
│   │  Skill   │───▶│ Request Processor  │───▶│   Model     │  │
│   │Repository│    │    Pipeline        │    │  Request    │  │
│   └──────────┘    └────────────────────┘    └─────────────┘  │
│        │                    │                                │
│        │            ┌───────┴────────┐                       │
│        │            │ Session State  │                       │
│        │            │  (loaded,docs) │                       │
│        │            └───────┬────────┘                       │
│        │                    │                                │
│   ┌────┴─────┐    ┌────────┴───────┐                        │
│   │  Skill   │───▶│ Tool Execution │                        │
│   │  Tools   │    │  (StateDelta)  │                        │
│   └──────────┘    └────────────────┘                        │
└──────────────────────────────────────────────────────────────┘

模型判断需要某技能 → 调用 skill_load 工具 → 工具执行产生 StateDelta → 写入 Session State

新一轮请求 → Processor 从 State 读取已加载技能 → 组装完整内容 → 注入到模型 Prompt 中

type Repository interface {
    // 返回所有 Skill 的摘要（名称 + 一句话描述）
    Summaries() []Summary
    // 根据名称获取完整的 Skill 定义
    Get(name string) (*Skill, error)
    // 获取 Skill 关联文档的存储路径
    Path(name string) (string, error)
}

skills/
├── code-review/
│   ├── SKILL.md          # 核心定义（YAML front matter + Markdown body）
│   ├── guide.md          # 辅助文档
│   └── reference.txt     # 辅助文档
└── data-analysis/
    ├── SKILL.md
    └── templates.md

---
name: code-review
description: 代码审查技能，涵盖代码规范、安全检查和性能优化
---

## 审查指南

当你进行代码审查时，请遵循以下步骤...

场景：Agent-A 加载了 code-review，Agent-B 加载了 data-analysis

❌ 不隔离：Agent-A 的 Prompt 里也会出现 data-analysis 的内容
✅ 带作用域：每个 Agent 只看到自己加载的 Skill

func LoadedKey(agentName, skillName string) string {
    return "temp:skill:loaded:" + agentName + "/" + skillName
}

func LoadedPrefix(agentName string) string {
    return "temp:skill:loaded:" + agentName + "/"
}

// Call 只负责验证和返回确认
func (t *LoadTool) Call(ctx context.Context, args LoadInput) string {
    if _, err := t.repo.Get(args.Skill); err != nil {
        return"error: skill not found"
    }
    return"loaded: " + args.Skill
}

// StateDelta 声明需要写入的状态变更
func (t *LoadTool) StateDelta(agentName string, args LoadInput) map[string][]byte {
    delta := map[string][]byte{
        LoadedKey(agentName, args.Skill): []byte("1"),
    }
    if args.IncludeAllDocs {
        delta[DocsKey(agentName, args.Skill)] = []byte("*")
    } elseiflen(args.Docs) > 0 {
        delta[DocsKey(agentName, args.Skill)] = marshalJSON(args.Docs)
    }
    return delta
}

ProcessRequest()
  │
  ├─ 1. 旧版 State 迁移（如需要）
  │
  ├─ 2. 清理过期的 Skill State（Turn 模式）
  │
  ├─ 3. 注入 Skill 概览列表（无条件执行）
  │     → "Available skills:\n- code-review: 代码审查\n- ..."
  │
  ├─ 4. 从 State 读取已加载的 Skill 列表
  │
  ├─ 5. 限制最大加载数量（如超限，按最近使用排序保留）
  │
  ├─ 6. 遍历已加载 Skill，构建注入内容:
  │     ├─ 获取 Skill 完整 Body
  │     ├─ 读取文档选择
  │     └─ 拼装 "[Loaded] skill-name\n{body}\n{docs}"
  │
  ├─ 7. 合并到 System Message
  │
  └─ 8. 清理一次性 Skill State（Once 模式）

（原始 System Prompt 内容）

Available skills:
- code-review: 代码审查技能
- data-analysis: 数据分析技能

[Loaded] code-review

## 审查指南
当你进行代码审查时，请遵循以下步骤...

Docs loaded: guide.md
[Doc] guide.md
（guide.md 的完整内容）

ProcessRequest()
  │
  ├─ 1. 从 State 读取已加载 Skill
  │
  ├─ 2. 索引对话历史中所有的 Tool Call 消息
  │
  ├─ 3. 找到每个 Skill 最后一次 Tool Response 的位置
  │
  ├─ 4. 将 Skill 完整内容写入对应的 Tool Result 消息体
  │
  ├─ 5. 为找不到匹配 Tool Result 的 Skill 构建回退内容
  │
  └─ 6. 必要时插入回退的 System Message

func maybeClearSkillStateForTurn(invocation Invocation) {
    // 使用一次性标记防止重复清理
    if invocation.GetFlag("skill_turn_cleared") {
        return
    }
    invocation.SetFlag("skill_turn_cleared", true)

    // 清除上一轮残留的 Skill State
    clearAllSkillKeys(invocation)
}

agent := NewAgent("my-agent",
    WithSkills(repo),
    WithMaxLoadedSkills(3),  // 最多同时保留 3 个已加载 Skill
)

Request Processor Pipeline:
  │
  ├─ [1] System Prompt Processor        // 基础 System Message
  ├─ [2] Context Processor              // 注入外部上下文
  ├─ [3] Skills Request Processor       // 注入 Skill 概览 + System Message 模式的内容
  ├─ [4] Content Processor              // 组装对话历史
  ├─ [5] Post-Tool Processor            // 处理工具调用结果后的提示
  └─ [6] Skills Tool Result Processor   // Tool Result 模式的内容回填

用户: "帮我做一下这段代码的审查"

→ Skills Request Processor 注入概览:
  System Message += "Available skills:\n- code-review: 代码审查\n- ..."

→ 模型看到概览，判断需要 code-review 技能

→ 模型调用 skill_load(skill="code-review", include_all_docs=true)

→ Tool 执行:
  - Call() 返回 "loaded: code-review"
  - StateDelta() 产生:
    {
      "temp:skill:loaded:my-agent/code-review": "1",
      "temp:skill:docs:my-agent/code-review":   "*"
    }

→ 框架将 StateDelta 写入 Session State

→ Skills Request Processor 处理:
  a. 注入概览（每次都做）
  b. 从 State 发现 code-review 已加载
  c. 从 Repository 获取 code-review 的完整 Body + 所有文档
  d. 注入到 Prompt:
     "[Loaded] code-review\n\n## 审查指南\n...\n\n[Doc] guide.md\n..."

→ 模型现在拥有完整的审查指导，开始执行代码审查任务

→ 新的 Invocation 开始

→ maybeClearSkillStateForTurn() 清除上轮的 Skill State

→ code-review 的内容不再出现在 Prompt 中

→ 如果新任务又需要，模型会重新加载