# Agent Skills（智能体技能）

本目录包含用于增强智能体在特定任务上能力的技能。

## 什么是 Agent Skills？

Agent Skills 是 Anthropic 提出的一种功能，用于提升智能体在专业任务上的表现。每个技能都是一个独立的目录，包含文档和资源，智能体可以动态加载。

## 目录结构

```
skills/
├── README.md (本文件)
├── canvas_workflow/
│   ├── SKILL.md (必需)
│   ├── examples/ (可选)
│   └── templates/ (可选)
└── your_skill_name/
    └── SKILL.md (必需)
```

## 创建新技能

### 1. 创建技能目录

```bash
mkdir -p backend/src/services/agents/skills/your_skill_name
```

### 2. 创建 SKILL.md

每个技能必须有一个带 YAML 前置元数据的 `SKILL.md` 文件：

```markdown
---
name: your_skill_name
description: 技能功能的简要描述
---

# 你的技能名称

关于技能的详细文档...

## 何时使用此技能

- 使用场景 1
- 使用场景 2

## 示例

...
```

### 3. YAML 前置元数据必需字段

- `name`: 技能的唯一标识符
- `description`: 简要描述（用于提示词）

### 4. 可选内容

- examples 目录，包含示例配置
- templates 目录，包含可复用的模式
- 智能体可以引用的脚本或资源

## 使用技能

### 在代码中启用技能

```python
from src.services.agents import AgentScopeService

# 创建服务时启用技能
service = AgentScopeService(
    use_multi_agent=True,
    enable_skills=True  # 启用技能
)
```

### 在 Toolkit 中启用技能

```python
from src.services.agents.base import ToolkitFactory

# 创建启用技能的工具包
toolkit = ToolkitFactory.create_canvas_toolkit(enable_skills=True)
```

## API 端点

### 列出所有技能

```bash
GET /api/v1/skills/list
```

返回可用技能列表及元数据。

### 获取技能提示词

```bash
GET /api/v1/skills/prompt
```

返回所有已注册技能的组合提示词。

### 注册技能

```bash
POST /api/v1/skills/register
Content-Type: application/json

{
  "skill_dir": "/path/to/skill"
}
```

### 移除技能

```bash
DELETE /api/v1/skills/{skill_name}
```

## 技能工作原理

1. **注册**：从目录注册技能
2. **提示词生成**：将每个技能的元数据转换为提示词
3. **系统提示词集成**：将技能提示词添加到智能体的系统提示词中
4. **动态加载**：智能体在执行过程中可以引用技能文档

## 最佳实践

### 1. 清晰的文档

- 编写清晰、简洁的描述
- 包含具体的使用场景
- 提供示例

### 2. 自包含

- 每个技能应该是独立的
- 包含所有必要的文档
- 不依赖外部资源

### 3. 命名规范

- 使用小写加下划线：`canvas_workflow`
- 具有描述性：`video_production_pipeline`
- 避免通用名称：`helper`、`utils`

### 4. 维护

- 保持技能更新
- 移除过时的技能
- 对技能变更进行版本控制

## 示例技能

### canvas_workflow

高级画布工作流模式和最佳实践。

**使用场景：**
- 多步骤视频制作
- 角色展示流程
- 分镜生成

## 故障排除

### 技能未加载

1. 检查 SKILL.md 是否存在
2. 验证 YAML 前置元数据格式
3. 检查文件权限
4. 查看日志中的错误

### 技能未出现在提示词中

1. 确保 `enable_skills=True`
2. 检查技能目录路径
3. 验证技能注册

## 配置

### 默认技能目录

```python
# 在 toolkit_factory.py 中
DEFAULT_SKILLS_DIR = "backend/src/services/agents/skills"
```

### 自定义技能目录

```python
toolkit = ToolkitFactory.create_toolkit(
    tools=tools,
    skills_dir="/custom/path/to/skills",
    enable_skills=True
)
```

## 未来增强

- [ ] 技能版本控制
- [ ] 技能依赖管理
- [ ] 技能市场
- [ ] 自动技能发现
- [ ] 技能性能指标
