# Stage Dsl

The map for reading and editing an OpenMAIC stage document with read_stage...

- Repository: https://github.com/THU-MAIC/OpenMAIC (42385 stars)
- Category: Documents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add THU-MAIC/OpenMAIC --skill stage-dsl -g -a claude-code -y`
Codex: `npx skills add THU-MAIC/OpenMAIC --skill stage-dsl -g -a codex -y`
Cursor: `npx skills add THU-MAIC/OpenMAIC --skill stage-dsl -g -a cursor -y`
Gemini CLI: `npx skills add THU-MAIC/OpenMAIC --skill stage-dsl -g -a gemini-cli -y`

## Description

The map for reading and editing an OpenMAIC stage document with read_stage, patch_stage, and grep_stage. Load it before patching a structure you have not patched before, when patch_stage rejects an operation, or whenever the path from a stage, outline, scene, content object, or action to the field you need is uncertain. It routes to field-level references for quizzes, interactive widgets, actions, and PBL projects; the installed slide-dsl skill remains the complete slide canvas manual.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# The stage document map

This is a map, not the field manual.

Use it to decide which subtree owns a value, which path to read, and which
reference chapter to load. Then read the exact source before writing.

## The document model

The durable structure is:

```text
stage
├── outline
└── scenes[]                    ordered by scene.order, shown as pages 1..N
    ├── id                     stable scene identity
    ├── order                  1-based page position
    ├── type                   slide | quiz | interactive | pbl
    ├── content                shape selected by scene.type
    │   ├── slide.canvas
    │   ├── quiz.questions[]
    │   ├── interactive.html / widgetConfig
    │   └── pbl.projectV2
    └── actions[]              ordered playback verbs
```

`stage` is the stage's metadata. `outline` is the generation plan. A persisted page
is a scene. Its `type` and `content.type` must agree.

The three generic tools do not replace page-list operations. Insert, delete,
reorder, and retitle pages with `edit_deck`.

## Tool vocabulary

| Need | Tool | How |
| --- | --- | --- |
| Read a scene | `read_stage` | `path:/scenes/<order|sceneId>` with the required detail |
| Edit scene content or actions | `patch_stage` | `target:/scenes/<order|sceneId>` and scene-root JSON Pointer ops |
| Search visible text or source | `grep_stage` | literal search over the whole stage |
| List stages in folders | `list_folder_stages` | returns the explicit `stageId` required by every stage tool |
| Insert, delete, reorder, or retitle pages | `edit_deck` | page-list operations stay outside the document patcher |
| Plan and build a new stage | conversation + `create_stage` + `generate_scene` | settle the page plan in conversation, then call `generate_scene` once per page with an explicit brief |
| Set the classroom cast | `set_roster` | write the settled roster before page generation |

## Addressing with read_stage

The rest: https://github.com/THU-MAIC/OpenMAIC/blob/HEAD/skills/agent-runtime/stage-dsl/SKILL.md