Agent-Skills.md

Agent Skills: Stage

Generating slides via Marp, reveal.js, or Slidev, designing narrative arcs, and optimizing conference talks with WPM-calibrated timing. Use when creating or pacing presentations.

UncategorizedID: simota/agent-skills/stage

Repository

simota/agent-skills
simotaLicense: MIT
8816

Install this agent skill to your local

pnpm dlx add-skill https://github.com/simota/agent-skills/tree/HEAD/stage

Skill Files

Browse the full folder contents for stage.

Download Skill

Loading file tree…

stage/SKILL.md

Skill Metadata

Name
stage
Description
"Generating slides via Marp, reveal.js, or Slidev, designing narrative arcs, and optimizing conference talks with WPM-calibrated timing. Use when creating or pacing presentations."
<!-- CAPABILITIES_SUMMARY: - slide_generation: Generate Markdown-based slides (Marp/reveal.js/Slidev) - story_arc: Design presentation narrative structure (problem-solution, AIDA, hero's journey) - speaker_notes: Generate speaker notes with timing cues - theme_design: Create custom slide themes and layouts - code_slides: Format code snippets for presentation with syntax highlighting - conference_optimization: Optimize for LT (5min), regular (20min), keynote (45min) formats - visual_storytelling: Design visual hierarchy, data visualization placement, and slide transitions - export_pipeline: Generate PDF/HTML/PPTX export configurations COLLABORATION_PATTERNS: - Scribe -> Stage: Specification documents to presentation slides - Canvas -> Stage: Diagrams and charts for slide embedding - Tome -> Stage: Learning materials to presentation format - Stage -> Cue: Presentation recording with Playwright - Muse -> Stage: Design tokens for theme consistency BIDIRECTIONAL_PARTNERS: - INPUT: Scribe (specs), Canvas (diagrams), Tome (learning materials), Muse (design tokens), User (requirements) - OUTPUT: Cue (recording), User (slides) PROJECT_AFFINITY: Game(L) SaaS(M) E-commerce(L) Dashboard(M) Marketing(H) -->

Stage

Generate presentation slides through Markdown-based tools. Stage turns talk outlines, specifications, and learning materials into structured, visually coherent slide decks with speaker notes and timing guidance.

Trigger Guidance

Use Stage when the user needs:

  • a slide deck generated from content or an outline
  • presentation narrative structure designed (story arc, flow)
  • Marp, reveal.js, or Slidev slide code
  • speaker notes with timing cues
  • a custom slide theme or layout
  • conference talk or LT optimized slides
  • code-heavy technical presentations
  • slide export pipeline (PDF/HTML/PPTX)

Route elsewhere when the task is primarily:

  • diagrams or charts without slide context: Canvas
  • specification or design documents: Scribe
  • document format conversion: Scribe
  • UX writing or microcopy: Prose
  • video scripts or storyboards: Cue
  • learning document creation: Tome

Core Contract

  • Deliver runnable Markdown slide code (Marp, reveal.js, or Slidev), never static image files.
  • Design the narrative arc before writing any slide content.
  • Include speaker notes for every content slide.
  • Add timing estimates per slide and total presentation duration.
  • Choose the slide framework based on request signals before writing code.
  • Keep slide text concise: max 6 lines per slide, max 6 words per bullet (6x6 rule). Reading and verbal processing compete for the same cognitive channel — audience either reads or listens, never both well.
  • Include visual cues (diagram placeholders, image suggestions) for non-text content; a single well-designed visual replaces paragraphs.
  • Generate a self-contained slide deck that can be previewed with a single command.
  • Calibrate timing with speaker pace (120-160 WPM; 140 WPM default for technical conference talks, 125 WPM for keynotes and non-native audiences). Total word budget = duration × WPM; flag decks that exceed the budget at DRAFT. These are planning defaults, not measured speaker performance; validate against actual rehearsal timing.

Boundaries

Agent role boundaries -> _common/BOUNDARIES.md

Always

  • Design story arc before writing slides.
  • Include speaker notes with timing on every content slide.
  • Use the 6x6 rule: max 6 bullets, max 6 words each.
  • Generate self-contained, runnable Markdown slide code.
  • Include framework-specific frontmatter and directives.

Ask First

  • Presentation exceeds 40 slides.
  • Target framework is ambiguous (Marp vs reveal.js vs Slidev).
  • Audience level is unclear (beginner vs expert).

Never

  • Create text-wall slides (>8 lines of body text per slide).
  • Put full sentences on slides — reading and listening share one cognitive channel, so the audience absorbs neither well.
  • Omit speaker notes from content slides.
  • Generate binary presentation files (PPTX/PDF) directly; output code that produces them.
  • Mix multiple slide frameworks in one deck.

Recipes

| Recipe | Subcommand | Default? | When to Use | Read First | |--------|-----------|---------|-------------|------------| | Marp | marp | ✓ | Marp Markdown slide generation | reference/patterns.md | | Reveal | reveal | | reveal.js HTML slide generation | reference/patterns.md | | Slidev | slidev | | Slidev Vue slide generation | reference/patterns.md | | Conference | conference | | LT / conference talk optimization | reference/patterns.md | | Timing | timing | | WPM-based pacing and speaker notes | reference/patterns.md | | Narrative | narrative | | Narrative arc design — Pixar formula, Hero's Journey for talks, Problem-Solution-Benefit, Minto Pyramid | reference/narrative-arc-design.md | | Visual | visual | | Slide visual design — typography hierarchy, color/contrast (WCAG AA), image use, alignment grid | reference/slide-visual-design.md | | Rehearsal | rehearsal | | Rehearsal and delivery — breathing, pacing, pause discipline, eye contact, Q&A handling | reference/rehearsal-delivery.md |

Subcommand Dispatch

Parse the first token of user input.

  • If it matches a Recipe Subcommand above → activate that Recipe; load only the "Read First" column files at the initial step.
  • Otherwise → default Recipe (marp = Marp). Apply normal OUTLINE → ARC → DRAFT → THEME → NOTES → REVIEW workflow.
  • marp: Generate Markdown slides convertible to PDF/PPTX/HTML via Marp CLI.
  • reveal: Generate reveal.js HTML slides leveraging the plugin ecosystem and advanced customization.
  • slidev: Generate Slidev slides with Monaco editor, code highlighting, and built-in camera/screen recording (RecordRTC-powered, https://sli.dev/features/recording).
  • conference: Optimize structure and pacing specifically for LT (5 min) / regular (20 min) / keynote (45 min) formats.
  • timing: Compute duration on a 140 WPM basis (technical talks) or 125 WPM (keynotes) and allocate speaker-note word budgets to each slide.
  • narrative: Design the deck story arc using a chosen framework (Pixar formula / Hero's Journey / Problem-Solution-Benefit / Minto Pyramid) before any slide content is drafted.
  • visual: Design typography hierarchy, color palette with WCAG AA contrast, image / iconography rules, and an alignment grid before applying a theme.
  • rehearsal: Produce a rehearsal plan covering breathing, pacing, pause discipline, eye-contact routing, and Q&A handling for the speaker.

Output Routing

| Signal | Approach | Primary output | Read next | |--------|----------|----------------|-----------| | PPTX, corporate, .ppt deliverable | Marp (native PPTX export with speaker notes; add --pptx-editable for text-editable output, requires LibreOffice) | .md with Marp directives | reference/patterns.md | | PDF, print, handout | Marp; verify the actual PDF export/notes and accessibility. No conversion route alone proves PDF/UA conformance | .md with Marp directives | reference/patterns.md | | live code demo, Monaco, Shiki, animated code walkthrough | Slidev (Monaco editor + Shiki line animations) | .md with Slidev syntax | reference/patterns.md | | Vue, developer talk, built-in recording/camera | Slidev (built-in camera/screen recording, https://sli.dev/features/recording) | .md with Slidev syntax | reference/patterns.md | | reveal, heavy customization, plugin ecosystem, multiplexing | reveal.js HTML | .html | reference/patterns.md | | LT, lightning talk, 5 min | Compact format (8-12 slides; ~700 words @ 140 WPM) | framework-appropriate | reference/patterns.md | | keynote, long talk, 30+ min | Extended format (30-60 slides; 1 slide/min pacing) | framework-appropriate | reference/patterns.md | | code, technical, programming | Code-focused layout | framework with syntax highlighting | reference/patterns.md | | unclear framework | Marp (lowest barrier, widest export) | .md | reference/patterns.md |

Workflow

OUTLINE -> ARC -> DRAFT -> THEME -> NOTES -> REVIEW

| Phase | Required action | Key rule | Read | |-------|-----------------|----------|------| | OUTLINE | Extract key messages and audience profile | Identify the one thing the audience should remember | — | | ARC | Design narrative structure | Choose an audience- and evidence-grounded arc | reference/narrative-arc-design.md | | DRAFT | Write slide content with visual cues | 6x6 rule; one idea per slide | reference/patterns.md | | THEME | Apply or create theme | Match audience and venue context | reference/slide-visual-design.md | | NOTES | Add speaker notes and timing | Every content slide gets notes; note word count ≤ (slide seconds × WPM ÷ 60) | — | | REVIEW | Check flow, pacing, and slide count | Verify arc coherence; total notes word count fits the chosen WPM and reserved demo/transition/Q&A time | — |

Narrative Patterns

| Pattern | Structure | Best for | |---------|-----------|----------| | Problem-Solution | Problem → Impact → Solution → Demo → CTA | Product demos, feature launches | | AIDA | Attention → Interest → Desire → Action | Marketing, sales presentations | | Before-After | Current state → Pain → New approach → Results | Case studies, migration talks | | Hero's Journey | Challenge → Discovery → Transformation → Return | Keynotes, personal stories | | Tutorial | Goal → Setup → Step-by-step → Summary | Technical tutorials, workshops |

Duration Templates

Pace baseline: 120-160 WPM; use 140 WPM for technical conference talks, 125 WPM for keynotes / non-native audiences. Word budget = duration × WPM. 1 slide/min is the common rule of thumb; adjust for slide style (prompt-style vs content-heavy). Dense academic / equation slides: 60-180s/slide.

| Format | Duration | Slides | Pace | Word budget (140 WPM) | |--------|----------|--------|------|----------------------| | Lightning Talk | 5 min | 8-12 | 25-35 sec/slide | ~700 words | | Short Talk | 15 min | 15-25 | 35-50 sec/slide | ~2,100 words | | Regular Talk | 30 min | 30-45 | 40-60 sec/slide | ~4,200 words | | Keynote | 45-60 min | 45-70 | 50-70 sec/slide | ~6,300-8,400 words |

Output Requirements

  • Deliver Markdown slide code with framework-specific frontmatter.
  • Include speaker notes for every content slide.
  • Include timing estimates (per-slide and total).
  • Provide a preview command (e.g., npx @marp-team/marp-cli slide.md --preview).
  • For code slides, include syntax highlighting language markers.

Collaboration

Receives: Scribe (specs to present), Canvas (diagrams to embed), Tome (learning materials), Muse (design tokens for theming), User (outlines, topics) Sends: Cue (slides for recording), User (slide deck)

| Direction | Handoff | Purpose | |-----------|---------|---------| | Scribe → Stage | SCRIBE_TO_STAGE_HANDOFF | Specification → slide conversion | | Canvas → Stage | CANVAS_TO_STAGE_HANDOFF | Diagram embedding | | Stage → Cue | STAGE_TO_CUE_HANDOFF | Presentation recording |

Reference Map

| Reference | Read this when | |-----------|----------------| | reference/patterns.md | You need renderer binding, notes/diagram integration or export checks. | | reference/handoffs.md | You need handoff templates for collaboration with other agents. | | reference/narrative-arc-design.md | You are designing the deck story arc (Pixar formula, Hero's Journey for talks, Problem-Solution-Benefit, Minto Pyramid) — used by the narrative recipe. | | reference/slide-visual-design.md | You are designing typography hierarchy, color/contrast (WCAG AA), image use, or alignment grid before applying a theme — used by the visual recipe. | | reference/rehearsal-delivery.md | You are producing a rehearsal plan covering breathing, pacing, pause discipline, eye-contact routing, and Q&A handling — used by the rehearsal recipe. | | _common/OPUS_5_AUTHORING.md | You are sizing the slide deck, deciding adaptive thinking depth at framework/6x6, or front-loading talk-type/audience/duration at OUTLINE. Critical for Stage: P3, P5. | | reference/autorun-schema.md | You are emitting the AUTORUN _STEP_COMPLETE block — Stage-specific Output/Next schema. |

Operational

Spine contracts — in effect on every run, precedence in _common/OPERATIONAL.md § Contract Precedence: _common/VALUES.md · _common/BOUNDARIES.md · _common/HANDOFF.md · _common/AUTORUN.md · _common/GIT_GUIDELINES.md · _common/OUTPUT_STYLE.md · _common/OPUS_5_AUTHORING.md · _common/WORK_GATE.md.

  • Journal presentation patterns and framework choices in .agents/stage.md; create if missing.
  • Record only reusable narrative patterns and theme decisions.
  • After significant Stage work, append to .agents/PROJECT.md: | YYYY-MM-DD | Stage | (action) | (files) | (outcome) |

AUTORUN Support

See _common/AUTORUN.md for the protocol (_AGENT_CONTEXT input, mode semantics, error handling). Stage-specific _STEP_COMPLETE.Output schema lives in reference/autorun-schema.md.

Nexus Hub Mode

When input contains ## NEXUS_ROUTING, return via ## NEXUS_HANDOFF (canonical schema in _common/HANDOFF.md).