技能包详解

如果说工具（Tool）是智能体的“手”，技能包（Skill Pack）就是智能体的“方法论”。工具解决“能不能做某个动作”，技能解决“遇到某类任务时应该怎么做”。技能包把判断标准、操作步骤、参考资料和工具使用方式写成可审查的文档，让智能体在重复场景中稳定执行。

工具 vs 技能

这两个概念容易混淆，可以从粒度和作用边界来区分：

维度	工具（Tool）	技能（Skill）
本质	原子能力	任务方法
粒度	单次调用	多步骤流程
示例	Read、Grep、PowerShell、WebFetch	合同审查、PDF 表单填写、网页调研
风险	由工具本身和参数决定	由技能流程中使用的工具决定
类比	一把锤子或一支笔	一本操作手册

例如，Read 只能读取文件；“数据分析报告”技能会指导智能体读取数据、清洗数据、统计分析、生成可视化并输出报告。技能不是新的执行权限，而是告诉智能体如何组合已有工具、按什么顺序推进、遇到异常时如何处理。

技能包包含什么

一个技能包的核心是 SKILL.md，也可以包含脚本、参考资料、模板和评测用例：

my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── evals/

SKILL.md 通常包含：

• 适用场景和不适用场景
• 输入要求和执行步骤
• 可用工具和权限边界
• 输出格式和完成标准
• 失败处理和升级路径
• 版本、作者、供应商或模型偏好等元信息

技能的本质

从技术角度看，技能包是一份结构化指令和相关资源。智能体加载技能后，会把其中的步骤、约束和完成标准作为任务上下文使用，因此技能行为是可审查、可复用的。

技能如何生效

技能有两种主要触发方式：

方式	说明	适合场景
显式调用	用户通过命令、技能列表或界面指定某个技能	你明确知道要用哪个技能
自动匹配	智能体根据任务和技能描述判断是否加载	你只描述目标，不关心具体技能

技能可声明 user-invocable、disable-model-invocation、allowed-tools、context 等字段，用来控制用户是否能直接调用、模型是否能自动触发、执行时可用哪些工具，以及是否使用 fork 子上下文。disable-model-invocation 也兼容 disable_model_invocation 写法。

显式调用

当你在技能列表中选择某个技能，或在对话中明确要求使用某个技能时，系统会把该技能加入当前任务上下文。它适合你已经知道目标流程的情况，例如“用合同审查技能检查这份协议”。

自动匹配

自动匹配依赖技能描述和触发条件。你只需要描述目标，智能体会判断是否需要加载某个启用的技能。它适合你只关心结果、不想手动决定流程的情况。

只有启用状态的技能会进入候选范围。如果技能声明了 allowed-tools，智能体只能在该技能允许的工具范围内执行；如果技能关闭模型自动调用，则不会被模型主动匹配，只能由用户或界面显式调用。

技能来源与优先级

DesireCore 会发现三类技能：

来源	位置	特点
全局技能	~/.desirecore/skills/	所有智能体共享，内置技能也在这里同步
智能体技能	智能体仓库内	只服务于当前智能体，可随智能体发布
项目技能	工作目录 .agents/skills/ 或 .claude/skills/	只在当前项目上下文中生效

只有启用状态的技能会进入智能体上下文。系统还会按工具实际可用性注入能力声明，避免智能体看到当前环境无法调用的能力。

全局技能 vs 智能体技能

全局技能适合文件处理、搜索优化、网页访问等通用能力，所有智能体都可以复用；智能体技能适合某个智能体的专业流程，例如特定行业审查、项目内发布流程或团队内部规范。

浏览和安装技能

你可以从技能市场安装技能，也可以在技能管理中导入本地技能。

在技能市场中，通常可以查看：

• 功能描述和适用场景
• 技能需要的工具和权限
• 作者、来源、版本和更新信息
• 适用的供应商、模型偏好或运行环境要求

本地导入支持：

• 单个 .md 技能文件
• 包含 SKILL.md 的文件夹
• .zip 压缩包

安装和导入时，系统会检查路径安全、文件结构和必要元信息。技能如果声明了供应商偏好，运行时会优先匹配有可用 Key 的对应供应商；如果声明了工具白名单，智能体只会在该范围内执行。

依赖检查会尽量在启用前暴露问题：

• 依赖工具已就绪：技能可以直接启用或导入
• 缺少工具或能力：界面会提示当前环境无法完整执行该技能
• 结构不完整：例如缺少 SKILL.md、元信息不合法或压缩包结构不符合要求时，导入会失败并给出原因

技能安装后不会自动授予系统权限。真正执行高风险操作时，仍然受工具权限、系统确认和审批机制约束。

内置全局技能

DesireCore 附带一组通用全局技能，用于常见的专业任务：

• 创建和打包技能
• Word / Excel / PowerPoint 文档处理
• PDF 阅读、表单和版面检查
• 网页访问和浏览器调试
• 前端产品与界面设计
• 邮件操作

这些技能随客户端和市场同步自动维护。你可以查看、禁用或复制它们，也可以创建自己的技能覆盖特定工作流。

管理已安装的技能

在技能管理中，你可以维护技能的可用状态和来源：

• 查看技能：检查已安装技能、内置技能、项目技能和智能体技能
• 启用/禁用：控制技能是否进入智能体上下文或候选匹配范围
• 查看详情：查看描述、依赖、触发方式、允许工具和资源文件
• 复制或自定义：基于内置技能创建自己的版本，避免更新覆盖你的本地流程
• 卸载或移除：删除不再需要的市场技能或本地技能

如果技能来自项目目录，是否生效还取决于当前工作目录和智能体是否使用该项目上下文。

创建自定义技能

创建技能时，建议先写清楚三个问题：

1. 这个技能在什么情况下应该使用？
2. 它应该按什么步骤执行？
3. 什么输出才算完成？

好的技能应该做到：

• 触发明确：描述清楚适用和不适用场景
• 步骤可执行：每一步都有输入、动作和输出
• 边界清楚：说明哪些操作需要确认，哪些情况要升级给用户
• 可验证：定义完成标准和检查方式
• 少即是多：把参考资料放进 references/，不要把所有背景都堆进主指令

基本创建流程

1. 新建一个技能目录或单个 Markdown 技能文件
2. 编写 SKILL.md，说明名称、用途、触发条件和执行步骤
3. 把长参考资料放入 references/，把可复用脚本放入 scripts/
4. 声明必要的工具边界、供应商偏好或上下文设置
5. 导入技能并启用
6. 用简单样例测试触发、执行步骤和输出格式

编写建议

技能指令应当清晰、具体、无歧义：

• 步骤明确：每一步做什么、输入什么、输出什么
• 条件判断：在什么情况下走哪个分支
• 错误处理：某一步失败后是重试、跳过，还是请求用户确认
• 完成标准：什么结果算完成，交付物应该放在哪里
• 权限边界：哪些操作必须先询问用户，哪些工具不能使用

先测试再复用

自定义技能会影响智能体的执行方式。正式用于重要任务前，建议先在简单样例中测试，确认触发、工具使用和输出格式符合预期。

技能更新

内置和市场技能会检测可用更新。系统会尊重用户修改：未改动的技能可以自动同步，已改动的技能不会被静默覆盖。需要保留本地定制时，可以复制技能并改成自己的名称和 ID。