【HarmonyOS 7】 HarmonyOS 应用 Skill创建和编排详解

【HarmonyOS 7】 HarmonyOS 应用 Skill 编排详解

一、前言

把应用接入系统 Agent 之后，还有一个更实际的问题：应用里的能力如何被发现、理解和复用？

如果每个应用都只提供一个大而全的 Agent，系统很难知道它具体擅长什么，开发者也很难把其中某个能力单独拿出来复用。

Skill 化的思路，是把应用能力拆成边界清楚、可以被调用和组合的能力单元。

Agent 更像任务的组织者，Skill 更像可以被调用的专业能力。用户说"根据我的会议安排提醒我出发并叫车"，Agent 负责拆解任务，日历 Skill、高德 Skill、闹钟 Skill 和打车 Skill 分别完成自己的部分。

二、Skill 和 API、Agent 有什么不同

（1）API 解决的是，程序如何调用程序。 （2）Skill 还需要解决，Agent 如何理解什么时候该调用它、需要什么输入、会返回什么结果，以及调用时有什么限制。 （3）Agent 解决的是，为了完成一个目标，接下来应该做什么。它可能调用多个 Skill，也可能根据上一步结果重新规划。

可以用下面的关系来理解：

用户目标
   ↓
Agent：理解、拆解、编排、确认
   ↓
Skill：查询日历 / 查路况 / 设闹钟 / 预约打车
   ↓
系统能力、应用能力或生态服务

因此，Skill 不是把 Prompt 写得更长，也不是把一个 API 换个名字。它需要有描述、有输入输出、有权限边界，还要能在真实设备上运行和验证。

三、一个应用内 Skill 大致长什么样

按照分享中的应用内 Skill 形态，Skill 可以随鸿蒙应用一起打包发布。应用包里既有应用模块，也有 Skill 描述和脚本实现。

一个便于理解的目录可以写成这样：

Application.app
├── modules/
│   └── entry/
├── my-skill/
│   ├── scripts/
│   │   └── query.ts
│   ├── assets/
│   │   └── icon.png
│   ├── references/
│   │   └── usage.md
│   ├── skill.md
│   └── module.json
└── ...

这里的文件名和目录仅用于说明组织方式，具体字段和打包规范以当前开放平台文档为准。几个文件的职责可以先这样分：

skill.md：说明 Skill 能做什么、适合什么场景、需要哪些输入
module.json：声明模块信息，以及可选的端侧能力和安全管理配置
scripts：放具体的脚本或 ArkTS 实现
references：放给开发和调试使用的参考资料
assets：放卡片或交互需要的静态资源

Skill 描述不要写成产品宣传语。比起"提供全方位智能服务"，下面这种描述更有用：

# 查询网点

## 能力
根据城市、当前位置和营业时间筛选可预约网点。

## 输入
- city：可选，城市名称
- location：可选，当前位置
- serviceTime：可选，希望办理的时间

## 输出
- 网点名称、地址、距离、营业时间
- 是否支持预约

## 需要确认
提交预约前必须展示网点和时间，并要求用户确认。

描述越具体，调用时越不容易出现"看起来相关，实际上不能完成"的问题。

四、Skill 的开发入口不止一种

小艺开放平台提供了现成的功能：

1、已有 Skill 快速导入

团队如果已经有符合生态规范的 Skill，可以先导入，再补齐鸿蒙应用需要的身份、端侧能力、卡片和安全配置。这个路径适合把已有能力快速接进来，但导入之后仍要做真机验证，不能只看文件结构能否通过。

2、从零开始 Vibe Coding

可以直接用自然语言描述一个小而明确的能力，例如：

读取应用内保存的会议记录，按日期筛选，返回会议时间和地点；如果会议距离当前时间不足 30 分钟，给出提醒建议，但不自动修改日历。

让工具先生成目录、描述和基础实现，再由开发者补充数据访问、权限和异常处理。这样可以缩短从想法到原型的时间，尤其适合验证 Skill 的边界和交互方式。

但 Vibe Coding 不能替代工程工作。生成代码之后，仍然要检查：

是否读取了不必要的数据
是否把用户输入直接拼进了高风险调用
是否正确处理空结果、超时和重复执行
是否把需要确认的动作直接执行了
是否适配了真机上的权限和生命周期

3、从 API 或 MCP 能力转成 Skill

已有 API 或 MCP 工具时，重点不是把接口名称原样搬过去，而是补齐 Agent 需要的上下文：它解决什么问题，何时调用，输入有什么限制，结果是否需要用户确认。

一个"查询实时路况"的 Skill，需要说明出发地、目的地、出发时间和返回的预计耗时；一个"预约打车"的 Skill，则需要增加车型、上车点、联系人和确认规则。两个接口都能返回 JSON，但它们的风险和调用前提不同。

五、端 Skill 和云 Skill 怎么分

分享中的平台同时覆盖端云 Skill，选择时可以看四个方面：

维度	端 Skill	云 Skill
数据来源	本地应用数据、设备状态	云端业务数据、远程服务
响应条件	依赖设备状态或应用生命周期	依赖网络和云端服务
适合能力	端内查询、设备控制、应用特性	内容检索、订单、行业服务、复杂计算
主要注意点	权限、隐私、资源和版本适配	身份、网络、超时、数据传输和成本

两者也可以组合。比如日历信息在设备侧读取，路况在云端查询，提醒在系统侧设置。此时要把每个 Skill 的输入输出和数据边界写清楚，避免 Agent 在多次调用过程中丢失上下文。

六、Skill 调试，管理，分发

一个 Skill 从开发到用户可用，至少要走四步：

开发 → 调测 → 管理 → 分发

开发

完成描述、实现、权限和结果呈现。优先从一个具体任务开始，不要一上来做覆盖几十个意图的万能 Skill。

调测

先在线调测，再上真机调测。在线调测适合检查输入输出和基础流程，真机调测才能发现权限、生命周期、系统入口和卡片展示的问题。

质量评测不能只测"回答是否正确"，还要测试：

• 同义表达能否命中；
• 缺少参数时是否会追问；
• 用户中途改口能否停止或重新规划；
• 结果过期后是否会重新查询；
• 外部服务失败时是否会给出可理解的提示。

安全检测则要关注越权访问、敏感字段、恶意输入、危险操作和日志泄露。

管理

上架、更新、下架都要有版本策略。Skill 的描述、权限和输出结构发生变化时，不能只替换脚本，还要考虑旧版本应用和旧任务是否仍能正常处理。

分发

分发不只是把 Skill 放进一个列表。用户能否通过系统入口找到它，取决于描述是否准确、适用场景是否清楚、任务推荐是否匹配。Skill 市场和基于任务的推荐，最终都建立在能力描述和调用质量之上。

七、多 Skill 编排任务链

下面这句话很适合作为验证多 Skill 编排的例子：

我下午有一个和开发者的线下会议，需要提前十分钟左右到达现场，请根据实时路况帮我提前定好出发提醒的闹钟，并预约打车。

这句话至少包含四个动作：

1. 从日历中查询会议时间和地点；
2. 调用地图 Skill 计算路况和预计耗时；
3. 根据活动开始时间推理出发时间，调用闹钟 Skill；
4. 调用生态打车 Skill，预约车辆。

它不是固定顺序的函数调用。第二步的路况结果会影响第三步的提醒时间，会议地点缺失时还需要先追问用户。一个比较稳妥的执行过程应该在每一步记录状态：

读取会议 ──成功──> 获得时间和地点
    │
    └─失败──> 请求用户补充会议地点

查询路况 ──成功──> 计算最晚出发时间
    │
    └─失败──> 给出默认估算，并询问是否继续

设置闹钟 ──成功──> 等待用户确认打车
    │
    └─失败──> 保留出发时间，提示手动设置

预约打车 ──成功──> 返回订单信息
    │
    └─失败──> 返回原因，不重复提交

这里有两个容易被忽略的点。

第一，Skill 要有明确的副作用说明。查询类 Skill 可以自动调用，设置闹钟和预约打车通常需要确认。第二，Skill 要支持幂等。用户重复说了一遍话、网络重试了一次，都不应该产生两个闹钟或两笔订单。

八、把行业能力拆成 Skill 集合

金融服务是比较典型的垂直场景。东方财富妙想的案例把能力拆成智能选股、模拟组合管理、自选股管理、综合诊基、综合诊股、热点发现、金融咨询检索和金融数据查询等多个 Skill，再根据用户意图组合调用。

这种拆分比"做一个金融聊天机器人"更容易维护：数据查询、行情解释、组合管理和检索各自有清楚的职责，模型负责选择和编排，业务规则仍由对应服务掌握。

不过，金融 Skill 对数据时效、来源、风险提示和权限的要求更高。行情查询可以自动完成，涉及交易或资产操作的动作则需要更严格的确认和审计。Skill 越专业，越不能只追求"看起来会回答"。

九、Skill 设计的几个经验

能力要小，但不要碎到无法使用

"查询网点"和"提交预约"可以拆开，因为两者权限和副作用不同；但如果把"读取城市""读取距离""格式化地址"也单独做成三个 Skill，编排成本反而会上升。

输入输出要稳定

返回结果尽量使用结构化字段，时间、金额、地点、状态不要只放在自然语言里。自然语言适合解释，结构化数据适合继续执行。

把确认点写进能力描述

需要用户确认的动作要在 Skill 描述中写清楚，不能寄希望于 Agent 每次都自行判断得很准确。

先做真实任务，再扩大覆盖范围

一个能稳定完成"查询会议并设置提醒"的 Skill，比一个声称支持几十种办公任务、但经常需要人工收尾的 Skill 更有价值。

让错误也成为结果的一部分

Skill 不应只定义成功返回，还要定义缺参、权限不足、资源不存在、服务超时和用户取消等情况。上层 Agent 只有拿到清楚的失败类型，才知道是重试、追问还是结束任务。

Skill 化不是给应用增加一个目录，也不是把 API 包装成几个关键词。它真正改变的是应用能力的组织方式：能力有明确边界，可以被 Agent 发现和调用，可以在端云之间选择运行位置，也可以和系统 Skill、生态 Skill 组合成完整任务。

从一个具体场景开始，先把描述、权限、输入输出和失败路径做扎实，再接入调测、评测和分发流程。这样做出来的 Skill，才有机会从一次演示变成用户愿意反复使用的应用能力。

小艺开放平台入口：developer.huawei.com/consumer/cn...