跳转到主要内容

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.

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://openapi.qoder.sh/api/v1/cloud/skills
Content-Type: multipart/form-data

​
curl 示例

# 先打包 Skill 目录
cd my-skill && zip -r ../my-skill.zip . && cd ..

# 上传
curl -X POST https://openapi.qoder.sh/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@my-skill.zip"
响应： 
{
  "id": "skl_abc123",
  "name": "code-review",
  "description": "执行结构化代码审查，输出改进建议",
  "version": "1.0.0",
  "created_at": "2026-05-01T10:00:00Z"
}

​
关联到 Agent

通过 Agent 的 skills 字段将 Skill 绑定到 Agent： 
curl -X PATCH https://openapi.qoder.sh/api/v1/cloud/agents/agt_abc123 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "skills": ["skl_abc123", "skl_def456"]
  }'
Skills 关联功能当前处于 M2 门控阶段，需要申请开通。

​
版本管理

每次上传同名 Skill 会创建新版本： 
# 更新 SKILL.md 中的 version 字段后重新上传
curl -X POST https://openapi.qoder.sh/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@my-skill-v2.zip"
Agent 关联的 Skill 始终使用最新版本。

​
获取 Skill 详情

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

​
列出所有 Skills

curl https://openapi.qoder.sh/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT"
响应： 
{
  "data": [
    {
      "id": "skl_abc123",
      "name": "code-review",
      "version": "1.0.0",
      "created_at": "2026-05-01T10:00:00Z"
    },
    {
      "id": "skl_def456",
      "name": "doc-generator",
      "version": "2.1.0",
      "created_at": "2026-04-20T08:30:00Z"
    }
  ]
}

​
删除 Skill

curl -X DELETE https://openapi.qoder.sh/api/v1/cloud/skills/skl_abc123 \
  -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。