技能
TIP
技能是把特定任务的操作流程写成可以按需加载的说明文档。模型平时只看技能目录，需要时才读取完整步骤，所以可以配置很多技能而不占用日常对话的上下文。
工具解决「能做什么」，技能解决「怎么做好」。把复杂业务的操作指南全部写进系统提示词，会很快占满上下文。技能的核心是一份 Markdown 说明文档，复杂时还可以附带脚本、模板和参考资料。
模型默认只加载一份「技能目录」，其中只有各技能的名称和简短描述。对话涉及某个领域时，模型才读取该技能的完整说明，并按步骤调用工具或执行脚本。这种机制称为「渐进披露」：技能说明的上下文开销只出现在实际读取它的那一轮。
技能页
点击「能力 → 技能」进入管理页面，这里列出了所有已发现的技能。可以在卡片和列表视图间切换、按来源分组，或按关键字搜索、按名称或更新时间排序。
点击任意技能打开详情面板：
- 名称、简介与正文预览。
- 来源：内置、宿主机目录、用户自定义、工作区、导入或市场。
- 文件清单：脚本、模板和参考文档。
- 环境变量声明：必填项、密钥和默认值。
- 覆盖关系：存在同名技能时，显示生效的版本和被遮蔽的副本。
导入与管理
技能页支持导入单个 SKILL.md 文件、技能文件夹或 .zip 压缩包。导入的技能与已有技能同名时会直接覆盖。已导入的技能可以在详情面板中删除。
随插件分发的内置技能是只读的。需要修改时，点击「复制」把它复制到用户自定义目录再改。
WARNING
同名技能不会合并，只有优先级最高的一份生效。修改技能后表现没变化时，先在详情面板中查看覆盖关系。
来源与优先级
同名技能按以下优先级决定生效版本：
- 工作区：当前 Agent 工作目录中的技能，优先级最高，只影响这个项目。
- 内置：随插件分发，只读。
- 宿主机目录：数据目录或指定宿主机路径下的技能，适合跨实例集中维护。
- 用户自定义：数据目录中的自定义技能文件夹，控制台中新建或复制的技能都保存在这里。
同一层级的同名技能按扫描顺序决定。从技能市场下载的技能存放在宿主机目录中，遵循同样的规则。
技能的结构
最简单的技能只有一个 SKILL.md 文件，由头部元数据和说明正文组成：
| 字段 | 作用 |
|---|---|
| 名称 | 技能的唯一标识，通常采用小写短横线命名。 |
| 描述 | 技能的功能简述，会显示在技能目录中。 |
| 版本 / 作者 / 许可 | 可选的来源与元信息。 |
| 平台 | 适用操作系统，如 macOS、Linux、Windows。 |
| 环境 | 适用的运行环境。 |
| 环境变量 | 运行所需的配置项，可标记为密钥、必填或提供默认值。 |
正文描述使用场景、执行步骤、注意事项和异常处理，写得越明确，模型执行越稳定。技能目录中的脚本、模板和参考文档，模型可以在加载技能后通过工具读取或执行。
环境变量与密钥
在元数据中声明的环境变量可以标记为：
- 必需：缺少时技能无法运行，加载时会提示。
- 密钥：不会出现在日志或模型上下文中。
- 默认值：未配置时使用的值。
管理员可以在场景规则中禁止某个群的技能使用已保存的密钥，依赖密钥的技能在该会话中就不可用。
TIP
不要把密码或 API Token 明文写进 SKILL.md。在元数据中声明环境变量，真实凭据保存在实例配置中，正文只引用变量名。
模型怎么用技能
模型初始只拿到技能目录。用户的输入命中某个技能的场景时，模型可以搜索或列出技能、读取完整说明、读取参考文件，或运行附带的脚本。读取的说明只存在于当前轮次，不会常驻系统提示，之后需要时再重新读取。
技能也可以直接注册专用工具，例如「查询订单」，模型无需阅读说明就能直接调用。
技能脚本
计算、格式转换、系统命令等确定性任务，交给脚本比让模型推理更可靠。推荐让模型负责分析和决策，把确定性操作封装进脚本。
执行脚本时，系统在受控的独立工作目录中运行，注入声明的环境变量，按权限模式检查是否需要审批，并把标准输出和错误返回给模型。
WARNING
技能脚本可以在宿主机上执行命令。不要把来源不明的技能直接导入生产环境，导入前审查脚本；无法确认安全时，把脚本执行设为需要审批。
技能市场与自动进化
启用技能市场后，可以在技能页中浏览、搜索和安装社区技能，它们遵循与本地技能相同的发现、覆盖和权限规则。
可选的「技能自进化」插件（默认未安装）允许模型根据成功经验生成技能草稿。草稿需要经过测试、人工审查并手动确认后才会生效，支持回滚；模型只能提交草稿，无法绕过审查上线。未安装该插件时，技能注册表是只读的，系统不会自行生成或修改技能。
与工具、MCP 的关系
- 工具：模型可以直接调用的原子动作。
- 技能：完成复杂任务的方法和流程，规定何时、按什么顺序调用工具。
- MCP：把外部服务的能力转换为工具的协议。
一份技能可以组合多个工具，一个 MCP 服务器可以提供多个工具，技能也可以调用 MCP 工具。无论来源如何，权限和审批规则都一样。
推荐配置
| 场景 | 建议 |
|---|---|
| 个人实例 | 只启用常用技能，让目录保持简短；敏感变量标记为密钥；脚本执行保留默认的审批 |
| 多人群聊 | 在「场景规则 → 能力 → 技能」中为各群配置允许/禁用列表和密钥权限；公共群只开放查询类技能 |
| 团队与项目 | 项目专属技能放在工作区目录；技能文件纳入版本控制，先在测试实例中验证 |
| 技能很多 | 依靠渐进披露，不要把太多技能转为常驻工具；定期清理，关注覆盖状态 |
常见问题
模型没识别到技能：检查技能是否被扫描到、是否被更高优先级的同名技能遮蔽、是否被场景规则禁用。详情面板会显示实际的生效状态。
技能已加载但模型不调用：描述太模糊或缺少触发条件。在描述和正文开头写明「何时使用这个技能」。
脚本提示缺少环境变量：在详情面板中检查并补齐必填变量；涉及密钥时，确认场景规则允许使用密钥。
导入后同名技能没生效：被更高优先级的同名技能遮蔽了。查看覆盖关系，重命名或移除冲突项。
技能正文太长：拆分成几个小技能，或把细节移到参考文件中，正文只保留核心流程。
