Magic Slide

Magic Slide

Generate polished HTML presentations with smooth Magic Move transitions — elements that appear on multiple slides animate fluidly between their positions. Treat Magic Move as a story-planning constraint, not an afterthought: arrange the outline so meaningful headings, card titles, numbers, images, or diagram nodes can persist across adjacent slides.

Skill Command Arguments

The user invoked this skill with: $ARGUMENTS

Visible TODO Requirement

Whenever this skill is invoked, create a visible TODO/plan before the first meaningful action and keep it updated until the turn stops.

• Use the host's planning tool when available: Codex update_plan, Claude Code TodoWrite, or the environment's equivalent visible checklist. This is required for every $magic-slide run, including preview-only commands, intake/question-only turns, new deck generation, follow-up deck edits, and visual-issues.json repair passes.
• Keep the list short and concrete: 3-7 items that match the current mode. Examples: "Resolve deck path", "Start preview server", "Read QA notes", "Repair slide 02 source", "Merge and inject runtime", "Mark QA notes pending confirmation", "Leave QA Overview open for review".
• Update item statuses as work advances. Do not wait until the end to mark everything done; the user should be able to see what is happening while the skill is running.
• If a required checkpoint stops the turn, such as requirements intake, web search choice, outline confirmation, or user QA confirmation, leave the TODO showing the waiting/checkpoint item.
• If no visible TODO tool exists, write a compact TODO checklist in the chat before proceeding and update it manually in later progress messages.

When invoked as /magic-slide preview [topic] in Claude Code or $magic-slide preview [topic] in Codex, run the preview fast path:

In a CelHive hosted Skill run, use $CELHIVE_SKILL_WORKSPACE/deck as the deck directory and invoke the host's generic Preview tool after generation. The package-level preview.json owns the managed command, port, health route, and Artifact roots; do not start a second preview process manually. Outside a managed host, keep the local serve.py workflow below.

1. Create the visible TODO list first, with preview-specific steps such as resolving the deck path, starting serve.py, and reporting the URL.
2. Treat the argument after preview as the topic/deck directory. If omitted, use .. Preview the index.html inside that directory. If the user passes an explicit .html file, preview that file directly.
3. Locate this skill directory if needed: SKILL_DIR=$(find ~ -type d -name "magic-slide-skill" 2>/dev/null | head -1)
4. Resolve a Python 3 interpreter using the Script Runtime Requirements below.
5. Start the preview server with the existing script: $PYTHON_BIN "$SKILL_DIR/scripts/serve.py" "$DECK_PATH"
6. Keep the server process running and give the user the displayed URL.
7. Do not ask deck-generation questions, create an outline, merge slides, or inject runtime unless the user explicitly asks for those tasks too.

For any other magic-slide invocation arguments, treat the arguments as the user's presentation request and follow the normal generation workflow.

Non-Preview Intake Gate

Before running commands, searching, creating folders, writing an outline, or generating slides for any non-preview deck request, complete Step 1 in references/workflows/step-01-requirements.md.

Hard gate:

• The visible TODO requirement still runs before this gate. If the turn stops for intake, leave the TODO showing that requirements are being gathered and that generation is waiting on the user's answers.
• If topic/audience-lens, aesthetic style, presentation language, or image policy is missing, inferred, or only implied, ask the Step 1 requirements question and stop.
• Do not treat the user's chat language as the presentation language.
• Do not treat a URL, company/product name, or "介绍一下 X" as a complete topic unless the audience/lens has also been explicitly supplied or confirmed.
• If the structured question tool is unavailable, use the plain-text fallback template from Step 1 as the whole response for that turn, then wait.

CRITICAL: Script Runtime Requirements

Magic Slide's bundled scripts require a Python 3 runtime. Core merge, inject, repair-note, and preview scripts use the Python standard library plus a modern browser; they do not require external Python packages. PipeLLM scripts require PIPELLM_API_KEY in the environment only when web search or image generation is used. Playwright is only required for agent-run screenshot QA, including scripts/check-magic-text-wrap.py.

PipeLLM web search is optional, user-approved, and returns sanitized untrusted evidence records. PipeLLM image generation is optional and user-approved. The scripts require --allow-external so external requests cannot happen without an explicit workflow gate; Step 2 owns the detailed prompt-injection boundary.

Before the first script execution in a turn, resolve a Python 3 interpreter:

PYTHON_BIN=$(command -v python3 || command -v python || true)
if [ -z "$PYTHON_BIN" ]; then
  echo "Magic Slide requires Python 3 to run its bundled scripts." >&2
  echo "Install Python 3, then rerun the Magic Slide command." >&2
  exit 1
fi
if ! "$PYTHON_BIN" -c 'import sys; raise SystemExit(0 if sys.version_info[0] == 3 else 1)'; then
  echo "Magic Slide requires Python 3, but the resolved python command is not Python 3." >&2
  exit 1
fi

Use $PYTHON_BIN for script invocations after it is resolved. If Python 3 is not available, stop and tell the user that Magic Slide needs Python 3 rather than rewriting or bypassing the scripts.

CRITICAL: Script Execution Rules

All scripts in this skill are located in the scripts/ directory relative to the skill root.

When executing scripts:

1. If a script execution fails with "No such file or directory":

   • DO NOT give up or tell the user "the script isn't available"
   • Find the skill directory using: find ~ -name "magic-slide-skill" -type d 2>/dev/null | head -1
   • Or search for SKILL.md: find ~ -name "SKILL.md" -path "*/magic-slide-skill/*" 2>/dev/null | head -1 | xargs dirname
   • Store the skill directory path in a variable
   • Re-execute the script using the absolute path: $PYTHON_BIN $SKILL_DIR/scripts/websearch.py

2. Always use absolute paths for script execution to avoid path issues

Example of correct execution:

# Find skill directory (do this once at the start)
SKILL_DIR=$(find ~ -type d -name "magic-slide-skill" 2>/dev/null | head -1)

# Execute scripts with absolute paths
$PYTHON_BIN "$SKILL_DIR/scripts/websearch.py" "query" --allow-external
$PYTHON_BIN "$SKILL_DIR/scripts/generate-image.py" "prompt text" --output ./assets/image.png --allow-external
$PYTHON_BIN "$SKILL_DIR/scripts/merge-slides.py" ./sources/ --lang en

CRITICAL: Injected Runtime Output Boundary

Treat scripts/inject-runtime.py and the behavior/results it injects into the finished deck as Magic Slide runtime output. During deck generation, updates, and QA, run the existing injector unchanged and preserve its injected behavior by default. Do not edit the injector, patch injected runtime blocks in {topic}/index.html, or add source CSS/HTML/JS whose purpose is to disable, hide, neutralize, or override injected features unless the user explicitly asks for that specific runtime behavior change.

Examples of prohibited "cleanup" without explicit user request: hiding the animated/custom cursor, restoring the system cursor with cursor: auto or cursor: default, removing or hiding navigation/progress/edit controls, turning off Magic Move, suppressing injected stagger, or bypassing runtime fit.

If a deck has a visual or layout issue, fix the modular source files (sources/style.css and sources/slide-XX.html) around the runtime behavior, then re-run merge and inject. If the issue appears to be caused by injected runtime behavior itself, report the suspected runtime issue or ask before changing it; only modify runtime behavior when the user requested that change.

Quick Workflow

Default to the balanced path. Keep the outline checkpoint, write a short design brief, then generate the full deck in one production pass. Do not build a separate prototype unless the user explicitly asks for that slower workflow. The visible TODO requirement applies before Step 1 and should be refreshed when the workflow changes from intake to outline, generation, QA, or repair.

USER INTERACTION RULE: All user confirmations MUST use the AskUserQuestion tool. Text-based questions are ONLY a fallback if the tool is unavailable or fails. Always try AskUserQuestion first. If you must fall back to plain text, end structured questions with a copyable response template, except for outline confirmation and the web-search yes/no question; see references/workflows/text-question-templates.md.

1. Step 1: Gather requirements — Ask ALL 4 question groups: topic/audience-lens, aesthetic style, language (REQUIRED - never infer from user's message language), images
2. Step 2: Web search — Ask user if they want online search (optional). If they say yes, run scripts/websearch.py first; built-in agent search is only a fallback after the script fails or returns no usable results.
3. Step 3: Generate outline — Create {topic}/sources/outline.md with MANDATORY elements: thesis spine, audience/lens, chapter arc, closing idea, Magic Move content-relay spine, presenter note mode, and per-slide speaker prompts. Get user confirmation (required checkpoint)
4. Step 4: Write Brief Lite — Output a compact design brief before CSS/HTML: visual world, rejected tropes, cover promise, tone mode, style-controlled type/color/material logic, slide families, and Magic Move content-relay motion grammar
5. Step 5: Generate production sources — Create style.css and all slide-XX.html files directly from the confirmed outline and Brief Lite, after making a primary/supporting continuity map for adjacent slide pairs and mapping outline speaker prompts into hidden presenter notes
6. Step 6: Merge slides — Combine modular sources into single HTML
7. Step 7: Inject runtime — Run the existing injector unchanged; preserve injected behavior/results unless the user explicitly asks otherwise
8. Step 8: Preview, autonomous overview QA repair, mandatory user revision pause, revision-note repair, user confirmation, and delivery — ALWAYS launch the skill preview server with scripts/serve.py, open the runtime QA capture URL, take one Playwright QA overview longshot for first-pass repair, then stop so the user can mark slide revisions. After repairing saved revision notes, mark them fixed and awaiting user confirmation instead of running a screenshot verification pass.

NON-NEGOTIABLE DELIVERY RULE: After generating or updating a deck, do not finish until $PYTHON_BIN "$SKILL_DIR/scripts/serve.py" {topic}/index.html is running and you have given the user the preview URL. Opening the HTML file directly is not enough: edit mode, save, image replacement, and close/shutdown controls require the Magic Slide preview server. Never substitute python3 -m http.server, npx serve, or a file URL for the skill server.

NON-NEGOTIABLE QA GATE: After serve.py is running for a newly generated deck, open ?ms_qa=overview&ms_qa_capture=1, wait until the QA wall reports iframe-loaded readiness, capture one Playwright full-page/scrolling QA overview longshot, and repair the most obvious rendered visual issues by slide number first. During this autonomous first pass, do not capture full-size single-slide screenshots after the overview repair. Follow references/workflows/step-10-preview.md for the detailed triage order and Playwright-only screenshot rule. Then reopen/leave QA Overview running and stop: tell the user to mark slide changes with Revise slide on the QA cards and return when ready. This user revision pause is mandatory before final QA or delivery. When continuing repairs, first read open JSON notes from {topic}/sources/qa/visual-issues.json.

NON-NEGOTIABLE UPDATE RULE: When the user continues in chat after a deck has been generated and asks for changes, read {topic}/sources/qa/visual-issues.json first and prioritize open revision requests when present. If open notes exist, repair from the saved JSON plus the corresponding {topic}/sources/slide-XX.html and {topic}/sources/style.css; screenshots are only for notes that are too ambiguous to interpret from JSON/source context and must be captured with Playwright. Edit the modular source files first, then re-run merge-slides.py, re-run the existing inject-runtime.py unchanged, mark repaired JSON records status: "fixed_pending_confirmation" with resolved: false, refresh or restart the Magic Slide preview server, and leave/open QA Overview for the user to confirm or continue requesting changes. Do not run a screenshot verification pass after repairing saved JSON notes unless the user explicitly asks for visual verification. Do not edit {topic}/index.html directly for agent-driven follow-up changes unless the user explicitly asks to patch the merged HTML, or the change comes from the browser edit mode Save flow.

Brief Lite is not optional. It is the quality guardrail that prevents generic or frightening template output. Keep it concise. Only use the slower prototype gate when the user asks for high-touch design exploration, a risky visual direction, or a small sample before generating the whole deck.