# How to Use OpenMAIC Built-In Skills and Create Custom Skills

> Explore OpenMAIC's 10+ built-in skills like stage-design and learn to create your own custom skills using the identical SKILL.md manifest structure for seamless integration.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-13

---

**OpenMAIC provides over 10 built-in skills**—including `stage-design`, `deep-interactive`, and `pptx-import`—that live under `skills/agent-runtime/`, while custom skills follow an identical [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) manifest structure and are loaded via the `source` parameter in the runtime API.

OpenMAIC (from THU-MAIC/OpenMAIC) is a multi-agent intelligent classroom framework where **skills** serve as the atomic units of capability. Each skill, whether built-in or custom, is defined by a [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) manifest file that declares its name, title, and description, enabling the agent runtime to discover and execute educational workflows dynamically.

## Available Built-In Skills in OpenMAIC

According to the OpenMAIC source code, built-in skills reside in the `skills/agent-runtime/` directory. Each subdirectory contains a [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) manifest file that describes the skill’s purpose and behavior. The following representative skills are available out of the box:

- **`stage-design`** — Classroom design: Provides baseline methods for building a single classroom stage, including planning, roster creation, scene generation, and finalization. Located at [`skills/agent-runtime/stage-design/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/stage-design/SKILL.md).

- **`deep-interactive`** — 深度交互: Drives courses where learners manipulate simulations, diagrams, code, or games on most pages, reserving slides for framing and consolidation. Located at [`skills/agent-runtime/deep-interactive/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/deep-interactive/SKILL.md).

- **`slide-dsl`** — 幻灯片 DSL: Supplies a domain-specific language for authoring slide-type pages, optimized for static presentation-style content. Located at [`skills/agent-runtime/slide-dsl/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/slide-dsl/SKILL.md).

- **`pro-editing`** — 高级编辑: Enables editing of an already persisted stage rather than building a new one from scratch. Located at [`skills/agent-runtime/pro-editing/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/pro-editing/SKILL.md).

- **`pptx-import`** — PPTX 导入: Imports existing PowerPoint decks into an OpenMAIC stage, converting each slide into a scene. Located at [`skills/agent-runtime/pptx-import/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/pptx-import/SKILL.md).

- **`slide-craft`** — Slide Craft: Focuses on generating slide-type pages with rich visual assets. Located at [`skills/agent-runtime/slide-craft/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/slide-craft/SKILL.md).

- **`learning-to-learn`** — 学习如何学习: Guides meta-learning activities, prompting students to reflect on their own learning processes. Located at [`skills/agent-runtime/learning-to-learn/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/learning-to-learn/SKILL.md).

- **`k12-core-literacy-planning`** — 核心素养教学设计: Provides Chinese K-12 core-literacy course design, covering a wide range of subjects and grade levels. Located at [`skills/agent-runtime/k12-core-literacy-planning/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/k12-core-literacy-planning/SKILL.md).

- **`fact-check`** — Fact-Check: Supplies a workflow for verifying factual claims within generated content. Located at [`skills/agent-runtime/fact-check/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/fact-check/SKILL.md).

- **`deep-research`** — 深度研究: Guides the creation of research-oriented courses that require extensive background material and citation handling. Located at [`skills/agent-runtime/deep-research/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/deep-research/SKILL.md).

This list is not exhaustive; the complete set is available in the `skills/agent-runtime/` directory of the repository.

## How to List and Load Built-In Skills Programmatically

The OpenMAIC workbench exposes a TypeScript API for enumerating and instantiating skills. The [`lib/workbench/agent-skills.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/agent-skills.ts) module provides the primary interface.

### Listing All Built-In Skills

Use the `listBuiltinSkills` function to retrieve metadata for every built-in skill:

```typescript
// Example: List all built‑in skills
import { listBuiltinSkills } from '@/lib/workbench/agent-skills';

async function showBuiltinSkills() {
  const skills = await listBuiltinSkills();   // → [{ name: 'stage-design', title: '课堂设计', … }, …]
  console.table(skills.map(s => ({ name: s.name, title: s.title })));
}
showBuiltinSkills();

```

This returns an array of skill objects containing the parsed [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) content, including the skill’s name, title, and description.

### Loading a Specific Skill

To load a specific skill for use in the runtime, use the `loadSkill` function with the `source: 'builtin'` parameter:

```typescript
// Example: Load a specific built‑in skill (e.g., deep‑interactive)
import { loadSkill } from '@/lib/workbench/agent-skills';

async function useDeepInteractive() {
  const skill = await loadSkill({ name: 'deep-interactive', source: 'builtin' });
  // `skill` now contains the parsed SKILL.md content and can be passed to the runtime.
  console.log('Loaded skill:', skill.title);
}
useDeepInteractive();

```

The `source` parameter distinguishes built-in skills from custom implementations, allowing the runtime to resolve the correct manifest file path.

### Triggering Skill-Based Workflows

Once loaded, skills orchestrate stage creation and scene generation through the agent runtime API:

```typescript
// Example: Trigger a stage‑building workflow using a built‑in skill
import { createStage, generateScene } from '@/api/agent-runtime';

async function buildStageWithStageDesign() {
  const stageId = await createStage({ title: 'My New Classroom' });
  await setRoster(stageId, { teacher: 'Ms. Lee', agents: ['Student A', 'Student B'] });
  // Assume we have a pre‑planned page plan:
  const pages = [
    { title: 'Introduction', type: 'slide', brief: 'Introduce the topic' },
    { title: 'Exploration', type: 'interactive', brief: 'Let students manipulate …' },
  ];
  for (const [i, p] of pages.entries()) {
    await generateScene(stageId, { order: i + 1, ...p });
  }
}
buildStageWithStageDesign();

```

## Creating Custom Skills with SKILL.md Manifests

Custom skills in OpenMAIC follow the exact same architecture as built-in skills. To create a custom skill:

1. Create a [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) manifest file defining the **name**, **title**, and **description** of your skill, following the schema used by built-in manifests.

2. Place the manifest in a directory structure matching your skill’s name (e.g., [`skills/agent-runtime/my-custom-skill/SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skills/agent-runtime/my-custom-skill/SKILL.md)).

3. Load the skill using `loadSkill()` with an appropriate `source` parameter (distinct from `'builtin'`) to indicate the custom origin, or reference it directly by path depending on your runtime configuration.

The `source` parameter in `loadSkill({ name: string, source: string })` functions as a discriminator, enabling the runtime to resolve built-in manifests from `skills/agent-runtime/` versus custom manifests from alternative locations.

## Core Implementation Files and API Reference

The skill system is implemented across several key modules in the OpenMAIC codebase:

- **[`lib/workbench/agent-skills.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/agent-skills.ts)** — Core helpers for listing, loading, and displaying built-in skills. This module exports `listBuiltinSkills` and `loadSkill`.

- **[`lib/workbench/composer-skills.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/composer-skills.ts)** — Integrates skill handles (`/skill`) into the composer UI and resolves them to skill metadata for visual representation.

- **[`lib/workbench/skill-load.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/skill-load.ts)** — Handles the UI representation of a skill load operation and its lifecycle, managing loading states and error boundaries.

- **[`tests/workbench/agent-skills.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/workbench/agent-skills.test.ts)** — Test suite that asserts the presence and correct labeling of built-in skills, ensuring the `skills/agent-runtime/` directory is correctly indexed.

- **`skills/agent-runtime/*/SKILL.md`** — Individual skill manifests (e.g., `stage-design`, `deep-interactive`, `pptx-import`) that define the declarative interface for each capability.

## Summary

- OpenMAIC ships with **10+ built-in skills** located in `skills/agent-runtime/`, each defined by a [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) manifest.
- Use `listBuiltinSkills()` from [`lib/workbench/agent-skills.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/agent-skills.ts) to enumerate available capabilities.
- Load specific skills via `loadSkill({ name, source: 'builtin' })` to parse manifests and initialize runtime behavior.
- **Custom skills** follow the identical [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) manifest structure; the `source` parameter in the loading API distinguishes built-in from custom implementations.
- The skill system integrates with the OpenMAIC composer UI through [`composer-skills.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/composer-skills.ts) and [`skill-load.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/skill-load.ts).

## Frequently Asked Questions

### What built-in skills come with OpenMAIC?

OpenMAIC includes skills for **stage design** (`stage-design`), **interactive simulations** (`deep-interactive`), **PowerPoint import** (`pptx-import`), **fact-checking** (`fact-check`), and **K-12 curriculum planning** (`k12-core-literacy-planning`), among others. Each skill is documented in its own [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) file under the `skills/agent-runtime/` directory.

### How do I load a specific skill in my code?

Import `loadSkill` from `@/lib/workbench/agent-skills` and call it with the skill name and source type: `await loadSkill({ name: 'deep-interactive', source: 'builtin' })`. This returns the parsed manifest content ready for the agent runtime.

### Can I create custom skills for specialized use cases?

Yes. Create a [`SKILL.md`](https://github.com/THU-MAIC/OpenMAIC/blob/main/SKILL.md) file following the same schema as built-in manifests (defining name, title, and description) and place it in your skill directory. The runtime loads custom skills through the same `loadSkill` API, using a distinct `source` parameter to differentiate from built-in assets.

### How does the skill system integrate with the OpenMAIC UI?

The [`lib/workbench/composer-skills.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/composer-skills.ts) module resolves skill handles to metadata for the composer interface, while [`lib/workbench/skill-load.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/skill-load.ts) manages the UI lifecycle of skill loading operations, ensuring skills are correctly instantiated before classroom generation begins.