mdpr-skill

name

mdpr-skill

description

Use when Codex should help with MDPR presentation workflows, including semantic agent hints, icon-keyword ideas, Markdown cleanup, visual review notes, Design Components boundary checks, and Styled Deck IR design coherence audits. Triggers include MDPR, mdpresent, Markdown-to-PPTX, PPTX review, agent-hint.json, review-report.json, design component hints, raw hex/theme violations, spacing/type/radius/shadow consistency, and MDPR rulebook or config fixes.

mdpr-skill

Purpose

Use this skill as the optional Codex companion for MDPR. MDPR remains the deterministic presentation runtime; this skill provides semantic hints, review findings, and rule/config improvement guidance around MDPR outputs and intermediate representations.

Core Boundary

• When the local CLI is available, start by reading branch-local guidance with node bin/mdpr-skill.js docs bootstrap --dense and then the narrow topic for the task, such as docs boundaries --dense, docs template-fill --dense, docs media --dense, docs preflight --dense, or docs review --dense. This mirrors the agent-ready CLI-docs pattern used by Astryx while keeping MDPR-specific runtime ownership intact.
• 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 weak, 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.
• Treat media policy as a hard handoff boundary: imageUse: "no-image" means no generated-image candidates, and iconUse: "no-new-icons" means no icon keyword candidates. If conflicting candidates appear, emit preflight warnings and rely on MDPR runtime diagnostics as the authoritative accept/ignore result.
• Treat all runtime-owned fields as forbidden in hints and review artifacts: coordinates, geometry, crop/cropRect, raw colors, typography, z-order, exact icons, final image paths, renderer objects, recipe/variant/layout IDs, and copied PowerPoint object IDs.

MDPR Runtime Sync Boundary

Use the local MDPR checkout as the source of truth when this skill is being updated for a revised MDPR runtime.

• Treat MDPR schemas as mirrored contracts, not skill-owned inventions. Before claiming compatibility with a revised MDPR checkout, run the schema-sync gate against the target MDPR path.
• Record the MDPR checkout path, commit hash or version, schema-sync command, and validation timestamp in review notes or artifacts before claiming compatibility with a revised MDPR runtime. Do not treat .cache/mdpr or any specific commit as a permanent assumption.
• Treat MDPR's validation.polish manifest field as the deterministic post-AI PPT polish gate. LLM notes may explain or triage polish concerns, but MDPR owns the pass/fail result for font hierarchy, layout composition, highlight pages, cover treatment, detail QA, and theme-gallery evidence.
• Treat MDPR's job-state validate/status and generated-assets validate commands as runtime mirror checks for the same contracts that mdpr-skill can create or inspect.
• Keep mdpr-skill changes compatible with MDPR's no-agent runtime: all generated hints, edit intents, change requests, and review artifacts must be optional inputs or review evidence.

Useful local commands:

git -C <mdpr-path> rev-parse HEAD
node bin/mdpr-skill.js gate validate-schema-sync --mdpr-path <mdpr-path>
node <mdpr-path>/packages/cli/dist/index.js job-state validate <job-state.json> --json
node <mdpr-path>/packages/cli/dist/index.js generated-assets validate <generated-assets.json> --json

Substitute the actual MDPR checkout and artifact paths, and verify referenced files exist before treating results as compatibility evidence.

LLM-Assisted PPTX Review Boundary

Use LLM judgment only for semantic, narrative, evidence, and review-note assistance. It must not override MDPR validation or replace deterministic overflow, text clipping, overline, coherence, spacing, type, radius, shadow, raw-hex, editability, or renderer gates.

When an LLM review mentions these issues, ground the note in an MDPR report finding, rendered evidence path, manifest field, or explicit source excerpt. Treat the LLM note as triage or explanation only; MDPR validation remains the source of truth for pass/fail status and release gating.

When reviewing revised-MDPR outputs, explicitly check whether the build manifest records validation.polish. Missing, stale, and failing status must come from MDPR build/validate output, MDPR manifest metadata, or MDPR-reported source hash/build metadata, not from LLM judgment. If validation.polish is missing, stale, or failing according to those MDPR-owned signals, recommend an MDPR runtime or validation-policy fix rather than presenting the LLM review as a release gate substitute.

The review command mirrors a positive validation.polish.requiredFailureCount as an error finding with type MDPR_POLISH_GATE_FAILED, the failed required chapter names, and runtimeOwner: MDPR. Do not emit that finding when the required failure count is zero.

Example MDPR-owned check after the runtime has built or validated a deck:

node <mdpr-path>/packages/cli/dist/index.js validate <deck.md> --visual --coherence --json

Main Workflows

Semantic Hints

Use when a deck, Slide Element IR, Presentation IR, or ambiguous Markdown would benefit from compact semantic guidance.

• Suggest intent, grouping, importance, evidence-bound icon-search keywords as structured icon keyword candidates, key-message priority, content split, readability, template-use, and media-policy semantics.
• When a user provides or references an existing PPTX/POTX/theme and does not explicitly ask for a new visual system, default to template-fill: preserve master slides, placeholders, and the existing theme frame. Do not add new cards, surfaces, icons, images, or style systems in this mode.
• In template-fill, treat the supplied PPTX/POTX slide master as the primary visual system. Do not pass --theme-style, --theme-color, --theme-harmony, --theme-gallery, --design, theme packs, or source-neutral DESIGN imports unless the user explicitly asks to transform the visual system. For the current mdpresent CLI, the safe default is mdpresent build deck.md --to pptx --out dist --template master.pptx plus validation; adding MDPR theme flags is a duplicate-theme risk.
• In template-fill, do not synthesize slide-bottom "key message", "caution", "takeaway", or similar callout bands unless the source deck or template has an explicit placeholder for them. Keep safety notes as normal body content, presenter notes, or review notes instead of adding a new visual layer.
• In template-fill, do not override template typography or text colors. Avoid explicit font-family, font-color, raw RGB/hex, decorative fills, or custom line colors in agent-created PowerPoint bridge output; use the existing placeholder defaults, slide master, and PowerPoint theme bindings.
• If template-fill or explicit media policy sets imageUse: "no-image" or iconUse: "no-new-icons", remove conflicting generated-image or icon keyword candidates before handoff; keep only a preflight warning if the conflict is useful review evidence.
• Suggest generated-image candidates only when the source contains image evidence or the user explicitly requests a generated asset. A large or ambiguous icon is not enough by itself. Positive permission requires generated-asset workflow intent, imageSearch: "explicit-request-only", and request/instruction evidence bound to the candidate.
• Default image search to disabled. Use source-image-only guidance when source images exist, and explicit-request-only guidance when the user asks for image generation or search.
• Default icon use to no-new-icons in template-fill workflows. Icon keyword candidates are allowed only as semantic search terms when the workflow permits icons, and each candidate must carry element/source evidence rather than an exact icon name, file path, placement, or style.
• For dense or wordy content, prefer semantic contentSplitCandidates and readabilityCandidates before visual decoration.
• For Korean decks and mixed Korean/English decks, prevent awkward wrapping as source cleanup: shorten claim titles, replace long inline tool names with a shorter label plus detail in notes, split long bullets into label/detail pairs, and move secondary evidence to speaker notes or a follow-up slide. Do not prescribe exact manual line breaks, font sizes, or coordinates; MDPR owns final typography and wrapping.
• Treat paragraph marker handling as MDPR-owned runtime behavior. Current MDPR normalizes dash and bullet-like lines such as -item, •, ·, –, —, −, ㆍ, and ▪ into stable list structure while preserving --- slide breaks, pipeline arrows, negative-number prose, year-leading prose such as 2026. Roadmap, fenced code, indented code, and raw <pre> blocks. Real ordered lists keep source numbering through MDPR splitting. mdpr-skill may suggest source cleanup or readability notes around these markers, and may consume MDPR source-cleanup diagnostics when available, but must not encode marker-specific layout or rendering decisions.
• Keep hints compatible with agent-hint.json-style weak semantic input.
• Validate that hints do not encode final rendering choices.
• Prefer minimal hints over broad restatement of the source.
• Run a preflight mindset inspired by reference skills such as taste-skill: one primary key message per slide by default, no broad restatement of every source block, no contradictory template-fill media/icon candidates, and no decorative hints that MDPR can already derive deterministically. For recursive Pro/RDD loops, reject duplicate or vague TODO proposals before import unless they name concrete files, acceptance checks, validation, and new evidence.
• Ground primary key-message candidates with evidenceRefs or claimRef when available. Treat ungrounded primary emphasis as a preflight warning, not as a final slide design instruction.
• Require explicit user/request/approval evidence before using style-transform. Existing PPTX/POTX/theme workflows stay template-fill unless the user asks to change the visual system.

Useful local commands when the repo CLI is available:

node bin/mdpr-skill.js hint --source-sha256 <64hex> --out .mdpresent/proposals/agent-hint.json
node bin/mdpr-skill.js hint --selection-context .mdpresent/ppt/selection-context.json --markdown deck.md --out .mdpresent/proposals/agent-hint.json

Review Reports

Use when reviewing generated MDPR artifacts, manifests, preview images, review reports, or handoff artifacts.

• Report visual concerns with evidence paths.
• Flag template-fill risks such as master-theme evidence missing, placeholder preservation evidence missing, slide-scoped placeholder mismatches, rasterized template-fill output, images without source/request, generated assets whose provenance is not bound to the asset or slide, undeclared image search, new icon substitution, dense content, overly long copy, duplicate theme application from MDPR theme flags, and awkward Korean/English wrapping visible in rendered previews.
• Distinguish source Markdown problems from MDPR runtime/rulebook problems.
• Turn repeated visual issues into deterministic MDPR rule or config recommendations.
• Keep the output actionable for MDPR maintainers.
• Reference MDPR manifest validation.polish when discussing post-AI PPT polish quality, and keep that manifest field as the release gate.

Useful local command:

node bin/mdpr-skill.js review --manifest dist/mdpresent-manifest.json --out .mdpresent/review/review-report.json

Narrative Spine Review

Use when source Markdown needs content-level review before MDPR renders or rebuilds a deck.

• Read Markdown, optional MDPR manifest summaries, and optional source notes.
• Emit claim-title and section-flow suggestions only.
• Include provenance such as source path, manifest slide count, heading text, or source-note excerpt.
• Do not emit layout IDs, placeholder IDs, coordinates, colors, typography, renderer object IDs, or pass/fail validation decisions.

Useful local command:

node bin/mdpr-skill.js narrative --markdown deck.md --manifest dist/mdpresent-manifest.json --source-notes notes.md --out .mdpresent/review/narrative-review.json

Template Layout Intent Review

Use when a PPTX template has been summarized as a layout catalog and the deck needs semantic layout-intent hints before MDPR chooses any actual layout.

• Read layout names and placeholder roles from a layout catalog or template summary.
• Emit semantic intents such as comparison, chart-focus, evidence, or section-divider.
• Treat existing PowerPoint master slides as the theme source when the workflow is template-fill. Ask for preservation evidence; do not transform the master, copy exact placeholder IDs, or choose final layouts.
• Include provenance through the catalog path, layout label, and placeholder roles.
• Do not emit placeholder coordinates, placeholder IDs, layout IDs, layout selection decisions, colors, typography, or renderer object IDs.

Useful local command:

node bin/mdpr-skill.js layout-intent --layout-catalog template-layout-catalog.json --out .mdpresent/review/layout-intent.json

LLM-Assisted Content Review Helpers

Use when the source needs semantic or editorial review before MDPR renders, or when MDPR-rendered evidence needs a human-readable review artifact.

• speaker-notes: draft presenter notes and reviewer comments from Markdown and optional source notes.
• citations: flag missing citations, stale sources, and unsupported claims from source metadata.
• rendered-preview: consume MDPR-generated PNG/contact-sheet paths and emit visual concern notes only. Validate these artifacts with validateRenderedPreviewCritiqueBoundary when available; the notes may cite slide labels, rendered image paths, contact sheets, and MDPR finding IDs, but must not prescribe exact coordinates, fonts, colors, icons, image paths, crops, copied master/layout IDs, z-order, or renderer object IDs.
• accessibility: draft alt text, plain-language, acronym expansion, and audience-fit suggestions.
• evidence-ledger: map slide claims to source metadata and MDPR evidence IDs.
• For readability and Korean decks, recommend shorter claim titles, fewer bullets, and moving detail to notes as content suggestions only. Do not pick font sizes or exact line breaks.
• Prefer MDPR-provided source-cleanup diagnostics over re-deriving parser heuristics. Use raw Markdown marker heuristics only as a conservative fallback when no MDPR cleanup diagnostics were supplied.

These helpers may cite source paths, headings, rendered image paths, MDPR finding IDs, source IDs, and evidence IDs. They must not emit coordinates, colors, typography, z-order, geometry, renderer object IDs, or pass/fail validation decisions.

For source-neutral style references, prefer DESIGN.md frontmatter sourceNeutral: true with semantic tone, density, layout intent, decoration, and image-policy sections only. Do not include literal hex colors, exact fonts, copied PowerPoint master/layout IDs, exact icons, image paths, crops, or renderer object IDs; MDPR owns final theme binding and template preservation.

Useful local commands:

node bin/mdpr-skill.js speaker-notes --markdown deck.md --source-notes notes.md --out .mdpresent/review/speaker-notes.json
node bin/mdpr-skill.js citations --markdown deck.md --sources sources.json --as-of 2026-06-27 --out .mdpresent/review/citation-review.json
node bin/mdpr-skill.js rendered-preview --images rendered-images.json --out .mdpresent/review/rendered-preview-review.json
node bin/mdpr-skill.js accessibility --markdown deck.md --audience "executive review" --out .mdpresent/review/accessibility-review.json
node bin/mdpr-skill.js evidence-ledger --markdown deck.md --sources sources.json --mdpr-evidence mdpr-evidence.json --out .mdpresent/review/evidence-ledger.json

Change Requests And Override Proposals

Use when an agent or PowerPoint bridge flow needs to record a proposed change without applying it directly to MDPR runtime output.

• Emit mdpr-change-request-v1 proposals for agent hints, edit intents, policy suggestions, pack candidates, or user-override candidates.
• Keep change requests in proposed state until the user explicitly approves or rejects them.
• Require approval metadata before any pack or override candidate is treated as a runtime input.
• Use edit override-candidate only for bounded split preferences such as splitBy, forceSingleSlide, or maxDensity. It must not encode coordinates, colors, recipes, variants, or final layout decisions.
• Prefer ppt propose --markdown when a PowerPoint selection context is tied to Markdown; this rejects stale source hashes before creating hints or change requests.

Useful local commands:

node bin/mdpr-skill.js edit override-candidate --source-sha256 <64hex> --slide-ref slide-3 --instruction "split dense evidence into smaller slides" --split-by h3 --out .mdpresent/proposals/split.override.json
node bin/mdpr-skill.js ppt propose --selection-context .mdpresent/ppt/selection-context.json --markdown deck.md --out .mdpresent/proposals/ppt-selection.change-request.json --hints-out .mdpresent/proposals/ppt-selection.agent-hint.json
node bin/mdpr-skill.js change approve .mdpresent/proposals/ppt-selection.change-request.json --approved-by <user-or-reviewer-id> --approved-at <ISO-8601> --out .mdpresent/proposals/ppt-selection.approved.change-request.json
node bin/mdpr-skill.js change reject .mdpresent/proposals/ppt-selection.change-request.json --out .mdpresent/proposals/ppt-selection.rejected.change-request.json

Production Override And PDF Boundary

Use when a revised MDPR runtime supports production override application or PDF output paths.

• mdpr-skill may propose user-approved override candidates and review resulting artifacts.
• MDPR owns applying production overrides, PDF output, renderer behavior, validation, and pass/fail decisions.
• Do not encode final layout, coordinates, colors, recipes, variants, renderer object IDs, or PDF rendering decisions in skill output.

Generator Comparison Boundary

PptxGenJS, python-pptx, and other PPTX generators are comparison points only. Use them to describe capability vocabulary or benchmark context; do not add them as dependencies, fallback renderers, or alternate runtimes. MDPR remains the deterministic runtime.

Codex PPT Compatibility Mapping

Use when a user asks to support or match codex-ppt-skill capabilities in MDPR or mdpr-skill.

• Treat codex-ppt as an image-based workflow reference, not as an alternate MDPR renderer.
• Map each feature to an MDPR-native rail: runtime, proposal, review, orchestration, bridge, or generated visual asset rail.
• Keep coverage.unmappedFeatureCount at 0 before claiming implementation coverage.
• Preserve the output-model distinction: codex-ppt produces full-slide image PPTX; MDPR defaults to editable PPTX/HTML/PDF.
• Use the compatibility map to create MDPR runtime TODOs for missing surfaces such as theme-pack registries, generated-asset provider metadata, slide task packets, and job-state tracking.
• Use codex-ppt slide-tasks when a user needs codex-ppt-style per-slide jobs around an MDPR build. These packets are for single-slide review or repair proposals and must remain free of geometry, renderer object ids, exact colors, z-order, and final layout decisions.
• Use codex-ppt job-state after task packet export when a workflow needs long-running slide review/repair state. recorded and accepted updates require artifact/report evidence, and blocked updates require a blocker reason; never treat chat text alone as completion evidence.
• Use codex-ppt generated-assets validate for generated visual asset provider and quality metadata. The manifest records provider id, model, prompt hash, source input hashes, size, quality, background, transparency policy, and output provenance without secrets and without becoming a full-slide renderer.
• Cross-check MDPR's mirrored validators for mdpr-job-state-v1 and mdpr-generated-assets-v1 when the revised MDPR runtime is available.
• Do not copy codex-ppt's full-slide image generation as a default MDPR path.

Useful local command:

node bin/mdpr-skill.js codex-ppt compat --source-ref ningzimu/codex-ppt-skill@93c1e013965a3b42f272252030b2e1a5abede710 --out artifacts/codex-ppt-compat/codex-ppt-compat.json
node bin/mdpr-skill.js codex-ppt slide-tasks --manifest artifacts/external-markdown-visual-eval/iteration-05/build/mdpresent-manifest.json --markdown artifacts/external-markdown-visual-eval/iteration-05/corpus.md --rendered-images artifacts/codex-ppt-slide-tasks/iteration-05/rendered-images.json --out artifacts/codex-ppt-slide-tasks/iteration-05/tasks
node bin/mdpr-skill.js codex-ppt job-state init --tasks artifacts/codex-ppt-slide-tasks/iteration-05/tasks/slide-task-packets.json --manifest artifacts/external-markdown-visual-eval/iteration-05/build/mdpresent-manifest.json --out artifacts/codex-ppt-slide-tasks/iteration-05/mdpr-job-state.json
node bin/mdpr-skill.js codex-ppt generated-assets validate --manifest artifacts/codex-ppt-generated-assets/sample.generated-assets.json
node <mdpr-path>/packages/cli/dist/index.js job-state status <job-state.json> --json
node <mdpr-path>/packages/cli/dist/index.js generated-assets validate <generated-assets.json> --json

Design Components Boundary

Use when working with MDPR's built-in design component runtime or related IR.

• Read Slide Element IR or Presentation IR as the content contract.
• Suggest only semantic hints around intent, grouping, importance, and icon keywords.
• For icon requests that are too large or semantically ambiguous, suggest a generated-image candidate only when source image evidence exists or the user explicitly approves generated assets; otherwise keep the finding as semantic review guidance.
• Explain design review findings in terms of MDPR rulebook/config changes.
• Do not choose recipes, variants, coordinates, shape sizes, typography, colors, z-order, arrows, effects, or exact icon assets.
• Do not duplicate MDPR renderer behavior in the skill.

Reusable Theme And Style Pack Proposals

Use when a user wants more theme variety, a reusable visual style, a new deck theme, or a style inspired by another PPT/PDF/image while preserving MDPR as the final renderer.

• Treat the source as a visual system, not as slide content to copy.
• Extract reusable tokens, semantic layout blueprints, decoration grammar, best-fit scenarios, and MDPR registration targets.
• For theme-specific usage, include proposal-only visualLanguage, imagePolicy, and styleSystem.decorationRules guidance when available: design dials may describe variance, motion, and density, but they must stay bounded selection evidence rather than renderer instructions.
• Emit an approval-bound mdpr-theme-candidate-v1, not agent-hint.json.
• Use registration.targets to distinguish mdpr-theme-pack, mdpr-profile, mdpr-rulebook, and deck-local-style-pack follow-up work.
• Keep generated image and reference-board guidance under imagePolicy.generatedAssetBoundary = "semantic-reference-only". Use it to describe when images support a theme, how imagery should be treated, and when generated imagery is forbidden, not to request exact image assets or full-slide image rendering.
• Write decoration guidance as update rules such as downshifting dense slides, preferring rule lines over decorative blobs, or using image frames only when a source image exists.
• Keep constraints.mdprOwnsFinalLayout, constraints.mdprOwnsFinalThemeBinding, constraints.noRawUseInAgentHints, and constraints.requiresDesignLockUpdate set to true.
• Do not include source-private content, exact slide copy, copied layouts, final coordinates, exact colors in hints, renderer object IDs, or exact icon/assets choices.
• If a candidate should become built-in, route it through MDPR approval/import gates before saying it is available as an MDPR runtime theme.

Useful local command:

node bin/mdpr-skill.js design import references/custom.DESIGN.md --out .mdpresent/proposals/custom.theme-candidate.json

Design Coherence Audit

Use when auditing Design Components Styled Deck IR before rendering or release.

Check for:

• raw hex in PPT theme mode
• mixed radius family
• mixed shadow family
• mixed spacing scale
• mixed type scale
• excessive accent use
• excessive decorative effects
• dense slides using expressive effects
• repeated layout rhythm
• non-editable PPTX primary text plans

Return JSON-style findings when the caller needs CI output, or a concise human-readable fix list when working interactively. Findings may explain why an issue exists, but fixes must stay at the MDPR rulebook/config or deterministic policy level.

PowerPoint Bridge Boundary

When working with mdpr-ppt or PowerPoint selection context:

• hint rail: emit weak agent-hint.json semantics only.
• review rail: emit review-report.json findings only.
• edit-intent rail: record page or decoration change requests as safe proposals.
• approved override / pack rail: require user approval before MDPR validates and applies override or pack candidates.
• Prefer --markdown deck.md with selection-context commands so stale source hashes are rejected before hints or proposals are handed to MDPR.

Never emit final PowerPoint geometry, object IDs, z-order, exact colors, or exact icon assets from a selection context.

Validation

Prefer the repo's existing commands when the mdpr-skill checkout is available:

node bin/mdpr-skill.js gate validate-schema-sync --mdpr-path <mdpr-path>
npm run validate
npm run check:mdpr
npm run check:mdpr-pandoc

For focused artifact work, validate the exact JSON schema or report contract touched by the task before presenting findings as release-ready. For revised MDPR compatibility work, include the schema-sync gate and any mirrored MDPR validator that corresponds to the artifact under review.