Agent Skills

Skills 为 Agent 附加领域专业知识。一个 Skill 是一组结构化的指令和流程，让 Agent 在特定任务上表现得更专业、更可靠。

如果你使用 QoderWork 或 Qoder IDE，可以从技能市场一键安装 Cloud Agents 技能，在本地对话中直接创建和管理 Cloud Agents，无需手动调用 API。

端点总表

方法	路径	说明
`POST`	`/api/v1/cloud/skills`	创建 Skill（含首个版本）
`GET`	`/api/v1/cloud/skills`	列出 Skills
`GET`	`/api/v1/cloud/skills/{skill_id}`	获取 Skill
`PUT`	`/api/v1/cloud/skills/{skill_id}`	更新 Skill ⚠️ 已废弃
`DELETE`	`/api/v1/cloud/skills/{skill_id}`	删除 Skill
`POST`	`/api/v1/cloud/skills/{skill_id}/versions`	创建 Skill 版本
`GET`	`/api/v1/cloud/skills/{skill_id}/versions`	列表 Skill 版本
`GET`	`/api/v1/cloud/skills/{skill_id}/versions/{version}`	获取 Skill 版本
`GET`	`/api/v1/cloud/skills/{skill_id}/versions/{version}/content`	下载 Skill 版本内容
`DELETE`	`/api/v1/cloud/skills/{skill_id}/versions/{version}`	删除 Skill 版本

版本化模型

Skill 采用「skill 壳 + 不可变版本快照」两层模型：

Skill 壳：承载 id、display_title、source、metadata 等与内容无关的属性，以及指向最新版本的 latest_version。
Skill 版本（version）：每个版本是一份不可变的完整内容快照。版本号是创建时刻的 epoch 微秒字符串（如 "1759178010641129"），由服务端生成，不可指定。
更新内容 = 通过 POST /skills/{skill_id}/versions 追加一个新版本；旧版本保持不变，可单独获取、下载和删除。
删除最新版本后，latest_version 自动回退到次新版本；所有版本删光时为 null。
Skill 的 name（来自 SKILL.md frontmatter）在所有版本间必须保持一致，创建后不可更改。

PUT /api/v1/cloud/skills/{skill_id} 已废弃。内容更新请改用创建 Skill 版本。

Skill 的作用

注入专业知识 —— 让通用 Agent 具备特定领域能力（如代码审查、文档生成）
标准化流程 —— 确保 Agent 按统一步骤执行，输出一致
可复用 —— 一次创建，多个 Agent 共享

Skill 文件结构

Skill 以 .zip 文件（或裸文件树 multipart 上传）提交，必须有唯一的顶级目录，且目录名等于 SKILL.md 中的 name：

my-skill/
├── SKILL.md          # 必需：Skill 定义文件
├── templates/        # 可选：模板文件
│   └── report.md
└── examples/         # 可选：示例文件
    └── sample.json

SKILL.md 是核心文件，使用 YAML frontmatter + Markdown 格式：

---
name: my-skill
description: 执行结构化代码审查，输出改进建议
---

# Code Review

## Steps
1. 分析代码结构和架构
2. 检查常见问题（安全、性能、可维护性）
3. 输出结构化审查报告

## Pitfalls
- 不要只关注格式问题，优先关注逻辑错误
- 给出具体修改建议，而非泛泛批评

创建 Skill

POST https://api.qoder.com/api/v1/cloud/skills
Content-Type: multipart/form-data

curl 示例

# 先打包 Skill 目录（保留顶级目录）
zip -r my-skill.zip my-skill/

# 上传
curl -X POST https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@my-skill.zip"

响应：

{
  "id": "skill_019e5d133c057536872f745e0b6dbd5d",
  "type": "skill",
  "display_title": "my-skill",
  "source": "custom",
  "latest_version": "1759178010641129",
  "created_at": "2026-05-01T10:00:00.123456Z",
  "updated_at": "2026-05-01T10:00:00.123456Z"
}

latest_version 由服务端生成，是创建时刻的 epoch 微秒字符串。SKILL.md frontmatter 中的 version（如 1.0.0）仅作信息标记用途，并非服务端版本号。

关联到 Agent

通过 Agent 的 skills 字段将 Skill 绑定到 Agent。绑定元素可携带可选的 version 字段：省略或传 "latest" 表示动态跟随最新版本；传数字时间戳表示钉住该版本（写入时会校验该版本真实存在，否则返回 400）。

curl -X POST https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "skills": [
      {"type": "custom", "skill_id": "skill_019e5d133c057536872f745e0b6dbd5d"},
      {"type": "custom", "skill_id": "skill_019e5cdc7a9278ba933d4c328096bac5", "version": "1759178010641129"}
    ]
  }'

版本管理

为已有 Skill 追加新版本：

curl -X POST https://api.qoder.com/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d/versions \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@my-skill-v2.zip"

未钉版的绑定始终使用最新版本；钉住数字版本的绑定固定使用该版本内容。

获取 Skill 详情

curl https://api.qoder.com/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

列出所有 Skills

curl https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

响应：

{
  "data": [
    {
      "id": "skill_019e5d133c057536872f745e0b6dbd5d",
      "type": "skill",
      "display_title": "code-review",
      "source": "custom",
      "latest_version": "1759178010641129",
      "created_at": "2026-05-01T10:00:00.123456Z",
      "updated_at": "2026-05-01T10:00:00.123456Z"
    },
    {
      "id": "skill_019e5cdc7a9278ba933d4c328096bac5",
      "type": "skill",
      "display_title": "doc-generator",
      "source": "custom",
      "latest_version": "1759264410332875",
      "created_at": "2026-04-20T08:30:00.482910Z",
      "updated_at": "2026-04-25T09:15:00.104276Z"
    }
  ],
  "next_page": null,
  "has_more": false
}

Skill 编写建议

明确触发条件 —— 在 description 中写清楚何时应使用此 Skill
步骤具体 —— Steps 中写精确操作，而非模糊描述
记录陷阱 —— Pitfalls 帮助 Agent 避免常见错误
提供验证 —— 告诉 Agent 如何确认任务完成

常见问题

Q：Skill 和 Agent system 提示词有什么区别？ A：system 是 Agent 的通用指令，对所有任务生效。Skill 是按需激活的专业模块，Agent 根据任务内容决定是否使用。 Q：一个 Agent 可以关联多少个 Skills？ A：无硬性限制，但建议控制在 10 个以内以确保 Agent 行为可预测。 Q：Skills 功能何时全面开放？ A：当前处于 M2 门控阶段，预计后续版本全量开放。可联系我们申请提前开通。 Q：zip 文件大小有限制吗？ A：压缩包不超过 50 MB，且解压后总大小同样不超过 50 MB。

下一步

Agent 工具

为 Agent 配备内置、MCP 和自定义工具。

定义 Agent

回顾 Agent 配置。

启动 Session

管理会话生命周期。

快速开始

5 步跑通第一个 Cloud Agent。

​端点总表

​版本化模型

​Skill 的作用

​Skill 文件结构

​创建 Skill

​curl 示例

​关联到 Agent

​版本管理

​获取 Skill 详情

​列出所有 Skills

​Skill 编写建议

​常见问题

​下一步

Agent 工具

定义 Agent

启动 Session

快速开始

端点总表

版本化模型

Skill 的作用

Skill 文件结构

创建 Skill

curl 示例

关联到 Agent

版本管理

获取 Skill 详情

列出所有 Skills

Skill 编写建议

常见问题

下一步