Agent Skills

为 Agent 附加领域专业知识。

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

如果你使用 QoderWork 或 Qoder 桌面端，可以从技能市场一键安装 Cloud Agents 技能，在本地对话中直接创建和管理 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 格式：

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 示例

# 先打包 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"

响应：

{
  "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 数组：

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 会创建新版本：

# 更新 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 详情

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

​

列出所有 Skills

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

响应：

{
  "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 工具

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

定义 Agent

回顾 Agent 配置。

启动 Session

管理会话生命周期。

快速开始

5 步跑通第一个 Cloud Agent。