Skill 版本管理概述
开发阶段需要快速修改和调试 Skill，生产使用时又需要稳定、可追溯的内容。Skill 版本管理让同一个 Skill 同时具备可持续编辑的工作区版本（HEAD）、创建后不可修改的正式版本，以及用于引用正式版本的版本别名，既能随时迭代内容，又能在生产侧按需控制版本的升级节奏。本文说明上述概念、正式版本的发布路径与可用状态，以及不同场景下引用方式的选择。
当前支持工作区版本、正式版本与系统保留别名 latest；自定义别名尚未开放，将在后续上线。自定义别名开放前，可以使用 latest 或按具体版本号引用正式版本。
基本概念
Skill 版本管理涉及以下概念：
概念 | 含义 | 是否可变 | 适用场景 |
工作区版本（HEAD） | 当前正在编辑和保存的 Skill 内容 | 可持续修改 | 开发、调试、快速迭代 |
正式版本 | 从工作区版本创建的内容快照，如 | 创建后不可修改 | 稳定使用、回滚、审计 |
版本别名 | 指向某个已发布正式版本的固定名称，包括系统保留别名 | 自定义别名可修改指向； | 在不修改 Agent 配置的情况下统一切换版本 |
工作区版本（HEAD）
HEAD 是工作区版本的代号，始终表示当前已保存的最新内容。修改并保存 Skill 后，工作区版本随之变化，直接引用工作区版本的 Agent 也会使用最新内容。工作区版本不是正式版本，不参与正式版本号排序，也不会被版本别名指向。
正式版本
正式版本是从工作区版本创建的不可变快照，创建后不能修改，用于保证内容稳定和可追溯。如果内容存在问题，需要回到工作区版本修正并创建新的正式版本。版本号默认采用语义化版本格式：
主版本：包含不兼容变更，例如
1.0.0→2.0.0。次版本：增加向后兼容的功能，例如
1.0.0→1.1.0。修订版本：向后兼容的问题修复，例如
1.0.0→1.0.1。
版本别名
版本别名是指向已发布正式版本的固定名称，指向可以修改，用于在不修改 Agent 配置的情况下统一切换版本。版本别名分为系统保留别名 latest 与自定义别名两类：
latest：当前已支持，自动指向最新已发布的正式版本，适用于自动跟随每次正式发布。latest由系统自动维护：每当一个新的正式版本发布后，系统自动将latest指向该版本；修改并保存工作区版本不会改变latest。latest不能修改、删除或被同名创建。自定义别名：尚未开放，将在后续上线。开放后由用户创建并指向指定正式版本，可以编辑指向和说明，也可以删除，适用于控制升级节奏、多环境使用与快速回滚。别名名称创建后不能直接修改；如需更名，应创建新别名、迁移引用后再删除旧别名。
自定义别名开放后，可以让
production指向1.1.0；后续将其改为指向1.2.0，使用production的 Agent 会自动切换到1.2.0，无需修改 Agent 配置。
正式版本发布与可用状态
工作区版本是正式版本发布的起点，本身不属于正式版本的状态。发布前的安全审核由独立的 AI 安全护栏产品提供，不属于 AgentCore 自身功能，使用前需先开通该产品。
发布路径
未开通 AI 安全护栏时，工作区版本可直接发布为正式版本，并进入“已发布”状态。开通 AI 安全护栏后，AgentCore 发布正式版本前会调用其审核能力，版本先进入“审核中”：审核通过后进入“待发布”，确认发布后成为“已发布”；审核未通过则进入“审核未通过”，不进入“待发布”，但可以选择强制发布。
可用状态与引用关系
“已发布”和“已下线”描述正式版本是否可供使用。版本别名不属于版本状态，而是指向已发布正式版本的引用旁路：latest 由系统自动维护，自定义别名由用户按需调整指向。
状态 | 出现条件 | 说明 | 可执行的主要操作 |
“审核中” | 已开通 AI 安全护栏并发起正式版本发布 | AI 安全护栏正在执行审核，尚未进入“待发布” | 等待审核结果 |
“审核未通过” | AI 安全护栏审核未通过 | 不进入“待发布”，但仍可选择强制发布 | 查看审核结果、强制发布 |
“待发布” | AI 安全护栏审核通过 | 审核已通过，等待确认发布 | 查看、发布 |
“已发布” | 成功发布后 | Agent 可直接使用，也可作为版本别名的目标 | 查看、按需下线 |
“已下线” | 已发布版本下线后 | 不再作为正常可用版本提供选择 | 查看、重新上线 |
正式版本的发布流程不会锁定工作区版本，仍可继续基于该版本开发下一次变更。
如何选择使用方式
选择引用方式时，先判断是否需要控制升级节奏。没有多环境或灰度需求的简单场景无需额外创建自定义别名：开发阶段引用工作区版本，正式使用时根据稳定性要求引用 latest，或按具体版本号引用正式版本。下表列出常见场景的推荐选择、生效时机与当前可用性：
使用场景 | 推荐选择 | 生效时机 | 当前可用性 | 原因 |
个人开发、频繁调试 | 引用工作区版本 | 开发者修改后立即生效 | 已支持 | 修改保存后即可验证，无需反复发布版本 |
希望每次发布后自动升级 | 引用 | 开发者发布新版本后自动生效 | 已支持 | 始终跟随最新已发布正式版本，无需手动切换 |
生产环境统一控制升级节奏 | 使用自定义别名 | 管理员调整别名指向后统一生效 | 尚未开放，开放前可引用 | 可以先验证新版本，再统一修改别名指向 |
关键生产任务、审计或复现实验 | 按具体版本号引用正式版本 | 除非主动修改 Agent 配置，否则始终不变 | 已支持 | 引用不会随工作区、发布或别名调整而变化 |
多环境管理 | 为不同环境创建独立别名，例如 | 管理员调整别名指向后统一生效 | 尚未开放，开放前可引用 | 各环境分别控制版本 |
推荐使用范式
推荐采用“工作区开发、正式版本发布、别名逐步推广”的流程，相关操作通过 AgentCore 控制台的 Skill 管理 完成：
编辑工作区版本并完成调试。
从当前工作区版本发起正式版本发布，填写版本号和版本说明。
未开通 AI 安全护栏时，版本直接发布；已开通时，AgentCore 调用 AI 安全护栏完成审核。审核通过后确认发布，审核未通过时根据审核结果处理，必要时选择强制发布。
需要自动跟随发布时使用
latest；需要控制升级节奏时，先将测试别名切换到新版本。验证通过后，再将生产别名切换到新版本。
出现问题时，将自定义别名重新指向上一个可用版本，实现快速回滚。
步骤 4 的测试别名切换以及步骤 5、步骤 6 依赖自定义别名，该能力尚未开放；开放前可以使用
latest或按具体版本号引用正式版本。
操作风险与确认要点
条件性发布状态与强制发布
“审核中”“审核未通过”和“待发布”依赖 AI 安全护栏的审核能力，只有已开通该产品的发布路径才会出现，并非所有正式版本都会经过。审核未通过的版本可以强制发布，操作前应确认审核结果及相关风险。
别名指向修改的影响范围
修改自定义别名的指向后，所有使用该别名的 Agent 都会切换到目标版本。建议先查看使用情况并完成验证，再切换指向。
删除别名与删除版本的区别
删除自定义别名不会删除其指向的正式版本，但使用该别名的 Agent 将无法继续通过该别名获取 Skill。建议先迁移引用，再删除别名。
版本下线前的引用确认
Agent 可能按具体版本号引用正式版本，自定义别名也可能指向该版本。下线前先确认相关引用，并根据实际使用情况安排迁移，避免版本下线后出现不可用风险。
生产环境的引用方式
工作区版本的任何修改都可能立即影响使用方。生产任务、共享 Skill 或无法及时验证下游影响的场景，建议引用 latest、自定义别名，或按具体版本号引用正式版本，不建议直接引用工作区版本。
了解更多
AgentCore 控制台：Skill 管理 用于完成版本发布与别名相关操作。
管理 Skill：版本创建与发布的具体操作步骤。