diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 09b4d5624..5e8d92bae 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -630,6 +630,12 @@ "description": "Complete toolkit for developing Power Platform custom connectors with Model Context Protocol integration for Microsoft Copilot Studio", "version": "1.0.0" }, + { + "name": "pptify", + "source": "pptify", + "description": "Generate production-ready PowerPoint decks with pptify skills, source ingestion, design-context selection, coordinate-explicit slide specs, visual assets, runtime tooling, and audit-driven quality gates.", + "version": "1.0.0" + }, { "name": "project-documenter", "source": "project-documenter", diff --git a/docs/README.plugins.md b/docs/README.plugins.md index 8568d9d11..7aa4fd6f1 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -72,6 +72,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | [power-bi-development](../plugins/power-bi-development/README.md) | Comprehensive Power BI development resources including data modeling, DAX optimization, performance tuning, visualization design, security best practices, and DevOps/ALM guidance for building enterprise-grade Power BI solutions. | 8 items | power-bi, dax, data-modeling, performance, visualization, security, devops, business-intelligence | | [power-platform-architect](../plugins/power-platform-architect/README.md) | Solution Architect for the Microsoft Power Platform, turning business requirements into functioning Power Platform solution architectures. | 1 items | power-platform, power-platform-architect, power-apps, dataverse, power-automate, power-pages, power-bi | | [power-platform-mcp-connector-development](../plugins/power-platform-mcp-connector-development/README.md) | Complete toolkit for developing Power Platform custom connectors with Model Context Protocol integration for Microsoft Copilot Studio | 3 items | power-platform, mcp, copilot-studio, custom-connector, json-rpc | +| [pptify](../plugins/pptify/README.md) | Generate production-ready PowerPoint decks with pptify skills, source ingestion, design-context selection, coordinate-explicit slide specs, visual assets, runtime tooling, and audit-driven quality gates. | 6 items | pptify, powerpoint, pptx, presentations, deck-generation, slides, design-context, visual-assets, quality-gates | | [project-documenter](../plugins/project-documenter/README.md) | Generate professional project documentation with draw.io architecture diagrams and Word (.docx) output with embedded images. Automatically discovers any project's technology stack and produces Markdown, diagrams, PNG exports, and a formatted Word document. | 3 items | documentation, architecture-diagrams, drawio, word-document, docx, png-images, c4-model, project-summary, auto-discovery | | [project-planning](../plugins/project-planning/README.md) | Tools and guidance for software project planning, feature breakdown, epic management, implementation planning, and task organization for development teams. | 15 items | planning, project-management, epic, feature, implementation, task, architecture, technical-spike | | [python-mcp-development](../plugins/python-mcp-development/README.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Python using the official SDK with FastMCP. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 2 items | python, mcp, model-context-protocol, fastmcp, server-development | diff --git a/docs/README.skills.md b/docs/README.skills.md index 9d7f9c1a6..f32abdf1e 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -272,6 +272,12 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [power-platform-architect](../skills/power-platform-architect/SKILL.md)
`gh skills install github/awesome-copilot power-platform-architect` | Use this skill when the user needs to transform business requirements, use case descriptions, or meeting transcripts into a technical Power Platform solution architecture, including component selection and Mermaid.js diagrams. | None | | [power-platform-mcp-connector-suite](../skills/power-platform-mcp-connector-suite/SKILL.md)
`gh skills install github/awesome-copilot power-platform-mcp-connector-suite` | Generate complete Power Platform custom connector with MCP integration for Copilot Studio - includes schema generation, troubleshooting, and validation | None | | [powerbi-modeling](../skills/powerbi-modeling/SKILL.md)
`gh skills install github/awesome-copilot powerbi-modeling` | Power BI semantic modeling assistant for building optimized data models. Use when working with Power BI semantic models, creating measures, designing star schemas, configuring relationships, implementing RLS, or optimizing model performance. Triggers on queries about DAX calculations, table relationships, dimension/fact table design, naming conventions, model documentation, cardinality, cross-filter direction, calculation groups, and data model best practices. Always connects to the active model first using power-bi-modeling MCP tools to understand the data structure before providing guidance. | `references/MEASURES-DAX.md`
`references/PERFORMANCE.md`
`references/RELATIONSHIPS.md`
`references/RLS.md`
`references/STAR-SCHEMA.md` | +| [pptify-context-prep](../skills/pptify-context-prep/SKILL.md)
`gh skills install github/awesome-copilot pptify-context-prep` | Prepare source material and design context before authoring a pptify deck spec. Use when converting documents, building RAPTOR summaries, analyzing reference PPTX decks, or selecting and loading pptify-design profiles. | `references/design-profiles.md` | +| [pptify-deck-generation](../skills/pptify-deck-generation/SKILL.md)
`gh skills install github/awesome-copilot pptify-deck-generation` | Generate PPTX decks end to end with pptify. Use when creating PowerPoint slides from prompts, source material, reference PPTX analysis, coordinate-explicit layout trees, or pptify JSON specs. | None | +| [pptify-quality-gates](../skills/pptify-quality-gates/SKILL.md)
`gh skills install github/awesome-copilot pptify-quality-gates` | Validate and repair pptify PPTX artifacts. Use when checking deck specs, PPTX packages, audits, coordinate-explicit layout trees, collisions, text overflows, warnings, visual hierarchy, asset layering, or reference deck alignment. | `references/audit-checklist.md` | +| [pptify-slide-spec](../skills/pptify-slide-spec/SKILL.md)
`gh skills install github/awesome-copilot pptify-slide-spec` | Author or repair coordinate-explicit pptify JSON deck specs. Use when writing layout_tree groups, objects, bboxes, tables, images, lines, shapes, type scale, or collision-safe content. | None | +| [pptify-tooling](../skills/pptify-tooling/SKILL.md)
`gh skills install github/awesome-copilot pptify-tooling` | Command reference for pptify plugin tools. Use when looking up install commands, plugin script syntax, or the workspace reality check. | `references/toolkit-setup.md` | +| [pptify-visual-assets](../skills/pptify-visual-assets/SKILL.md)
`gh skills install github/awesome-copilot pptify-visual-assets` | Find, generate, and place visual assets for pptify PPTX decks. Use when adding icons, images, SVGs, raster conversions, infographics, image placeholders, or asset-backed slide objects. | None | | [pr-dashboard](../skills/pr-dashboard/SKILL.md)
`gh skills install github/awesome-copilot pr-dashboard` | Open a GitHub PR dashboard in the browser. Use when the user asks to see their pull requests, open the PR dashboard, show PRs for a date range, or check PR status. Trigger phrases include "show my PRs", "open PR dashboard", "pull request dashboard". | `assets/dashboard.html`
`scripts/lib`
`scripts/pr-dashboard-cli.mjs` | | [pr-screenshots](../skills/pr-screenshots/SKILL.md)
`gh skills install github/awesome-copilot pr-screenshots` | Embed before/after screenshots and annotated images in pull request descriptions. Covers PR description patterns, image upload for Azure DevOps and GitHub, and sizing best practices. | None | | [prd](../skills/prd/SKILL.md)
`gh skills install github/awesome-copilot prd` | Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis. | None | diff --git a/eng/update-readme.mjs b/eng/update-readme.mjs index 147a91c14..fc90f0e65 100644 --- a/eng/update-readme.mjs +++ b/eng/update-readme.mjs @@ -302,8 +302,8 @@ function generateInstructionsSection(instructionsDir) { return { file, filePath, title }; }); - // Sort by title alphabetically - instructionEntries.sort((a, b) => a.title.localeCompare(b.title)); + // Sort by title alphabetically with a fixed locale so generated output is stable across OSes. + instructionEntries.sort((a, b) => a.title.localeCompare(b.title, "en")); console.log(`Found ${instructionEntries.length} instruction files`); diff --git a/plugins/pptify/.github/plugin/plugin.json b/plugins/pptify/.github/plugin/plugin.json new file mode 100644 index 000000000..8eaf08de7 --- /dev/null +++ b/plugins/pptify/.github/plugin/plugin.json @@ -0,0 +1,29 @@ +{ + "name": "pptify", + "description": "Generate production-ready PowerPoint decks with pptify skills, source ingestion, design-context selection, coordinate-explicit slide specs, visual assets, runtime tooling, and audit-driven quality gates.", + "version": "1.0.0", + "author": { + "name": "PPTify maintainers" + }, + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "keywords": [ + "pptify", + "powerpoint", + "pptx", + "presentations", + "deck-generation", + "slides", + "design-context", + "visual-assets", + "quality-gates" + ], + "skills": [ + "./skills/pptify-context-prep/", + "./skills/pptify-deck-generation/", + "./skills/pptify-quality-gates/", + "./skills/pptify-slide-spec/", + "./skills/pptify-tooling/", + "./skills/pptify-visual-assets/" + ] +} \ No newline at end of file diff --git a/plugins/pptify/README.md b/plugins/pptify/README.md new file mode 100644 index 000000000..f01fdc5ef --- /dev/null +++ b/plugins/pptify/README.md @@ -0,0 +1,47 @@ +# PPTify Plugin + +Generate production-ready PowerPoint decks with pptify skills, source ingestion, design context, coordinate-explicit slide specs, visual assets, runtime tooling, and audit-driven quality gates. + +## Installation + +```bash +copilot plugin install pptify@awesome-copilot +``` + +## What's Included + +### Skills + +| Skill | Description | +| --- | --- | +| `pptify-context-prep` | Prepare source material and design context before authoring a pptify deck spec. | +| `pptify-deck-generation` | Generate PPTX decks end to end from prompts, source material, reference PPTX analysis, coordinate-explicit layout trees, or pptify JSON specs. | +| `pptify-quality-gates` | Validate and repair PPTX artifacts by checking specs, PPTX packages, audits, layout trees, collisions, text overflows, warnings, visual hierarchy, asset layering, and reference deck alignment. | +| `pptify-slide-spec` | Author or repair coordinate-explicit pptify JSON deck specs with layout tree groups, objects, bounding boxes, tables, images, lines, shapes, type scale, and collision-safe content. | +| `pptify-tooling` | Look up pptify install commands, plugin script syntax, and workspace reality checks. | +| `pptify-visual-assets` | Find, generate, and place icons, images, SVGs, raster conversions, infographics, image placeholders, and asset-backed slide objects. | + +## Optional Toolkit + +The bundled skills include reference material for design profile selection and manual quality checks. To run helper scripts for source prep, design context, visual assets, extraction, or audits, users can optionally install the PPTify toolkit from its source repository. The current external toolkit does not provide an importable `pptify` renderer module. + +Do not clone or install the external toolkit automatically. Install it only when the user explicitly asks to use helper scripts: + +```powershell +git clone https://github.com/kimtth/agent-pptify-kit +cd agent-pptify-kit +uv sync # base project +uv sync --extra plugins # add source ingestion and image helpers +``` + +## Usage + +Ask Copilot to create or repair a deck and mention `pptify`. The plugin guides the agent to collect required deck inputs, prepare source and reference context, select a design profile, author a coordinate-explicit JSON spec, build through the available PowerPoint path, and repair audit findings before reporting artifact paths. + +## Source + +Plugin skills are sourced from [kimtth/agent-pptify-kit](https://github.com/kimtth/agent-pptify-kit) for submission to [Awesome Copilot](https://github.com/github/awesome-copilot). + +## License + +MIT \ No newline at end of file diff --git a/skills/pptify-context-prep/SKILL.md b/skills/pptify-context-prep/SKILL.md new file mode 100644 index 000000000..0b8aa65e6 --- /dev/null +++ b/skills/pptify-context-prep/SKILL.md @@ -0,0 +1,76 @@ +--- +name: pptify-context-prep +description: "Prepare source material and design context before authoring a pptify deck spec. Use when converting documents, building RAPTOR summaries, analyzing reference PPTX decks, or selecting and loading pptify-design profiles." +--- + +# PPTify Context Prep + +> **Prerequisite:** Before running any plugin script in this skill, run the workspace detection check in `pptify-tooling`. If `pptify-plugin/` is absent, follow the install or graceful-degradation steps there before continuing. + +Use this skill before writing a deck spec. It covers two parallel preparation tracks: **source context** (documents, research, reference PPTX) and **design context** (predefined style profiles from `pptify-design`). + +## Source Documents + +- Convert long source documents to markdown before planning slides: `uv run python pptify-plugin/documents/document_to_markdown.py --source source.pdf --output-path source.md`. +- Build a structured summary tree when a source is long or multi-topic: `uv run python pptify-plugin/documents/document_to_raptor_tree.py --markdown-path source.md --output-path source-summary.json --title "Source" --pretty`. +- For URL-based, topic-plus-research, source-backed, or multi-source decks, combine converted/downloaded source markdown into a corpus and run the RAPTOR summary before slide planning, even when individual sources are short. +- Record the corpus path, summary path, source count, and source URLs in `summary.source_enrichment` so enrichment evidence survives review. +- Use the summary tree to identify audience, thesis, slide sequence, evidence, risks, and decision points. +- Do not paste entire long documents into the deck spec; summarize into concise slide messages and cite sources in footers when needed. + +## Reference PPTX + +- Use the importable helpers in `pptify-plugin/extraction` or package inspection to inspect production complexity, slide text, style, brand, template, and layout-rhythm facts. The `python -m pptify --analyze-pptx` command is unavailable unless the core renderer package is restored. +- Use the extracted facts as agent context when the new deck should follow a source deck's language, slide count, topic sequence, executive tone, colors, fonts, template conventions, and layout rhythm. +- When authoring the new spec, translate `brands.primary_color`, `brands.accent_colors`, `brands.fonts`, `template.slide_size`, `template.layout_usage`, and `layout.slides[*].dominant_flow` into explicit `layout_tree` primitives, colors, typography, spacing, and coordinates. +- Use extraction helpers when the goal is reconstructing or preserving an existing production deck rather than authoring a new editable deck. +- For new editable decks, treat reference layout rhythm as prompt context; generated coordinates must be authored directly by the agent in `layout_tree`. +- Never copy or mutate a referenced PPTX as the generation strategy. Use analysis as context and build a new PPTX artifact. + +## Design Profile Selection + +Load [`references/design-profiles.md`](references/design-profiles.md) for the full profile catalog with IDs, `best_for` guidance, key style signals, and license information. Use it whether or not the toolkit is installed — when the toolkit is present, it cross-checks the catalog with the live output of `design_context_catalog.py`. + +Use profiles from `pptify-design/sources.json`; do not invent a new design template when the user asks for predefined templates. + +- Use `fluent-ui-design-tokens` as the default for new decks, including Microsoft, M365, Teams, Power Platform, enterprise-aligned, general modern, stylish, product, app, pitch, or unspecified visual style requests. +- Use `primer-primitives` for GitHub-style product, developer, or token-driven engineering decks. +- Use `corazzon-pptx-design-styles` when a broader modern style catalog or multiple visual direction options are explicitly useful. Pick one style from the catalog and lock its palette, typography, spacing, and signature element before layout planning. +- Use `likaku-mck-ppt-design-skill` for consulting, strategy, governance, or operations decks that need action-title discipline and structured native PPTX layouts. +- Use `awesome-copilot-design-agents` when the agent prompt itself needs design review, UX discovery, visual hierarchy, or accessibility framing. +- Keep source attribution and license metadata attached to the context used. +- If no catalog profile fits, use reference PPTX analysis, search for another public source, or ask the user for a source template. +- Record selected profile IDs, source URLs, and style lock details in `summary.design_context` before building the PPTX. + +Load profiles: + +```powershell +uv run python pptify-plugin/design/design_context_catalog.py --list --pretty +uv run python pptify-plugin/design/design_context_catalog.py --profile fluent-ui-design-tokens --include-context --pretty +uv run python pptify-plugin/design/design_context_catalog.py --profile primer-primitives --include-context --pretty +uv run python pptify-plugin/design/design_context_catalog.py --profile corazzon-pptx-design-styles --include-context --pretty +``` + +## Applying Context to Spec Authoring + +1. Put the selected profile payload into the agent context before writing `deck-spec.json`. +2. Translate source signals into explicit `layout_tree` objects, colors, fills, lines, typography, spacing, bboxes, and z-order. +3. Keep meaningful slide content as `classification: "content"` objects and decorative/background elements as `classification: "layout_design"` objects. +4. Use source CSS or reference deck rhythm only as design evidence; final coordinates must be authored directly in inches. +5. Add at least one style-derived visible design element to every normal content slide: accent band, rule, card shell, grid cell, diagram primitive, shape motif, image treatment, or pattern. A plain title-plus-bullets slide fails the design gate. +6. Do not treat `pptify-design` profiles as content source material; they are design context only. + +## Source-to-Deck Planning + +- Convert source material into one message per slide before authoring visual structure. +- Treat charts and dashboard-style slides as source-evidence-driven exhibits; do not create generic metric or dashboard slides when the source corpus does not provide relevant data. +- Preserve important terminology, product names, metrics, dates, and user-provided wording. +- Reduce dense narrative into executive slide titles plus short sections. +- Track open assumptions in speaker notes or audit-facing summary fields instead of overcrowding slides. + +## Restrictions + +- Do not copy external fonts, icon packs, photos, or binary assets unless their license and source are explicitly added. +- Do not claim the output is a Primer, Fluent UI, or Awesome Copilot artifact; these are context sources for a new `pptify` deck. +- Do not let source CSS override pptify quality gates: built decks still need zero content collisions and zero text overflows. +- Do not accept default PowerPoint theme colors, Calibri-only text boxes, plain white backgrounds, or placeholder-style bullet layouts as a finished design. diff --git a/skills/pptify-context-prep/references/design-profiles.md b/skills/pptify-context-prep/references/design-profiles.md new file mode 100644 index 000000000..ed863c6e1 --- /dev/null +++ b/skills/pptify-context-prep/references/design-profiles.md @@ -0,0 +1,174 @@ +# PPTify Design Profile Catalog + +Source: `pptify-design/sources.json` — updated 2026-05-20. +Load this file when `pptify-plugin/design/design_context_catalog.py` is unavailable. + +## Quick-Select Guide + +| Profile ID | Best for | +|---|---| +| `fluent-ui-design-tokens` | Microsoft, M365, Teams, Power Platform, enterprise — **default for new decks** | +| `primer-primitives` | GitHub-style, developer products, token-driven UI reviews, engineering docs | +| `corazzon-pptx-design-styles` | 30 modern style catalog; use when visual variety or multiple direction options are needed | +| `likaku-mck-ppt-design-skill` | Consulting, strategy, governance, operations — strict action-title discipline | +| `sunbigfly-ppt-agent-skills` | Source-backed, stage-gated delivery pipelines with human approval at each phase | +| `awesome-copilot-design-agents` | Prompting agent for design review, UX discovery, visual hierarchy reasoning | +| `nexu-io-open-design` | Direction-picker workflows with explicit style-lock and artifact-lint gates | +| `alchaincyf-huashu-design` | Brand-constrained enterprise decks requiring exact color/type fidelity | +| `pptwork-oh-my-slides` | HTML-prototype-first workflows; raster fidelity + constrained PPTX editability as separate deliverables | +| `erickittelson-slidemason` | Cautionary reference: JSX primitive composition — auto-layout incompatibility | +| `gabberflast-academic-pptx-skill` | High-stakes governance, board, or investor presentations needing narrative rigour | + +## Profiles + +### `fluent-ui-design-tokens` +**Name:** Fluent UI Design Token Guidance +**Kind:** design-system-context +**License:** MIT — Copyright (c) Microsoft Corporation +**Source:** [microsoft/fluentui](https://github.com/microsoft/fluentui/blob/master/docs/architecture/design-tokens.md) +**Token categories:** color, spacing, border radius, font, line height, stroke, shadow, duration, easing +**Themes:** webLightTheme, webDarkTheme, teamsLightTheme, teamsDarkTheme, teamsHighContrastTheme +**Agent rule:** Use design tokens instead of hardcoded colors, spacing, or typography values. +**Best for:** Microsoft-aligned decks, Teams, M365, Power Platform governance, enterprise product reviews + +--- + +### `primer-primitives` +**Name:** Primer Primitives Design Tokens +**Kind:** design-system-context +**License:** MIT — Copyright (c) 2018 GitHub Inc. +**Source:** [primer/primitives](https://github.com/primer/primitives) +**Token categories:** color, spacing, typography, motion, z-index +**Spacing scale:** xxs, xs, sm, md, lg, xl +**Typography roles:** display, title, subtitle, body, caption, codeBlock, codeInline +**Color examples:** `#ffffff`, `#1f2328`, `#F6F8FA`, `#0969da`, `#1a7f37`, `#cf222e` +**Best for:** GitHub-style decks, developer products, token-driven UI reviews, engineering documentation + +--- + +### `corazzon-pptx-design-styles` +**Name:** corazzon/pptx-design-styles — 30 Modern PPTX Style Templates +**Kind:** pptx-style-template-context +**License:** MIT — Copyright TodayCode / corazzon contributors +**Source:** [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles) +**30 styles:** Glassmorphism, Neo-Brutalism, Bento Grid, Dark Academia, Gradient Mesh, Claymorphism, Swiss International, Aurora Neon Glow, Retro Y2K, Nordic Minimalism, Typographic Bold, Duotone Color Split, Monochrome Minimal, Cyberpunk Outline, Editorial Magazine, Pastel Soft UI, Dark Neon Miami, Hand-crafted Organic, Isometric 3D Flat, Vaporwave, Art Deco Luxe, Brutalist Newspaper, Stained Glass Mosaic, Liquid Blob Morphing, Memphis Pop Pattern, Dark Forest Nature, Architectural Blueprint, Maximalist Collage, SciFi Holographic Data, Risograph Print +**Style families:** modern-ui, editorial, retro, technical, luxury, organic, experimental +**Source inputs per style:** hex colors, font pairings, layout rules, signature elements, avoid lists +**Agent rule:** Pick one style, lock its palette and typography, then translate visual effects into explicit pptify `layout_tree` primitives or documented raster accents. Do not mix styles accidentally. +**Best for:** Choosing a predefined modern style from a broad catalog; generating multiple visual direction options before deck production + +--- + +### `likaku-mck-ppt-design-skill` +**Name:** likaku/Mck-ppt-design-skill — McKinsey-Style Native PPTX Layout Runtime +**Kind:** pptx-pattern-context +**License:** MIT — Copyright likaku contributors +**Source:** [likaku/Mck-ppt-design-skill](https://github.com/likaku/Mck-ppt-design-skill) +**Pattern count:** ~70 consulting-style layout patterns +**Pattern families:** structure-navigation, data-metrics, frameworks-matrices, content-narrative +**Action title discipline:** required on every content slide +**Geometry norms (inches):** kicker_y=0.48, title_y=0.72, rule_y=1.12, content_top_y=1.30 +**Agent rule:** Use the source taxonomy as design inspiration only. Author exact `layout_tree` coordinates, sizes, and primitives. Action titles on every content slide. +**Best for:** Consulting decks for strategy, governance, or operations reviews; strict action-title discipline + +--- + +### `sunbigfly-ppt-agent-skills` +**Name:** sunbigfly/ppt-agent-skills — Staged Deck Generation Pipeline +**Kind:** agent-pipeline-context +**License:** MIT — Copyright sunbigfly contributors +**Source:** [sunbigfly/ppt-agent-skills](https://github.com/sunbigfly/ppt-agent-skills) +**Pipeline stages:** interview → source-compression → outline → style-lock → slide-plan → visual-qa → dual-export +**Stage outputs:** structured brief JSON, compressed source ≤800 words, outline JSON, style_lock JSON, complete spec.json, qa-report, pptx + raster +**Agent rule:** Never skip the interview. Source compression before outline. Style lock is stage-gated. Per-slide plans are full specs. Action titles mandatory. +**Best for:** Source-grounded decks; high-stakes presentations; workflows requiring explicit human approval at each phase + +--- + +### `awesome-copilot-design-agents` +**Name:** Awesome Copilot Design Agent and Prompt Context +**Kind:** agent-prompt-context +**License:** MIT — Copyright GitHub, Inc. +**Source:** [github/awesome-copilot](https://github.com/github/awesome-copilot) +**Key files:** `agents/gem-designer.agent.md`, `agents/se-ux-ui-designer.agent.md`, `skills/penpot-uiux-design/SKILL.md`, `skills/prompt-optimizer/SKILL.md` +**Prompt focus:** existing design systems, visual hierarchy, UX discovery, accessibility, slides and reports design intentionality +**Best for:** Prompting an LLM to reason about deck design; UX discovery before deck planning; design review checklists; visual hierarchy guidance + +--- + +### `nexu-io-open-design` +**Name:** nexu-io/open-design — Claude Design Style +**Kind:** agent-skill-context +**License:** MIT — Copyright nexu-io contributors +**Source:** [nexu-io/open-design](https://github.com/nexu-io/open-design) +**Key patterns:** direction-picker, sandbox-preview, artifact-lint, design-critique +**Stage gates:** direction selection → style lock → preview approval → artifact lint → critique gate +**Agent rule:** Never start layout without a locked direction. Run artifact lint after every build. Preview before full deck. +**Best for:** Reasoning about deck design direction before committing; parallel design options for selection; lint and critique gates on generated decks + +--- + +### `alchaincyf-huashu-design` +**Name:** alchaincyf/huashu-design — HTML-Native Brand Design Pipeline +**Kind:** agent-skill-context +**License:** MIT — Copyright alchaincyf contributors +**Source:** [alchaincyf/huashu-design](https://github.com/alchaincyf/huashu-design) +**Key patterns:** brand-asset-protocol, visual-directions, html-to-editable-pptx, playwright-check +**Brand lock fields:** primary_palette, neutral_palette, typeface_display, typeface_body, tone +**Agent rule:** Brand lock is non-negotiable. Parallel directions before deck plan. Every text frame must be individually editable. +**Best for:** Brand-constrained enterprise decks requiring exact color/type fidelity; multi-direction style exploration before committing + +--- + +### `pptwork-oh-my-slides` +**Name:** PPTWork/oh-my-slides — HTML-as-Source PPTX Build Artifact Pipeline +**Kind:** pptx-export-context +**License:** MIT — Copyright PPTWork contributors +**Source:** [PPTWork/oh-my-slides](https://github.com/PPTWork/oh-my-slides) +**Key patterns:** html-source, preset-picker, mini-preview, raster-export, constrained-editable +**Export model:** HTML (design source) → raster export (fidelity) + constrained PPTX (editability) +**Forbidden in editable PPTX:** background images, raster embeds of slide content, CSS transform rotate, SVG filter effects +**Agent rule:** Never promise both pixel fidelity and full editability from the same export path. Raster embeds in editable PPTX are a quality failure. +**Best for:** HTML-prototype-first workflows; design fidelity and PowerPoint editability as separate deliverables; Playwright-in-the-loop generation + +--- + +### `erickittelson-slidemason` +**Name:** erickittelson/slidemason — JSX Primitive Composition (Cautionary Reference) +**Kind:** agent-skill-context +**License:** MIT — Copyright erickittelson contributors +**Source:** [erickittelson/slidemason](https://github.com/erickittelson/slidemason) +**Key patterns:** jsx-primitives, jsx-bento, bespoke-slide, primitive-composition +**Primitive map:** Card→`_shape(round_rect)`, Text→`_text()`, Line→`_line()`, Image→`_image()`, Oval→`_shape(oval)` +**Editability failure modes:** nested flex containers, auto-sized text frames, SVG filter effects, rotated text boxes, image fills on shapes +**Agent rule:** Auto-layout is the enemy of editability. All coordinates are in inches. Bespoke layout is a last resort. +**Best for:** Understanding limits of programmatic slide composition; cautionary reference for auto-layout / PPTX editability incompatibility + +--- + +### `gabberflast-academic-pptx-skill` +**Name:** Gabberflast/academic-pptx-skill — Narrative Discipline Gates +**Kind:** agent-skill-context +**License:** MIT — Copyright Gabberflast contributors +**Source:** [Gabberflast/academic-pptx-skill](https://github.com/Gabberflast/academic-pptx-skill) +**Key patterns:** action-title, ghost-deck-test, one-exhibit-discipline, evidence-slide, citation-slide +**Narrative gates:** action title on every content slide; ghost deck test passes; one exhibit per slide; last slide names a specific next action; every quantitative claim has a source +**Agent rule:** Run ghost deck test before building slides. Rewrite descriptive titles as action titles. One exhibit per slide is a hard rule. The closing slide must name a decision, deadline, and owner. +**Best for:** High-stakes governance or board presentations requiring narrative rigour; decks reviewed by investors, regulators, or boards + +--- + +## Using This Catalog + +**When the toolkit is present**, load full style context with: + +```powershell +uv run python pptify-plugin/design/design_context_catalog.py --profile --include-context --pretty +``` + +**When the toolkit is absent**, use the entries above to: + +1. Select the profile ID that best matches the user's audience, topic, and delivery context. +2. Lock the palette, typography, and signature element conventions described in the profile's `source_signals`. +3. Record the selected profile ID, source URL, and license in `summary.design_context` before building the deck spec. +4. Translate the style signals directly into explicit `layout_tree` primitives — colors, fills, rules, card shells, accent bands, and bboxes. diff --git a/skills/pptify-deck-generation/SKILL.md b/skills/pptify-deck-generation/SKILL.md new file mode 100644 index 000000000..c222fad16 --- /dev/null +++ b/skills/pptify-deck-generation/SKILL.md @@ -0,0 +1,104 @@ +--- +name: pptify-deck-generation +description: "Generate PPTX decks end to end with pptify. Use when creating PowerPoint slides from prompts, source material, reference PPTX analysis, coordinate-explicit layout trees, or pptify JSON specs." +--- + +# PPTify Deck Generation + +Use this skill when a Copilot or coding agent needs to generate PPTX slides with `pptify`. + +## Intake + +1. Before creating workflow artifacts, collect any missing required inputs with the VS Code prompt input dialog (`vscode_askQuestions` or equivalent). Batch concise questions, offer sensible defaults for optional fields, and continue after the user answers. +2. Identify the audience, decision, business framework, core narrative, required language, target slide count, source material, reference PPTX, branding constraints, output artifact paths, and delivery deadline. +3. If the user gives only a topic, create a reasonable executive narrative and mark assumptions in the generated spec summary. When the request asks for web research, source-backed content, or data enrichment, persist source material and run the source pipeline before authoring slides. +4. If the user provides source files, URLs, research material, or a reference deck, prepare them before generating the slide spec. +5. If the user requests text-to-image or generated images with OpenAI, Azure OpenAI, or Azure AI Foundry, create `.env` from `.env.template` when needed and have the user fill provider settings or secrets directly in `.env`. Do not ask for API keys or tokens in chat or in the dialog. +6. Do not claim an infographic is model-generated until provider, model or deployment, auth mode, prompt, output path, and attempt status are known. The image helper has no local fallback provider. + +## Required Input Dialog + +- Use the prompt input dialog for missing required workflow values such as audience, slide count, source material, design/reference context, output filenames, and artifact destinations. +- Use `.env` for missing text-to-image provider values such as provider, model or deployment, endpoint, auth method, timeout, and required API keys. Collect only non-secret prompt, image size, and output path values through the dialog when needed. +- Treat API keys, tokens, connection strings, and passphrases as secrets. Do not collect them through chat or the dialog; the user must enter them directly in `.env` or authenticate with a managed tool such as `az login`. + +## Prepare Sources and References + +Follow `pptify-context-prep` to convert source documents, build RAPTOR summaries, analyze reference PPTX files, and select and load a design profile. Record results in `summary.source_enrichment` and `summary.design_context` before authoring `deck-spec.json`. + +## Confirm Business Framework + +The business framework is defined by the user, not by the assistant. If the user has already specified a framework, use it directly. If no framework has been specified, present the available options and ask which one to use before planning the deck. Include `custom` when the user wants to provide their own structure, naming convention, or slide sequence. Do not auto-select a framework on the user's behalf. + +| Framework | Best for | +|---|---| +| `mckinsey` | Executive proposals, consulting deliverables, strategic recommendations | +| `scqa` | Problem-solving presentations, situation analysis, incident reports | +| `pyramid` | Complex arguments requiring strong logical structure | +| `mece` | Issue decomposition, audits, multi-workstream analysis | +| `action-title` | Executive communications where every slide must drive action | +| `assertion-evidence` | Technical or academic presentations, research findings | +| `exec-summary-first` | C-suite briefings, board decks, press releases | +| `custom` | User-defined structures, organization-specific playbooks, hybrid narrative patterns | + +## Framework Story Templates + +Use the selected framework as the starting narrative spine, then adapt slide count and evidence density to the user's source material. + +| Framework | Default slide spine | +|---|---| +| `mckinsey` | Title → executive summary → situation → complication → key question → recommendation → 2-3 evidence slides → options → roadmap → appendix | +| `scqa` | Title → situation → complication → question → answer → evidence → implementation plan → summary | +| `pyramid` | Title → main answer → argument 1 → argument 2 → argument 3 → evidence → summary | +| `mece` | Title → issue tree → workstream slides → synthesis | +| `action-title` | Title → action summary → action-titled content slides → next steps | +| `assertion-evidence` | Title → overview assertion → assertion/evidence slides → conclusion | +| `exec-summary-first` | Title → full answer on slide 2 → supporting detail → appendix | +| `custom` | Ask for framework name, objective, slide sequence, title rules, layout preferences, and evidence expectations before planning | + +Record the resolved framework in `summary.business_framework`, including source, slide sequence, title rules, and approved assumptions. + +## Storytelling Principles + +- Apply the Pyramid Principle: put the conclusion first, make each slide title state the slide's conclusion or assertion, and avoid questions or vague labels. +- Make every `keyMessage` answer "So what?" for the audience. +- Keep topics MECE: mutually exclusive and collectively exhaustive. +- Write specific slide titles, such as "Azure AI cuts development costs by 40%" or "3 implementation patterns enable rapid onboarding," instead of generic labels like "About Azure AI" or "Implementation Patterns Overview." +- Include concrete data, numbers, dates, owners, sources, or quantified directional signals in bullets when the source material supports them. +- Keep speaker notes useful: two to three sentences, never empty and never just a dash. +- Avoid generic statements; every bullet should be specific, defensible, and tied to the selected framework's role in the story. + +## Plan the Deck + +1. Produce one clear message per slide before choosing visuals. +2. Map the selected business framework to the deck outline and document the selected framework in `summary.business_framework`. +3. Choose a slide form for each message: title, agenda, comparison, process, metrics, roadmap, risk, architecture, evidence, decision, infographic, dashboard-style overview, or appendix. +4. Use charts and dashboard-style slides only when source evidence contains relevant quantitative or structured data. Represent them as explicit tables, labels, shapes, lines, or image-backed exhibits. +5. Keep each slide to three to five major content groups. +6. Preserve user-provided terminology, names, metrics, dates, and executive tone. +7. Decide the exact coordinates, dimensions, z-order, colors, fonts, and font sizes before building. Current plugin scripts will not generate layout or resize text for you. +8. Record the selected profile ID, source URL, style lock, palette, typography, spacing rhythm, and signature elements in `summary.design_context` and translate source signals into explicit primitives in `layout_tree`. +9. Every normal content slide should include at least one style-derived design element such as an accent band, card shell, grid, divider, shape motif, image treatment, or pattern. Plain white title-plus-bullet slides are not production-ready. + +## Build and Validate + +1. Current workspace reality check: no importable `pptify/` package or `python -m pptify` CLI is present in this snapshot. Restore the core renderer package before relying on renderer-specific commands. +2. Every generated slide must include `layout_tree`. Follow `pptify-slide-spec` for the full coordinate contract. +3. If the core renderer is restored, render the authored spec with `uv run python -m pptify deck-spec.json --out deck.pptx --audit deck-audit.json`. Otherwise create the PPTX through direct PowerPoint generation and keep plugin evidence/audits alongside it. Direct `python-pptx` generation must still implement the locked design context; default placeholders and bullet-only slides are failures. +4. For reference-guided generation, include analysis/source summaries and the extracted `styles`, `brands`, `template`, and `layout` context before writing `deck-spec.json`. +5. Include the selected `pptify-design` context before writing `deck-spec.json` for every new deck unless a user-provided brand guide or reference PPTX is the primary style source. +6. Inspect the audit for content collisions, text overflows, and warnings. +7. Verify workflow gates: source-backed decks include source corpus and RAPTOR summary metadata; requested generated images include a provider attempt manifest; successful generated raster infographics include a final hidden SVG appendix slide; generated decks include `summary.design_context` and style-derived visual elements. +8. Rebuild after each repair until generated slides have zero collisions, zero overflows, and no default-theme design failures, or clearly report the residual issue. + +```powershell +# Preferred renderer when available; otherwise use direct PowerPoint generation and keep this audit step. +uv run python -m pptify deck-spec.json --out deck.pptx --audit deck-audit.json +uv run python pptify-plugin/audit/audit.py deck-spec.json --json +``` + +## Response Contract + +1. When asked to author the deck spec, write strict JSON with no markdown fences unless the user explicitly asks for prose. +2. When required workflow or artifact inputs are missing, prompt for them with the input dialog before authoring or building. +3. When acting as a coding agent in the workspace, create or update the spec or generation script, produce the PPTX with the available PowerPoint path, validate the audit and PPTX package, and report the generated artifact paths. diff --git a/skills/pptify-quality-gates/SKILL.md b/skills/pptify-quality-gates/SKILL.md new file mode 100644 index 000000000..9be914ee1 --- /dev/null +++ b/skills/pptify-quality-gates/SKILL.md @@ -0,0 +1,62 @@ +--- +name: pptify-quality-gates +description: "Validate and repair pptify PPTX artifacts. Use when checking deck specs, PPTX packages, audits, coordinate-explicit layout trees, collisions, text overflows, warnings, visual hierarchy, asset layering, or reference deck alignment." +--- + +# PPTify Quality Gates + +> **Prerequisite:** Before running `audit.py`, run the workspace detection check in `pptify-tooling`. If `pptify-plugin/` is absent, load [`references/audit-checklist.md`](references/audit-checklist.md) and apply the manual checklist — it covers all 8 audit dimensions without requiring the script. + +Use this skill before considering a generated PPTX complete. + +## Workflow + +1. Confirm required artifacts exist or collect missing paths before validating. +2. Run the workspace detection check from `pptify-tooling`. +3. Run `audit.py` when available; otherwise load `references/audit-checklist.md` and apply the manual checks. +4. Repair the spec or generation script, rebuild the PPTX, and rerun the audit. +5. Stop only when collisions, overflows, small fonts, package checks, and design-context checks are clean or clearly reported. + +## Required Artifacts + +- If required artifact paths or names are missing, collect them with the VS Code prompt input dialog (`vscode_askQuestions` or equivalent) before building, validating, or repairing. +- Keep the generated spec, PPTX, and audit together: `deck-spec.json`, `deck.pptx`, and `deck-audit.json`. +- Keep the agent-authored JSON spec or generation script on disk so it can be reviewed, repaired, and rebuilt. +- Save analysis or extraction manifests when reference PPTX context was used. +- Save the selected `pptify-design` profile IDs, source URLs, license IDs, and style lock details in `summary.design_context` for every newly generated deck unless a user-provided brand guide or reference PPTX is the primary style source. + +## Audit Checks + +- A production-ready generated deck should have zero content collisions. +- A production-ready generated deck should have zero text overflows. +- A production-ready generated deck should have zero `classification: "content"` objects with `style.font_size` below 9 pt. Run `uv run python pptify-plugin/audit/audit.py deck-spec.json --json` and check `total_small_fonts`. +- Review audit `warnings` for each slide even when collisions and overflows are zero. +- Check that slide count, language, tone, and major topic sequence match the user request or reference context. +- Check that the selected design context profile matches the user request and that source-backed context was translated into explicit primitives, colors, spacing, typography, and bboxes. +- Fail generated decks that have no `summary.design_context`, plain white backgrounds throughout, Calibri-only text, default theme colors, or placeholder-like title-plus-bullet layouts unless the user explicitly requested that style. +- Confirm every normal content slide contains at least one style-derived visual element such as an accent band, card shell, grid, divider, shape motif, image treatment, or pattern. +- When a deck includes hidden appendix slides, inspect `ppt/presentation.xml` for `p:sldId show="0"` and confirm the hidden slides are last unless the user asked otherwise. +- When a generated infographic has both raster and SVG assets, verify the visible slide uses the raster for text fidelity and the SVG appears only in the hidden appendix slide. +- For important deliverables, open the generated PPTX with `python-pptx` or inspect the zip package to confirm slide count, relationships, media, and hidden-slide metadata. + +## Repair Loop + +- If content collides, move or resize objects, reduce content density, split slides, or change the coordinate plan. +- If text overflows, shorten bullets, split sections, enlarge target bboxes, or split slides. **Lower explicit `font_size` only as a last resort, and never below 9 pt for content objects.** +- If visual hierarchy is weak, edit explicit colors, type scale, dividers, metric cards, callouts, or whitespace in the layout tree. +- If the deck looks like default `python-pptx`, load a `pptify-design` profile, add `summary.design_context`, choose a style lock, and rebuild with explicit background/accent/card/rule primitives. +- If an asset covers text, lower its `z_index`, move it to `layout_design`, resize it, or change its bbox. +- If coordinates are cramped or inconsistent, repair the agent-authored bboxes directly; current plugin scripts will not run a browser or auto-layout pass. +- Rebuild after each spec repair and inspect the new audit or package checks. + +## Verification Commands + +- Current workspace reality check: no importable `pptify/` package or `python -m pptify` CLI is present in this snapshot. Use the standalone audit plugin and package inspection unless the core renderer package is restored. +- Audit a layout-tree spec and run the full test suite: + +```powershell +uv run python pptify-plugin/audit/audit.py deck-spec.json --json +uv run python -m unittest discover -s tests -v +``` + +- If the core renderer package is restored, add renderer/CLI smoke tests before considering rendered deck behavior covered. diff --git a/skills/pptify-quality-gates/references/audit-checklist.md b/skills/pptify-quality-gates/references/audit-checklist.md new file mode 100644 index 000000000..4afc618bd --- /dev/null +++ b/skills/pptify-quality-gates/references/audit-checklist.md @@ -0,0 +1,88 @@ +# PPTify Manual Audit Checklist + +Load this file when `pptify-plugin/audit/audit.py` is unavailable. +Apply every check manually to `deck-spec.json` before considering a deck production-ready. + +## 1. Content Collisions + +For every slide, inspect all `layout_tree` objects. Two `classification: "content"` objects collide when their bounding boxes overlap: + +``` +A.x < B.x + B.w AND B.x < A.x + A.w +A.y < B.y + B.h AND B.y < A.y + A.h +``` + +- **Pass:** zero overlapping content objects per slide. +- **Fail:** any overlap → move objects, resize bboxes, reduce content density, or split the slide. + +## 2. Text Overflows + +For each text object estimate whether its text fits within its bbox. + +Rough capacity: +- Characters per line ≈ `(bbox.w × 10) / font_size` +- Lines available ≈ `(bbox.h × 72) / (font_size × 1.2)` + _(bbox in inches, font_size in pt)_ + +- **Pass:** estimated text volume ≤ available capacity. +- **Fail:** likely overflow → shorten bullets, enlarge bbox, or split slide. + **Never set `font_size` below 9 pt for `classification: "content"` objects.** + +## 3. Font Size Minimums + +Scan every object with `classification: "content"`. Check `style.font_size`. + +- **Pass:** all content objects ≥ 9 pt. +- **Fail:** any content object < 9 pt → increase font size and split content if needed. + +## 4. Design Context Presence + +Inspect `summary.design_context` in the spec root. + +- **Pass:** field present and contains `profile_id`, source URL, and license ID. +- **Fail — any of the following:** + - `summary.design_context` absent → load a `pptify-design` profile (see `references/design-profiles.md` in `pptify-context-prep`) and rebuild. + - Plain white backgrounds throughout with no accent elements. + - Calibri-only text with default theme colors across all slides. + - All slides are title-plus-bullets only (no cards, shapes, rules, or image treatments). + +## 5. Visual Design Per Slide + +For each normal content slide (exclude section headers and hidden appendix slides): + +- **Pass:** at least one style-derived visual element present — accent band, card shell, grid cell, rule/divider, shape motif, image treatment, or background pattern. +- **Fail:** slide is plain white with only text objects → add a design element derived from the selected profile's `source_signals`. + +## 6. Narrative and Count + +- Slide count is within ±2 of the user's requested count. +- Topic sequence matches the requested business framework (McKinsey, SCQA, pyramid, etc.) or the user's stated structure. +- If `likaku-mck-ppt-design-skill` or `gabberflast-academic-pptx-skill` context was used: every content slide has an **action title** (not a descriptive label). Run the ghost-deck test: read only slide titles — they must tell the full story on their own. + +## 7. Hidden Slides + +If the deck contains hidden slides (`hidden: true`): + +- **Pass:** hidden slides are last in the `slides` array unless the user specified otherwise. +- In the rendered PPTX, confirm `ppt/presentation.xml` contains `p:sldId show="0"` on the correct entries. + +## 8. Asset Layering + +For slides mixing image/SVG objects with text: + +- **Pass:** image/SVG `z_index` is lower than all overlapping text objects. +- **Fail:** image covers text → lower `z_index`, adjust bbox, or reclassify as `classification: "layout_design"`. +- When a generated infographic exists as both raster and SVG: the raster must be on the **visible** slide; the SVG must be in a **hidden appendix** slide only. + +## 9. Audit Script (when toolkit is present) + +```powershell +uv run python pptify-plugin/audit/audit.py deck-spec.json --json +``` + +Check `total_collisions`, `total_overflows`, `total_small_fonts`, and `warnings` per slide even when the numeric totals are zero. + +## Completion Criterion + +All 8 checks pass before delivery. +Any failure triggers the repair loop in `pptify-quality-gates`: fix the spec, rebuild, and re-audit. diff --git a/skills/pptify-slide-spec/SKILL.md b/skills/pptify-slide-spec/SKILL.md new file mode 100644 index 000000000..590a48687 --- /dev/null +++ b/skills/pptify-slide-spec/SKILL.md @@ -0,0 +1,133 @@ +--- +name: pptify-slide-spec +description: "Author or repair coordinate-explicit pptify JSON deck specs. Use when writing layout_tree groups, objects, bboxes, tables, images, lines, shapes, type scale, or collision-safe content." +--- + +# PPTify Slide Spec + +Use this skill when writing or repairing a coordinate-explicit JSON deck spec. + +Author final coordinates directly in `layout_tree`; current plugin scripts will not choose layouts, measure browser boxes, or shrink text to fit. Split dense material across slides rather than relying on tiny fonts. + +## Workflow + +1. Define slide messages, design context, and slide size before writing objects. +2. Create each slide with `id`, `title`, and a complete `layout_tree`. +3. Place groups and objects with final inch-based bboxes, z-order, and style values. +4. Add at least one style-derived `layout_design` element on every normal content slide. +5. Audit collisions, text density, font sizes, and default-theme failures before shipping. + +## Deck Shape + +- Return a JSON object with a top-level `slides` array for generated decks. +- Keep slide IDs stable and readable, such as `s01_overview`. +- Use top-level `summary` for deck metadata that belongs in the audit but not on slides. +- When source-backed design context from `pptify-design` is used, record selected profile IDs, source URLs, and license IDs in `summary.design_context`. +- For newly generated decks, `summary.design_context` is required unless a user-provided brand guide or reference PPTX is documented as the primary style source. +- Use `render_mode: "layout"` or omit it for generated decks; OOXML mode is for extracted specs with `ooxml_elements`. +- Every generated slide must include `layout_tree`; do not rely on shorthand layout specs. + +## Slide Fields + +- Each generated slide must include `id`, `title`, and `layout_tree`. +- Use `hidden: true` only for appendix/reference slides that should remain in the PPTX package but not appear during normal presentation. +- Do not use `pattern`, `layout_pattern`, `composition.pattern`, `layout`, `sections`, `bullets`, `objects`, or `theme` as render-time shorthand. +- Do not overfill a slide: prefer three to five major content groups. +- Decide all positions, sizes, z-order, colors, font sizes, and object relationships in the JSON before rendering. +- Do not ship default `python-pptx`-looking slides: plain white background, Calibri-only text, default theme colors, and bullet-only layouts are design failures unless explicitly requested. + +## Layout Tree + +- Include `slide_size` with explicit `width` and `height` in inches. +- Include `root_group_id`. +- Include `groups`, keyed by group ID. +- Include `objects`, keyed by object ID. +- Add `notes` only when notes are useful for audit or speaker context. + +Example skeleton: + +```json +{ + "id": "s01_overview", + "title": "Overview", + "layout_tree": { + "id": "s01_overview", + "title": "Overview", + "slide_size": { "width": 13.333, "height": 7.5 }, + "root_group_id": "root", + "groups": { + "root": { + "id": "root", + "role": "slide", + "layout_mode": "absolute", + "object_ids": ["title"], + "group_ids": [], + "bbox": { "x": 0, "y": 0, "width": 13.333, "height": 7.5 } + } + }, + "objects": { + "title": { + "id": "title", + "kind": "text", + "role": "title", + "classification": "content", + "content": { "text": "Overview" }, + "style": { "font_size": 30, "bold": true, "color": "#111827" }, + "bbox": { "x": 0.75, "y": 0.55, "width": 8.5, "height": 0.65 }, + "z_index": 2 + } + }, + "notes": [] + } +} +``` + +## Groups + +- Each group must include `id`, `role`, `layout_mode`, `object_ids`, `group_ids`, and `bbox`. +- Use `layout_mode: "absolute"` for generated slides to make the coordinate contract explicit. +- Keep group IDs unique and stable so audit repairs can target them. +- Use groups for semantic organization and audit readability; coordinates are still final object coordinates. + +## Objects + +- Every object must include `id`, `kind`, `role`, `classification`, `content`, `style`, `bbox`, and `z_index`. +- Supported `kind` values: `text`, `shape`, `image`, `line`, `table`. +- Supported shape names (`content.shape`): `rect`, `round_rect`, `oval`, `triangle`, `diamond`, `hexagon`, `parallelogram`, `chevron`, `pentagon`, `trapezoid`, and arrow variants. +- Use `classification: "layout_design"` for decorative or background objects. +- Use `classification: "content"` for meaningful text, tables, lines, and media. +- Shape content must include `content.shape`; text on a shape uses `content.text`. +- Image content uses `content.path`, `content.blob_base64`, and `content.alt`. +- Table content uses `content.rows` as a list of row arrays. +- Line content must include `content.x1`, `content.y1`, `content.x2`, and `content.y2`. +- Do not use `chart` objects; render charts as explicit shapes, labels, lines, tables, or file-backed images. + +## Styling + +- Every text-bearing object and table must include `style.font_size` and `style.color`. +- Every line object must include `style.line` and `style.line_width`. +- Every shape object must include `content.shape`, `style.fill`, and `style.line`. +- Specify text color with `style.color`; do not rely on a later tool to infer contrast or default text color. +- Use `z_index` intentionally: low values for backgrounds and decorations, higher for text and foreground content. +- Every normal content slide must include at least one `layout_design` object or style-derived visual structure such as an accent band, card shell, grid, divider rule, signature shape, or image treatment. +- If a vector-traced SVG is provided only for editability, keep the readable raster image in the visible slide and put the SVG on a separate hidden final slide. + +### Type Scale + +| Role | Recommended (pt) | Minimum (pt) | +|---|---|---| +| Slide title | 24–32 | 20 | +| Section heading / H2 | 16–20 | 14 | +| Claim / callout | 13–15 | 12 | +| Body / narrative | 11–12 | 10 | +| Evidence / bullet | 10–11 | 10 | +| Label / caption | 9–10 | 9 | +| Footer / meta (Courier) | 8–9 | 8 | + +Decorative text (`classification: "layout_design"`) such as monogram numerals, rule labels, or background watermarks is exempt from the minimum floor. + +## Repair Rules + +- If content collides, edit bboxes, z-order, grouping, slide density, or split the slide. +- If text overflows, shorten copy, enlarge the bbox, or split content across slides. **Lower `font_size` only as a last resort, and never below the type scale minimum.** +- If an object is misplaced, repair the final coordinates directly; do not add layout hints expecting a later tool to resolve them. diff --git a/skills/pptify-tooling/SKILL.md b/skills/pptify-tooling/SKILL.md new file mode 100644 index 000000000..d1d641de8 --- /dev/null +++ b/skills/pptify-tooling/SKILL.md @@ -0,0 +1,89 @@ +--- +name: pptify-tooling +description: "Command reference for pptify plugin tools. Use when looking up install commands, plugin script syntax, or the workspace reality check." +--- + +# PPTify Tooling + +## Workflow + +1. Run the workspace detection check before invoking any plugin script. +2. If `pptify-plugin/` is missing, read `references/toolkit-setup.md` before responding. +3. Ask before cloning or installing the optional external toolkit. +4. Run helper scripts only after dependencies are present. +5. Treat the renderer import check as diagnostic; current external toolkit installs helper scripts, not `python -m pptify`. + +## Install + +```powershell +uv sync # base project +uv sync --extra plugins # add source ingestion and image helpers +``` + +## Workspace Detection + +Run this check **before** invoking any plugin script. Do not assume the toolkit is present. + +```powershell +# PowerShell +Test-Path "pptify-plugin\README.md" +``` +```bash +# bash / macOS / Linux +test -f pptify-plugin/README.md && echo "present" || echo "missing" +``` + +**Decision table — act on the result before continuing:** + +| `pptify-plugin/` found | `pyproject.toml` found | Action | +|---|---|---| +| Yes | Yes | Proceed: run `uv run python pptify-plugin/...` commands normally | +| Yes | No | Run `uv sync --extra plugins` in the repo root, then retry | +| No | — | **Read [`references/toolkit-setup.md`](references/toolkit-setup.md) now** (before responding), then ask the user whether to install the optional toolkit or apply graceful fallbacks | + +**Optional toolkit install:** + +Do not clone or install the external toolkit automatically. Ask the user before fetching code from `https://github.com/kimtth/agent-pptify-kit`. + +If the user approves installation: + +```powershell +# Clone into the workspace root (or a subdirectory if another project already occupies it) +git clone https://github.com/kimtth/agent-pptify-kit . +uv sync --extra plugins +``` + +If the workspace root already belongs to a different project, ask the user where to place the toolkit before cloning. + +**Graceful degradation — if install is not possible, apply these fallbacks:** + +| Affected skill | Blocked capability | Fallback | +|---|---|---| +| `pptify-context-prep` | Document-to-markdown conversion, RAPTOR summary, design profile loading | Ask the user to paste source content directly; load `references/design-profiles.md` from `pptify-context-prep` for bundled design profile guidance | +| `pptify-visual-assets` | Icon search, image search, raster→SVG, infographic generation | Use `bbox` placeholder objects with descriptive `content.alt`; omit image objects rather than leaving them empty | +| `pptify-quality-gates` | Spec audit via `audit.py` | Apply the manual checklist rules in that skill; skip the `audit.py` output check | +| `pptify-deck-generation` | End-to-end PPTX render via `pptify` CLI | Stop and inform the user — PPTX generation requires the renderer; do not produce a partial artifact | + +**Renderer reality check:** + +```powershell +# Diagnostic only; this currently fails in the external toolkit +uv run python -c "import pptify; print('renderer present')" +``` + +If the import fails with `ModuleNotFoundError: No module named 'pptify'`, the `python -m pptify` render command is unavailable. This is expected for the current external toolkit. Use standalone plugin scripts for all non-render steps, and do not claim that `uv sync` restores the renderer. + +## Plugin Scripts + +| Purpose | Command | +|---|---| +| Convert document to markdown | `uv run python pptify-plugin/documents/document_to_markdown.py --source --output-path out.md` | +| Build RAPTOR summary tree | `uv run python pptify-plugin/documents/document_to_raptor_tree.py --markdown-path source.md --output-path summary.json --title "Title" --pretty` | +| List design profiles | `uv run python pptify-plugin/design/design_context_catalog.py --list --pretty` | +| Load design profile context | `uv run python pptify-plugin/design/design_context_catalog.py --profile fluent-ui-design-tokens --include-context --pretty` | +| Search web images | `uv run python pptify-plugin/images/web_image_search.py --query "topic" --max-num 8 --pretty` | +| Search Iconify icons | `uv run python pptify-plugin/images/iconfy_search.py --query governance --collection fluent --color 0078D4 --max-num 8 --pretty` | +| Raster to SVG | `uv run python pptify-plugin/images/raster_image_to_svg.py --source logo.png --output-path logo.svg --pretty` | +| Generate infographic | `uv run python pptify-plugin/images/text_prompt_to_infographic.py --provider azure-openai --size "1024x1024" --prompt "..." --output-path out.png --pretty` | +| Audit spec | `uv run python pptify-plugin/audit/audit.py deck-spec.json --json` | +| Run tests | `uv run python -m unittest discover -s tests -v` | diff --git a/skills/pptify-tooling/references/toolkit-setup.md b/skills/pptify-tooling/references/toolkit-setup.md new file mode 100644 index 000000000..e3b5e1689 --- /dev/null +++ b/skills/pptify-tooling/references/toolkit-setup.md @@ -0,0 +1,96 @@ +# PPTify Toolkit Setup + +Load this file when `pptify-plugin/` is not found in the workspace and the user wants to install the optional PPTify toolkit. + +## Repository + +| Field | Value | +|---|---| +| URL | https://github.com/kimtth/agent-pptify-kit | +| License | MIT | +| Package manager | `uv` (Python) | + +## Install + +Do not clone or install this external repository automatically. First explain that the built-in awesome-copilot skill includes bundled references, while the external toolkit is only needed for helper-script execution. The current external toolkit does not provide an importable `pptify` renderer module. Continue only after the user explicitly asks to install it. + +```powershell +# 1. Clone into workspace root (use a subdirectory if the root already has a project) +git clone https://github.com/kimtth/agent-pptify-kit . + +# 2. Install base dependencies +uv sync + +# 3. Install plugin extras: source ingestion, image helpers, audit tools +uv sync --extra plugins +``` + +If `uv` is not available: + +```powershell +pip install uv +# or on macOS/Linux: +# curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +If the workspace root belongs to another project, ask the user before cloning. Suggest a named subdirectory, e.g. `git clone https://github.com/kimtth/agent-pptify-kit pptify-kit`. + +## Module Map + +| Module path | Requires extra | What it provides | +|---|---|---| +| `pptify-plugin/documents/document_to_markdown.py` | plugins | Convert PDF, DOCX, HTML, or plain text to markdown for source prep | +| `pptify-plugin/documents/document_to_raptor_tree.py` | plugins | Build a RAPTOR hierarchical summary tree from a markdown source | +| `pptify-plugin/design/design_context_catalog.py` | plugins | List and load pptify-design profiles; returns style context for spec authoring | +| `pptify-plugin/images/web_image_search.py` | plugins | Search the web for candidate images without required API keys | +| `pptify-plugin/images/iconfy_search.py` | plugins | Search Iconify icon library for SVG icons by query, collection, and hex color | +| `pptify-plugin/images/raster_image_to_svg.py` | plugins | Convert raster images to SVG wrappers; optional vector trace mode | +| `pptify-plugin/images/text_prompt_to_infographic.py` | plugins | Generate infographic images via OpenAI or Azure OpenAI (no local fallback) | +| `pptify-plugin/audit/audit.py` | plugins | Validate a deck spec JSON for collisions, overflows, small fonts, and warnings | +| `pptify-plugin/extraction/pptx_extractor.py` | plugins | Extract slide text, style, layout, and media metadata from a reference PPTX | +| `pptify-plugin/extraction/pptx_style_master.py` | plugins | Extract brand, template, and master-slide style facts from a reference PPTX | + +## Image Generation `.env` + +Create `.env` in the workspace root before invoking `text_prompt_to_infographic.py`. Never put secrets in chat or in the prompt dialog — fill the file directly in the editor or terminal. + +```dotenv +# Provider: openai | azure-openai | azure-ai-foundry +PPTIFY_IMAGE_PROVIDER= + +# --- OpenAI --- +OPENAI_API_KEY= +OPENAI_IMAGE_MODEL=gpt-image-1 + +# --- Azure OpenAI --- +AZURE_OPENAI_API_KEY= +AZURE_OPENAI_ENDPOINT= +AZURE_OPENAI_DEPLOYMENT= + +# --- Azure AI Foundry --- +AZURE_AI_FOUNDRY_ENDPOINT= +AZURE_AI_FOUNDRY_MODEL= +``` + +Use `az login` when managed identity or CLI auth is preferred over an API key. + +## Verification After Install + +```powershell +# Confirm the helper CLI is available +uv run python pptify-cli help + +# List available design profiles +uv run python pptify-plugin/design/design_context_catalog.py --list --pretty + +# Run a spec audit smoke test +uv run python pptify-plugin/audit/audit.py deck-spec.json +``` + +Renderer check, for diagnostics only: + +```powershell +uv run python -c "import pptify; print('renderer present')" +``` + +If this fails with `ModuleNotFoundError: No module named 'pptify'`, that is expected for the current external toolkit. Use the standalone `pptify-plugin/` helper scripts and do not run `python -m pptify`. diff --git a/skills/pptify-visual-assets/SKILL.md b/skills/pptify-visual-assets/SKILL.md new file mode 100644 index 000000000..dee379013 --- /dev/null +++ b/skills/pptify-visual-assets/SKILL.md @@ -0,0 +1,65 @@ +--- +name: pptify-visual-assets +description: "Find, generate, and place visual assets for pptify PPTX decks. Use when adding icons, images, SVGs, raster conversions, infographics, image placeholders, or asset-backed slide objects." +--- + +# PPTify Visual Assets + +> **Prerequisite:** Before running any plugin script in this skill, run the workspace detection check in `pptify-tooling`. If `pptify-plugin/` is absent, apply the graceful-degradation fallbacks documented there. + +Use this skill when a deck needs icons, images, diagrams, infographics, or media-backed slide objects. + +## Workflow + +1. Run the workspace detection check from `pptify-tooling`. +2. Choose the asset type: icon, web image, raster/SVG conversion, or generated infographic. +3. Run the relevant helper script and save its output path or result JSON. +4. Add the asset to `layout_tree.objects` with final bbox, `z_index`, `content.alt`, and `classification`. +5. Recheck layering so assets do not cover readable text. + +```powershell +uv run python pptify-plugin/images/iconfy_search.py --query governance --collection fluent --color 0078D4 --max-num 8 --pretty +uv run python pptify-plugin/images/web_image_search.py --query "factory traceability dashboard" --max-num 8 --pretty +uv run python pptify-plugin/images/raster_image_to_svg.py --source logo.png --output-path logo.svg --pretty +``` + +## Icons + +- Search Iconify when an icon improves scanning: `uv run python pptify-plugin/images/iconfy_search.py --query governance --collection fluent --color 0078D4 --max-num 8 --pretty`. +- Prefer simple, single-color SVG icons that match the theme accent. +- Use icons as supporting visual cues, not as replacements for required text. + +## Images + +- Search candidate images with `uv run python pptify-plugin/images/web_image_search.py --query "factory traceability dashboard" --max-num 8 --pretty`. +- Use local file paths in image objects when an image is selected: `content.path` plus `content.alt`. +- Give images an explicit `bbox` and use concise adjacent text. +- Do not use image placeholders as fallback assets; select an approved asset or omit the image object. + +## SVG and Raster Handling + +- Convert raster images to SVG wrappers with `uv run python pptify-plugin/images/raster_image_to_svg.py --source logo.png --output-path logo.svg --pretty`. +- Use `--mode vector-trace` only when optional tracing dependencies are installed and a true vector result is needed. +- Keep generated SVGs simple and readable when they are intended for PowerPoint editing. +- Vector tracing raster infographics can lose or distort text. Keep the original generated raster on visible slides when text fidelity matters, and place the traced SVG on a separate hidden final appendix slide for editability/reference. + +## Infographics + +- Generate text-to-image infographics only through OpenAI or Azure OpenAI providers configured by the user. +- Do not substitute a local fallback image provider when user-managed provider access is missing. +- Before generating any text-to-image artifact, collect missing required values with the VS Code prompt input dialog (`vscode_askQuestions` or equivalent): provider, prompt, model or deployment, image size, output path, and any non-secret access settings. +- For OpenAI image generation, create `.env` from `.env.template` when needed and have the user fill `PPTIFY_IMAGE_PROVIDER=openai`, `OPENAI_API_KEY`, and optionally `OPENAI_IMAGE_MODEL` directly in `.env`. +- For Azure `gpt-image-2` or `gpt-image-2.0` requests, create `.env` from `.env.template` when needed and have the user fill `PPTIFY_IMAGE_PROVIDER=azure-openai`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_IMAGE_DEPLOYMENT`, optional timeout, and any required key auth value directly in `.env`. +- Never ask the user to paste API keys, tokens, or connection strings into chat or into the prompt input dialog. If Entra auth is preferred, tell them to run `az login` in a terminal. +- The image helper loads `.env` automatically before generation. Example: `uv run python pptify-plugin/images/text_prompt_to_infographic.py --provider azure-openai --size "1024x1024" --prompt "Cloud governance roadmap" --output-path infographic.png --pretty`. +- Save an attempt manifest beside the image output with provider, model or deployment, auth mode, prompt path, output path, success status, and error details on failure. A failed model call should be reported as failed, not replaced by a local placeholder and described as generated. +- If a provider call times out after authentication succeeds, retry once with a longer timeout when the user has already provided non-secret provider details. +- NotebookLM bridge commands are unavailable in this workspace snapshot because `pptify-plugin/images/notebooklm_infographic.py` is absent. Do not call a NotebookLM bridge unless that script is restored. +- For generated infographics, prefer the raster output as the visible slide asset. Add any raster-to-SVG vector trace as `hidden: true` on the final slide rather than replacing the visible infographic. + +## Asset Placement + +- Put decorative asset containers in `layout_tree.objects` with `classification: "layout_design"`. +- Put meaningful icons, diagrams, images, and infographics in `layout_tree.objects` with `classification: "content"`. +- Every asset object needs final inch-based `bbox` coordinates and a deliberate `z_index`. +- Use `z_index` so assets do not cover readable text. \ No newline at end of file