Skills

Skill 是基于文件系统的可复用资源，为 Agent 提供领域专长：工作流程、上下文和最佳实践，把一个通用 Agent 变成领域专家。每挂载一个 Skill 都会占用少量会话上下文（用于帮助模型理解何时使用它），Agent 会在任务相关时自动调用。 Skill 有两种来源：

平台内置 Skill（type: zai）：平台预置、开箱可用。当前两份：planning（拆步骤、跟 todo）、code-review（按正确性 / 安全 / 清晰度审代码）。列表会随平台更新，以 GET /v1/skills?source=zai 为准。
自定义 Skill（type: custom）：你自己编写并上传的技能。

创建自定义 Skill

一个自定义 Skill 就是一个目录：根下必须有 SKILL.md（frontmatter 中的 description 不能为空），加上任意配套文件。通过 multipart 上传整个目录，每个文件 part 的字段名就是它的相对路径，所有文件必须位于同一个顶层目录下：

curl -sS -X POST "$BASE_URL/v1/skills" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -F "display_title=Financial Modeling" \
  -F "financial-modeling/SKILL.md=@financial-modeling/SKILL.md" \
  -F "financial-modeling/templates/dcf.xlsx=@financial-modeling/templates/dcf.xlsx"

创建成功返回 201 和 Skill 对象。记下 id（skill_ 前缀）与 latest_version，挂载到 Agent 时需要引用：

{
  "id": "skill_xxxxxxxxxxxx",
  "type": "skill",
  "display_title": "Financial Modeling",
  "source": "custom",
  "latest_version": "1759264410641129",
  "created_at": "2026-08-03T08:00:00.000Z",
  "updated_at": "2026-08-03T08:00:00.000Z"
}

上传约束：

所有文件总量 ≤ 20 MB，文件数 ≤ 200（超出的文件 part 会被静默丢弃，不报错）。
根目录必须包含 SKILL.md，且 frontmatter 含非空 description。
display_title 是可选的 multipart 文本 part，作为展示名持久化。
同一账号下不能重复创建相同目录名的 Skill（返回 409 skill_directory_conflict）；每个账号有 Skill 总数配额，超出返回 429。

版本管理

Skill 的版本是不可变的。要更新一个 Skill，向 POST /v1/skills/:id/versions 重新上传完整目录（约束同创建），生成一个新版本；版本号是服务端生成的 epoch 微秒串。相关接口：

接口	说明
POST /v1/skills	创建 Skill 及其首个版本（multipart 上传）
GET /v1/skills	列出可见 Skill（自己的 + 平台内置），支持 `?source=custom	zai` 过滤
GET /v1/skills/:id	获取 Skill
DELETE /v1/skills/:id	删除 Skill
POST /v1/skills/:id/versions	上传新版本（multipart）
GET /v1/skills/:id/versions	列出版本
GET /v1/skills/:id/versions/:v	获取版本元数据（name / description / directory 从上传内容解析）
GET /v1/skills/:id/versions/:v/content	下载该版本的 ZIP 包
DELETE /v1/skills/:id/versions/:v	删除版本

删除整个 Skill 时，只要仍有持久化配置引用它，就会返回 409。删除单个版本时，固定引用该版本的配置会阻止删除；跟随 latest 的引用通常可随最新版本指针迁移，但不能删除它依赖的最后一个版本。归档 Agent 不会解除历史版本中的引用。

把 Skill 挂载到 Agent

创建 Agent 时通过 skills 数组挂载，单个 Agent 最多 20 个 Skill。挂载 Skill 时必须同时配置 agent_toolset_20260601，否则创建或更新返回 400。每个条目的字段：

字段	说明
type	必填。zai（平台内置）或 custom（自己上传）。
skill_id	必填。Skill 标识；自定义 Skill 用创建时返回的 skill_ ID。
version	可选。省略、传 null 或传 latest 时跟随 Skill 的最新版本；传具体版本号时固定该版本。

agent=$(curl -sS "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "Financial Analyst",
  "model": "glm-5.3",
  "system": "You are a financial analysis agent.",
  "tools": [{"type": "agent_toolset_20260601"}],
  "skills": [
    {"type": "custom", "skill_id": "skill_xxxxxxxxxxxx", "version": "1759264410641129"}
  ]
}
EOF
)

挂载的 Skill 越多，会话沙箱的启动时间越长。只挂载当前任务需要的 Skill。会话运行时，每个 Skill 出现在 /workspace/skills/<目录名>/，Agent 按需读取。

同一账号下自定义 Skill 的目录名不能重复，冲突时返回 409 skill_directory_conflict。平台内置 Skill 的 skill_id 就是名称（如 planning）。需要自动使用后续新版本时可省略 version；需要稳定复现时，用 GET /v1/skills?source=zai 返回的 latest_version 显式固定。 Skill 也可以在创建会话时通过 agent.skills 覆盖，只影响该会话，见创建会话。

编写 Skill 的建议

SKILL.md 是入口：frontmatter 写清 name 与 description（模型靠它判断何时使用），正文写工作流程与规范；大块参考资料放在子文件里，让模型按需读取，避免一次性占用上下文。
一个 Skill 解决一类任务：范围过宽的 Skill 会稀释触发信号；按领域拆分成多个 Skill 更有效。
附带可执行资产：模板、脚本、示例文件都可以放进目录，Agent 能在沙箱里直接使用它们。

下一步

定义 Agent

skills 数组的完整更新语义

创建会话

按会话覆盖 Skill 配置

本页对应 OpenAPI

Skill：创建、版本、下载

开始使用

定义 Agent

配置运行环境

运行会话

上下文与记忆

自动化

参考

创建自定义 Skill

版本管理

把 Skill 挂载到 Agent

编写 Skill 的建议

下一步

定义 Agent

创建会话

本页对应 OpenAPI

​创建自定义 Skill

​版本管理

​把 Skill 挂载到 Agent

​编写 Skill 的建议

​下一步

定义 Agent

创建会话

本页对应 OpenAPI

创建自定义 Skill

版本管理

把 Skill 挂载到 Agent

编写 Skill 的建议

下一步