如何设计一个优秀的 Skills

大家好，我是石小石~

---

引言：AI 的下一阶段，不只是更会思考

最近，被一个新概念深深吸引了： "具身交互智能" 。

它的核心主张很直白：让 AI 拥有身体、感知世界、理解环境，并通过语音、表情、动作和实时响应，自然地与人交互。通俗一点说，就是让大模型 / Agent 不只停留在聊天框里，而是拥有 3D 身体、语音表达、动作反馈和实时交互能力，真正进入屏幕、网页、机器人、展厅、门店、教育等真实场景。

作为全球较早布局具身交互智能的AI科技公司，魔珐科技依托自研文生3D多模态大模型与端侧交互技术，打造了魔珐星云具身交互智能开放平台。

借助其具身驱动SDK，仅需少量代码，就可以补齐 AI 的"身体、表达和交互"，实现AI 从文本交互走向具身交互的关键一步。

一个 Demo，验证「具身交互」的可能性

概念看够了，动手才是真的。于是，我用魔珐星云 SDK，做了一个可交互的 AI 具身智能体 Demo：发送文字消息后，数字人会实时语音播报，同时配合自然的表情和肢体动作，整个过程响应低于 500ms，并支持全程随时打断，体验流畅。

从 Demo 的制作和体验过程中，我有一个很明显的感受：AI 的下一阶段，不只是更会思考，而是更会交互。 从文本对话到操作界面、调用工具、生成可视化结果，AI 正在从文本交互走向具身交互，这将是未来的核心方向。

关联文章地址：

星云SDK + 油猴：给LLM塑造肉身，陪伴你在每个网页；

AI具身交互：实现一个会说话的3D虚拟伴侣

DEMO在线体验地址：www.axureshow.com/project/HDZ...

Skills：技术平权的下一步

Demo 做出来了，但一个现实问题随之浮现：体验门槛。

虽然官方教程和我的 Demo 代码已经尽量精简，几行代码就能跑起来，但由于 Demo 主要基于前端技术栈构建，其他技术栈的开发者想要上手体验，依然有不小的认知成本。后端同学、移动端同学、甚至非技术岗的产品经理，看到一堆 HTML/JS 代码可能就直接劝退了。

于是，我基于魔珐星云 SDK 开发了一套 Skills 技能模板------不同技术栈的同学只需简单描述需求，就能快速生成属于自己的交互 Demo，不再被技术选型卡住。

这就是 Skills 带来的 技术平权 ：不是降低技术本身的天花板，而是抬高地板，让每个人都能站在更高的起点上。

借此机会，我结合使用魔珐星云 SDK 开发 Skills 的实际经历，和大家分享如何设计一个优秀的 Skills。

什么是 Skills？

Skills 是一种轻量级的开放格式 ，可通过专业知识和工作流程扩展 AI 代理的功能。从本质上讲，一项技能就是一个包含 SKILL.md 文件的文件夹。该文件包含了元数据（名称和描述，至少包括这两项）以及向执行特定任务的代理提供操作指南的指令。技能还可以整合脚本（scripts）、模板（templates）和参考资料（references）。

一个规范的 Skill 结构如下：

nebula-avatar-skill/
├── SKILL.md          # 必填项：说明 + 元数据
├── scripts/          # 可选项：可执行代码
├── references/       # 可选项：参考文档
└── assets/           # 可选项：模板、资源
    └── templates/

四层架构，各司其职：

层级	职责	类比
SKILL.md	灵魂文件，定义身份、指令、边界	岗位说明书
scripts/	执行引擎，可运行的自动化脚本	工具箱
references/	知识库，深度参考文档	参考手册
assets/templates/	开箱即用的模板和资源	零件库

理解了这个结构，你就理解了 Skills 的设计哲学：用最小的文件结构，承载最大的能力密度。

如何编写一个优秀的 Skills？

一个优秀的 Skill 应该具备以下七个核心特性：

1. 边界明确------明确正向、负向触发条件，精准界定执行边界，解决模型判断执行时机偏差的问题，提升执行命中率。
2. 渐进式披露------以 SKILL.md 为入口导航，拆分示例、脚本等详细资料，实现信息按需加载，降低模型加载压力。
3. 输入输出结构化------以类函数签名规范输入输出格式，统一交互标准，实现无歧义、可解析的模型交互。
4. 步骤明确可执行------核心步骤采用指令式具象描述，摒弃笼统表述，确保模型可直接落地执行。
5. 工作流与反馈闭环------复杂任务搭配固定工作流与检查清单，规范执行顺序、校验执行质量，形成验证修正闭环。
6. 失败策略完备------预设各类异常场景的处理方案与失败路径，避免模型随意发挥，保障执行稳定性。
7. 职责绝对单一------单一 Skill 仅负责一项核心能力、对应一个核心动作，功能独立，规避冗余与执行不确定性。

下面，结合星云虚拟人 Skill 的实际开发，逐层拆解如何落地这些原则。

一、SKILL.md：灵魂文件的设计

SKILL.md 是 Agent 加载 Skill 后首先读取的文件，它决定了 Agent 能不能正确理解并执行 这个 Skill。设计 SKILL.md 要把握一个核心原则：单一职责。

以魔珐星云 SDK 集成 Skill 为例，这个 Skill 的目的非常明确------帮助用户快速搭建一个最小可视化 Demo。所有内容围绕这一个目标展开，不多不少。

• 元数据：description 是入口

---
name: nebula-avatar-demo
description:
  快速创建魔珐星云 3D 虚拟人交互应用，支持 AI 对话能力。当用户提到数字人、虚拟人、3D 交互、
  星云 SDK、XmovAvatar、具身交互、AI 对话时使用。支持纯 HTML 快速体验、Vue3 项目集成、自定义框架集成三种模式。
---

description 是整个 Skill 最关键的字段，Agent 通过它决定是否加载这个 Skill。三个原则：说清楚做什么 ，说清楚什么时候触发 ，说清楚支持哪些模式。

• ❌ 反面案例：description: 处理 AI 交互相关任务 ------太模糊，Agent 不知道什么时候该用它。
• ✅ 正面案例：description: 快速创建魔珐星云 3D 虚拟人交互应用，支持 AI 对话能力。当用户提到数字人、虚拟人、3D 交互、星云 SDK、XmovAvatar、具身交互、AI 对话时使用。 ------功能、触发关键词、支持能力都清晰。

注意触发词的设计：除了业务关键词（数字人、虚拟人），还要覆盖技术关键词（XmovAvatar、星云 SDK），甚至用户可能的口语化表达（具身交互、AI 对话）。触发词越丰富，命中率越高。

• 角色定义：给 Agent 一个身份

角色定义是 Skill 的"人格设定"，它告诉 Agent"你是谁、你擅长什么、你的边界在哪里"。由于我们的 Skill 目标是生成一个可运行的前端 Demo，因此角色定义应该聚焦在 Web 前端与 3D 交互的专业能力上：

# Role: 魔珐星云 SDK 集成专家

你是一名精通 Web 前端开发与 Web 3D 交互的架构师。
你的核心职能是基于最佳实践，协助开发者快速搭建"最小化可行"的数字人 Web Demo，
并提供高级功能扩展的架构指导。

**注意**：魔珐 SDK 具备自带背景渲染能力，初始代码无需手动处理背景层。

这段定义做了三件事：明确专业领域、界定核心职能、预设技术约束。Agent 读到这段话，就知道自己该以什么视角、什么能力水平来完成任务。

• # Context: 技术背景

由于我们的 Skill 涉及魔珐星云平台，SKILL.md 中需要简要交代技术背景，帮助 Agent 理解"我在为什么平台写代码"。这部分内容要精炼，核心信息包括：

# Role: 魔珐星云 SDK 集成专家

魔珐科技是全球较早布局具身交互智能的 AI 科技公司，以自研文生 3D 多模态大模型和端侧交互技术为核心，
打造魔珐星云具身交互智能开放平台。
星云不是功能工具，不是内容产品------它是 AI 终端时代的平台级能力。
让所有终端里的 AI，以具身的形态服务人、陪伴人、娱乐人。

- 品牌使命：让 AI 进入终端，以具身智能交互服务人类
- 能力主张：让 AI 拥有身体，感知世界，理解环境，自然表达
- 官网：[魔珐星云](https://xingyun3d.com/?utm_campaign=daily&utm_source=juejiin-jz-1&utm_medium=&utm_term=&utm_content=)
- 定位：让每一块屏幕和应用，都拥有 AI 具身交互智能体
- 典型场景：AI 金融顾问、AI 非遗讲解员、医院 AI 导诊、AI 情感陪伴、儿童陪伴机器人、AI 睡前故事等

> 关于魔珐星云平台的详细介绍，请参阅 references/platform-intro.md

---

渐进式披露的落地 ：当技术背景内容较多时，不要在 SKILL.md 中堆砌。可以在 references/ 下创建一个 xingyun-intro.md，将详细的平台介绍写进去，然后在 SKILL.md 中只保留一句话概述 + 引用路径：

关于魔珐星云平台的详细介绍，请参阅 references/platform-intro.md

这样做的好处是：SKILL.md 保持轻量，Agent 按需加载详细资料，既降低了初始 Token 消耗，又保证了深度信息的可获取性。这就是渐进式披露的核心思想。

二、前置条件：让用户少走弯路

很多 Skill 只写了"怎么用"，忘了写"用之前要做什么"。用户拿到 Skill 后第一步就卡住，体验极差。前置条件越具体越好。以星云 Skill 为例：

## 前置条件

前往 魔珐星云平台 注册账号，填写邀请码`JM2A7C9LSW`，获得1000积分。
1. 注册成功后进入「控制台」
2. 点击「具身驱动」创建应用
3. 选择你喜欢的数字人形象、场景及音色，然后点击「创建并进入调试」
4. 点击页面右上角「接入SDK」按钮获取 APP_ID 和 APP_SECRET

三步到位，用户照着做就能拿到所有需要的凭证。

三、分级使用步骤：从简到繁，覆盖不同需求

直接给出技术使用步骤时，应该从简到繁、分级提供。比如星云 Skill 提供了三种使用方式，从最简到最灵活：

方式一（默认）：纯 HTML 快速体验

一个文件搞定，打开浏览器就能跑。我们把写好的代码片段放在 assets/templates/ 下：

核心代码

<script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/xmovAvatar@latest.js"></script>

const sdk = new XmovAvatar({
  containerId: "#sdk", // 必填：数字人挂载容器
  appId: "your_appid", // 必填：应用 AppID
  appSecret: "your_appsecret", // 必填：应用 AppSecret
  gatewayServer: "https://nebula-agent.xingyun3d.com/user/v1/ttsa/session", // 必填：服务接口地址

  // SDK 事件回调，方便调试
  onMessage(message) {
    console.log("SDK message:", message);
  },
});

// 初始化 SDK，加载数字人资源
await sdk.init({
  onDownloadProgress(progress) {
    console.log(`资源加载进度：${progress}%`);
  },
});

SKILL.md 只保留核心调用逻辑的说明

## 方式一（默认）：纯 HTML 快速体验

一个文件搞定，打开浏览器就能跑。模板文件位于 `assets/templates/index.html`。

**执行步骤**：

1. 将 `assets/templates/index.html` 的内容输出为 `index.html` 文件
2. 告知用户在浏览器中打开该文件
3. 在顶部输入框填写 App ID 和 App Secret
4. 点击「连接」按钮，等待数字人加载完成
5. 在底部输入框输入文字，点击「发送播报」即可驱动数字人说话

**核心架构**：

- 配置解耦：AppID/AppSecret 通过前端 DOM 输入，严禁硬编码
- 布局策略：标准文档流布局，通过 JS 动态控制容器 CSS 实现横/竖屏切换
- 状态管理：精确的连接状态流转（未连接 → 连接中 → 已连接/失败 → 已断开）

方式二：Vue 模板项目

如果用户要求使用 Vue，在 references/ 中详细介绍 Vue 的集成方法，如果有可参考的完整代码，放在 assets/templates/ 中，并在skill.md中给与适当说明。

## 方式二：Vue3 项目集成（推荐，含 AI 对话能力）
如果用户要求使用 Vue 框架或需要 AI 对话能力，请参阅 `references/vue-integration.md` 获取详细集成指南。

模板项目位于 `assets/templates/vue-template/`，包含以下文件：

- `src/composables/useAvatar.js` --- SDK 封装 Hook（含 AI 对话集成）
- `src/utils/ai-service.js` --- AI 对话服务封装（支持 OpenAI 兼容接口）
- `src/components/AvatarStage.vue` --- 数字人舞台组件
- `src/components/ChatPanel.vue` --- 对话面板组件（支持手动/AI 两种模式）
- `src/components/ConfigPanel.vue` --- 配置面板组件（含 AI 配置）
- `src/App.vue` --- 主应用组件

**执行步骤**：

1. 将 `assets/templates/vue-template/` 下的文件复制到用户项目中对应位置
2. 确保用户项目已安装 Vue 3
3. 在 `App.vue` 中引入组件
4. 告知用户填写 App ID 和 App Secret
5. 若使用 AI 模式，还需填写 AI API Key 和 Base URL（默认兼容 OpenAI 接口）

**AI 对话能力说明**：

- **对话模式切换**：支持手动输入播报和 AI 智能对话两种模式
- **上下文管理**：自动维护对话历史，支持多轮对话
- **流式响应**：支持 AI 流式输出，实时播报
- **打断机制**：用户可随时打断 AI 播报，发送新指令
- **兼容性强**：支持 OpenAI、DeepSeek 等主流 AI 接口

> AI 对话集成的详细实现，请参阅 references/full-dialogue-integration.md

方式三：自定义集成

只提供核心 API 调用方式，接入什么框架由用户决定：

## 方式三：自定义集成

如果用户需要集成到已有项目中，提供以下核心 API 调用方式，框架适配由用户决定。详细的 API 文档请参考 `references/api-reference.md`。

**最小集成代码**：

```javascript
// 1. 引入 SDK
// <script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/xmovAvatar@latest.js"></script>

// 2. 实例化
// .....

// 3. 初始化
// .....

// 4. 播报
sdk.speak("你好，我是数字人", true, true);

// 5. 销毁（页面关闭前必须调用）
sdk.destroy();
```

---

这种"分级提供"的设计很关键。不同用户的需求不同：有人只想看看效果，有人要集成到项目里，有人需要深度定制。一个 Skill 覆盖三种场景，比写三个 Skill 更实用。

四、参考性规范：API 文档的精准投喂

背景和基础用法交代清楚之后，接下来就该告诉 Agent "具体怎么干活"了。但这里有一个关键的设计取舍：SKILL.md 不应该是一个无所不包的巨型文档。它的定位是导航入口，核心信息精炼呈现，深度资料按需引用。

以星云 Skill 为例，SKILL.md 中我们列出核心 API 的速查表，让 Agent 在生成代码时能快速定位方法签名：

类型	中文名	API 方法	说明
连接与销毁	初始化连接	init(config)	初始化数字人实例，连接服务，拉取资源
	销毁	destroy()	关闭数字人连接
模式切换	离线模式	offlineMode()	数字人循环播放缓存视频，不消耗积分
	在线模式	onlineMode()	从离线模式回到在线模式
状态切换	待机等待	idle()	数字人长时间等待
	倾听	listen()	用户输入语音，数字人处于倾听状态
	思考	think()	用户提问后，未开始回复的状态
	说话	speak(ssml, is_start, is_end)	控制虚拟人说话

这份表格已囊括最小演示案例所需的全部 API，但真实业务交互场景的需求往往更为丰富：用户可能需要自定义字幕样式、对话弹窗展示图片，或是内嵌视频播放器等拓展功能。针对这类进阶能力，可采用如下方案统一管理：在 SKILL.md 中按功能主题分模块梳理，详细的配套说明文档统一收纳至 references 目录下。

五、禁止性护栏：约束边界

Skill 不仅要告诉 Agent "该做什么"，更要明确 "不该做什么"。比如星云 Skill 的禁止性护栏按严重程度分为四条红线：

# 禁止性护栏

## 生命周期红线

- **必须**保留 `beforeunload` / `onUnmounted` → `sdk.destroy()` 逻辑
- **原因**：防止用户直接刷新页面导致 Token 未释放，触发 "10005" 错误
- **严禁**在 `init()` 未完成时调用 `speak` / `idle` 等状态 API

## API 幻觉红线

- SDK 没有内置视频播放器，遇到视频需求必须用 HTML `<video>` 标签自行实现
- SDK 没有 PPT 渲染器，遇到 PPT 需求必须用 HTML `<img>` 自行实现
- **不要自行编造 SDK 不存在的 API 方法**

## 配置红线

- 不要在代码中硬编码 AppID 和 AppSecret，必须使用输入框或环境变量
- 不要省略错误处理逻辑（try-catch）
- 不要移除 SDK 自带背景渲染层

## 语音打断规范

- 严禁直接调用 `speak` 覆盖正在播放的语音
- 必须先调用 `sdk.interactiveIdle()` 打断当前语音
- 监听 `onVoiceStateChange` 回调，在状态变为 `idle` 或 `end` 后再发送新指令

护栏的核心思想：与其让 Agent 自由发挥后出错，不如提前画好跑道。 每一条红线背后，都是一个真实的踩坑故事。

六、学习路径：渐进式引导的设计

Skill 除了完成业务任务外，还需引导用户养成规范、高效的使用习惯，例如在用户发起交互时给予分层提示。比如搭建了一套阶梯式学习路径，循序渐进引导开发者完成上手教学。

## 学习路径

对于初次接触魔珐星云 SDK 的开发者，建议按照以下渐进式学习路径：

1. **Lesson 1（5分钟）**：呈现数字人 - 在网页中显示 3D 数字人
2. **Lesson 2（10分钟）**：状态切换与播报 - 让数字人说话、切换状态
3. **Lesson 3（进阶）**：proxyWidget、字幕控制、流式播报、语音打断、屏幕适配
4. **Lesson 4（生产环境）**：安全鉴权、错误处理、房间限流问题解决

每个 Lesson 都对应一份独立的参考文档，用户可以按自己的节奏逐步学习。这种设计的核心思想：不要一次性给用户所有信息，而是根据用户的掌握程度，逐步开放更复杂的能力。

七、参考文档索引：渐进式披露的完整体现

一个 Skill 的知识密度越高，越需要克制"一次性全塞给 Agent"的冲动。一个优秀Skill 的做法是：SKILL.md 只放索引，详细内容拆到 references/ 目录按需加载。

星云 Skill 的 references/ 目录下包含 9 份参考文档，覆盖平台介绍、API 文档、集成指南、问题排查等各个方面。在 SKILL.md 末尾提供完整的文档索引：

# 参考文档索引

本 Skill 包含以下参考文档，按需查阅：

1. **references/platform-intro.md** - 魔珐星云平台介绍与应用场景
2. **references/learning-path.md** - 从零到一渐进式学习路径（Lesson 1-4）
3. **references/api-reference.md** - SDK API 完整参考文档
4. **references/widget-guide.md** - Widget 事件与自定义 UI 实现指南
5. **references/vue-integration.md** - Vue3 项目集成详细指南
6. **references/full-dialogue-integration.md** - 完整对话应用集成指南（ASR+LLM+数字人）
7. **references/sdk-compatibility.md** - SDK 浏览器与设备兼容性说明
8. **references/version-history.md** - SDK 版本更新记录
9. **references/troubleshooting.md** - 常见问题与解决方案

这份索引是渐进式披露 的核心体现：SKILL.md 保持轻量，Agent 按需加载详细资料。当用户遇到兼容性问题，Agent 查阅 sdk-compatibility.md；当用户需要 AI 对话能力，Agent 查阅 full-dialogue-integration.md。一份索引，九种深度，按需获取。

八、反馈验证：确保可运行

一个 Skill 的最后一步，是确保产出物经过验证。

# 反馈验证

代码生成后，执行以下检查清单：

1. □ AppID / AppSecret 是否使用占位符或用户输入，而非硬编码？
2. □ SDK 的 `init()` 是否在 `destroy()` 之前调用？
3. □ 是否包含 `try-catch` 错误处理？
4. □ `proxyWidget` 中的事件名是否与 API 文档一致？
5. □ 是否包含 `beforeunload` / `onUnmounted` 的销毁逻辑？
6. □ 是否遵循了用户的技术栈适配要求（Vue/React/原生）？
7. □ 页面是否能正常打开并显示 3D 数字人？

样做的目的是：让 Skill 产出的不只是"能跑的代码"，而是"经得起交付的代码"。 开发者拿到后不用逐行 debug 初始化顺序、不用回头查事件名拼写、不用担心密钥泄露------复制即用，打开即跑。对于 Skill 作者而言，这份清单也相当于把质量门禁从"人工 Review"下沉到了"生成时自检"，减少了大量的来回修改成本。

Skills最终文件展示

经过上述设计原则的梳理，最终 Skill 的目录结构如下：

nebula-avatar-demo/
├── SKILL.md                           # Skill 核心文档
├── README.md                          # 项目说明
│
├── assets/
│   └── templates/
│       ├── index.html                 # 纯 HTML 快速体验模板
│       └── vue-template/              # Vue3 完整项目模板
├── references/                        # 参考文档
│   ├── platform-intro.md              # 平台介绍与应用场景
│   ├── learning-path.md               # 从零到一学习路径
│   ├── api-reference.md               # SDK API 完整参考
│   ├── widget-guide.md                # Widget 事件与自定义 UI
│   ├── vue-integration.md             # Vue3 集成详细指南
│   ├── full-dialogue-integration.md   # 完整对话应用集成（ASR+LLM）
│   ├── sdk-compatibility.md           # SDK 兼容性说明
│   ├── version-history.md             # SDK 版本更新记录
│   └── troubleshooting.md             # 常见问题与解决方案
│
└── scripts/
    └── setup.sh                       # 快速启动脚本
```

有了这套 Skill，在 Trae 的对话框里只需要一句：

不到一分钟，一个可运行的数字人 Demo 就搭好了------不用翻 API 文档，不用手动配环境，Skill 会自动帮你拉模板、引 SDK、写交互逻辑。

以下是使用这套 Skill 生成的 Demo 实际运行效果：

nebula-avatar-demo技能git地址：gitee.com/sxshi/nebul...

总结：好 Skill 的设计哲学

回顾整个设计过程，一个好的 Skill 本质上是在解决一个问题：如何让 AI Agent 在正确的时机、以正确的方式、做正确的事。

设计原则	落地方式	核心价值
边界明确	description 精确描述触发条件	提升命中率
渐进式披露	SKILL.md 精简 + references/ 按需加载	降低 Token 消耗
分级使用步骤	从简到繁覆盖三种场景	适配不同用户
步骤明确可执行	指令式描述，附带代码片段	减少 Agent 幻觉
禁止性护栏	明确"不该做什么"	防止跑偏
反馈验证闭环	检查清单 + 验证脚本	确保可运行

回到开头的那个核心观点：大模型让 AI 学会了思考，魔珐星云让 AI 进入终端，以具身的方式与人交互。 如果你也想体验具身交互智能的魅力，不妨试试魔珐星云 SDK------注册时使用邀请码 JM2A7C9LSW 可以获得 1000 积分，几行代码就能让你的第一个数字人 Demo 跑起来。

我是石小石，一个喜欢折腾新技术的开发者。如果这篇文章对你有帮助，欢迎点赞、收藏、关注三连~

有任何问题欢迎评论区交流，也欢迎直接体验魔珐星云 SDK，自己动手做一个具身交互 Demo ✌️