mdpr-skill – Documents & Office skill for AI agents

mdpr-skill

Overview

Use this skill as the optional agent companion for

[MDPR](https://github.com/ch040602/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](https://github.com/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.