本文旨在引导您在 Skill 管理页对 Skill 进行创建、编辑、版本管理与生命周期治理。Skill 支持草稿/在线/离线三态状态机、历史版本记录与一键回滚，并可发布至 SkillHub 供全员浏览与 Agent 关联，解决在线 Skill 更新易中断关联 Agent、无法追溯历史变更等问题。
功能说明
Skill 是 Agent 的原子能力单元，用于描述“这个 Agent 能做什么”。对外它对应 A2A 协议 AgentCard 中的
AgentSkill 对象（id/name/description/tags/examples），对内是 AI 网关侧一条可复用的能力配置记录。同一个 Skill 可被多个 Agent API 复用，修改一次即可同步生效。名词定义
术语 | 定义 |
草稿 | 编辑态，仅创建者可见，不可发布 Hub，不可被 Agent 关联 |
在线 | 已发布状态，可被 Agent 关联；是否显示在 SkillHub 由发布状态决定 |
离线 | 已下线，不可被新 Agent 关联，已关联 Agent 保留但提示警告 |
当前版本 | Skill 主记录对应的版本，即最近一次生效内容 |
历史版本 | 仅保留 1 条，即“当前版本”变更前的上一个版本快照 |
前提条件
已创建 AI 网关实例，且实例状态为运行中。
若需将 Skill 挂载到 Agent 并通过 A2A 协议对外暴露，网关数据面版本需 ≥ 3.9.6。
若使用 ZIP 包方式创建 Skill，需提前准备包含
SKILL.md 的压缩包。操作场景一：Skill 管理
创建 Skill
1. 登录 AI 网关控制台。
2. 在左侧导航栏选择实例列表，单击目标 AI 网关实例 ID 进入实例详情页。
3. 单击左侧 Skill 管理后，单击新建 Skill。
4. 在新建 Skill 弹窗中配置基础信息：
参数名 | 是否必填 | 取值范围/默认值 | 说明 |
Skill 名称 | 是 | 最长 64 个字符 | 展示名称，如“TAPD-Test”。 |
描述 | 是 | 最长 255 个字符 | 一句话描述能力，写入 AgentCard skills[].description，对外可见。 |
Tags | 是 | 最多 5 个，单个最长 20 个字符 | 不可重复。写入 AgentCard skills[].tags。支持 Enter / 逗号 / 空格添加，Chip 形式展示，单击 × 删除。 |
Examples | 否 | 最多 10 条，单条最长 512 个字符 | 使用示例，写入 AgentCard skills[].examples。单击添加示例新增一行。 |
5. （可选）在 Skill 文件区域上传 ZIP 包：
参数名 | 是否必填 | 取值范围 | 说明 |
Skill 文件（.zip） | 否 | 仅支持 .zip 格式 | 支持拖拽或单击上传。上传后系统自动解析 SKILL.md 中的元信息（名称/描述/标签）并回填至上方字段，仅在字段为空时回填，不覆盖已填内容。 |
6. 单击确定创建，列表中出现新建的 Skill。
查看 Skill 详情
1. 在 Skill 管理列表中单击目标 Skill 左侧的详情进入详情页。
2. 详情页包含以下页签：
页签 | 内容 |
基本信息 | Skill ID、名称、描述、Tags、Examples、当前版本号、状态、创建人、创建/更新时间、版本历史 |
Skill 状态流转
1. 进入“Skill 管理”，选择目标 Skill
2. 支持的状态流转：
操作 | 前置条件 | 结果 |
上线 | 当前为草稿或离线 | 在线 |
下线 | 当前为在线，且未被 Agent 绑定 | 离线；若已发布 Hub 会在同一操作中自动取消发布 |
发布到 Hub | 当前为在线 | 发布后该 Skill 将对所有用户可见，可在 SkillHub 浏览与下载。 |
从 Hub 移除 | 当前为在线，并且已发布 Skillhub | 移除后该 Skill 仅自己可见，其他用户将无法在 SkillHub 中看到。 |
操作场景二：版本管理与回滚
1. 每次编辑并保存在线 Skill 的名称/标签/示例/描述后，原内容自动归档为“历史版本”，编辑内容成为新的“当前版本”
2. 进入 Skill 详情页“版本历史”，可查看当前版本与历史版本（最多 2 项，当前版本置顶）
字段 | 说明 |
版本号 | 格式 x.y.z 或系统时间戳，不可与已存在版本重复 |
创建人/创建时间 | 该版本快照的原始创建人和时间 |
是否当前 | 标注是否为当前生效版本 |
3. 单击回滚将当前版本与历史版本互换：历史版本立即成为当前版本并生效，原当前版本转为历史版本，无需额外发布操作
4. 仅存在 1 个版本（无历史版本）时，回滚按钮不可用
说明：
Skill 内容变更后，若该 Skill 已被 Agent API 关联，变更会异步同步至所有关联的 Agent API（约 5 分钟内完成），同步状态可在同步任务记录中查看，失败可手动重试。
操作场景三：Agent 关联 Skill
新建 Agent 服务时支持关联 Skill，Agent 关联 Skill 选择器仅展示“在线”状态的 Skill（不要求已发布至 SkillHub）
已关联 Skill 状态变化时的提示：
Skill 当前状态 | Agent 详情页展示 |
在线 | 正常 |
离线 | 橙色警告“该 Skill 已离线，建议更换” |
已删除 | 红色提示“该 Skill 已删除，请重新配置” |
说明：
被 Agent 绑定的 Skill 不可删除、不可下线，需先解除绑定
仅“在线”状态 Skill 支持下载；草稿/离线不可下载
