Review and refine Markdown presentations with AI hints

mdpr-skill

Overview

Use this skill as the optional agent companion for
MDPR, a deterministic
Markdown-to-presentation runtime. MDPR owns parsing, layout, theming,
validation, and final PPTX/HTML/PDF rendering. This skill helps an agent review
MDPR workflows, propose weak semantic hints, and explain visual findings without
taking control of slide geometry.

The upstream skill source is
ch040602/mdpr-skill, which includes
schemas, review commands, compatibility artifacts, visual evidence examples, and
MDPR boundary documentation.

When to Use This Skill

• Use when the user asks about MDPR, mdpresent, Markdown-to-PPTX, or
  Markdown presentation review.
• Use when generated MDPR artifacts need semantic, narrative, accessibility, or
  visual review notes.
• Use when the user wants Codex-style presentation workflow hints while keeping
  MDPR as the deterministic renderer.
• Use when comparing MDPR output against image-only deck generators such as a
  codex-ppt style workflow.
• Use when a reusable theme or style-pack proposal should be expressed as an
  approval-bound MDPR candidate instead of direct final slide edits.

Core Boundary

• Let MDPR own parsing, slide splitting, recipes, layout, coordinates,
  geometry, typography, colors, z-order, arrows, effects, exact icon assets,
  renderer object IDs, and final PPTX objects.
• Keep agent output semantic, evidence-based, and schema-valid.
• Express fixes as Markdown cleanup, MDPR rulebook changes, config changes,
  deterministic policy changes, or approval-bound proposals.
• Preserve the ability to build the same deck with all agent hints disabled.
• Do not mutate source Markdown unless the user explicitly asks for a cleaned
  source draft.

How It Works

Step 1: Identify the MDPR Surface

Classify the user's request before producing advice:

• semantic hints: compact intent, grouping, importance, and icon-keyword
  suggestions.
• review report: visual or narrative concerns grounded in rendered evidence,
  manifests, or validation reports.
• layout intent: high-level layout goals from a summarized template catalog,
  never concrete placeholder coordinates.
• theme candidate: reusable token and style-pack proposal for later MDPR
  approval/import gates.
• codex-ppt compatibility: feature mapping and comparison notes only; do not
  turn MDPR into a full-slide image renderer.

Step 2: Ground Every Finding

Reference available evidence such as:

• source Markdown path or heading text
• MDPR manifest summaries
• rendered preview image paths
• validation report IDs
• source notes or citation metadata
• schema names such as agent-hint.json, review-report.json, or
  mdpr-theme-candidate-v1

If evidence is missing, say what artifact is needed instead of inventing a
pass/fail result.

Step 3: Keep Hints Weak

Allowed hints:

• slide or section intent
• content grouping
• relative importance
• icon-search keywords
• accessibility or citation review notes
• generated-image candidate briefs when an icon would be too small or too
  semantically ambiguous

Disallowed hints:

• final coordinates, sizes, z-order, geometry, or object IDs
• exact colors, typography, arrows, effects, or icon asset choices
• final layout IDs or placeholder IDs
• pass/fail validation decisions not backed by MDPR validation

Step 4: Route Fixes to MDPR-Owned Changes

When repeated issues appear, recommend a deterministic follow-up surface:

• Markdown cleanup
• MDPR rulebook change
• MDPR config/profile change
• MDPR theme-pack registration
• MDPR validation improvement
• approval-bound deck-local override or style-pack candidate

Useful Local Commands

Run these only when the upstream mdpr-skill CLI is available in the current
workspace and the referenced input files exist.

node bin/mdpr-skill.js hint --source-sha256 <64hex> --out .mdpresent/proposals/agent-hint.json
node bin/mdpr-skill.js review --manifest dist/mdpresent-manifest.json --out .mdpresent/review/review-report.json
node bin/mdpr-skill.js narrative --markdown deck.md --manifest dist/mdpresent-manifest.json --out .mdpresent/review/narrative-review.json
node bin/mdpr-skill.js layout-intent --layout-catalog template-layout-catalog.json --out .mdpresent/review/layout-intent.json
node bin/mdpr-skill.js accessibility --markdown deck.md --audience "executive review" --out .mdpresent/review/accessibility-review.json

Examples

Review a Rendered MDPR Deck

1. Read the source Markdown, manifest summary, rendered image list, and any
   validation report.
2. Separate source-content problems from renderer/rulebook problems.
3. Report only evidence-backed visual concerns.
4. Recommend deterministic MDPR fixes when the same issue repeats.

Finding: Slide 4 has weak visual hierarchy between the metric and explanation.
Evidence: rendered/slide-04.png, manifest slide id `s4`, heading "Revenue Mix".
MDPR-owned fix: adjust the metric-card recipe spacing rule or choose a
deterministic layout profile with stronger numeric emphasis.

Propose a Theme Candidate

1. Treat the source design as a visual system, not content to copy.
2. Extract reusable tokens, semantic layout blueprints, decoration grammar, and
   best-fit scenarios.
3. Emit an approval-bound mdpr-theme-candidate-v1.
4. Keep mdprOwnsFinalLayout, mdprOwnsFinalThemeBinding, and
   noRawUseInAgentHints true.

{
  "schema": "mdpr-theme-candidate-v1",
  "source": "rendered reference set approved by user",
  "useCases": ["executive review", "research update"],
  "constraints": {
    "mdprOwnsFinalLayout": true,
    "mdprOwnsFinalThemeBinding": true,
    "noRawUseInAgentHints": true
  }
}

Compare with codex-ppt Style Workflows

Use codex-ppt only as a capability reference or image-only baseline. Preserve
the output-model distinction: codex-ppt style workflows may produce full-slide
images, while MDPR defaults to editable PPTX/HTML/PDF with deterministic
validation.

Comparison note: codex-ppt style output may optimize for a single rasterized
slide image. MDPR should instead preserve editable slide objects and route
visual improvements through recipes, themes, and validation policies.

Best Practices

• Do: Prefer concise semantic hints over restating the source.
• Do: Keep review notes actionable for MDPR maintainers.
• Do: Call out missing evidence before making quality claims.
• Do: Treat LLM judgment as triage only; MDPR validation remains the release
  gate.
• Avoid: Turning generated asset prompts into final asset selections.
• Avoid: Recommending raw colors, coordinates, or renderer object IDs from
  agent judgment alone.

Limitations

• This skill does not replace MDPR runtime validation.
• This skill does not generate final slide coordinates or final PPTX objects.
• This skill does not make MDPR depend on an LLM.
• This skill should not be used to copy private deck designs or proprietary
  slide content.

Common Pitfalls

• Problem: Treating mdpr-skill output as final slide layout.
  Solution: Keep hints semantic and let MDPR choose final layout, geometry,
  and renderer objects.

• Problem: Reporting visual issues without evidence.
  Solution: Link each finding to source Markdown, a manifest entry, rendered
  previews, validation reports, or another concrete artifact.

• Problem: Copying codex-ppt image-only behavior into MDPR.
  Solution: Use image-only generators as comparison baselines while
  preserving MDPR's editable PPTX/HTML/PDF output model.

Security & Safety Notes

• Review only files the user has provided or authorized.
• Do not fetch private references, credentials, or paid assets without explicit
  permission.
• Do not include secrets, API keys, or private source content in generated
  review reports or theme candidates.
• Treat all CLI commands as local workspace commands; confirm input paths exist
  before running them.

Related Skills

• @frontend-slides - Use for browser-native HTML presentation generation.
• @2slides-ppt-generator - Use for hosted API-based presentation generation.
• @office-productivity - Use for broader document, spreadsheet, and slide
  workflow coordination.