JECloud AI Skill 是小匠的「业务能力插件」——导入一个 .zip 包，就能给助手新增一项专门技能（数据分析、菜单地图、登录引导……）。本章讲怎么在 /admin/skills 导入、查看、删除 Skill 包。
3.1 Skill 是什么
Skill 是一个把"一类业务能力"打包成可装可卸的插件的机制。每个 Skill 是一个 .zip 包，里面至少包含 SKILL.md（描述文件）和若干脚本资源；小匠在运行时按对话语义触发对应 Skill，调用其中定义的工具完成任务（查菜单、跑数据、走业务流程）。
举几个常见的：
- jecloud-data-analysis —— 数据分析（底部「数据分析」按钮背后就是它）
- jecloud-login —— 登录引导与凭据准备
- jecloud-platform-build —— 业务平台模型 / 菜单生成
- jecloud-requirement-research —— 需求分析
提示： Skill ≠ MCP 工具：Skill 是「场景级能力」（说人话：一组按业务剧本编排好的工具调用 + 提示词）；MCP 工具是「单步动作」（一次 API 调用）。一个 Skill 通常会调用多个 MCP 工具来完成一个完整业务任务。MCP 配置见 MCP 外部工具管理。
3.2 入口与列表
左侧导航 能力配置 → Skill 管理，对应路由 /admin/skills。页面顶部是搜索框 + 「全部 N」标签（显示当前 Skill 总数）+ 「导入 Skill 包」主按钮 + 刷新按钮，主区是 Skill 卡片网格，每张卡片显示：序号 / 名称 / 「已加载」状态徽章 / 副标题（作者：xxx，无作者退回 skill 名）/ 一句话描述 / 版本号（v1.2.3）/ 删除按钮。整张卡片可点击，点开即弹出 Skill 详情。
| 列 / 元素 | 含义 | 来源 |
|---|---|---|
| 名称 | Skill 唯一标识，比如 jecloud-data-analysis | SKILL.md frontmatter name |
| 状态徽章 | 「已加载」绿点（所有列表中的 skill 都已加载，不可切换） | UI 常量 |
| 副标题（作者） | 显示 作者：xxx，无 author 时退回 skill 名 | SKILL.md frontmatter author |
| 描述 | 一两句话讲它能干嘛、什么时候触发 | SKILL.md frontmatter description |
| 版本 | 语义化版本号（v1.2.3），无则显示 — | SKILL.md frontmatter version |
| 删除按钮 | 红色垃圾桶图标，点击二次确认后从磁盘移除整个 skill 目录 | — |
小贴士： 「全部 N」总数：顶部标签里的 N 可以快速核对"刚导入的有没有进去"。搜索框支持按名称 / 副标题 / 描述模糊搜索。
3.3 导入 Skill 包
右上角 「导入 Skill 包」 按钮打开「导入 Skill 包」弹窗，操作流程：
- 选择 / 拖入 .zip：拖拽 .zip 到虚线区域，或点击「选择文件」浏览本地文件（限
.zip扩展名） - 自动解析预览：上传到
preview接口，后台读取SKILL.md的 frontmatter 后回填只读的name与描述两个预览字段；命名规则提示：jecloud-<area>[-<subject>] - 重名检测：如果该
name已存在，会在预览区显示「⚠ skill 已存在，提交时会被拒」橙色徽标，「导入」按钮被禁用，无法覆盖（与旧版"同名覆盖"不同） - 点击「导入」：解压落盘，新 Skill 出现在列表里；按钮文本变成「导入中…」
- 取消 / 关闭：未提交时可点「取消」或右上 ✕ 关闭，提交期间不能关
提示： 同名不覆盖、需先删除：本页代码不支持同名覆盖——已存在的 skill 必须先在列表里点删除按钮移除，才能再次导入同名包。要"升级版本"也是这个流程。
注意： SKILL.md 不规范会直接报错：非 .zip 文件、根目录缺
SKILL.md、frontmatter 解析失败，都会在预览区域显示红色错误信息。这种情况找 skill 开发者修一下 SKILL.md frontmatter 重新打包。
3.4 Skill 详情
点击卡片任意位置即可弹出 Skill 详情弹窗（不是右侧抽屉），标题区显示中文名 / name 与 v版本号，主体分若干段，全部只读：
- 基本信息：
name/ 中文名（cn，若与 name 不同）/ 版本 / 作者 - 说明：从 SKILL.md frontmatter
description来的完整文本（保留换行） - 标签：frontmatter
tags数组，渲染成圆角小徽标 - 运行时：frontmatter
enabledForRuntime（agent / dev-time / 两者），以/分隔展示 - 元数据来源说明：底部一行小字提示「元数据来源：
SKILL.mdfrontmatter（只读 · 修改请编辑源文件）」
弹窗底部只有「关闭」按钮，没有任何编辑入口。
小贴士： 不能在线编辑、不展示 SKILL.md 全文：详情弹窗只读且只展示 frontmatter 字段，不渲染 SKILL.md 正文。要改 skill 内容只能修源码、重新打包、删旧包后再导入。
3.5 删除 Skill
列表卡片右下角红色垃圾桶按钮即「删除」动作（本页代码不提供启禁开关，所有列表里的 skill 都在「已加载」状态运行）。点击后弹二次确认：
确认删除「jecloud-xxx」？此操作会从磁盘移除整个 skill 目录，无法撤销。
确认后调用 DELETE 接口，删除 data/skill-packages/<name>/ 整个目录，刷新列表并 toast 提示「已删除 xxx」。失败时 toast 显示错误详情。
注意： 删除不可撤销：本页执行的是「磁盘级移除」，没有回收站、没有软删除；要回滚必须重新导入原始 .zip。开发期反复测试请保留原始包文件。
3.6 调试技巧
开发 / 验证一个新 Skill 时，常用以下手段定位问题：
- 看调用日志 traces：发一条触发该 Skill 的消息，去监控 → 调用日志看本次对话实际调用了哪些工具、耗时多少、有没有报错。Skill 没被触发就在这看不到——说明触发条件或 description 写得不够明确。
- 对照 SKILL.md description：小匠靠 description 决定什么场景触发哪个 skill。description 写得含糊（"做数据相关的事"）就触发不准；要写具体场景词（"查询业务数据 / 出报表 / 销售统计 / 库存查询"）。
- 删除对比：怀疑某 skill 干扰回答，先把它删了再发同样问题对比——能快速验证"这条回答是不是它造成的"（验证完记得重新导入原始 .zip 恢复）。
- 查看落盘文件：导入后去
data/skill-packages/<name>/看解压结果是否完整（脚本 / 资源都在），尤其是 docker 部署模式下挂载卷有没有写权限。 - 看系统日志：解析 SKILL.md 失败、加载脚本异常这种底层问题，会打在监控 → 系统日志里，按时间倒序看最近一条。
小贴士： 本地开发热更新：开发期不想每次都重打包导入——可以让开发者把源码直接 mount 进
data/skill-packages/<name>/，重启 agent 容器即可生效；但正式投产时一定走 .zip 导入，否则其他产品 / 其他环境拉不到这份代码。
注意： API key 类敏感配置不要写进 SKILL.md：SKILL.md 在详情页是明文可见的——任何 admin 都能看到。Skill 内部需要的 API key、密钥这些走环境变量或 MCP 服务端配置，绝不写进包里。
提示： 下一步：导入 Skill 后 → 在 chat 里发一条能触发该 skill 的消息验证 → 去调用日志面板看 traces 是否有这次 skill 调用记录。