Skill 管理

两层管理

当前系统将 skill 管理拆成两层：

• 全局 skill 仓库管理：管理员维护共享 skill 来源
• 项目内 skill 管理：manager 与 owner 将全局 skill 安装到当前项目

管理员全局 Skill 管理

入口：

• Workspace 左下角菜单中的 Skill 管理
• 页面路径：/workspace/admin/skills

manager 与 owner 可以做什么：

• 添加 GitHub 或其他 Git 仓库地址
• 为 repository 指定分支
• 手动同步单个 repository
• 搜索 repository 或 skill
• 折叠/展开 repository
• 删除单个 skill
• 删除整个 repository

仓库同步与解析

当管理员添加 repository 后，系统会自动：

1. 将仓库下载到全局 skill 存储目录
2. 递归扫描仓库中的 SKILL.md
3. 将每个包含 SKILL.md 的目录识别为一个 skill
4. 解析 skill 名称、路径与描述
5. 生成可供项目安装的全局 skill 列表

说明：

• skill 名称默认取 SKILL.md 所在目录名
• 描述优先读取 SKILL.md frontmatter 中的 description
• 如果没有 frontmatter 描述，则回退到正文中的首个有效段落

项目内 Skills 管理

入口：

• 项目工作台顶部的 Skills 按钮

弹框结构：

• 左侧为 已安装 和各个 repository 列表
• 右侧展示当前选中分组下的 skills
• 顶部搜索框用于过滤当前分组中的 skills

你可以做什么：

• 从某个 repository 选择 skill 并安装到当前项目
• 对全局 skill 执行“启用全局”或“停用全局”
• 查看当前项目已经安装的 skill
• 删除已安装的 skill

开发模式下，系统会通过全局只读 skill 挂载自动启用两类内置 skill：

• agent-authoring
• visualizer-authoring

它们位于：

/global/skills/builtin/<skill-name>

说明：

• 这两个 skill 属于 mode-managed 内置能力
• 开发模式开启时自动出现
• 切回标准模式后会自动移除
• 不需要也不支持按普通 skill 的方式手动安装、删除或导入

安装与删除后的实际位置

项目已安装的 skill 会保存到：

.agent/skills/<namespace>/<skill-name>

为兼容旧项目，.agent/skills/<skill-name> 的一层目录结构仍然可以继续被发现和使用。 如果目标目录名已被当前项目占用，系统不会自动改名；请手动指定新的安装名称。

注意：

• 右侧 Local Workspace 文件树默认隐藏 .agent 目录
• 这不会影响 /skill:<name> 对项目 skill 的发现与调用
• 删除已安装 skill 时，会同时删除数据库记录和对应本地目录

全局启用 Skill

如果你只想让某个全局 skill 在当前项目里可用，但不希望复制一份到本地安装目录，可以直接使用 启用全局。

启用后的特点：

• 当前项目会保存一条全局启用记录
• 不会在 .agent/skills 下生成新的安装快照
• 该 skill 继续引用全局仓库中的定义，适合想保持统一来源的场景
• 需要停用时，可在同一位置执行 停用全局

使用建议

• 共享 skill 优先通过全局 repository 统一维护，不建议直接手工修改项目内 .agent/skills
• skill 更新后，管理员先在全局管理页执行同步，再由项目按需重新安装
• 如果仓库中存在多个 SKILL.md，请确保目录命名清晰，便于项目管理者识别

如果你需要创建或修改文件预览插件，建议直接使用内置的 visualizer-authoring：

• 它会指导你创建 .agent/visualizers/<namespace>/<name>/
• 会生成 VISUALIZER.yaml 与 web/index.html 的基本结构
• 自带模板和示例，当前包含 CSV visualizer 的参考例子

Skill 导入导出

项目已安装的 Skills 支持打包导出与批量导入，方便跨项目迁移与备份。

导出 Skills

在项目 Skills 弹框中，你可以：

1. 选择要导出的已安装 Skills（支持多选）
2. 点击导出按钮
3. 系统将选中的 Skills 打包成 zip 文件下载

导出的 zip 文件结构：

skills-20260401-120000.zip
├── manifest.json           # 元数据清单
└── skills/                 # Skills 文件目录
    └── <namespace>/<skill-name>/  # Skill 目录
        ├── SKILL.md
        └── ...其他文件

从其他项目导入 Skills

除了导入 zip 文件，还可以直接从其他项目导入已安装的 Skills：

操作路径：

1. 在项目 Skills 弹框中点击"从项目导入"按钮
2. 在弹出的对话框中选择源项目（下拉菜单显示所有可访问项目）
3. 系统自动加载源项目中已安装的 Skills 列表
4. 查看 Skill 名称、标题、描述和安装路径
5. 点击"从项目导入"按钮导入单个 Skill

导入特点：

• 如果 Skill 名称与当前尝试查找的名称匹配，会显示"名称匹配"标签便于识别
• 按名称匹配优先、标题字母顺序排列
• 只显示已安装的 Skills（不包含开发模式的 agent-authoring）
• 导入时自动复制 Skill 目录和创建安装记录

适用场景：

• 快速复制其他项目中已验证的 Skills
• 避免重新从 repository 安装相同 Skills
• 团队成员共享已配置好的 Skill 组合

注意事项：

• 如果目标项目已存在同名 Skill，导入会失败
• 导入的 Skill 使用源项目的当前版本快照
• 需要有源项目的访问权限才能看到其 Skills

导入 Skills

在项目 Skills 弹框中，你可以：

1. 点击导入按钮
2. 上传 Skills zip 文件
3. 系统自动解析 manifest.json 并安装 Skills

导入时会：

• 解析 zip 文件中的 manifest.json
• 将 Skills 目录复制到项目的 .agent/skills/ 下
• 创建数据库安装记录

注意事项：

• 如果项目中已存在同名 Skill，导入会失败并提示冲突
• 导入后 Skills 立即可用于 Agent 调用
• 建议在导入前确认 Skills 来源可信