14.2 Skill 加载流程

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

Skill 的发现只是第一步——发现后的 Skill 还需要通过工具调用才能真正生效。本节解析 Skill 从发现到注入 Agent 上下文的完整流程。

14.2.1 Skill.dirs()——搜索路径构建

Skill.dirs() 返回所有包含 Skill 的目录路径，这些路径会被传递给 Agent 的 System Prompt，让 Agent 知道有哪些 Skill 可用：

// skill/skill.ts
export async function dirs() {
  return state().then((x) => x.dirs)
}

在 Skill 发现过程中，每个成功加载的 Skill 的目录会被记录到 dirs Set 中：

const addSkill = async (match: string) => {
  const md = await ConfigMarkdown.parse(match)
  // ... 解析和验证 ...
  dirs.add(path.dirname(match))  // 记录目录
  skills[parsed.data.name] = { /* ... */ }
}

14.2.2 SkillTool——通过工具加载 Skill 到上下文

Skill 不是在 Agent 启动时自动全部加载的——那样会浪费宝贵的上下文窗口空间。相反，Agent 通过调用 skill 工具来按需加载特定的 Skill。

skill 工具的工作流程：

1. Agent 查看可用 Skill 列表（在 System Prompt 中）
2. Agent 判断当前任务需要某个 Skill
3. Agent 调用 skill 工具：skill({ name: "git-master" })
4. 工具返回 Skill 的完整 Markdown 内容
5. Skill 内容作为工具调用结果进入对话上下文
6. Agent 后续行为受到 Skill 内容的指导

这种按需加载的设计意味着：

• 节省 Token：只有实际需要的 Skill 才会占用上下文空间。

• Agent 自主决策：Agent 根据任务需求自主选择加载哪些 Skill。

• 动态组合：同一个会话中可以根据不同阶段的需要加载不同的 Skill。

14.2.3 Skill 与 Agent Prompt 的关系

Agent 的 System Prompt 中会包含所有可用 Skill 的名称和描述，但不包含 Skill 的完整内容：

Available Skills:
- git-master: Expert at Git operations including atomic commits, rebase, squash
- frontend-ui-ux: Designer-turned-developer who crafts stunning UI/UX
- playwright: Browser automation via Playwright MCP

Agent 看到这个列表后，根据用户的请求判断是否需要加载某个 Skill。例如：

• 用户说"帮我提交代码"→ Agent 加载 git-master

• 用户说"修复这个 CSS 布局"→ Agent 加载 frontend-ui-ux

• 用户说"测试这个网页"→ Agent 加载 playwright

这种"目录 + 按需加载"的模式，类似于操作系统的"按需分页"（Demand Paging）——不预先加载所有内容，而是在实际访问时才加载。

14.2.4 Skill 查询 API

Skill 模块暴露了三个公开方法：

// 获取单个 Skill
export async function get(name: string): Promise<Info | undefined> {
  return state().then((x) => x.skills[name])
}

// 获取所有 Skill
export async function all(): Promise<Info[]> {
  return state().then((x) => Object.values(x.skills))
}

// 获取所有 Skill 目录
export async function dirs(): Promise<string[]> {
  return state().then((x) => x.dirs)
}

这些 API 被以下消费者使用：

消费者	使用的 API	用途
skill 工具	Skill.get(name)	加载指定 Skill 的内容
System Prompt 构建器	Skill.all()	获取 Skill 列表展示给 Agent
Tool Registry	Skill.dirs()	从 Skill 目录加载自定义工具
Command 模块	Skill.all()	将 Skill 注册为 Slash Command

14.2.5 小结

Skill 的加载流程遵循"延迟加载"原则：

Instance 启动
  ↓
Skill 发现：扫描所有路径，构建 Skill 索引
  ↓
System Prompt：将 Skill 名称和描述列表注入 Agent
  ↓
Agent 运行中：根据需要调用 skill 工具
  ↓
Skill 内容注入对话上下文
  ↓
Agent 行为受 Skill 指导

这种两阶段设计（先发现索引，再按需加载内容）是上下文窗口资源有限情况下的最优策略。