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:

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

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"
$PYTHON_BIN "$SKILL_DIR/scripts/generate-image.py" "prompt text" --output ./assets/image.png
$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, and Magic Move content-relay spine. 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
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.

Detailed Workflow Steps

Each step has detailed instructions in the references/workflows/ directory. Read the relevant file when you reach that step:

• Step 1: Gather Requirements - MUST ask ALL 4 question groups: topic/audience-lens, style, language (REQUIRED), images. Never skip language question.
• Step 2: Web Search - Optional online search for current information
• Step 3: Generate Outline - Create and confirm presentation structure
• Step 4: Write Brief Lite - Compact required design brief before coding
• Step 5: Generate Production Sources - Create style.css and all slides directly from the confirmed outline and Brief Lite
• Step 6: Merge Slides - Combine modular sources into single HTML
• Step 7: Inject Runtime - Run the existing injector and preserve injected behavior/results unless explicitly requested otherwise
• Step 8: Preview & Final QA - Launch preview and verify quality

Legacy optional workflow files:

• Optional: Build Visual Prototype - Use only when the user requests a sample first
• Optional: Pass Visual Gate - Use only with the optional prototype workflow

Post-Generation Editing

Users can edit the presentation in two ways, but agent-driven follow-up work
must preserve the source-of-truth files.

Editing requires the preview server. Before mentioning edit mode, ensure the deck is being served through scripts/serve.py and give the user the server URL. If the server is not running, start it first.

Keyboard scope. When a deck is opened through the local serve.py preview route (http://localhost:.../deck/...), all runtime shortcuts are available. When the same HTML is opened outside that local preview context, only presentation-safe shortcuts remain active: O for overview, C for cursor visibility, Space/arrow keys for slide navigation.

1. Edit modular sources (default for all agent changes):

• Edit {topic}/sources/slide-XX.html or style.css
• Re-run merge and inject scripts
• Refresh browser

2. Edit merged HTML (only for explicit quick fixes or browser edit mode):

• Press 'e' in browser to enter edit mode
• Click any text to edit inline
• Click "Save" to write changes back to index.html
• The preview server attempts to sync browser-saved changes back to sources/
• If editing index.html directly outside the browser Save flow, warn that the
  modular sources may become stale and prefer sources/ instead

File Structure

{topic}/
├── index.html          # Final merged presentation (deliverable)
├── assets/             # Final presentation assets (if generated)
│   ├── image-1.png
│   └── ...
└── sources/            # Process files and modular source files
    ├── outline.md      # Confirmed outline
    ├── create_sources.mjs  # Optional generation helper, if used
    ├── qa/             # QA screenshots/reports, if generated
    ├── style.css
    ├── slide-01.html
    ├── slide-02.html
    └── ...

Keep the topic root clean. Apart from index.html, assets/, and sources/,
all process artifacts belong inside {topic}/sources/.

Key Reference Files

Read these files as needed during generation. Treat them as the single
authoritative source for their topic; do not reconstruct long versions of their
rules in this file or workflow steps.

• design-system.md — aesthetic direction and anti-template guardrails
• generation-guide.md — production planning and generation strategy
• layout-guide.md — layout primitives, stage fit, overflow, vertical balance, and source-note placement
• html-contract.md — required slide structure, deck tone mode, root backgrounds, SVG contract, file naming, and verification checklist
• flip-engine.md — Magic Move / data-magic-id planning and reliability rules
• images.md — generated image use, uploadable wrappers, and cover-image policy

Design Philosophy

1. Outline must be an argument, not a topic list — Every slide advances a thesis, not just "this also exists"
2. Brief Lite first — Commit to a topic-specific visual world and primary light/dark tone before writing CSS. Keep it concise, but output it so the design promise is visible.
3. Magic Move is planned early — The outline should create content relay opportunities before HTML exists: overview/detail, metric/hero-stat, map/zoom, compare/case, and other primary anchors. Do not rely on decorative duplicates to manufacture motion late.
4. Generate once, inspect, then pause — Produce the full deck after outline and Brief Lite, repair obvious Playwright QA overview longshot issues, then stop for the mandatory user Revise slide marking pass before final delivery.
5. QA overview is visual, not diagnostic — Use the overview as a rendered slide wall and revision-note capture surface for human/agent visual review. Keep separate checks limited to syntax, preview startup, runtime controls, and Playwright-rendered screenshot inspection.
6. Cover is a special moment — Slide 1 must be a distinct opening
   composition with concise cover copy; for product/AI/infrastructure decks it
   should stay title-led rather than carrying readable process diagrams. Use
   design-system.md, images.md, and html-contract.md for the detailed
   cover rules.
7. Fast iteration — If something's wrong, revise CSS and affected source slides quickly, then merge/inject again.
8. Merged HTML is an artifact — Treat {topic}/index.html as generated output. Direct HTML edits are only for explicit one-off patches or the browser edit mode Save flow.
9. Layout reliability is mandatory — Follow layout-guide.md for
   primitives, stage fit, overflow, vertical balance, and source-note placement.
10. No artificial slide chrome or Magic-only labels — Follow
    html-contract.md and flip-engine.md: do not generate browser-bar-like
    top strips, full-width brand pills, or body token rows whose main purpose is
    to create Magic Move continuity.

Quality bar: Every deck should feel distinctive and intentional, not like the first thing that came to mind. If another topic could use the same design unchanged, the design is too generic.

Readability bar: Treat unreadable text as a broken deck, not a taste issue.
Use html-contract.md, layout-guide.md, and design-system.md for the
detailed text contrast and text-fit rules.

Output Quality

Every presentation should be:

• Self-contained — Single HTML file, no external dependencies
• Smooth — Magic Move creates fluid transitions
• Portable — Works offline, easy to share
• Editable — Modular sources for easy iteration
• Distinctive — Unique visual style, not generic AI aesthetics

The goal is speed with taste: decide the visual world, preview it early, then generate fast and iterate against the rendered deck.