Skip to main content
构建Agent

Agent Skills

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 编写建议

  1. 明确触发条件 —— 在 description 中写清楚何时应使用此 Skill
  2. 步骤具体 —— Steps 中写精确操作，而非模糊描述
  3. 记录陷阱 —— Pitfalls 帮助 Agent 避免常见错误
  4. 提供验证 —— 告诉 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。
操作指南
实践教程
API参考