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

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 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 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 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.

• 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.

• 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.

• 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.

• 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.

• slide-craft — Slide Craft: Focuses on generating slide-type pages with rich visual assets. Located at 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.

• 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.

• fact-check — Fact-Check: Supplies a workflow for verifying factual claims within generated content. Located at 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.

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 module provides the primary interface.

Listing All Built-In Skills

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

// 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 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:

// 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:

// 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 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).

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 — Core helpers for listing, loading, and displaying built-in skills. This module exports listBuiltinSkills and loadSkill.

• 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 — Handles the UI representation of a skill load operation and its lifecycle, managing loading states and error boundaries.

• 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 manifest.
• Use listBuiltinSkills() from 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 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 and 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 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 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 module resolves skill handles to metadata for the composer interface, while lib/workbench/skill-load.ts manages the UI lifecycle of skill loading operations, ensuring skills are correctly instantiated before classroom generation begins.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}