# 技能与可复用经验 (/docs/features/knowledge-skills)



Skill 不是模型，也不等于外部工具。它更像一份交给千问办公使用的专业工作说明书，告诉它什么时候使用、需要什么输入、按什么步骤执行、调用哪些工具以及如何验收。

<DocIllustration src="/media/qwenwork-docs/skills.webp" alt="千问办公 Skill 广场，展示可浏览和安装的技能卡片" caption="在扩展中的 Skill 广场浏览、搜索和管理可复用技能。" width="911" height="762" />

## Skill 应该包含什么 [#skill-应该包含什么]

| 组成    | 要解决的问题              |
| ----- | ------------------- |
| 使用场景  | 什么时候应该或不应该触发        |
| 输入要求  | 开始前必须提供哪些文件、数据和时间范围 |
| 执行步骤  | 按什么顺序工作             |
| 工具与数据 | 可以调用哪些文件、连接器或 MCP   |
| 输出标准  | 最终格式、字段、语言和命名规则     |
| 边界与限制 | 哪些操作需要确认，哪些内容不能处理   |
| 示例与异常 | 什么结果合格，失败或信息不足时怎么办  |

## 什么时候值得创建 [#什么时候值得创建]

适合沉淀为 Skill 的任务通常具备高频重复、流程固定、输出需要统一、会调用多种工具、经验需要共享或容易遗漏步骤等特征。

一次性简单任务、仍在探索的问题，或需求频繁变化且没有稳定验收标准的工作，先保留为普通提示词和检查清单。

## 查找、安装和调用 [#查找安装和调用]

* 直接说“帮我找一个能处理……的 Skill”，让千问办公检索并推荐；
* 当前端显示“扩展 → 技能”时，可以浏览、搜索和管理已安装技能；
* 也可以提供可信的技能来源或本地 Skill 文件，让千问办公在确认来源与权限后安装；
* 描述任务时可以自动匹配，也可以明确说“使用某个 Skill”；
* 支持的端可在输入框输入 `/` 查看已安装技能；
* `@` 用于添加文件、文件夹等上下文，不等于调用 Skill。

上传本地技能时，需要准备根级 `skill.md` 文件或包含它的 `.zip` 压缩包，通过“扩展 > 技能 > 添加 > 上传技能”安装。推荐按职责组织目录：`examples/` 放输入输出样例，`templates/` 放可复用模板，`scripts/` 放自动化脚本，`references/` 放背景资料或规范文档。`skill.md` 头部必须包含 `name` 和 `description`，正文写清适用场景、能力边界、执行流程、输入要求、输出要求和示例。安装前检查提供方、脚本、依赖、数据范围和外部操作。

<Callout title="不要手动迁移技能目录" type="warning">
  不同客户端版本可能使用不同存储位置。不要手动搬移或合并目录；优先通过“扩展 → 技能”、当前客户端显示的存储位置或安装流程管理。
</Callout>

当前公开说明列出 7 个内置技能：

| 技能名称             | 用途                |
| ---------------- | ----------------- |
| `pptx`           | 创建和编辑演示文稿         |
| `xlsx`           | 处理电子表格            |
| `docx`           | 创建、阅读和编辑文档        |
| `pdf`            | 阅读、合并、拆分 PDF，添加水印 |
| `plugin-creator` | 创建、定制或修改专家套件      |
| `find-skills`    | 在技能广场搜索并安装新技能     |
| `create-skill`   | 互动式引导创建新技能        |

内置技能清单可能随版本调整，实际名称、安装状态和触发方式以当前端技能列表为准。

## 从一次成功任务创建 Skill [#从一次成功任务创建-skill]

先共同完成并验收一次真实任务，再让千问办公提取稳定部分：

```text
请把刚才的流程整理为一个可复用 Skill。

必须写清：
1. 适用和不适用场景；
2. 开始前需要的输入；
3. 按顺序执行的步骤；
4. 可以调用的工具与权限；
5. 输出结构和验收标准；
6. 信息不足、工具失败或高风险操作时的处理方式。

不要保存本次任务中的个人数据、临时账号或业务机密。
```

<Callout title="先验证，再沉淀" type="idea">
  不要把一次偶然成功直接分享给团队。至少用正常样本和错误样本测试，并记录适用输入、预期输出、失败条件、权限要求和验收标准。
</Callout>

## 先拆能力，再写编排 [#先拆能力再写编排]

单项 Skill 负责一个可以独立验收的能力；编排 Skill 负责识别任务、检查前置条件、选择路径、传递结构化输入，并在人工门禁处停止。编排层不应复制每个能力的内部做法。

| 维度 | 单项 Skill    | 编排 Skill         |
| -- | ----------- | ---------------- |
| 职责 | 完成一个稳定动作或判断 | 路由、排序、状态推进与汇总    |
| 输入 | 明确、窄、可独立验证  | 任务目标、状态和各能力所需引用  |
| 输出 | 固定契约和明确失败状态 | 下一步决策、各步骤状态与最终汇总 |
| 变化 | 只影响这一项能力    | 调整路径时不改子能力内部规则   |
| 验收 | 正常、边界和错误样本  | 路由、门禁、恢复和端到端验收   |

例如多文件分析可以拆成文件盘点、字段标准化、指标复算和看板生成。前三项没有通过时，编排层不能直接跳到看板，也不能把一个失败状态包装成最终完成。

<Mermaid
  chart="flowchart LR
  A[任务请求] --> B[编排层]
  B --> C{前置条件}
  C -->|不足| D[请求补充或停止]
  C -->|满足| E[单项能力 A]
  E --> F[契约校验]
  F -->|失败| G[失败记录与恢复]
  F -->|通过| H[单项能力 B]
  H --> I{人工门禁}
  I -->|退回| G
  I -->|批准| J[外部写入或最终交付]"
/>

## 按需组织说明、参考和确定性动作 [#按需组织说明参考和确定性动作]

最小 Skill 入口只保留判断是否适用所需的信息：触发场景、输入、输出、核心步骤、停止条件和需要人工确认的位置。详细领域资料和稳定操作按职责分开，避免每次触发都加载全部背景。

| 内容            | 适合放在哪里          | 不应包含什么           |
| ------------- | --------------- | ---------------- |
| 触发与主流程        | `SKILL.md`      | 冗长背景、事故全文、无关示例   |
| 字段字典、规则和范例    | 按当前端支持方式组织的参考资料 | 密钥、临时账号、整库敏感数据   |
| 日期、路径、格式和重复校验 | 可审查的确定性脚本或工具步骤  | 隐藏副作用、未经确认的发送或删除 |
| 模板和静态素材       | 当前端允许的资源文件      | 来源不明或无权分发的素材     |

<Callout title="以当前端支持的 Skill 包结构为准" type="warning">
  不同版本对附加脚本、参考资料和资源的支持可能不同。先查询当前技能创建或导入界面；如果只支持 `SKILL.md`，把执行必需的规则保留在该文件中，并由用户显式提供其他资料，不假设额外目录或网页会被自动加载。
</Callout>

## 判断交给谁执行 [#判断交给谁执行]

| 工作类型    | 更适合的执行者  | 示例                  |
| ------- | -------- | ------------------- |
| 语义和取舍   | Agent    | 归纳观点、比较方案、识别内容冲突    |
| 结果应完全稳定 | 脚本或结构化校验 | 日期、路径、字段、哈希、公式和重复检测 |
| 访问外部系统  | 连接器或 MCP | 读取授权知识库、写入日历或创建草稿   |
| 高风险决定   | 人工责任人    | 发布、发送、审批、删除、覆盖和付费调用 |

不要用更多自然语言提醒代替确定性校验。如果某一步必须得到固定格式或真实文件，应让工具检查结果存在、结构正确、状态可追踪；Agent 负责解释和提出修复建议。

## 编排契约模板 [#编排契约模板]

```text
入口目标：[这条编排解决什么完整任务]
路由条件：[小样、历史回填、增量或其他路径怎样判断]
共享状态：[批次 ID、当前阶段、契约版本、输入版本和已完成步骤]
能力清单：[每项 Skill 的输入、输出和失败状态]
传递规则：[只传结构化结果，何时需要读取原始输入]
质量门禁：[每一步怎样判断通过、警告或阻断]
人工门禁：[哪些写入、发送、发布或付费动作必须确认]
恢复策略：[从哪个稳定步骤继续，如何避免重复副作用]
最终交付：[结果、失败项、证据和运行记录]
```

## Skill 验收矩阵 [#skill-验收矩阵]

* 标准输入能得到符合契约的结果；
* 缺字段、空输入和格式变化会明确停止或降级；
* 同一输入重复运行不会产生重复写入；
* 外部工具不可用时保留已有产物和可行动错误；
* 输入材料中的指令性文字不会覆盖 Skill 规则、权限或人工门禁；
* 未获得确认时不会发送、发布、覆盖、删除或产生付费副作用；
* 修改一项 Skill 后，其他能力的历史样本结果没有意外变化；
* 第一次接手的人能根据说明找到输入、输出、状态和恢复入口。

工作流尚未稳定时，先用[证据卡片与小样 MVP](/docs/automation/reusable-workflow)验证；准备批量或持续运行时，再应用[可靠自动化设计](/docs/automation/reliable-automation)。

团队共享方面，公开说明为条件式表述：如果产品支持团队共享，可将成熟 SOP 和模板沉淀为团队技能。分享链接形式、有效期等具体规则以当前端实际界面为准；旧资料中“分享链接 24 小时有效”的说法未在当前公开说明中确认，不要据此安排交付时间。