自学教程

Skills 发布

Skills 教程

当 Skill 完成编码、调试、性能优化、并发测试之后，就进入发布环节。开发阶段的技能只在本地环境可用，发布就是将 Skill 标准化打包、校验、分发，让其他人或插件环境能够加载、使用这个技能。很多开发者只重视功能开发，忽略发布规范，导致本地正常的 Skill，部署到其他环境后出现加载失败、参数识别异常、描述解析错误、文件缺失等问题。

Skills 发布不是简单复制文件夹，而是一套打包、校验、版本管理、分发、上线、回滚的标准化工程流程，是技能从“本地Demo”转变为可分享、可复用的正式技能的最后一步。

一、发布前检查（发布前置校验清单）

发布之前必须完成全量自检，提前拦截大部分上线故障，避免发布后才发现问题。

  1. 文件完整性检查
    确认目录结构完整，核心文件SKILL.md、脚本文件、配置文件全部存在，无遗漏。不要携带本地临时文件、调试日志、缓存文件、IDE 配置文件（如.vscode临时缓存、debug日志）。

实战案例：开发者直接复制整个项目文件夹发布，附带大量本地日志文件，导致TraeCode插件加载时解析缓慢，甚至加载失败。

  1. 技能描述与参数校验
    核对SKILL.md中的技能描述、参数定义、触发规则，确保参数名称、类型、说明和脚本代码保持一致，不存在描述和代码逻辑不一致的情况。
  2. 功能回归测试
    在干净环境下重新测试核心场景、边界场景、异常场景，验证技能在脱离本地开发环境后，功能依然正常。不能只在开发环境测试。
  3. 性能与并发测试
    如果技能包含异步、并发逻辑，需要做简单压测，确认并发执行、超时、异常场景下不会内存泄漏、不会卡死。
  4. 版本与变更记录
    标记当前版本号，记录本次发布变更内容：新增能力、修复Bug、参数改动、性能优化，方便后续迭代和回滚。

二、Skill 打包规范

打包的目标：产出一个干净、独立、可直接解压使用的技能包。

  1. 清理冗余文件
    删除开发调试产物：临时输出文件、测试数据、本地日志、断点调试脚本、IDE配置。只保留运行必需文件。
  2. 目录结构保持标准
roll-dice/
├─ SKILL.md        # 技能定义、描述、参数
└─ index.js        # 执行脚本

不要嵌套多余层级，解压后插件可以直接识别为Skill目录。
3. 打包格式
一般采用zip压缩包打包，技能根目录作为压缩包内部第一层目录。

错误示例：压缩包内第一层是skills-demo，技能文件夹藏在子目录，插件无法识别。
正确示例：zip解压后直接得到roll-dice文件夹。

三、版本管理策略

推荐使用语义化版本 主版本.次版本.修订版本，例如 1.0.0

  • 主版本（Major）：破坏性变更，参数改动、目录结构重构，旧版本无法兼容
  • 次版本（Minor）：新增功能，原有接口、参数保持不变，向下兼容
  • 修订版本（Patch）：Bug修复、文案优化、性能微调，无功能变更

实战案例：roll-dice 1.0.0 基础掷骰子功能；1.1.0 增加多面骰子参数；1.1.1 修复参数校验bug。

每次发布，在变更记录中写明：

  • 版本号
  • 发布时间
  • 更新内容
  • 兼容性说明（是否兼容旧版本）

四、发布渠道与分发方式

根据使用场景，分为本地私有发布和公开仓库发布两种模式。

1. 本地私有发布（团队/个人自用，本次TraeCode场景）

适合仅自己或小团队内部使用，不上传到公共仓库。

  • 打包zip包，直接分发给团队成员
  • 使用者解压后放入.agents/skills/目录，重启TraeCode插件即可加载
  • 优点：简单、数据不外流；缺点：不方便版本同步，需要手动分发更新包

2. Git仓库发布（推荐，可长期迭代）

将Skill目录上传到Git仓库（如GitHub/Gitee），便于版本管理、多人协作。

  • 新建仓库，单独存放该Skill，或者放在skills-demo仓库的examples目录
  • 打tag标记每个发布版本，方便拉取指定版本
  • 其他人可以直接git clone或者下载对应版本zip包使用

实战案例：liqiang88/skills-demo仓库，就是典型的Git仓库发布，多个示例Skill统一托管，使用者可以直接下载hello-world、roll-dice等demo。

五、上线验证

发布完成后，必须在目标环境做上线验证，不能假设发布就一定成功。

  1. 在全新环境部署技能包，加载到TraeCode插件
  2. 触发技能，测试正向流程、异常输入
  3. 查看加载日志，确认无解析报错、无警告
  4. 验证版本号、技能描述展示正常

六、发布后的运维：升级与回滚

发布不是一次性动作，后续迭代会涉及升级和故障回滚。

  1. 升级
    新版本发布后，使用者替换技能目录，或者拉取Git最新版本。如果是破坏性主版本升级，需要提示用户旧版本不兼容，需要修改调用方式。
  2. 回滚机制（重要）
    新版本上线如果出现严重问题，快速切换回上一个稳定版本。
  • 保留历史版本包，不要直接覆盖删除旧版本
  • Git仓库可以直接切回旧tag版本，快速回滚

实战案例：新版本修改了参数名称，导致旧的调用流程全部失效，通过回滚到上一个patch版本，快速恢复业务。

七、发布的风险与避坑

  1. ❌ 不要直接发布未清理的开发目录，大量临时文件会拖慢加载甚至报错
  2. ❌ 不要不做版本管理，直接覆盖旧技能，出现问题无法回滚
  3. ❌ 不要修改SKILL.md参数定义但不更新脚本，导致描述和代码不一致
  4. ❌ 不要忽略兼容性，随意修改参数名称，破坏原有调用链路
  5. ✅ 每次发布保留变更日志；✅ 上线前在干净环境做验证

八、总结

Skills发布是技能工程化的收尾环节，打通了从本地开发到交付使用的链路。
完整的发布流程包含发布自检、清理打包、版本标记、分发上线、上线验证、升级与回滚。
一个规范发布的Skill，具备独立、干净、可复用、可追溯、可回滚的特性，能够稳定在TraeCode插件中加载运行，也可以分享给其他开发者使用。开发决定技能能不能实现，发布决定技能能不能稳定交付。

标签：

0 条笔记