概述
技能 API 允许您列出可用技能、获取技能详情和查看版本历史。技能是基于 Markdown 的工作流定义，用于驱动具有预定义系统提示和配置的单代理执行。端点
| 端点 | 方法 | 描述 |
|---|---|---|
/api/v1/skills | GET | 列出所有技能 |
/api/v1/skills/{name} | GET | 获取技能详情 |
/api/v1/skills/{name}/versions | GET | 获取技能版本历史 |
列出技能
GET /api/v1/skills
查询参数
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
category | string | 否 | 按类别筛选（如 research、development、analysis） |
响应
{
"skills": [
{
"name": "deep-research",
"version": "1.0.0",
"category": "research",
"description": "带引用和验证的全面研究",
"requires_tools": ["web_search", "web_fetch"],
"dangerous": false,
"enabled": true
},
{
"name": "code-review",
"version": "1.0.0",
"category": "development",
"description": "审查代码中的问题和改进点",
"requires_tools": ["file_read"],
"dangerous": false,
"enabled": true
}
],
"count": 2,
"categories": ["research", "development", "analysis"]
}
示例
# 列出所有技能
curl http://localhost:8080/api/v1/skills \
-H "X-API-Key: sk_test_123456"
# 按类别筛选
curl "http://localhost:8080/api/v1/skills?category=research" \
-H "X-API-Key: sk_test_123456"
获取技能
GET /api/v1/skills/{name}
路径参数
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 技能名称（如 deep-research） |
响应
{
"skill": {
"name": "deep-research",
"version": "1.0.0",
"category": "research",
"description": "带引用和验证的全面研究",
"content": "# 深度研究技能\n\n你是一个研究代理...",
"requires_role": "research",
"requires_tools": ["web_search", "web_fetch"],
"dangerous": false,
"enabled": true,
"budget_max": 50000
},
"metadata": {
"source_path": "config/skills/research/deep-research.md",
"content_hash": "sha256:abc123...",
"loaded_at": "2025-01-20T10:00:00Z"
}
}
示例
curl http://localhost:8080/api/v1/skills/deep-research \
-H "X-API-Key: sk_test_123456"
错误响应
404 Not Found：{
"error": "Skill not found"
}
获取技能版本
GET /api/v1/skills/{name}/versions
路径参数
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 技能名称（如 deep-research） |
响应
{
"name": "deep-research",
"versions": [
{
"name": "deep-research",
"version": "1.0.0",
"category": "research",
"description": "带引用的全面研究",
"requires_tools": ["web_search", "web_fetch"],
"dangerous": false,
"enabled": true
},
{
"name": "deep-research",
"version": "0.9.0",
"category": "research",
"description": "Beta 研究技能",
"requires_tools": ["web_search"],
"dangerous": false,
"enabled": false
}
],
"count": 2
}
示例
curl http://localhost:8080/api/v1/skills/deep-research/versions \
-H "X-API-Key: sk_test_123456"
在任务中使用技能
提交任务时使用skill 参数：
curl -X POST http://localhost:8080/api/v1/tasks \
-H "X-API-Key: sk_test_123456" \
-H "Content-Type: application/json" \
-d '{
"query": "研究量子计算的最新发展",
"skill": "deep-research"
}'
版本选择
使用name@version 语法指定版本：
curl -X POST http://localhost:8080/api/v1/tasks \
-H "X-API-Key: sk_test_123456" \
-H "Content-Type: application/json" \
-d '{
"query": "审查这个 Pull Request",
"skill": "code-review@1.0.0"
}'
技能会展开为系统提示覆盖和可选的角色分配。它们提供了一种无需修改代码即可定义可重用工作流的方式。
技能结构
技能定义为带有 YAML frontmatter 的 Markdown 文件：---
name: my-skill
version: "1.0.0"
category: development
description: "描述此技能的功能"
requires_role: developer
requires_tools:
- file_read
- file_write
dangerous: false
enabled: true
budget_max: 50000
---
# 技能指令
你是一个专业代理...
## 指南
1. 首先，分析请求
2. 然后，执行相应操作
3. 最后，报告结果
Frontmatter 字段
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 技能标识符 |
version | string | 是 | 语义版本 |
category | string | 否 | 分组类别 |
description | string | 否 | 可读描述 |
requires_role | string | 否 | 使用的角色预设 |
requires_tools | array | 否 | 所需工具 |
dangerous | boolean | 否 | 需要提升权限 |
enabled | boolean | 否 | 技能是否启用 |
budget_max | integer | 否 | 最大 token 预算 |
危险技能
标记为dangerous: true 的技能需要特殊授权：
- Admin 或 Owner 角色，或
- API key 中显式的
skills:dangerous范围
# 危险技能调用（需要授权）
curl -X POST http://localhost:8080/api/v1/tasks \
-H "X-API-Key: sk_admin_key" \
-H "Content-Type: application/json" \
-d '{
"query": "执行系统维护",
"skill": "system-admin"
}'
危险技能可以执行特权操作。仅向可信的 API key 授予
skills:dangerous 范围。相关内容
提交任务
提交任务时使用技能
自定义工具
添加技能可用的工具