第15章技能系统 —— 按需注入领域知识

2026-05-23 约 1600 字预计阅读 8 分钟

上一篇我们剖析了 MCP 的扩展机制。本章我们看技能系统——按需注入领域知识的 Markdown 文件。

技能系统是什么

一句话定义：按需注入的领域知识 Markdown 文件——技术文档、编码规范、领域知识。

Skills = 按需加载的领域知识定位：Harness 的扩展层核心，增强 Model 的领域知识

图表代码

graph LR
    SkillsList[Skills 列表
只有目录信息] -->|Model 判断需要| Load[加载 Skills
读取 Markdown]
    Load -->|注入| Context[上下文 messages
增强推理]
    Context -->|推理| Model[Model 推理
领域知识增强]graph LR
    SkillsList[Skills 列表
只有目录信息] -->|Model 判断需要| Load[加载 Skills
读取 Markdown]
    Load -->|注入| Context[上下文 messages
增强推理]
    Context -->|推理| Model[Model 推理
领域知识增强]graph LR
    SkillsList[Skills 列表
只有目录信息] -->|Model 判断需要| Load[加载 Skills
读取 Markdown]
    Load -->|注入| Context[上下文 messages
增强推理]
    Context -->|推理| Model[Model 推理
领域知识增强]

graph LR
    SkillsList[Skills 列表<br/>只有目录信息] -->|Model 判断需要| Load[加载 Skills<br/>读取 Markdown]
    Load -->|注入| Context[上下文 messages<br/>增强推理]
    Context -->|推理| Model[Model 推理<br/>领域知识增强]

核心机制：

Skills 目录：列出可用 Skills（只有名称和简要描述）
按需加载：Model 判断需要后加载具体内容
Markdown 格式：Skills 使用 Markdown 文件存储
上下文注入：加载后注入 messages 数组

技能系统设计理念

格言

“用到时再加载, 别全塞 prompt 里” —— 技能先列目录，用到时再展开

设计原理

问题：前置塞入所有领域知识会占用大量 tokens。

解决方案：按需加载，Model 判断需要后才加载。

方案	Token 占用	优点	缺点
前置塞入全部	20K+ tokens	Model 无需判断	占用大量上下文
按需加载	2K-5K tokens（按需）	节省上下文	需 Model 判断

图表代码

graph TB
    subgraph Before["前置塞入全部（旧方案）"]
        B1[全部 Skills
20K+ tokens]
        B2[占用大量上下文]
    end
    
    subgraph After["按需加载（新方案）"]
        A1[Skills 目录
500 tokens]
        A2[按需加载
2K-5K tokens]
    end
    
    Before -->|优化| After
    
    style Before fill:#FFE0E0
    style After fill:#E0FFE0graph TB
    subgraph Before["前置塞入全部（旧方案）"]
        B1[全部 Skills
20K+ tokens]
        B2[占用大量上下文]
    end
    
    subgraph After["按需加载（新方案）"]
        A1[Skills 目录
500 tokens]
        A2[按需加载
2K-5K tokens]
    end
    
    Before -->|优化| After
    
    style Before fill:#FFE0E0
    style After fill:#E0FFE0graph TB
    subgraph Before["前置塞入全部（旧方案）"]
        B1[全部 Skills
20K+ tokens]
        B2[占用大量上下文]
    end
    
    subgraph After["按需加载（新方案）"]
        A1[Skills 目录
500 tokens]
        A2[按需加载
2K-5K tokens]
    end
    
    Before -->|优化| After
    
    style Before fill:#FFE0E0
    style After fill:#E0FFE0

graph TB
    subgraph Before["前置塞入全部（旧方案）"]
        B1[全部 Skills<br/>20K+ tokens]
        B2[占用大量上下文]
    end
    
    subgraph After["按需加载（新方案）"]
        A1[Skills 目录<br/>500 tokens]
        A2[按需加载<br/>2K-5K tokens]
    end
    
    Before -->|优化| After
    
    style Before fill:#FFE0E0
    style After fill:#E0FFE0

Skills 类型

Skills 分类

Skills 类型	内容	Token 数量	适用场景
CLAUDE.md	项目约定、架构、注意事项	1K-3K	每个项目
技术 Skills	编程语言、框架用法	2K-10K	技术开发
规范 Skills	编码规范、测试要求	1K-5K	质量保证
领域 Skills	业务规则、合规要求	2K-10K	特定领域
工作 Skills	工作流程、操作指南	1K-5K	特定操作

图表代码

graph TB
    subgraph SkillsTypes["Skills 类型"]
        T1[CLAUDE.md
项目约定]
        T2[技术 Skills
编程语言/框架]
        T3[规范 Skills
编码规范/测试]
        T4[领域 Skills
业务规则]
        T5[工作 Skills
工作流程]
    endgraph TB
    subgraph SkillsTypes["Skills 类型"]
        T1[CLAUDE.md
项目约定]
        T2[技术 Skills
编程语言/框架]
        T3[规范 Skills
编码规范/测试]
        T4[领域 Skills
业务规则]
        T5[工作 Skills
工作流程]
    endgraph TB
    subgraph SkillsTypes["Skills 类型"]
        T1[CLAUDE.md
项目约定]
        T2[技术 Skills
编程语言/框架]
        T3[规范 Skills
编码规范/测试]
        T4[领域 Skills
业务规则]
        T5[工作 Skills
工作流程]
    end

graph TB
    subgraph SkillsTypes["Skills 类型"]
        T1[CLAUDE.md<br/>项目约定]
        T2[技术 Skills<br/>编程语言/框架]
        T3[规范 Skills<br/>编码规范/测试]
        T4[领域 Skills<br/>业务规则]
        T5[工作 Skills<br/>工作流程]
    end

CLAUDE.md —— 项目 Skills

一句话定义：项目根目录的 Markdown 文件，包含项目约定、架构、注意事项。

CLAUDE.md = 项目级 Skills 定位：自动注入到上下文，告知 Model 项目特定信息

内容结构：

# Project Guidelines

## Architecture
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL

## Conventions
- Use TypeScript strict mode
- Follow ESLint rules
- Write unit tests for new features

## Important Notes
- Never modify database schema without migration
- Always run tests before commit
- Use environment variables for secrets

注入方式：自动注入到 System Prompt。

图表代码

graph LR
    CLAUDE[CLAUDE.md
项目约定] -->|自动注入| System[System Prompt]
    System -->|发送| Model[Model 推理]graph LR
    CLAUDE[CLAUDE.md
项目约定] -->|自动注入| System[System Prompt]
    System -->|发送| Model[Model 推理]graph LR
    CLAUDE[CLAUDE.md
项目约定] -->|自动注入| System[System Prompt]
    System -->|发送| Model[Model 推理]

graph LR
    CLAUDE[CLAUDE.md<br/>项目约定] -->|自动注入| System[System Prompt]
    System -->|发送| Model[Model 推理]

技术 Skills

示例：Python Patterns：

# Python Patterns Skill

## Immutable Patterns
- Always create new objects, NEVER mutate existing ones
- Use update() instead of modify()

## File Organization
- Many small files > Few large files
- 200-400 lines typical, 800 max
- Extract utilities from large modules

## Error Handling
- Handle errors explicitly at every level
- Provide user-friendly messages in UI
- Log detailed context on server side

## Testing
- Minimum 80% test coverage
- TDD: Write test first (RED) → Implement (GREEN) → Refactor

按需加载触发：Model 判断需要 Python 编程知识时加载。

规范 Skills

示例：Testing Guide：

# Testing Guide Skill

## Test Coverage
- Minimum: 80% coverage
- Target: 90% for critical paths

## Test Types
- Unit Tests: Individual functions
- Integration Tests: API endpoints
- E2E Tests: Critical user flows

## TDD Workflow
1. Write test first (RED)
2. Run test - should FAIL
3. Write minimal implementation (GREEN)
4. Run test - should PASS
5. Refactor (IMPROVE)
6. Verify coverage >= 80%

按需加载触发：Model 判断需要写测试时加载。

Skills 加载流程

完整流程

图表代码

sequenceDiagram
    participant Model as Model 推理
    participant System as System Prompt
    participant Registry as Skills 注册表
    participant Loader as Skills 加载器
    participant Files as Skills 文件
    
    System->>Model: 注入 Skills 列表（目录）
    Model->>Model: 判断需要哪些 Skills
    
    Model->>Registry: 查询 Skills 文件路径
    Registry-->>Model: 返回路径
    
    Model->>Loader: 请求加载 Skills
    Loader->>Files: 读取 Markdown 文件
    Files-->>Loader: 返回内容
    Loader-->>Model: 注入到上下文
    
    Model->>Model: 增强推理sequenceDiagram
    participant Model as Model 推理
    participant System as System Prompt
    participant Registry as Skills 注册表
    participant Loader as Skills 加载器
    participant Files as Skills 文件
    
    System->>Model: 注入 Skills 列表（目录）
    Model->>Model: 判断需要哪些 Skills
    
    Model->>Registry: 查询 Skills 文件路径
    Registry-->>Model: 返回路径
    
    Model->>Loader: 请求加载 Skills
    Loader->>Files: 读取 Markdown 文件
    Files-->>Loader: 返回内容
    Loader-->>Model: 注入到上下文
    
    Model->>Model: 增强推理sequenceDiagram
    participant Model as Model 推理
    participant System as System Prompt
    participant Registry as Skills 注册表
    participant Loader as Skills 加载器
    participant Files as Skills 文件
    
    System->>Model: 注入 Skills 列表（目录）
    Model->>Model: 判断需要哪些 Skills
    
    Model->>Registry: 查询 Skills 文件路径
    Registry-->>Model: 返回路径
    
    Model->>Loader: 请求加载 Skills
    Loader->>Files: 读取 Markdown 文件
    Files-->>Loader: 返回内容
    Loader-->>Model: 注入到上下文
    
    Model->>Model: 增强推理

sequenceDiagram
    participant Model as Model 推理
    participant System as System Prompt
    participant Registry as Skills 注册表
    participant Loader as Skills 加载器
    participant Files as Skills 文件
    
    System->>Model: 注入 Skills 列表（目录）
    Model->>Model: 判断需要哪些 Skills
    
    Model->>Registry: 查询 Skills 文件路径
    Registry-->>Model: 返回路径
    
    Model->>Loader: 请求加载 Skills
    Loader->>Files: 读取 Markdown 文件
    Files-->>Loader: 返回内容
    Loader-->>Model: 注入到上下文
    
    Model->>Model: 增强推理

加载实现

# Skills 按需加载实现

# 1. Skills 目录（System Prompt 注入）
skills_list = """
可用 Skills：
- python-patterns: Python 编程模式（用到 Python 时加载）
- testing-guide: 测试指南（写测试时加载）
- api-design: API 设计规范（设计 API 时加载）
- security-review: 安全审查指南（审查安全时加载）
"""

# System Prompt 注入 Skills 列表
system_prompt = base_system_prompt + skills_list

# 2. Model 判断需要后加载
if need_skill("testing-guide"):
    # 读取 Skills 文件
    skill_path = "skills/testing-guide.md"
    skill_content = read_file(skill_path)
    
    # 注入到 messages
    messages.append({
        "role": "user",
        "content": f"Skills: testing-guide\n\n{skill_content}"
    })

Skills 注册表

注册表结构：

{
  "skills": {
    "python-patterns": {
      "name": "python-patterns",
      "description": "Python 编程模式",
      "path": "skills/python-patterns.md",
      "trigger_keywords": ["python", "Python", "pytest", "django"]
    },
    "testing-guide": {
      "name": "testing-guide",
      "description": "测试指南",
      "path": "skills/testing-guide.md",
      "trigger_keywords": ["test", "testing", "coverage", "TDD"]
    },
    "api-design": {
      "name": "api-design",
      "description": "API 设计规范",
      "path": "skills/api-design.md",
      "trigger_keywords": ["API", "REST", "endpoint", "GraphQL"]
    }
  }
}

触发关键词：Model 的响应中包含触发关键词时加载 Skills。

Skills 文件格式

Markdown 结构

推荐结构：

# Skills 名称

## 一句话定义
[一句话描述 Skills 用途]

## 核心内容

### 内容章节1
[具体知识]

### 内容章节2
[具体知识]

## 最佳实践
[推荐做法]

## 注意事项
[重要提醒]

## 示例
[代码或配置示例]

Skills 文件示例

# React Hooks Guide

## 一句话定义
React Hooks 使用指南——useState、useEffect、useContext 等核心 Hook 用法。

## 核心内容

### useState
- 用于管理组件状态
- 返回 [state, setState]
- setState 可以接收新值或函数

```typescript
const [count, setCount] = useState(0);
setCount(prev => prev + 1);  // 函数式更新

useEffect

用于副作用处理
第二参数控制依赖
cleanup 函数清理副作用

useEffect(() => {
  const timer = setInterval(() => setCount(c => c + 1), 1000);
  return () => clearInterval(timer);  // cleanup
}, [setCount]);  // 依赖数组

最佳实践

不要在循环、条件或嵌套函数中调用 Hook
使用 useCallback 缓存函数
使用 useMemo 缓存计算结果

注意事项

useEffect 依赖数组必须完整
cleanup 函数必须返回
避免过度使用 useMemo（性能权衡）


## Skills 目录结构

### 目录组织

skills/ ├── README.md # Skills 说明文档 ├── python-patterns.md # Python 编程模式 ├── testing-guide.md # 测试指南 ├── api-design.md # API 设计规范 ├── security-review.md # 安全审查指南 ├── react-hooks.md # React Hooks 指南 ├── database-patterns.md # 数据库模式 └── git-workflow.md # Git 工作流


### Skills README

**README.md 内容**：

```markdown
# Skills 目录

本目录包含按需加载的领域知识 Skills。

## 可用 Skills

| Skills | 描述 | 适用场景 |
|--------|------|---------|
| python-patterns | Python 编程模式 | Python 开发 |
| testing-guide | 测试指南 | 写测试 |
| api-design | API 设计规范 | 设计 API |
| security-review | 安全审查指南 | 安全审查 |
| react-hooks | React Hooks 指南 | React 开发 |
| database-patterns | 数据库模式 | 数据库设计 |
| git-workflow | Git 工作流 | Git 操作 |

## 加载机制

Skills 按需加载，Model 判断需要后自动加载。

Skills vs 内置知识

对比

维度	Skills	内置知识（System Prompt）
加载方式	✅ 按需加载	❌ 前置塞入
Token 占用	✅ 小（按需）	❌ 大（全部）
可定制	✅ Markdown 文件可编辑	❌ 硬编码
领域知识	✅ 丰富（任意 Skills）	❌ 有限（只有基础）
项目级	✅ CLAUDE.md 项目特定	❌ 全局通用

图表代码

graph TB
    subgraph Skills["Skills 按需加载"]
        S1[按需加载]
        S2[Token 小]
        S3[可定制]
        S4[领域丰富]
        S5[项目级 CLAUDE.md]
    end
    
    subgraph BuiltIn["内置知识"]
        B1[前置塞入]
        B2[Token 大]
        B3[硬编码]
        B4[领域有限]
        B5[全局通用]
    end
    
    style Skills fill:#E0FFE0
    style BuiltIn fill:#FFE0E0graph TB
    subgraph Skills["Skills 按需加载"]
        S1[按需加载]
        S2[Token 小]
        S3[可定制]
        S4[领域丰富]
        S5[项目级 CLAUDE.md]
    end
    
    subgraph BuiltIn["内置知识"]
        B1[前置塞入]
        B2[Token 大]
        B3[硬编码]
        B4[领域有限]
        B5[全局通用]
    end
    
    style Skills fill:#E0FFE0
    style BuiltIn fill:#FFE0E0graph TB
    subgraph Skills["Skills 按需加载"]
        S1[按需加载]
        S2[Token 小]
        S3[可定制]
        S4[领域丰富]
        S5[项目级 CLAUDE.md]
    end
    
    subgraph BuiltIn["内置知识"]
        B1[前置塞入]
        B2[Token 大]
        B3[硬编码]
        B4[领域有限]
        B5[全局通用]
    end
    
    style Skills fill:#E0FFE0
    style BuiltIn fill:#FFE0E0

graph TB
    subgraph Skills["Skills 按需加载"]
        S1[按需加载]
        S2[Token 小]
        S3[可定制]
        S4[领域丰富]
        S5[项目级 CLAUDE.md]
    end
    
    subgraph BuiltIn["内置知识"]
        B1[前置塞入]
        B2[Token 大]
        B3[硬编码]
        B4[领域有限]
        B5[全局通用]
    end
    
    style Skills fill:#E0FFE0
    style BuiltIn fill:#FFE0E0

协作关系

Skills + 内置知识：

图表代码

graph LR
    subgraph Knowledge["知识来源"]
        BuiltIn[内置知识
System Prompt
工具定义]
        CLAUDE[CLAUDE.md
项目约定]
        Skills[Skills 按需加载
领域知识]
    end
    
    Knowledge -->|注入| Model[Model 推理]graph LR
    subgraph Knowledge["知识来源"]
        BuiltIn[内置知识
System Prompt
工具定义]
        CLAUDE[CLAUDE.md
项目约定]
        Skills[Skills 按需加载
领域知识]
    end
    
    Knowledge -->|注入| Model[Model 推理]graph LR
    subgraph Knowledge["知识来源"]
        BuiltIn[内置知识
System Prompt
工具定义]
        CLAUDE[CLAUDE.md
项目约定]
        Skills[Skills 按需加载
领域知识]
    end
    
    Knowledge -->|注入| Model[Model 推理]

graph LR
    subgraph Knowledge["知识来源"]
        BuiltIn[内置知识<br/>System Prompt<br/>工具定义]
        CLAUDE[CLAUDE.md<br/>项目约定]
        Skills[Skills 按需加载<br/>领域知识]
    end
    
    Knowledge -->|注入| Model[Model 推理]

分工：

内置知识：工具定义、约束规则、格式要求
CLAUDE.md：项目约定、架构、注意事项（自动注入）
Skills 按需加载：技术知识、领域知识（按需注入）

Skills 的最佳实践

Skills 文件编写

编写要点：

要点	说明	示例
一句话定义	开头一句话描述用途	“Python 编程模式指南”
结构清晰	分章节组织内容	核心内容、最佳实践、注意事项
示例丰富	包含代码或配置示例	`useState` 用法示例
触发关键词	包含关键词触发加载	“test”、“Python”、“API”

Skills 加载优化

优化建议：

建议	说明	效果
Skills 文件精简	只包含必要内容	减少 Token
触发关键词精确	避免过度触发	减少不必要加载
分层 Skills	分为基础/高级 Skills	按深度加载

Skills 目录管理

管理建议：

建议	说明
定期更新	Skills 内容随技术演进更新
分类组织	按类型分类（技术/规范/领域）
版本控制	Skills 文件 Git 管理
README 维护	README 保持最新

Skills 生态

开源 Skills 集合

项目	Skills 类型	说明
cc-harness-skills	内存、验证、多 Agent	Skills 示例库
agent-rules-books	编码规则（Clean Code、DDD）	规则集合

企业 Skills 定制

企业 Skills 内容：

企业 Skills	内容	用途
企业架构规范	架构约定、技术选型	企业项目
业务规则	业务逻辑、合规要求	特定业务
安全规范	安全审查、合规检查	安全保证
API 规范	API 设计、接口约定	API 开发

本章小结

技能系统定义：按需注入的领域知识 Markdown 文件
设计格言：用到时再加载，别全塞 prompt 里
Skills 类型：CLAUDE.md（项目）、技术 Skills、规范 Skills、领域 Skills、工作 Skills
CLAUDE.md：项目约定、架构、注意事项，自动注入
加载流程：Skills 列表注入 → Model 判断 → 查询路径 → 读取文件 → 注入上下文
Markdown 结构：一句话定义 → 核心内容 → 最佳实践 → 注意事项 → 示例
Skills 注册表：名称、描述、路径、触发关键词
Skills vs 内置知识：Skills 按需加载可定制，内置知识前置塞入硬编码
协作关系：内置知识（工具定义）+ CLAUDE.md（项目约定）+ Skills（领域知识）
最佳实践：精简文件、精确关键词、分类组织、定期更新
Skills 生态：开源 Skills 集合 + 企业 Skills 定制

预告：下一篇我们进入第五部分——Agent 与 Harness 的协作模式。

☕ 如果这篇文章对你有帮助

欢迎请我喝杯咖啡，你的支持是我持续创作的动力 ❤️

捐赠支持 GitHub Sponsors

第15章 技能系统 —— 按需注入领域知识

技能系统是什么

技能系统设计理念

格言

设计原理

Skills 类型

Skills 分类

CLAUDE.md —— 项目 Skills

技术 Skills

规范 Skills

Skills 加载流程

完整流程

加载实现

Skills 注册表

Skills 文件格式

Markdown 结构

Skills 文件示例

useEffect

最佳实践

注意事项

Skills vs 内置知识

对比

协作关系

Skills 的最佳实践

Skills 文件编写

Skills 加载优化

Skills 目录管理

Skills 生态

开源 Skills 集合

企业 Skills 定制

本章小结

相关内容

第15章技能系统 —— 按需注入领域知识