Skills 为 Agent 附加领域专业知识。一个 Skill 是一组结构化的指令和流程，让 Agent 在特定任务上表现得更专业、更可靠。
Skill 的作用
注入专业知识 —— 让通用 Agent 具备特定领域能力（如代码审查、文档生成）
标准化流程 —— 确保 Agent 按统一步骤执行，输出一致
可复用 —— 一次创建，多个 Agent 共享
Skill 文件结构
Skill 以 .zip 文件上传，包含以下内容：
my-skill/
├── SKILL.md # 必需：Skill 定义文件
├── templates/ # 可选：模板文件
│ └── report.md
└── examples/ # 可选：示例文件
└── sample.json
SKILL.md 是核心文件，使用 YAML frontmatter + Markdown 格式：
name: code-review
description: 执行结构化代码审查，输出改进建议
version: 1.0.0
# Code Review
## Steps
1. 分析代码结构和架构
2. 检查常见问题（安全、性能、可维护性）
3. 输出结构化审查报告
## Pitfalls
- 不要只关注格式问题，优先关注逻辑错误
- 给出具体修改建议，而非泛泛批评
创建 Skill
POST https://api.qoder.com.cn/api/v1/cloud/skills
Content-Type: multipart/form-data
curl 示例
# 先打包 Skill 目录
cd my-skill && zip -r ../my-skill.zip . && cd ..
# 上传
curl -X POST https://api.qoder.com.cn/api/v1/cloud/skills \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@my-skill.zip"
响应：
{
"id": "skill_019e5d133c057536872f745e0b6dbd5d",
"type": "skill",
"name": "code-review",
"description": "执行结构化代码审查，输出改进建议",
"skill_type": "custom",
"status": "active",
"version": 1,
"content_sha256": "3f4b80bd74ef8aa801005a17f1843019ddcebd4ded36b5bd46bfffb3d39ff71a",
"content_size": 191,
"metadata": {},
"created_at": "2026-05-01T10:00:00Z",
"updated_at": "2026-05-01T10:00:00Z"
}
version 是服务端自动维护的整数（从 1 开始），每次重新上传成功后递增。SKILL.md frontmatter 中的 version（如 1.0.0）仅作信息标记用途，并非服务端版本号。
关联到 Agent
通过 Agent 的 skills 字段将 Skill 绑定到 Agent。注意：使用 PUT 全量替换 + 携带当前 version（PATCH 返回 405）：
curl -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_abc123 \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"version": 1,
"skills": [{"type": "custom", "skill_id": "skill_019e5d133c057536872f745e0b6dbd5d"}, {"type": "custom", "skill_id": "skill_019e5cdc7a9278ba933d4c328096bac5"}]
}'
版本管理
每次上传同名 Skill 会创建新版本：
# 更新 SKILL.md 中的 version 字段后重新上传
curl -X POST https://api.qoder.com.cn/api/v1/cloud/skills \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@my-skill-v2.zip"
Agent 关联的 Skill 始终使用最新版本。
获取 Skill 详情
curl https://api.qoder.com.cn/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d \
-H "Authorization: Bearer $QODER_PAT"
列出所有 Skills
curl https://api.qoder.com.cn/api/v1/cloud/skills \
-H "Authorization: Bearer $QODER_PAT"
响应：
{
"data": [
{
"id": "skill_019e5d133c057536872f745e0b6dbd5d",
"name": "code-review",
"description": "执行结构化代码审查，输出改进建议",
"version": 1,
"content_sha256": "3f4b80bd74ef...",
"content_size": 191,
"metadata": {},
"skill_type": "custom",
"status": "active",
"type": "skill",
"created_at": "2026-05-01T10:00:00Z",
"updated_at": "2026-05-01T10:00:00Z"
},
{
"id": "skill_019e5cdc7a9278ba933d4c328096bac5",
"name": "doc-generator",
"description": "生成技术文档",
"version": 3,
"content_sha256": "a1b2c3d4e5f6...",
"content_size": 420,
"metadata": {},
"skill_type": "custom",
"status": "active",
"type": "skill",
"created_at": "2026-04-20T08:30:00Z",
"updated_at": "2026-04-25T09:15:00Z"
}
]
}
删除 Skill
curl -X DELETE https://api.qoder.com.cn/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d \
-H "Authorization: Bearer $QODER_PAT"
删除 Skill 后，已关联该 Skill 的 Agent 在下次 Session 创建时将不再加载它。
Skill 编写建议
明确触发条件 —— 在 description 中写清楚何时应使用此 Skill
步骤具体 —— Steps 中写精确操作，而非模糊描述
记录陷阱 —— Pitfalls 帮助 Agent 避免常见错误
提供验证 —— 告诉 Agent 如何确认任务完成
常见问题
Q：Skill 和 instructions 有什么区别？ A：instructions 是 Agent 的通用指令，对所有任务生效。Skill 是按需激活的专业模块，Agent 根据任务内容决定是否使用。
Q：一个 Agent 可以关联多少个 Skills？ A：无硬性限制，但建议控制在 10 个以内以确保 Agent 行为可预测。
Q：Skills 功能何时全面开放？ A：当前处于 M2 门控阶段，预计后续版本全量开放。可联系我们申请提前开通。
Q：zip 文件大小有限制吗？ A：单个 Skill zip 文件不超过 10MB。