核心概念

Skills 系统

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

Skills 系统

Skills 是 aster 的基于文件系统的“技能包”系统。它允许你把领域知识、工作流程和最佳实践放在磁盘上，让 Agent 在需要时按步骤调用，而不是一次性把所有内容塞进提示词。

🎯 核心概念

从概念上看，一个 Skill 就像是给 Agent 加装的一个模块：

每个 Skill 是一个目录，至少包含：
- SKILL.md：YAML 元数据（name / description / allowed-tools 等） + 正文说明
- 可选脚本：例如 scripts/*.py、scripts/*.sh
- 可选额外文档：例如 README.md、forms.md
Agent 启动时只加载元数据，把 Skill 当成“可用能力”列在系统提示词 / 用户消息前缀中；
真正用到某个 Skill 时，模型会先用文件类工具（如 Read、Bash）打开对应的 SKILL.md，按其中说明去调用脚本和其它工具。

整体是一个三层渐进加载（progressive disclosure）的结构：

Level 1：元数据（总是加载）
- 只包含 name、description 和 SKILL.md 路径提示。
- 这些信息会在每轮对话前注入到 System Prompt / User Message 的 “Active Skills / Skills Overview” 区域。
Level 2：Skill 说明书（按需读取）
- SKILL.md 正文中描述详细步骤、约束和示例。
- 当模型判断某个 Skill 相关时，应先用工具读取该文件，再按照其中指令执行。
Level 3：脚本与资源（按需执行/引用）
- 包括脚本、附加 Markdown 文档等。
- 只在说明书中明确要求时，通过现有工具调用或读取。

用户消息
  ↓
注入工具手册 + Active Skills 列表（只包含 name / description / SKILL.md 路径）
  ↓
模型根据描述选择某个 Skill
  ↓
使用 Read 或 Bash 打开对应的 SKILL.md
  ↓
按说明调用脚本 / 其它工具，完成任务

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 元数据和 Skill 说明正文：

---
name: markdown-segment-translator
description: 将长Markdown文档分段翻译，保持格式和术语准确性。适用于“翻译整篇 Markdown 文档”之类的请求。
allowed-tools: ["Bash", "Read", "Write"]

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 唯一标识符，1–64 个字符，只能包含小写字母、数字和连字符
`description`	string	✅	Skill 做什么、什么时候用，建议明确写出触发场景
`allowed-tools`	string	❌	建议使用的工具列表，例如 `["Read","Write","Bash"]`

注意：当前版本中，Skills 注入器不会根据 triggers 自动筛选技能。你仍然可以在 YAML 中声明 triggers 等扩展字段，但它们更多用于自定义过滤逻辑、UI 展示或文档说明，而不是内置激活机制。

🔔 触发元数据（可选）

如果你希望在自己的代码中基于“关键词”“上下文”等条件筛选技能，可以在 SKILL.md 的 YAML 中定义一个 triggers 字段，并在上层自行解析和使用。默认的 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 注入流程

在当前实现中，Skills 注入流程可以简化理解为：

┌────────────────────┐
│  用户发送消息      │
└──────────┬─────────┘
           │
           ▼
┌────────────────────┐
│  构造系统提示词    │  追加 Tools Manual + Active Skills 元数据列表
└──────────┬─────────┘
           │
           ▼
┌────────────────────┐
│  发送给模型        │
└──────────┬─────────┘
           │
           ▼
┌────────────────────┐
│  模型在需要时      │  使用 Read/Bash 打开对应 SKILL.md
│  主动加载 SKILL.md │
└──────────┬─────────┘
           │
           ▼
┌────────────────────┐
│  按说明调用脚本等  │
└────────────────────┘

注入策略

aster 根据模型能力选择把 Skills 元数据注入到 System Prompt 或 User Message，并且只注入“轻量信息”，不注入 SKILL.md 正文。

支持 System Prompt 的模型：

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

  ## Active Skills

  - `consistency-checker`: 在写作过程中检查角色、世界设定和时间线一致性 (SKILL file: `skills/consistency-checker/SKILL.md`)
  - `markdown-segment-translator`: 将长 Markdown 文档按段切分并翻译 (SKILL file: `skills/markdown-segment-translator/SKILL.md`)

User Message:
  [用户消息]

不支持 System Prompt 的模型：

User Message:
  ## Skills Overview

  - `consistency-checker`: 在写作过程中检查角色、世界设定和时间线一致性 (SKILL file: `skills/consistency-checker/SKILL.md`)
  - `markdown-segment-translator`: 将长 Markdown 文档按段切分并翻译 (SKILL file: `skills/markdown-segment-translator/SKILL.md`)

  ---

  [用户消息]

模型在看到这些条目后，如果决定使用某个 Skill，应该首先用 Read 或 Bash 打开提示中的 SKILL.md 路径，阅读说明书，然后按说明中的步骤调用脚本和其它工具。

多 Skill 组合

当多个 Skill 配置为启用状态时，它们会按名称排序后依次出现在列表中：

## Active Skills

- `coding-standards`: 代码规范和风格要求 (SKILL file: `skills/coding-standards/SKILL.md`)
- `security-checklist`: 常见安全检查清单 (SKILL file: `skills/security-checklist/SKILL.md`)
- `test-guidelines`: 测试用例设计和覆盖建议 (SKILL file: `skills/test-guidelines/SKILL.md`)

📁 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 示例

aster 提供了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计数、智能压缩和自动优化