---

theme: cyanosis

Hello everyone, I'm Shi Xiaoshi~

---

Introduction: The Next Stage of AI is Not Just About Thinking Better

Recently, I've been deeply captivated by a new concept: "Embodied Interactive Intelligence".

Its core proposition is straightforward: Give AI a body, let it perceive the world, understand the environment, and interact naturally with people through voice, expressions, actions, and real-time responses. Simply put, it means moving large models/agents beyond the chat box, giving them a 3D body, voice expression, motion feedback, and real-time interaction capabilities, truly entering real-world scenarios like screens, web pages, robots, exhibition halls, stores, and education.

As an AI technology company that pioneered the global layout of embodied interactive intelligence, Mofa Technology relies on its self-developed text-to-3D multimodal large model and end-side interaction technology to build the Mofa Nebula Embodied Interactive Intelligence Open Platform.

With its embodied driving SDK, just a small amount of code is needed to complete AI's "body, expression, and interaction," achieving the critical step of moving AI from text interaction to embodied interaction.

A Demo to Verify the Possibility of "Embodied Interaction"

Concepts are enough to look at, but hands-on work is what counts. So, I used the Mofa Nebula SDK to create an interactive AI Embodied Agent Demo: after sending a text message, the digital human broadcasts it in real-time voice, accompanied by natural expressions and body movements. The entire process responds in under 500ms and supports interruption at any time, providing a smooth experience.

From the process of making and experiencing the Demo, I had a very clear feeling: The next stage of AI is not just about thinking better, but about interacting better. From text dialogue to operating interfaces, calling tools, and generating visual results, AI is moving from text interaction to embodied interaction, which will be the core direction of the future.

Related article links:

Nebula SDK + Tampermonkey: Giving LLM a Physical Form to Accompany You on Every Webpage;

AI Embodied Interaction: Implementing a Talking 3D Virtual Companion

DEMO Online Experience Address: https://www.axureshow.com/project/HDZcuEZb/

Skills: The Next Step in Technology Democratization

The Demo was made, but a practical problem immediately surfaced: the experience threshold.

Although the official tutorials and my Demo code have been simplified as much as possible, running with just a few lines of code, since the Demo is mainly built on a frontend tech stack, developers from other tech stacks still face significant cognitive costs to get started. Backend developers, mobile developers, and even non-technical product managers might be immediately deterred by a pile of HTML/JS code.

So, I developed a set of Skills templates based on the Mofa Nebula SDK—developers from different tech stacks only need to briefly describe their requirements to quickly generate their own interactive Demo, no longer blocked by technology choices.

This is the technology democratization brought by Skills: not lowering the ceiling of the technology itself, but raising the floor, allowing everyone to stand on a higher starting point.

Taking this opportunity, I combined my actual experience developing Skills using the Mofa Nebula SDK to share with everyone how to design an excellent Skills.

What are Skills?

Skills is a lightweight, open format that extends the functionality of AI agents with specialized knowledge and workflows. Essentially, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at least these two items) and instructions providing operational guidance to agents performing specific tasks. Skills can also integrate scripts (scripts), templates (templates), and reference materials (references).

A standard Skill structure is as follows:

nebula-avatar-skill/
├── SKILL.md          # Required: Description + Metadata
├── scripts/          # Optional: Executable code
├── references/       # Optional: Reference documents
└── assets/           # Optional: Templates, resources
    └── templates/

Four-layer architecture, each with its own role:

Layer	Responsibility	Analogy
SKILL.md	Soul file, defines identity, instructions, boundaries	Job description
scripts/	Execution engine, runnable automation scripts	Toolbox
references/	Knowledge base, in-depth reference documents	Reference manual
assets/templates/	Out-of-the-box templates and resources	Parts library

Understanding this structure, you understand the design philosophy of Skills: Use the smallest file structure to carry the greatest density of capability.

How to Write an Excellent Skills?

An excellent Skill should possess the following seven core characteristics:

1. Clear Boundaries—Clearly define positive and negative trigger conditions, precisely delineate execution boundaries, solve the problem of model misjudgment of execution timing, and improve execution hit rate.
2. Progressive Disclosure—Use SKILL.md as the entry navigation, split detailed materials like examples and scripts, achieve on-demand information loading, and reduce model loading pressure.
3. Structured Input/Output—Standardize input/output formats with function-signature-like specifications, unify interaction standards, and achieve unambiguous, parseable model interaction.
4. Clear and Executable Steps—Core steps use imperative, concrete descriptions, abandon vague statements, ensuring the model can directly execute them.
5. Workflow and Feedback Loop—Complex tasks are paired with fixed workflows and checklists to standardize execution order, verify execution quality, and form a verification-correction loop.
6. Complete Failure Strategy—Preset handling plans and failure paths for various exception scenarios to prevent the model from improvising and ensure execution stability.
7. Absolute Single Responsibility—A single Skill is only responsible for one core capability, corresponding to one core action, with independent functionality, avoiding redundancy and execution uncertainty.

Below, combined with the actual development of the Nebula Avatar Skill, we will break down layer by layer how to implement these principles.

I. SKILL.md: Designing the Soul File

SKILL.md is the first file the Agent reads after loading a Skill. It determines whether the Agent can correctly understand and execute this Skill. Designing SKILL.md requires grasping one core principle: Single Responsibility.

Taking the Mofa Nebula SDK integration Skill as an example, the purpose of this Skill is very clear—to help users quickly build a minimal visual Demo. All content revolves around this single goal, no more, no less.

• Metadata: description is the entry point

---
name: nebula-avatar-demo
description:
  Quickly create a Mofa Nebula 3D avatar interactive application, supporting AI dialogue capabilities. Use when users mention digital human, avatar, 3D interaction,
  Nebula SDK, XmovAvatar, embodied interaction, AI dialogue. Supports three modes: pure HTML quick experience, Vue3 project integration, and custom framework integration.
---

description is the most critical field of the entire Skill. The Agent uses it to decide whether to load this Skill. Three principles: clearly state what it does, clearly state when it triggers, clearly state which modes are supported.

• ❌ Negative example: description: Handles AI interaction related tasks —Too vague, the Agent doesn't know when to use it.
• ✅ Positive example: description: Quickly create a Mofa Nebula 3D avatar interactive application, supporting AI dialogue capabilities. Use when users mention digital human, avatar, 3D interaction, Nebula SDK, XmovAvatar, embodied interaction, AI dialogue. —Function, trigger keywords, and supported capabilities are all clear.

Note the design of trigger words: besides business keywords (digital human, avatar), also cover technical keywords (XmovAvatar, Nebula SDK), and even colloquial expressions users might use (embodied interaction, AI dialogue). The richer the trigger words, the higher the hit rate.

• Role Definition: Give the Agent an Identity

Role definition is the "personality setting" of the Skill. It tells the Agent "who you are, what you're good at, and where your boundaries are." Since our Skill's goal is to generate a runnable frontend Demo, the role definition should focus on professional capabilities in Web frontend and 3D interaction:

# Role: Mofa Nebula SDK Integration Expert

You are an architect proficient in Web frontend development and Web 3D interaction.
Your core function is to assist developers in quickly building a "minimum viable" digital human Web Demo based on best practices,
and provide architectural guidance for advanced feature expansion.

**Note**: The Mofa SDK has built-in background rendering capabilities; initial code does not need to manually handle the background layer.

This definition does three things: clarifies the professional domain, defines the core function, and presets technical constraints. When the Agent reads this, it knows from what perspective and at what capability level to complete the task.

• # Context: Technical Background

Since our Skill involves the Mofa Nebula platform, the SKILL.md needs to briefly explain the technical background to help the Agent understand "what platform am I writing code for." This part should be concise, with core information including:

# Role: Mofa Nebula SDK Integration Expert

Mofa Technology is an AI technology company that pioneered the global layout of embodied interactive intelligence, centered on its self-developed text-to-3D multimodal large model and end-side interaction technology,
building the Mofa Nebula Embodied Interactive Intelligence Open Platform.
Nebula is not a functional tool, nor a content product—it is a platform-level capability for the AI terminal era.
Let AI in all terminals serve, accompany, and entertain people in an embodied form.

- Brand Mission: Let AI enter terminals, serving humanity with embodied intelligent interaction
- Capability Proposition: Give AI a body, perceive the world, understand the environment, express naturally
- Official Website: [Mofa Nebula](https://xingyun3d.com/?utm_campaign=daily&utm_source=juejiin-jz-1&utm_medium=&utm_term=&utm_content=)
- Positioning: Equip every screen and application with an AI embodied interactive agent
- Typical Scenarios: AI financial advisor, AI intangible cultural heritage narrator, hospital AI guide, AI emotional companion, children's companion robot, AI bedtime stories, etc.

> For a detailed introduction to the Mofa Nebula platform, please refer to references/platform-intro.md

---

Implementation of Progressive Disclosure: When the technical background content is extensive, do not pile it into SKILL.md. You can create an xingyun-intro.md under references/, write the detailed platform introduction there, and keep only a one-sentence summary + reference path in SKILL.md:

For a detailed introduction to the Mofa Nebula platform, please refer to references/platform-intro.md

The benefit of this approach: SKILL.md remains lightweight, and the Agent loads detailed materials on demand, reducing initial Token consumption while ensuring the availability of in-depth information. This is the core idea of Progressive Disclosure.

II. Prerequisites: Help Users Avoid Detours

Many Skills only write "how to use" but forget to write "what to do before use." Users get stuck at the first step after getting the Skill, leading to a terrible experience. Prerequisites should be as specific as possible. Taking the Nebula Skill as an example:

## Prerequisites

Go to the Mofa Nebula Platform to register an account, fill in the invitation code `JM2A7C9LSW` to get 1000 points.
1. After successful registration, enter the 'Console'
2. Click 'Embodied Drive' to create an application
3. Choose your preferred digital human image, scene, and voice, then click 'Create and Enter Debugging'
4. Click the 'Access SDK' button at the top right of the page to get APP_ID and APP_SECRET

Three steps to get it done; users can follow along and get all the required credentials.

III. Tiered Usage Steps: From Simple to Complex, Covering Different Needs

When directly providing technical usage steps, they should be tiered from simple to complex. For example, the Nebula Skill provides three usage methods, from the simplest to the most flexible:

Method 1 (Default): Pure HTML Quick Experience

One file does it all; open it in a browser and it runs. We place the written code snippets under assets/templates/:

Core Code

<script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/[email protected]"></script>

const sdk = new XmovAvatar({
  containerId: "#sdk", // Required: Digital human mount container
  appId: "your_appid", // Required: Application AppID
  appSecret: "your_appsecret", // Required: Application AppSecret
  gatewayServer: "https://nebula-agent.xingyun3d.com/user/v1/ttsa/session", // Required: Service interface address

  // SDK event callbacks, convenient for debugging
  onMessage(message) {
    console.log("SDK message:", message);
  },
});

// Initialize SDK, load digital human resources
await sdk.init({
  onDownloadProgress(progress) {
    console.log(`Resource loading progress: ${progress}%`);
  },
});

SKILL.md only retains the explanation of the core calling logic

## Method 1 (Default): Pure HTML Quick Experience

One file does it all; open it in a browser and it runs. The template file is located at `assets/templates/index.html`.

**Execution Steps**:

1. Output the content of `assets/templates/index.html` as an `index.html` file
2. Inform the user to open the file in a browser
3. Fill in the App ID and App Secret in the top input boxes
4. Click the 'Connect' button, wait for the digital human to finish loading
5. Enter text in the bottom input box, click 'Send Broadcast' to drive the digital human to speak

**Core Architecture**:

- Configuration Decoupling: AppID/AppSecret are input via frontend DOM, hardcoding is strictly prohibited
- Layout Strategy: Standard document flow layout, dynamically control container CSS via JS to achieve horizontal/vertical screen switching
- State Management: Precise connection state flow (Disconnected → Connecting → Connected/Failed → Disconnected)

Method 2: Vue Template Project

If the user requires using Vue, detail the Vue integration method in references/. If there is complete reference code available, place it in assets/templates/ and provide appropriate instructions in skill.md.

## Method 2: Vue3 Project Integration (Recommended, includes AI dialogue capability)
If the user requires using the Vue framework or needs AI dialogue capability, please refer to `references/vue-integration.md` for a detailed integration guide.

The template project is located at `assets/templates/vue-template/`, containing the following files:

- `src/composables/useAvatar.js` — SDK Encapsulation Hook (includes AI dialogue integration)
- `src/utils/ai-service.js` — AI dialogue service encapsulation (supports OpenAI compatible interfaces)
- `src/components/AvatarStage.vue` — Digital human stage component
- `src/components/ChatPanel.vue` — Dialogue panel component (supports manual/AI modes)
- `src/components/ConfigPanel.vue` — Configuration panel component (includes AI config)
- `src/App.vue` — Main application component

**Execution Steps**:

1. Copy the files under `assets/templates/vue-template/` to the corresponding locations in the user's project
2. Ensure the user's project has Vue 3 installed
3. Import the components in `App.vue`
4. Inform the user to fill in the App ID and App Secret
5. If using AI mode, also need to fill in the AI API Key and Base URL (default compatible with OpenAI interface)

**AI Dialogue Capability Description**:

- **Dialogue Mode Switching**: Supports switching between manual input broadcast and AI intelligent dialogue modes
- **Context Management**: Automatically maintains dialogue history, supports multi-turn conversations
- **Streaming Response**: Supports AI streaming output, real-time broadcasting
- **Interruption Mechanism**: Users can interrupt AI broadcasting at any time to send new commands
- **Strong Compatibility**: Supports mainstream AI interfaces like OpenAI, DeepSeek, etc.

> For detailed implementation of AI dialogue integration, please refer to references/full-dialogue-integration.md

Method 3: Custom Integration

Only provide the core API calling method; the user decides which framework to integrate into:

## Method 3: Custom Integration

If the user needs to integrate into an existing project, provide the following core API calling methods; framework adaptation is up to the user. For detailed API documentation, please refer to `references/api-reference.md`.

**Minimal Integration Code**:

```javascript
// 1. Import SDK
// <script src="https://media.xingyun3d.com/xingyun3d/general/litesdk/[email protected]"></script>

// 2. Instantiate
// .....

// 3. Initialize
// .....

// 4. Broadcast
sdk.speak("Hello, I am a digital human", true, true);

// 5. Destroy (must be called before page closes)
sdk.destroy();
```

---

This "tiered provision" design is crucial. Different users have different needs: some just want to see the effect, some want to integrate into a project, some need deep customization. One Skill covering three scenarios is more practical than writing three Skills.

IV. Reference Specifications: Precise Feeding of API Documentation

After the background and basic usage are clearly explained, the next step is to tell the Agent "how to do the specific work." But there's a key design trade-off here: SKILL.md should not be an all-encompassing giant document. Its positioning is a navigation entry point, with core information presented concisely and in-depth materials referenced on demand.

Taking the Nebula Skill as an example, in SKILL.md we list a quick reference table of core APIs, allowing the Agent to quickly locate method signatures when generating code:

Type	Chinese Name	API Method	Description
Connection & Destruction	Init Connection	init(config)	Initialize digital human instance, connect service, fetch resources
	Destroy	destroy()	Close digital human connection
Mode Switch	Offline Mode	offlineMode()	Digital human loops cached video, no points consumed
	Online Mode	onlineMode()	Return from offline mode to online mode
State Switch	Standby Wait	idle()	Digital human waits for a long time
	Listen	listen()	User inputs voice, digital human is in listening state
	Think	think()	After user asks, state before starting reply
	Speak	speak(ssml, is_start, is_end)	Control avatar to speak

This table already includes all APIs needed for a minimal demo case, but real business interaction scenarios often have richer requirements: users may need custom subtitle styles, dialogue pop-ups displaying images, or embedded video players and other extended functions. For such advanced capabilities, the following scheme can be used for unified management: organize by functional themes in SKILL.md, and collect detailed supporting documentation into the references directory.

V. Prohibitive Guardrails: Constraining Boundaries

A Skill must not only tell the Agent "what to do" but also clearly define "what not to do." For example, the Nebula Skill's prohibitive guardrails are divided into four red lines by severity:

# Prohibitive Guardrails

## Lifecycle Red Lines

- **Must** retain `beforeunload` / `onUnmounted` → `sdk.destroy()` logic
- **Reason**: Prevent users from directly refreshing the page causing unreleased Tokens, triggering "10005" errors
- **Strictly Prohibit** calling state APIs like `speak` / `idle` before `init()` is complete

## API Hallucination Red Lines

- The SDK has no built-in video player; when encountering video requirements, must use HTML `<video>` tags to implement independently
- The SDK has no PPT renderer; when encountering PPT requirements, must use HTML `<img>` to implement independently
- **Do not fabricate API methods that do not exist in the SDK**

## Configuration Red Lines

- Do not hardcode AppID and AppSecret in the code; must use input boxes or environment variables
- Do not omit error handling logic (try-catch)
- Do not remove the SDK's built-in background rendering layer

## Voice Interruption Specification

- Strictly prohibit directly calling `speak` to overwrite currently playing voice
- Must first call `sdk.interactiveIdle()` to interrupt the current voice
- Listen to the `onVoiceStateChange` callback, and only send new commands after the state changes to `idle` or `end`

The core idea of guardrails: Rather than letting the Agent improvise and then make mistakes, it's better to draw the runway in advance. Behind every red line is a real story of stepping on a pitfall.

VI. Learning Path: Designing Progressive Guidance

Besides completing business tasks, a Skill also needs to guide users to develop standardized and efficient usage habits, such as giving tiered prompts when users initiate interactions. For example, a stepped learning path was built to progressively guide developers through the onboarding process.

## Learning Path

For developers new to the Mofa Nebula SDK, it is recommended to follow this progressive learning path:

1. **Lesson 1 (5 minutes)**: Presenting the Digital Human - Display a 3D digital human on a webpage
2. **Lesson 2 (10 minutes)**: State Switching and Broadcasting - Make the digital human speak, switch states
3. **Lesson 3 (Advanced)**: proxyWidget, Subtitle Control, Streaming Broadcast, Voice Interruption, Screen Adaptation
4. **Lesson 4 (Production Environment)**: Secure Authentication, Error Handling, Room Rate Limiting Problem Solving

Each Lesson corresponds to an independent reference document, allowing users to learn progressively at their own pace. The core idea of this design: Don't give users all the information at once, but gradually unlock more complex capabilities based on their mastery level.

VII. Reference Document Index: The Complete Embodiment of Progressive Disclosure

The higher the knowledge density of a Skill, the more necessary it is to restrain the impulse to "stuff everything into the Agent at once." The practice of an excellent Skill is: SKILL.md only contains the index, detailed content is split into the references/ directory for on-demand loading.

The Nebula Skill's references/ directory contains 9 reference documents, covering platform introduction, API documentation, integration guides, troubleshooting, and more. A complete document index is provided at the end of SKILL.md:

# Reference Document Index

This Skill includes the following reference documents, consult as needed:

1. **references/platform-intro.md** - Mofa Nebula Platform Introduction and Application Scenarios
2. **references/learning-path.md** - Zero-to-One Progressive Learning Path (Lesson 1-4)
3. **references/api-reference.md** - Complete SDK API Reference Documentation
4. **references/widget-guide.md** - Widget Events and Custom UI Implementation Guide
5. **references/vue-integration.md** - Detailed Vue3 Project Integration Guide
6. **references/full-dialogue-integration.md** - Complete Dialogue Application Integration Guide (ASR+LLM+Digital Human)
7. **references/sdk-compatibility.md** - SDK Browser and Device Compatibility Notes
8. **references/version-history.md** - SDK Version Update Records
9. **references/troubleshooting.md** - Common Problems and Solutions

This index is the core embodiment of Progressive Disclosure: SKILL.md remains lightweight, and the Agent loads detailed materials on demand. When users encounter compatibility issues, the Agent consults sdk-compatibility.md; when users need AI dialogue capabilities, the Agent consults full-dialogue-integration.md. One index, nine depths, obtained on demand.

VIII. Feedback Verification: Ensuring Runnability

The final step of a Skill is to ensure the output has been verified.

# Feedback Verification

After code generation, execute the following checklist:

1. □ Are AppID / AppSecret using placeholders or user input, rather than hardcoded?
2. □ Is the SDK's `init()` called before `destroy()`?
3. □ Is `try-catch` error handling included?
4. □ Are the event names in `proxyWidget` consistent with the API documentation?
5. □ Is the `beforeunload` / `onUnmounted` destruction logic included?
6. □ Are the user's tech stack adaptation requirements (Vue/React/Native) followed?
7. □ Can the page open normally and display the 3D digital human?

The purpose of doing this is: To make the Skill produce not just "code that can run," but "code that is deliverable." Developers don't need to debug initialization order line by line, don't need to go back and check event name spellings, don't need to worry about key leaks—copy and use, open and run. For Skill authors, this checklist also effectively sinks the quality gate from "manual Review" down to "self-check at generation time," reducing a significant amount of back-and-forth modification costs.

Final Skills File Display

After sorting through the above design principles, the final Skill directory structure is as follows:

nebula-avatar-demo/
├── SKILL.md                           # Skill Core Document
├── README.md                          # Project Description
│
├── assets/
│   └── templates/
│       ├── index.html                 # Pure HTML Quick Experience Template
│       └── vue-template/              # Vue3 Complete Project Template
├── references/                        # Reference Documents
│   ├── platform-intro.md              # Platform Introduction and Application Scenarios
│   ├── learning-path.md               # Zero-to-One Learning Path
│   ├── api-reference.md               # Complete SDK API Reference
│   ├── widget-guide.md                # Widget Events and Custom UI
│   ├── vue-integration.md             # Detailed Vue3 Integration Guide
│   ├── full-dialogue-integration.md   # Complete Dialogue Application Integration (ASR+LLM)
│   ├── sdk-compatibility.md           # SDK Compatibility Notes
│   ├── version-history.md             # SDK Version Update Records
│   └── troubleshooting.md             # Common Problems and Solutions
│
└── scripts/
    └── setup.sh                       # Quick Start Script
```

With this set of Skills, just one sentence is needed in Trae's dialog box:

In less than a minute, a runnable digital human Demo is set up—no need to flip through API docs, no need to manually configure environments, the Skill automatically pulls templates, imports the SDK, and writes the interaction logic.

Below is the actual running effect of a Demo generated using this set of Skills:

nebula-avatar-demo Skill Git Address: https://gitee.com/sxshi/nebula-avatar-demo

Summary: The Design Philosophy of a Good Skill

Reviewing the entire design process, a good Skill essentially solves one problem: How to make an AI Agent do the right thing, at the right time, in the right way.

Design Principle	Implementation Method	Core Value
Clear Boundaries	Precisely describe trigger conditions in description	Improve hit rate
Progressive Disclosure	Streamlined SKILL.md + on-demand loading from references/	Reduce Token consumption
Tiered Usage Steps	Cover three scenarios from simple to complex	Adapt to different users
Clear, Executable Steps	Imperative descriptions with code snippets	Reduce Agent hallucination
Prohibitive Guardrails	Clearly define "what not to do"	Prevent deviation
Feedback Verification Loop	Checklist + verification script	Ensure runnability

Returning to the core point from the beginning: Large models have taught AI to think, and Mofa Nebula allows AI to enter terminals, interacting with people in an embodied way. If you also want to experience the charm of embodied interactive intelligence, why not try the Mofa Nebula SDK—use the invitation code JM2A7C9LSW when registering to get 1000 points, and with just a few lines of code, you can get your first digital human Demo running.

I am Shi Xiaoshi, a developer who enjoys tinkering with new technologies. If this article was helpful to you, welcome to like, bookmark, and follow~

Feel free to exchange ideas in the comments section, and you are also welcome to directly experience the Mofa Nebula SDK and make an embodied interaction Demo yourself ✌️