The Complete Production SOP: How to Deploy and Run Marp Markdown Presentation Engine in Autonomous AI Agents
Step-by-step SOP to install and run Marp Markdown Presentation Engine in Codex, Claude Code, and Cursor. Includes verified prompts, CSS rules, and fixes.
Technical Overview & Architectural Context
Without structured procedural boundaries, autonomous AI agents generating Marp presentations frequently inject invalid frontmatter, produce broken scoped CSS syntax, or attempt to run headless browser exports that fail due to missing sandboxed Chromium dependencies. LLMs commonly output standard markdown headers rather than adhering to Marp directive semantics (like `paginate: true`, `theme: gaia`, and scoped style blocks), resulting in malformed slide transitions and clipped slide boundaries. The `marp-markdown-presentation-styler` skill enforces strict deterministic boundaries on how agents structure slide decks. It confines agent generation to validated triple-dash separators (`---`), enforces compliant Marp CSS overrides, and enforces zero-network CLI builds that pass deterministic layout tests before the agent confirms task execution.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the Marp presentation skill manifest directly into the agent skill directory.
Autonomous coding agents like Claude Code, Cursor, and Codex automatically parse local skill definitions when placed in the root `.agents/skills` or `.claude/skills` directory. This mounts the frontmatter triggers (`compile marp markdown to slides`, `export marp to pdf`, `create custom marp theme`) into the agent's intent-routing layer.
mkdir -p .agents/skills/marp-markdown-presentation-styler && curl -fsSL https://askills.dev/api/skills/marp-markdown-presentation-styler/raw -o .agents/skills/marp-markdown-presentation-styler/SKILL.md---
name: "marp-markdown-presentation-styler"
description: "Write slick presentation slides in plain Markdown with Marp CLI and custom CSS themes."
metadata:
author: "Marp"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "compile marp markdown to slides"
- "export marp to pdf"
- "create custom marp theme"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: true
net_access: false
---
# Marp Markdown Presentation Engine
Converts Markdown files into responsive HTML5 slides, PDFs, or PPTX presentations using Marp core directives.Keep presentation assets inside `./slides/assets` and pin theme references in Marp frontmatter to prevent agent hallucination of external CDNs.
Ensure `fs_write` is restricted to your target workspace path; never allow the agent to write compiled PDFs outside project directories.
Toolchain Validation & Headless Browser Dependency Verification
Install the Marp CLI and verify the local Chromium binary required for PDF compilation.
Marp requires `@marp-team/marp-cli` to compile Markdown into PDF, PPTX, or standalone HTML. When running within containerized sandboxes or restricted terminal sessions, headless Chrome must be discovered via `CHROME_PATH` or Puppeteer environment flags.
npm install -D @marp-team/marp-cli && npx @marp-team/marp-cli --version{
"scripts": {
"slides:build": "marp --pdf presentation.md -o dist/presentation.pdf --allow-local-files",
"slides:preview": "marp --server presentation.md"
},
"devDependencies": {
"@marp-team/marp-cli": "^3.4.0"
}
}Pass `--allow-local-files` to enable rendering local SVGs and diagram images without triggering network security violations.
Puppeteer will crash in Linux agent containers if missing shared system libraries like `libnss3` or `libatk-1.0`.
Trigger Activation & Deterministic Markdown Generation
Prompt the agent with precise trigger phrases to generate valid Marp frontmatter and scoped slides.
Initiate generation using one of the mapped triggers (`compile marp markdown to slides`, `export marp to pdf`). The agent adheres to the structural rules: setting `marp: true`, applying scoped CSS overrides for title cards, and enforcing pagination boundaries.
---
marp: true
theme: gaia
_class: lead
paginate: true
backgroundColor: #1e1e2e
color: #cdd6f4
style: |
section.lead h1 {
color: #89b4fa;
}
footer {
font-size: 0.6rem;
}
---
# Enterprise Architecture 2026
### Distributed Systems & Agentic Workflows
---
<!-- paginate: true -->
## Architecture Blueprint
- Deterministic agent pipelines
- Ephemeral container runtimes
- Audit-logged execution traces
<footer>Confidential - Engineering Review</footer>Use `_class: lead` with leading underscore to apply layout styling exclusively to the active slide instead of cascading globally.
Do not mix HTML standard comment directives with Marp directives; Marp requires `<!-- paginate: true -->` syntax inside slide bodies.
Automated Quality Gate & Visual Build Verification
Execute the Marp build check and validate exit status code 0 before finalizing changes.
Instruct the agent to validate compilation via the Marp CLI dry-run or direct output build. If errors occur due to unclosed tags or syntax defects, the agent self-heals before delivering output.
npx marp presentation.md --dry-run && npx marp presentation.md --pdf -o dist/deck.pdf --allow-local-files#!/usr/bin/env bash
set -euo pipefail
if ! npx @marp-team/marp-cli presentation.md --dry-run; then
echo "Marp syntax linting failed! Check frontmatter and CSS."
exit 1
fi
echo "Marp validation passed successfully."Always execute `--dry-run` during the agent self-verification step to validate parsing without invoking heavy PDF render pipelines.
Avoid committing generated binary PDFs into git history; ensure `dist/` is added to `.gitignore`.
Real-World Scenario: Automated Quarterly Technical Review Slide Deck Generation
“Using the marp-markdown-presentation-styler skill, compile marp markdown to slides for our Q3 Technical Review. Create a custom dark theme matching Catppuccin Mocha, include 4 slides covering executive summary, performance benchmarks, architectural changes, and next steps, then export marp to pdf.”
Runtime Troubleshooting & Failure Modes
Root Cause: Headless Chromium is missing or inaccessible in the agent's sandboxed environment, preventing Marp CLI from capturing slide screenshots for PDF rendering.
export CHROME_PATH=$(which google-chrome || which chromium) && npx marp presentation.md --pdf --allow-local-filesRoot Cause: Malformed style block in YAML frontmatter. CSS inside YAML requires the pipe literal scalar syntax (`style: |`) or proper HTML `<style>` tags within markdown body.
Replace invalid inline style directive with:
style: |
section {
font-family: 'Helvetica Neue', sans-serif;
}Frequently Asked Questions (Marp Markdown Presentation Engine SOP)
Q:Can I use Marp Markdown Presentation Engine across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. Once installed under `.agents/skills/marp-markdown-presentation-styler/SKILL.md` or linked in Claude/Cursor project settings, all compatible agent runtimes recognize its triggers and execution rules identically.
Q:How does Marp Markdown Presentation Engine prevent context window overflow during long agent sessions?
The skill provides concise, deterministic SOP guidelines and specific CLI command patterns rather than dumping lengthy presentation examples. This keeps token usage minimal while providing clear syntax rules for frontmatter and scoped CSS.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100 and only requires workspace-level file access and standard CLI execution permissions for `npx marp`. Network access is disabled by default to keep slide builds private and hermetic.
Ready to equip your autonomous agent with Marp Markdown Presentation Engine?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.