skills-management

管理 Skills

Skill 是一个可复用的能力包，通常包含一个 SKILL.md、提示词、参考资料和可选脚本。智能体先看到 Skill 的描述，再按需要读取 SKILL.md；Skill 声明的工具和 MCP 依赖会随激活状态加入模型请求。

什么时候用 Skill

把一类稳定、可复用的工作方式放进 Skill，例如文档处理、研究流程、报表生成或某个外部服务的操作规范。单次任务要求写在对话中；需要跨对话复用的规则和资料再考虑 Skill 或用户工作区文件。

Skill 保存在哪里

来源	位置和事实	谁可以安装/管理
内置	随代码发布，启动时同步索引	管理员可以启用/停用，不能删除或直接编辑
共享上传/远程	Skill 持久目录 + PostgreSQL 索引	管理员按共享范围管理
个人	当前用户 UserWorkspace 的 agents/skills/<slug>	当前用户；不创建共享 Skill 数据库记录

运行时路径是：

• 共享和内置 Skill：/home/gem/skills/<slug>/，对 Agent 只读；
• 个人 Skill：/home/gem/user-data/agents/skills/<slug>/，位于当前用户的 UserWorkspace。

同一用户有个人 Skill 和共享 Skill 使用同一个 slug 时，个人版本覆盖该用户看到的共享版本。删除个人版本后，如果共享版本仍可访问，会恢复共享版本。

创建 Skill

标准目录至少包含根级 SKILL.md：

my-skill/
├── SKILL.md
├── tools/       # 可选脚本
└── prompts/     # 可选提示词或参考资料

SKILL.md 使用 YAML frontmatter：

---
name: 文档整理
slug: document-cleanup
description: 按指定结构整理文档，并保留可核对的来源。
tool_dependencies: []
mcp_dependencies: []
skill_dependencies: []
---

# 文档整理

## 何时使用

说明这个 Skill 解决什么问题，以及什么时候不该使用。

## 操作步骤

写出 Agent 应遵循的步骤、限制和验收方式。

必填字段是 name 和 description。slug 可省略，省略时直接使用 name，因此省略 slug 时 name 本身也必须是小写字母、数字和单个短横线组成的值；中文或带空格的展示名称会校验失败。建议显式填写 slug，把自然语言名称和稳定标识分开。名称和 slug 最多 128 个字符。

依赖字段含义：

字段	作用
tool_dependencies	需要的内置工具
mcp_dependencies	需要的 MCP 服务器
skill_dependencies	需要先提供说明的其他 Skill

个人 Skill 只作为用户文件读取，不解析这些平台依赖；需要依赖工具、MCP 或其他 Skill 时，安装为共享 Skill。

安装方式

进入“扩展 → Skills”，可以选择：

1. 推荐 Skill：从推荐列表生成安装草稿。
2. 上传：上传 ZIP 或单个 SKILL.md，解析后生成草稿。
3. 远程安装：从 GitHub 仓库、ModelScope Skill 或合集拉取一个或多个 Skill。
4. 在线编辑：编辑已有且有管理权限的共享 Skill 文件和依赖。
5. Agent 内安装：主智能体使用 install_skill 把 Skill 安装到当前用户的个人来源；子智能体不能使用该工具。

上传和远程安装都先解析为草稿，再选择个人或共享位置并确认。确认前可以检查名称、说明、文件和依赖；取消草稿不会写入正式 Skill。

远程来源限制

管理员在“设置 → 基本设置 → Skill 配置 → 远程来源白名单”中维护 remote_skill_source_policy.allowed_hosts。默认允许 github.com 和 modelscope.cn；主机名必须精确匹配，保存空列表会关闭远程安装。

示例来源：

anthropics/skills
https://github.com/anthropics/skills
https://modelscope.cn/skills/@anthropics/pdf
https://modelscope.cn/collections/MiniMax/MiniMax-Office-skills