How to use the Stage Document Map agent skill (stage-dsl)

What the skill makes the agent do

An OpenMAIC stage is stored as a document with an outline and an ordered list of scenes. Each scene has an id, an order number, a type (slide, quiz, interactive or pbl), type-specific content, and an ordered list of playback actions. Without a map, an agent has to guess where a value lives.

With stage-dsl loaded, the agent knows which tool owns which job: read_stage to read a scene, patch_stage to change a specific field, and grep_stage to search visible text or source across the stage. For page-list changes such as inserting, deleting, reordering or retitling pages, the skill directs the agent to edit_deck instead.

• Reads a single scene by page order or stable scene id, in a compact tree view or the exact source JSON.
• Patches one field at a time, with multiple operations applied atomically so a failed step does not leave a partial write.
• Searches literally and case-insensitively across visible text or serialized scene JSON.
• Points to separate reference chapters for quizzes, interactive widgets, playback actions and PBL projects.

Install the stage-dsl skill

Download the stage-dsl ZIP from the skill page. Then choose one of two routes depending on where you want the skill to be available.

For Claude Code, unzip the download into ~/.claude/skills/ to make it available for you across projects, or into a project's .claude/skills/ folder to limit it to that project. For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/.
• Project install: unzip into the project's .claude/skills/ folder.
• Claude apps: upload the ZIP under Settings → Capabilities → Skills.

Check what the skill needs before you start

The skill only works inside an OpenMAIC environment that exposes its stage tools. It assumes these tools are available: read_stage, patch_stage, grep_stage, list_folder_stages, edit_deck, create_stage, generate_scene and set_roster.

For full slide canvas editing, the skill relies on the companion slide-dsl skill, which is the complete slide manual. Install it alongside stage-dsl. The skill's source states that it runs no scripts and uses no network access.

• OpenMAIC stage tools available to the agent.
• The companion slide-dsl skill for slide canvas edits.
• No scripts are run by this skill.
• No network access is used by this skill.

Trigger the skill with natural requests

You do not need a special command. Ask the agent for a change to a stage in plain language, and the skill is loaded when the agent needs to find or edit a structure it has not handled before, when a patch was rejected, or when the path to a field is unclear.

Name the page and the kind of change. Page numbers and scene ids both work as targets, so 'page 3' or a specific scene id gives the agent a clear starting point.

• 'In the stage, find every place that says "Lesson 2" and change it to "Unit 2".'
• 'On page 4, change the first quiz option text to "Photosynthesis".'
• 'Show me the quiz questions on page 5 before you change anything.'
• 'Replace the closing sentence of the widget description on page 7.'
• 'Move page 6 after page 8' (the agent should use edit_deck for this).

How a safe edit works

The skill asks the agent to follow a fixed sequence for every edit. The agent reads the target scene in source form, locates the exact field and array index, loads the matching reference chapter if the structure is unfamiliar, patches the smallest field that expresses the change, reads the same path again to verify, and uses a text read or grep when checking that old wording is gone.

For a change inside a large HTML document or long text, the skill prefers a short unique anchor replaced with str_replace over rewriting the whole field with set. An anchor must match exactly once unless replaceAll is set.

• Read the scene with detail set to source before writing.
• Patch the smallest leaf that matches the intent.
• Read the same path again to confirm the stored value.
• Use grep_stage or a text read to confirm old copy no longer remains.

Reference chapters and when to read them

The main skill file is a map. Each field type has its own chapter, and the agent should read the matching one before writing to that structure for the first time or after a rejected patch. The slide canvas is covered by slide-dsl rather than this skill.

• references/quiz.md: quiz questions, options, answers and grading fields.
• references/widget.md: interactive HTML and typed widget configuration.
• references/actions.md: narration, spotlight, whiteboard, video, discussion and widget playback actions.
• references/pbl.md: PBL projectV2 roles, milestones, microtasks and runtime-owned fields.
• Slide canvas and elements: the installed slide-dsl skill.