Easyslides Distill

EasySlides PPTX Distill

This Skill is the plugin-local entry point for turning a source PowerPoint into an inspectable, reusable EasySlides template. It is a staged operation:

1. Graph the native OOXML source into factual parts, relationships, objects, geometry, text, and assets.
2. Distill that evidence into identity, geometry, primitives, slots, patterns, and risks.
3. Generalize the accepted identity into semantic layout families, capacity-bounded named slots, and renderable component/symbol assets.

The canonical production surface is deliberately small and evidence-driven: three to five stable page shells. cover, content, and ending are required; toc and chapter are optional and are materialized only when the source deck provides evidence for them. Source pages are evidence, not runtime layouts. Repeated content forms are grouped into body_variants.json; repeated visual primitives become component or symbol assets. A distillation that exposes one public SVG per source slide fails this policy unless it is explicitly marked as a source-evidence or mirror candidate.

The first pass must preserve the source identity. It is not a redesign pass and it is not a one-off PPTX fill operation. A completed distillation has three deliberately separate layers: source evidence, a source-faithful review candidate, and a content-free semantic production family. A mechanical copy of the source slide roster is never the production template.

The reusable layer must not retain source-specific titles, body copy, data, photos, or logos in replaceable slots. Fixed chrome remains protected.

When to Use

Use this Skill when the request contains any of these intents:

• make this PPT/PPTX into an EasySlides template;
• extract the visual language or component assets from a PPTX;
• create a mirror or slot-guided mirror template;
• preserve the source page structure while replacing material;
• explain which parts of a source deck are fixed chrome and which are content slots;
• verify that a distilled template can accept a second, unrelated material set.

Use the regular easyslides route instead when the user wants a new story, allows page count or order to change, or only wants a one-off native PPTX fill.

Required Repository Reading

From the repository root, read these files before running the workflow:

1. SKILL.md
2. ARCHITECTURE.md
3. workflows/routing.md
4. workflows/pptx-to-easyslides-template.md
5. the repository PPTX workflow or the installed pptx skill
6. workflows/create-template.md
7. workflows/template-asset-bank.md
8. references/template-designer.md

The repository files are authoritative for commands and current output names. Do not create a second export backend or silently bypass the existing SVG, shape IR, DrawingML, and native PPTX paths.

Distillation Model

Every source deck must be described with the following machine-readable ideas. They may be represented in distilled_spec.json, template_language.md, and the generated contract sidecars:

• identity_must_preserve: palette, typography, page ratio, chrome, recurring labels, visual rhythm, cover/ending treatment, and other source identity;
• structural_primitives: rails, headers, title bars, section numerals, dividers, cards, axes, chart frames, image masks, markers, and footer rules;
• slot_candidates: title, subtitle, body, list, table, chart, image, label, caption, quote, page marker, and other material-bearing slots;
• adaptable_patterns: page roles and repeatable compositions that may accept new material;
• forbidden_drift: changes that would make a claimed source-faithful template visibly become a different design;
• template_language: concise natural-language rules for future generation;
• adaptation_strategy: classic, mirror, or slot-guided mirror behavior, including density and overflow policy;
• source_geometry_risks: authored oddities, placeholder artifacts, clipping, unsupported effects, rotation, crop, opacity, and other risks that must not be mistaken for freeform slots.

Rendered source pages are the visual truth. Prose summaries and object-level metadata are evidence, not a replacement for rendered inspection.

Workflow

1. Establish the source workspace

Use the canonical plugin command from the repository root. It creates evidence and the faithful review draft; it does not promote assets by default:

python scripts/easyslides.py distill "path\to\source.pptx" --template-id my_template

The hub delegates this route to scripts/pptx_template_distill.py; use the hub so plugin discovery and CLI help stay aligned.

When a reference workspace already exists, use the command's documented --from-existing-source form instead of importing the source twice. Keep the raw source and imported assets under:

templates/reference/template_asset_sources/<template_id>/

The source workspace should contain manifest.json, source_graph.json, distill_manifest.json, rendered or extracted assets, SVG evidence, and a contact sheet whenever the command supports them.

For a source graph without the full template build, use:

python scripts/pptx_source_graph.py "path\to\source.pptx" --output tmp\source_graph.json

The graph is factual. It intentionally leaves object classification as unknown; semantic component registration belongs to the next phase.

2. Read the evidence before generalizing

Inspect the generated contact sheet and the source render evidence. Then read:

• distilled_spec.json
• source_graph.json
• distill_manifest.json
• identity_spec.json
• layout_spec.json
• component_catalog.json
• slot_contracts.json
• asset_provenance.json
• adaptation_policy.json
• review_queue.json
• design_system_pack.json
• component_registry_fragment.json
• projection_manifest.json
• template_language.md
• adaptation_strategy.json
• source_geometry_risks.json
• editable_rebuild_plan.json

Confirm which elements are fixed chrome and which are material slots. Preserve rotated side labels, decorative words, CONTENTS or equivalent section labels, section numerals, page markers, cover geometry, and ending geometry unless the user explicitly asks to replace them.

3. Build the evidence-driven shell profile

The runtime template lives under:

templates/layouts/<template_id>/

It must contain the three required shell SVGs plus optional toc and chapter shell SVGs when the source evidence supports them, plus:

• design_spec.md
• layouts.json
• page_catalog.json
• story_structure.json
• rules.md
• body_variants.json
• source_page_roster.json
• contract sidecars generated by scripts/template_contract_pack.py

Use the existing repository command to create or refresh the draft. The command must select one source exemplar for each active shell, preserve all source pages in the reference workspace, and group content pages by visual form and density. Do not synthesize a missing TOC or chapter page, and do not add a new public page because a source slide has a different title or evidence arrangement.

The generated layouts.json must declare:

{
  "global_contract": {
    "canonical_shell_policy": "evidence_driven_three_to_five_stable_shells",
    "canonical_shell_minimum": 3,
    "canonical_shell_limit": 5,
    "required_shell_roles": ["cover", "content", "ending"],
    "optional_shell_roles": ["toc", "chapter"],
    "active_shell_roles": ["cover", "content", "ending"]
  },
  "body_variants": "body_variants.json",
  "source_page_roster": "source_page_roster.json"
}

The contract pack rejects missing required shells, more than five public pages, unsupported optional shells, or missing source roster/variant sidecars.

Each body variant must also declare how it uses reusable components. New output uses ordered component_refs objects with stable asset_id, unique instance_id, semantic role, contiguous order, required, and slot_bindings. Bare component names in the legacy components field remain readable, but new distillation output must not write them. A variant with no component dependencies writes component_refs: [] and an explicit open composition mode.

Validate this relationship independently:

python scripts/body_variant_contract.py templates/layouts/my_template --json

4. Build the source-scoped review candidate and asset evidence

First run the complete distillation promotion gate. Only when its promotion_report.json has status=pass and promotable=true may the source-scoped candidate be materialized:

python scripts/easyslides.py distill "path\to\source.pptx" --template-id my_template --promote-assets

It produces:

templates/layouts/<template_id>/                 # evidence-driven 3-5-shell runtime layer
templates/layouts/<template_id>_reusable/        # source-scoped review candidate
templates/components/source_templates/<id>_kit/  # source-scoped asset evidence
templates/reference/template_asset_sources/<id>/ # evidence and contracts

The asset kit includes component_asset_manifest.json for repeated visual components and symbol_asset_manifest.json for repeated shapes, connectors, groups, and other symbol-like primitives. Only assets with an actual renderable SVG fragment belong in component/symbol manifests. Unknown, metadata-only, or one-off objects remain in review_queue.json and are not silently promoted.

The default command is equivalent to the former no-promotion mode. The compatibility flag remains accepted:

python scripts/easyslides.py distill "path\to\source.pptx" --template-id my_template --no-promote-assets

The source-scoped candidate is never automatically registered as a main template. It must remain evidence or be generalized into the same evidence-driven shell family with layouts.json, body_variants.json, named data-slot bindings, explicit capacities, and a fail-closed template_status.json. Render material through:

python scripts/easyslides.py semantic-render templates/layouts/my_semantic_template plans/deck_plan.json --out svg_output
python scripts/easyslides.py template-gate templates/layouts/my_semantic_template --pptx exports/review.pptx --report reports/production_gate.json

Production rendering must bind exact slot names. DOM-order text replacement, source page numbers, and a fixed source slide count are forbidden routing signals.