zhaoweiguo 的知识库

Agent Skill 加载机制

3分钟阅读

适用于 Claude Code / OpenClaw 生态的 skill 系统。

物理存储

~/.claude/skills/          # 全局 skill（npx skills install -g）
<project>/.claude/skills/  # 项目级 skill（npx skills install --local）

每个 skill 是一个目录，核心文件：

my-skill/
├── skill.md        # skill 定义：触发条件、描述、指令
└── (可选资源文件)

加载时机：两阶段懒加载

Skill 采用两阶段设计，核心思路是「用到什么知识，临时加载什么知识」，而非全量注入：

session start
  → harness 扫描 skills 目录
  → 读取每个 skill.md 的 YAML 元数据（name、description、触发条件）
  → 仅把轻量摘要注入 system prompt（~100 tokens/skill）
  → LLM 知道有哪些 skill、何时触发，但不知道完整指令内容

当 LLM 判断需要调用某个 skill 时：

运行时触发
  → Skill tool call
  → harness 读取 skill.md 全文，通过 tool_result 按需展开
  → LLM 获得完整指令，按 skill 执行

这是懒加载，不是全量注入。skill 越多，session 启动时的 token 消耗仍然可控，因为注入的只是摘要，而非全文。

两阶段注入示意

Layer 1（session 启动，始终存在）：
┌─────────────────────────────────────┐
│ Skills available:                   │  ~100 tokens/skill
│   - git: Git workflow helpers       │
│   - test: Testing best practices    │
└─────────────────────────────────────┘

Layer 2（按需加载，仅触发时注入）：
┌─────────────────────────────────────┐
│ tool_result:                        │  完整 skill 全文
│   <skill name="git">                │  可达数百到数千 tokens
│     Full git workflow instructions  │
│   </skill>                          │
└─────────────────────────────────────┘

触发机制

LLM 根据 skill.md 中的触发条件描述判断是否调用：

TRIGGER when: user asks to create a PR, merge code, or finish a branch
DO NOT TRIGGER when: user asks about git status or git log

优先级

  • 项目级 skill 优先于全局 skill（同名时覆盖）
  • npx skills install → 全局；npx skills install --local → 项目

关键设计约束

约束原因
skill 描述（摘要）要简洁session 启动阶段会注入摘要，摘要过长会直接抬高 token 成本
触发条件要精确避免误触发或漏触发
skill 全文可以很长只在触发时通过 tool_result 展开，不影响平时 token
session 期间 skill 列表固定session 启动后不支持动态注册新 skill

相关页面

关系图谱

反向链接