analysis_claude_code/docs/v4-Skills机制.md

v4: Skills 机制

核心洞察：Skills 是知识包，不是工具。

知识外化：从训练到编辑的范式转变

Skills 机制体现了一个深刻的范式转变：知识外化 (Knowledge Externalization)。

传统方式：知识内化于参数

传统 AI 系统的知识都藏在模型参数里。你没法访问、没法修改、没法复用。

想让模型学会新技能？你需要：

1. 收集大量训练数据
2. 设置分布式训练集群
3. 进行复杂的参数微调（LoRA、全量微调等）
4. 部署新模型版本

这就像大脑突然失忆，但你没有任何笔记可以恢复记忆。知识被锁死在神经网络的权重矩阵中，对用户完全不透明。

新范式：知识外化为文档

代码执行范式改变了这一切。

┌─────────────────────────────────────────────────────────────────┐
│                     知识存储层级                                  │
│                                                                  │
│  Model Parameters → Context Window → File System → Skill Library │
│       (内化)            (运行时)        (持久化)      (结构化)     │
│                                                                  │
│  ←───────── 训练修改 ──────────→  ←────── 自然语言修改 ─────────→  │
│     需要集群、数据、专业知识              任何人都可以编辑           │
└─────────────────────────────────────────────────────────────────┘

关键突破：

• 过去：修改模型行为 = 修改参数 = 需要训练 = 需要 GPU 集群 + 训练数据 + 专业知识
• 现在：修改模型行为 = 修改 SKILL.md = 编辑文本文件 = 任何人都可以做

这就像给 base model 外挂了一个可热插拔的 LoRA 权重，但你不需要对模型本身进行任何参数训练。

为什么这很重要

1. 民主化：不再需要 ML 专业知识来定制模型行为
2. 透明性：知识以人类可读的 Markdown 存储，可审计、可理解
3. 复用性：一个 Skill 写一次，可以在任何兼容 Agent 上使用
4. 版本控制：Git 管理知识变更，支持协作和回滚
5. 在线学习：模型在更大的上下文窗口中"学习"，无需离线训练

传统的微调是离线学习：收集数据→训练→部署→使用。 Skills 是在线学习：运行时按需加载知识，立即生效。

知识层级对比

层级	修改方式	生效时间	持久性	成本
Model Parameters	训练/微调	数小时-数天	永久	$10K-$1M+
Context Window	API 调用	即时	会话内	~$0.01/次
File System	编辑文件	下次加载	永久	免费
Skill Library	编辑 SKILL.md	下次触发	永久	免费

Skills 是最甜蜜的平衡点：持久化存储 + 按需加载 + 人类可编辑。

实际意义

假设你想让 Claude 学会你公司特有的代码规范：

传统方式：

1. 收集公司代码库作为训练数据
2. 准备微调脚本和基础设施
3. 运行 LoRA 微调（需要 GPU）
4. 部署自定义模型
5. 成本：$1000+ 和数周时间

Skills 方式：

# skills/company-standards/SKILL.md
---
name: company-standards
description: 公司代码规范和最佳实践
---

## 命名规范
- 函数名使用小写+下划线
- 类名使用 PascalCase
...

成本：0，时间：5分钟

这就是知识外化的力量：把需要训练才能编码的知识，变成任何人都能编辑的文档。

问题背景

v3 给了我们子代理来分解任务。但还有一个更深的问题：模型怎么知道如何处理特定领域的任务？

• 处理 PDF？需要知道用 pdftotext 还是 PyMuPDF
• 构建 MCP 服务器？需要知道协议规范和最佳实践
• 代码审查？需要一套系统的检查清单

这些知识不是工具——是专业技能。Skills 通过让模型按需加载领域知识来解决这个问题。

核心概念

1. 工具 vs 技能

概念	是什么	例子
Tool	模型能做什么	bash, read_file, write_file
Skill	模型知道怎么做	PDF 处理、MCP 构建

工具是能力，技能是知识。

2. 渐进式披露

Layer 1: 元数据 (始终加载)     ~100 tokens/skill
         └─ name + description

Layer 2: SKILL.md 主体 (触发时)   ~2000 tokens
         └─ 详细指南

Layer 3: 资源文件 (按需)        无限制
         └─ scripts/, references/, assets/

这让上下文保持轻量，同时允许任意深度的知识。

3. SKILL.md 标准

skills/
├── pdf/
│   └── SKILL.md          # 必需
├── mcp-builder/
│   ├── SKILL.md
│   └── references/       # 可选
└── code-review/
    ├── SKILL.md
    └── scripts/          # 可选

SKILL.md 格式：YAML 前置 + Markdown 正文

---
name: pdf
description: 处理 PDF 文件。用于读取、创建或合并 PDF。
---

# PDF 处理技能

## 读取 PDF

使用 pdftotext 快速提取：
\`\`\`bash
pdftotext input.pdf -
\`\`\`
...

实现（约 100 行新增）

SkillLoader 类

class SkillLoader:
    def __init__(self, skills_dir: Path):
        self.skills = {}
        self.load_skills()

    def parse_skill_md(self, path: Path) -> dict:
        """解析 YAML 前置 + Markdown 正文"""
        content = path.read_text()
        match = re.match(r'^---\s*\n(.*?)\n---\s*\n(.*)$', content, re.DOTALL)
        # 返回 {name, description, body, path, dir}

    def get_descriptions(self) -> str:
        """生成系统提示词的元数据"""
        return "\n".join(f"- {name}: {skill['description']}"
                        for name, skill in self.skills.items())

    def get_skill_content(self, name: str) -> str:
        """获取完整内容用于上下文注入"""
        return f"# Skill: {name}\n\n{skill['body']}"

Skill 工具

SKILL_TOOL = {
    "name": "Skill",
    "description": "加载技能获取专业知识。",
    "input_schema": {
        "properties": {"skill": {"type": "string"}},
        "required": ["skill"]
    }
}

消息注入（保持缓存）

关键洞察：Skill 内容进入 tool_result（user message 的一部分），而不是 system prompt：

def run_skill(skill_name: str) -> str:
    content = SKILLS.get_skill_content(skill_name)
    # 完整内容作为 tool_result 返回
    # 成为对话历史的一部分（user message）
    return f"""<skill-loaded name="{skill_name}">
{content}
</skill-loaded>

Follow the instructions in the skill above."""

def agent_loop(messages: list) -> list:
    while True:
        response = client.messages.create(
            model=MODEL,
            system=SYSTEM,  # 永不改变 - 缓存保持有效！
            messages=messages,
            tools=ALL_TOOLS,
        )
        # Skill 内容作为 tool_result 进入 messages...

关键洞察：

• Skill 内容作为新消息追加到末尾
• 之前的所有内容（system prompt + 历史消息）都被缓存复用
• 只有新追加的 skill 内容需要计算，整个前缀都命中缓存

与生产版本对比

机制	Claude Code / Kode	v4
格式	SKILL.md (YAML + MD)	相同
加载	Container API	SkillLoader 类
触发	自动 + Skill 工具	仅 Skill 工具
注入	newMessages (user message)	tool_result (user message)
缓存机制	追加到末尾，前缀全部缓存	追加到末尾，前缀全部缓存
版本控制	Skill Versions API	省略
权限	allowed-tools 字段	省略

关键共同点：两者都将 skill 内容注入对话历史（而非 system prompt），保持 prompt cache 有效。

为什么这很重要：缓存与成本

自回归模型与 KV Cache

大模型是自回归的：生成每个 token 都要 attend 之前所有 token。为避免重复计算，提供商实现了 KV Cache：

请求 1: [System, User1, Asst1, User2]
        ←────── 全部计算 ──────→

请求 2: [System, User1, Asst1, User2, Asst2, User3]
        ←────── 缓存命中 ──────→ ←─ 新计算 ─→
               (更便宜)            (正常价格)

缓存命中要求前缀完全相同。

需要注意的模式

操作	影响	结果
编辑历史	改变前缀	缓存无法复用
中间插入	后续前缀变化	需要重新计算
修改 system prompt	最前面变化	整个前缀需重新计算

推荐：只追加

# 避免: 编辑历史
messages[2]["content"] = "edited"  # 缓存失效

# 推荐: 只追加
messages.append(new_msg)  # 前缀不变，缓存命中

长上下文支持

主流模型支持较大的上下文窗口：

• Claude Sonnet 4.5 / Opus 4.5: 200K
• GPT-5.2: 256K+
• Gemini 3 Flash/Pro: 1M

200K tokens 约等于 15 万词，一本 500 页的书。对于大多数 Agent 任务，现有上下文窗口已经足够。

把上下文当作只追加日志，而非可编辑文档。

设计哲学：知识外化的实践

知识作为一等公民

回到开篇讨论的知识外化范式。传统观点：AI Agent 是"工具调用器"——模型决定用什么工具，代码执行工具。

但这忽略了一个关键维度：模型怎么知道应该怎么做？

Skills 是知识外化的完整实践：

过去（知识内化）：

• 知识锁在模型参数里
• 修改需要训练（LoRA、全量微调）
• 用户无法访问或理解
• 成本：$10K-$1M+，周期：数周

现在（知识外化）：

• 知识存在 SKILL.md 文件中
• 修改就是编辑文本
• 人类可读、可审计
• 成本：免费，周期：即时生效

Skills 承认：领域知识本身就是一种资源，需要被显式管理。

1. 分离元数据与内容：description 是索引，body 是内容
2. 按需加载：上下文窗口是宝贵的认知资源
3. 标准化格式：写一次，在任何兼容的 Agent 上使用
4. 注入而非返回：Skills 改变认知，不只是提供数据
5. 在线学习：在更大的上下文窗口中即时"学习"，无需离线训练

知识外化的本质是把隐式知识变成显式文档：

• 开发者用自然语言"教"模型新技能
• Git 管理和共享知识
• 版本控制、审计、回滚

这是从"训练 AI"到"教育 AI"的范式转变。

系列总结

版本	主题	新增行数	核心洞察
v1	Model as Agent	~200	模型是 80%，代码只是循环
v2	结构化规划	~100	Todo 让计划可见
v3	分而治之	~150	子代理隔离上下文
v4	领域专家	~100	Skills 注入专业知识

---

工具让模型能做事，技能让模型知道怎么做。