> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Skills
> 为 Agent 附加领域专业知识。
Skills 为 Agent 附加**领域专业知识**。一个 Skill 是一组结构化的指令和流程，让 Agent 在特定任务上表现得更专业、更可靠。
如果你使用 QoderWork 或 Qoder 桌面端，可以从技能市场一键安装 [Cloud Agents 技能](https://qoder.com/marketplace/skill?id=official_FjWvobU0)，在本地对话中直接创建和管理 Cloud Agents，无需手动调用 API。
## Skill 的作用
* **注入专业知识** —— 让通用 Agent 具备特定领域能力（如代码审查、文档生成）
* **标准化流程** —— 确保 Agent 按统一步骤执行，输出一致
* **可复用** —— 一次创建，多个 Agent 共享
## Skill 文件结构
Skill 以 `.zip` 文件上传，包含以下内容：
```
my-skill/
├── SKILL.md # 必需：Skill 定义文件
├── templates/ # 可选：模板文件
│ └── report.md
└── examples/ # 可选：示例文件
└── sample.json
```
`SKILL.md` 是核心文件，使用 YAML frontmatter + Markdown 格式：
```markdown theme={null}
name: code-review
description: 执行结构化代码审查，输出改进建议
version: 1.0.0
# Code Review
## Steps
1. 分析代码结构和架构
2. 检查常见问题（安全、性能、可维护性）
3. 输出结构化审查报告
## Pitfalls
- 不要只关注格式问题，优先关注逻辑错误
- 给出具体修改建议，而非泛泛批评
```
## 创建 Skill
```
POST https://api.qoder.com/api/v1/cloud/skills
Content-Type: multipart/form-data
```
### curl 示例
```bash theme={null}
# 先打包 Skill 目录
cd my-skill && zip -r ../my-skill.zip . && cd ..
# 上传
curl -X POST https://api.qoder.com/api/v1/cloud/skills \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@my-skill.zip"
```
响应：
```json theme={null}
{
"id": "skill_019e5d133c057536872f745e0b6dbd5d",
"type": "skill",
"display_title": "code-review",
"description": "执行结构化代码审查，输出改进建议",
"source": "custom",
"latest_version": "1",
"created_at": "2026-05-01T10:00:00Z",
"updated_at": "2026-05-01T10:00:00Z"
}
```
`latest_version` 由服务端维护，并以字符串返回。SKILL.md frontmatter 中的 `version`（如 `1.0.0`）仅作信息标记用途，并非服务端版本号。
## 关联到 Agent
通过 Agent 的 `skills` 字段将 Skill 绑定到 Agent。使用 `POST` 更新并携带当前 `version`；显式传入 `skills` 时会替换已保存的 skills 数组：
```bash theme={null}
curl -X POST https://api.qoder.com/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 会创建新版本：
```bash theme={null}
# 更新 SKILL.md 中的 version 字段后重新上传
curl -X POST https://api.qoder.com/api/v1/cloud/skills \
-H "Authorization: Bearer $QODER_PAT" \
-F "file=@my-skill-v2.zip"
```
Agent 关联的 Skill 始终使用最新版本。
## 获取 Skill 详情
```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d \
-H "Authorization: Bearer $QODER_PAT"
```
## 列出所有 Skills
```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/skills \
-H "Authorization: Bearer $QODER_PAT"
```
响应：
```json theme={null}
{
"data": [
{
"id": "skill_019e5d133c057536872f745e0b6dbd5d",
"type": "skill",
"display_title": "code-review",
"description": "执行结构化代码审查，输出改进建议",
"source": "custom",
"latest_version": "1",
"created_at": "2026-05-01T10:00:00Z",
"updated_at": "2026-05-01T10:00:00Z"
},
{
"id": "skill_019e5cdc7a9278ba933d4c328096bac5",
"type": "skill",
"display_title": "doc-generator",
"description": "生成技术文档",
"source": "custom",
"latest_version": "3",
"created_at": "2026-04-20T08:30:00Z",
"updated_at": "2026-04-25T09:15:00Z"
}
],
"next_page": null,
"first_id": "skill_019e5d133c057536872f745e0b6dbd5d",
"last_id": "skill_019e5cdc7a9278ba933d4c328096bac5",
"has_more": false
}
```
## Skill 编写建议
1. **明确触发条件** —— 在 description 中写清楚何时应使用此 Skill
2. **步骤具体** —— Steps 中写精确操作，而非模糊描述
3. **记录陷阱** —— Pitfalls 帮助 Agent 避免常见错误
4. **提供验证** —— 告诉 Agent 如何确认任务完成
## 常见问题
**Q：Skill 和 Agent `system` 提示词有什么区别？** A：`system` 是 Agent 的通用指令，对所有任务生效。Skill 是按需激活的专业模块，Agent 根据任务内容决定是否使用。
**Q：一个 Agent 可以关联多少个 Skills？** A：无硬性限制，但建议控制在 10 个以内以确保 Agent 行为可预测。
**Q：Skills 功能何时全面开放？** A：当前处于 M2 门控阶段，预计后续版本全量开放。可联系我们申请提前开通。
**Q：zip 文件大小有限制吗？** A：单个 Skill zip 文件不超过 10MB。
## 下一步
为 Agent 配备内置、MCP 和自定义工具。
回顾 Agent 配置。
管理会话生命周期。
5 步跑通第一个 Cloud Agent。