核心概念

Skills 系统

动态知识库注入和领域专业化能力

Skills 系统

Skills 是 AgentSDK 的动态知识库注入系统，允许您为 Agent 添加领域专业知识、工作流程和最佳实践，而无需修改系统提示词或重新训练模型。

🎯 核心概念

Skills 系统通过 Injector（注入器） 在运行时动态加载和注入知识库内容，使 Agent 能够根据上下文自动激活相关技能。

用户消息 → Trigger检测 → 加载Skills → 注入知识库 → Agent处理
    ↓
"写小说"  →  keyword触发  → consistency-checker.md → 注入到Prompt → Claude思考

Skills vs 其他扩展方式

特性	Skills	Custom Tools	Slash Commands
用途	知识库注入	执行操作	快捷指令
触发方式	自动/关键词	Agent主动调用	用户输入
内容形式	Markdown文档	Go代码	命令脚本
适用场景	领域知识、规范	文件操作、API	快速启动

📦 Skill 定义

Skill 目录结构

Skill 使用目录结构组织，而不是单个文件。每个 Skill 是一个独立目录，包含定义文件和可选的工具脚本：

workspace/skills/
├── markdown-segment-translator/
│   ├── SKILL.md                    # Skill定义文件
│   └── scripts/
│       └── segment_tool.py         # Python工具脚本
├── pdf/
│   ├── SKILL.md
│   ├── README.md                   # 详细说明（可选）
│   └── scripts/
│       ├── pdf_to_markdown.py
│       └── fill_pdf_form.py
├── pdfmd/
│   ├── SKILL.md
│   └── pdf_extract.py
└── consistency-checker/
    └── SKILL.md

目录要求：

✅ 必须包含 SKILL.md 定义文件
❌ 可选：scripts/ 工具脚本目录
❌ 可选：README.md 详细文档
❌ 可选：其他资源文件

SKILL.md 文件格式

Skill 定义文件使用 Markdown 格式，包含 YAML 元数据和知识库内容：

---
name: markdown-segment-translator
description: 将长Markdown文档分段翻译，保持格式和术语准确性
allowed-tools: ["Bash", "Read", "Write"]
triggers:
  - type: keyword
    keywords: ["翻译", "translate", "translation"]
  - type: file
    extensions: [".md"]
version: 2.0.0  # 可选：版本号
---

# Markdown 分段翻译技能

## 功能说明

此技能专门用于翻译长Markdown文档，采用分段处理策略，避免单次翻译超时。

### 核心特性

- 自动分段（默认200行/段）
- 保持Markdown格式
- 学术术语优化
- 自动合并结果

## 使用方法

### 3步工作流

1. **分段**: 使用Bash调用segment_tool.py segment
2. **翻译**: 对每个segment使用Agent的LLM翻译
3. **合并**: 使用Bash调用segment_tool.py merge

### 严格规则

⚠️ Agent必须严格遵守：

1. **禁止**: 不要一次性翻译整个文档
2. **必须**: 使用Bash执行Python脚本
3. **必须**: 使用LLM逐段翻译
4. **必须**: 保持Markdown格式完整

完整示例请查看：Markdown翻译器详解

元数据字段说明

字段	类型	必需	说明
`name`	string	✅	Skill唯一标识符
`description`	string	✅	Skill功能描述
`allowed-tools`	string	❌	允许使用的工具列表
`triggers`	Trigger	✅	触发条件列表

🔔 触发机制

Skills 支持四种触发方式，可以单独使用或组合使用。

1. 关键词触发（keyword）

当用户消息包含特定关键词时自动激活：

triggers:
  - type: keyword
    keywords: ["一致性", "检查", "consistency", "verify"]

示例：

// 用户输入："帮我检查一下角色一致性"
// → 触发 consistency-checker Skill

2. 上下文触发（context）

在特定命令或状态下激活：

triggers:
  - type: context
    condition: "during /write"

适用场景：

特定 Slash Command 执行期间
特定工作流程阶段
Agent 处于特定模式

3. 总是激活（always）

无条件激活，始终注入知识库：

triggers:
  - type: always

适用场景：

核心工作规范
必须遵守的安全准则
通用最佳实践

4. 文件扩展名触发（file）

当操作特定扩展名的文件时激活：

triggers:
  - type: file
    extensions: [".md", ".txt"]

适用场景：

Markdown文档处理
PDF文件操作
特定文件类型专用知识

示例：

// 用户输入："翻译 document.md"
// → 触发 markdown-segment-translator Skill（关键词 + 文件扩展名）

组合触发

可以为一个 Skill 定义多个触发条件，任一条件满足即激活：

triggers:
  - type: keyword
    keywords: ["翻译", "translate"]
  - type: file
    extensions: [".md"]
  - type: context
    condition: "during /translate"

这样设计的好处：

关键词触发：用户明确表达翻译意图
文件触发：自动识别Markdown文件
上下文触发：在翻译命令期间自动激活

⚙️ Skills 注入流程

┌─────────────────┐
│  用户发送消息   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Injector检测   │  遍历所有Skill的触发条件
│  触发条件       │
└────────┬────────┘
         │
         ▼
    ┌────┴────┐
    │  匹配？  │
    └────┬────┘
         │ 是
         ▼
┌─────────────────┐
│  加载Skill内容  │  从文件系统/OSS/S3加载
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  注入策略选择   │
└────────┬────────┘
         │
    ┌────┴────┐
    │ 模型支持 │
    │SystemPrompt?│
    └────┬────┘
         │
    ┌────┴────┐
    │   是    │   否
    ▼         ▼
┌────────┐ ┌────────┐
│注入到   │ │注入到   │
│System   │ │User    │
│Prompt   │ │Message │
└────┬───┘ └────┬───┘
     │          │
     └────┬─────┘
          ▼
    ┌─────────────┐
    │  发送给LLM  │
    └─────────────┘

注入策略

AgentSDK 根据模型能力自动选择注入位置：

支持 System Prompt 的模型（如 Claude、GPT-4）：

System Prompt:
  [原始系统提示词]

  ## Activated Skills

  ### consistency-checker
  [Skill内容]

User Message:
  [用户消息]

不支持 System Prompt 的模型（如部分国产模型）：

User Message:
  ## Knowledge Base

  ### consistency-checker
  [Skill内容]

  ---

  [用户消息]

多 Skill 组合

当多个 Skill 同时激活时，它们会按名称排序后依次注入：

## Activated Skills

### coding-standards
[内容...]

### security-checklist
[内容...]

### test-guidelines
[内容...]

📁 Skills Package 组织

目录结构

workspace/
└── skills/
    ├── markdown-segment-translator/
    │   ├── SKILL.md
    │   └── scripts/
    │       └── segment_tool.py
    ├── pdf/
    │   ├── SKILL.md
    │   └── scripts/
    ├── pdfmd/
    │   ├── SKILL.md
    │   └── pdf_extract.py
    └── consistency-checker/
        └── SKILL.md

加载配置

在 Agent 配置中指定 Skills Package 位置：

ag, err := agent.Create(ctx, &types.AgentConfig{
    TemplateID: "assistant",
    SkillsPackageConfig: &types.SkillsPackageConfig{
        Path: "./workspace/skills",
    },
    ModelConfig: &types.ModelConfig{
        ExecutionMode: types.ExecutionModeNonStreaming, // 配合Skills优化性能
    },
    // ... 其他配置
}, deps)

内置 Skills 示例

AgentSDK 提供了4个生产级 Skills 示例，可直接使用或作为参考：

Skill	功能	适用场景
markdown-segment-translator	Markdown分段翻译	文档翻译、性能优化
pdf	PDF处理工具集	PDF转换、表单填写
pdfmd	PDF快速提取	学术论文阅读
consistency-checker	写作一致性检查	创意写作

查看所有示例：Skills 示例

支持的存储方式

存储类型	Path 格式	说明
本地文件系统	`./path/to/skills`	开发测试推荐
阿里云OSS	`oss://bucket/prefix`	生产环境推荐
AWS S3	`s3://bucket/prefix`	跨区域部署
HTTP(S)	`https://cdn.com/skills`	CDN分发

🎨 使用场景

1. 写作助手

---
name: writing-coach
description: 提供写作技巧和风格建议
triggers:
  - type: keyword
    keywords: ["写作", "文章", "blog"]
---

# 写作最佳实践

## 结构
- 开头：吸引注意力的钩子
- 中间：逻辑清晰的论述
- 结尾：有力的总结

## 风格
- 使用主动语态
- 避免冗余表达
- 保持段落简短

2. 代码审查

---
name: go-code-review
description: Go语言代码审查标准
allowed-tools: ["Read", "Grep"]
triggers:
  - type: file_pattern
    pattern: "**/*.go"
  - type: keyword
    keywords: ["review", "审查"]
---

# Go代码审查清单

## 错误处理
- 所有错误必须检查
- 使用errors.Is/As判断错误类型
- 返回有意义的错误信息

## 并发安全
- 检查共享数据的保护
- 避免goroutine泄漏
- 正确使用context

3. 文档处理

实际生产环境的 Skill 示例，支持大文档分段处理：

---
name: markdown-segment-translator
description: 自动分段翻译长Markdown文档
allowed-tools: ["Bash", "Read", "Write"]
triggers:
  - type: keyword
    keywords: ["翻译", "translate"]
  - type: file
    extensions: [".md"]
---

# Markdown 分段翻译

## 性能优化

- 自动分段：200行/段，避免超时
- 并行处理：可同时处理多个段落
- 格式保持：完整保留Markdown语法
- 断点续传：支持中断后继续

## 使用流程

1. 分段：segment_tool.py segment --input doc.md
2. 翻译：Agent逐段翻译
3. 合并：segment_tool.py merge

查看完整实现和性能数据

🚀 最佳实践

1. Skill 粒度设计

2. 触发条件选择

always：仅用于核心规范和安全准则
keyword：用于可选的专业知识
context：用于特定流程阶段
file_pattern：用于文件类型专用规范

3. 知识库内容组织

# Skill 名称

## 概述
简短说明 Skill 的用途

## 核心规则
关键规则和原则

## 检查清单
可操作的步骤列表

## 示例
正确和错误的对比示例

## 参考资料
相关文档链接

4. 性能优化

Skill 大小控制：

推荐大小：≤ 2000 tokens/Skill
延迟加载：避免使用过多 always 触发
缓存策略：频繁使用的 Skill 可以预加载

分段处理策略：对于大文档处理类 Skill（如翻译），采用分段策略：

自动分段：200-500行/段
配合 ExecutionMode.NonStreaming 加速
实测可获得 3-5 倍性能提升

示例：

// 配置非流式模式以优化Skills性能
ModelConfig: &types.ModelConfig{
    ExecutionMode: types.ExecutionModeNonStreaming,
}

查看性能优化详情

5. 版本管理

skills/
├── v1/
│   ├── coding-standards.md
│   └── security-checklist.md
└── v2/
    ├── coding-standards.md  (新版本)
    └── security-checklist.md

🔗 相关资源

Skills 示例 - 4个生产级Skills实现
Markdown翻译器详解 - 完整的分段处理示例
API 参考 - Skills API 文档
最佳实践 - 高级技巧和模式

⚡ 快速开始

# 1. 创建 Skills 目录
mkdir -p workspace/skills

# 2. 创建你的第一个 Skill（目录结构）
mkdir -p workspace/skills/helper
cat > workspace/skills/helper/SKILL.md << 'EOF'
---
name: helper
description: 通用助手技能
allowed-tools: ["Read", "Write"]
triggers:
  - type: keyword
    keywords: ["帮助", "help"]
---

# 助手指南

我可以帮你：
- 回答问题
- 编写代码
- 审查文档
- 优化性能

请告诉我你需要什么帮助！
EOF

# 3. 在代码中启用 Skills
# 见上文"加载配置"部分

下一步：访问 Skills 示例查看4个生产级实现，包括性能优化的Markdown翻译器、完整的PDF处理工具集等。

Edit this pageorReport an issue

模型路由(Model Routing)

使用 Router 在多模型之间进行简单路由，支持 cost-first / quality-first 等策略

Context Window Management

上下文窗口管理 - Token计数、智能压缩和自动优化