Skip to content
Back to search

knowledge-cat-ppt-skill

Story-first Agent Skill for creating, routing, and QA-checking PPT, HTML, and image-first presentation decks

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gnipbao--knowledge-cat-ppt-skill/badge.svg)](/listings/gnipbao--knowledge-cat-ppt-skill)

HTML

<a href="/listings/gnipbao--knowledge-cat-ppt-skill"><img src="/api/listings/gnipbao--knowledge-cat-ppt-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Repository URL:

https://github.com/gnipbao/knowledge-cat-ppt-skill.git

Codex

git clone https://github.com/gnipbao/knowledge-cat-ppt-skill.git ~/.codex/skills/knowledge-cat-ppt-skill

Restart Codex or refresh local skills.

From a cloned repository:

python3 scripts/install_skill.py --agent codex --force

Claude Code

git clone https://github.com/gnipbao/knowledge-cat-ppt-skill.git ~/.claude/skills/knowledge-cat-ppt-skill

Restart Claude Code or refresh local skills.

From a cloned repository:

python3 scripts/install_skill.py --agent claude --force

Manual Install

Copy the whole folder into your agent's skills directory:

cp -R knowledge-cat-ppt-skill ~/.codex/skills/

or:

cp -R knowledge-cat-ppt-skill ~/.claude/skills/

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 383 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: knowledge-cat-ppt-skill
  3. description: "Create, critique, and repair high-quality presentation decks with a story-first, output-engine-aware workflow. Use when the user asks for PPT, PowerPoint, slides, deck, pitch deck, keynote, course deck, academic deck, consulting deck, HTML slides, web presentation, image-first slides, social carousel, speaker notes, deck outline, slide plan, template replication, deck review, deck polish, or conversion from documents, articles, Markdown, PDFs, URLs, or existing .pptx files. Also use when the user says Knowledge Cat PPT or asks for an industry-grade presentation skill."
  4. ---
  5. # Knowledge Cat PPT Skill
  6. ## Overview
  7. Knowledge Cat PPT is a presentation operating system for agents. Its job is to turn messy source material into a persuasive, teachable deck, choose the right production lane, and verify the result through content and visual QA.
  8. Do not treat "make slides" as a formatting task. First determine the audience, the decision or learning outcome, the story spine, and the output format. Then build the deck.
  9. ## Resource Guide
  10. Load only what the current task needs:
  11. - Read `references/benchmark-synthesis.md` when explaining the design philosophy, comparing PPT skill patterns, or improving this skill.
  12. - Read `references/benchmark-quality-gates.md` when the user asks for the best version, benchmark-grade output, open-source comparison, case-study evidence, or quality claims above normal client-ready delivery.
  13. - Read `references/engine-routing.md` before choosing native PPTX, HTML deck, image-first PPTX, or review-only mode.
  14. - Read `references/story-architecture.md` when turning source material into a deck brief, narrative spine, action titles, or slide plan.
  15. - Read `references/design-systems.md` when choosing style direction, layout family, visual tokens, imagery, or anti-generic design rules.
  16. - Read `references/template-replication.md` when the user provides an existing `.pptx`, screenshot, brand deck, style reference, or asks to clone a template.
  17. - Read `references/html-production-lock.md` before building production HTML decks, visual prototypes, browser-based talks, or HTML decks with local images/screenshots.
  18. - Read `references/html-visual-systems.md` after the HTML production lock when a browser deck needs benchmark-level visual rhythm, a reusable style package, or contact-sheet QA.
  19. - Read `references/style-template-library.md` when the user provides many PPT style prompts, asks for common PPT style websites, asks which style to choose, or wants Knowledge Cat to exceed Guizang-style HTML template depth.
  20. - Read `references/native-pptx-recipes.md` when building or repairing editable PowerPoint decks.
  21. - Read `references/html-deck-recipes.md` when building browser-based decks, fast visual prototypes, or single-file HTML presentations.
  22. - Read `references/style-prompt-intake.md` when the user uploads or pastes theme/style prompts, prompt tables, visual DNA blocks, AI image style prompts, or asks for Image2/GPT-Image-driven PPT styling.
  23. - Read `references/image-first-recipes.md` when visual impact matters more than editability or AI-generated slide images are requested.
  24. - Read `references/qa-rubric.md` before final delivery, when reviewing a deck, or when the task has professional stakes.
  25. - Read `references/open-source-product.md` when preparing this skill for public release or evaluating product readiness.
  26. - Use `scripts/validate_deck_plan.py` after writing a JSON deck plan. The expected shape is documented in `assets/deck-plan.schema.json`.
  27. - Use `scripts/init_deck_project.py` to create an HTML deck project from the bundled starter template.
  28. - Use `scripts/validate_html_deck.py` to statically check an HTML deck before browser QA.
  29. - Use `scripts/build_native_pptx.mjs` to turn a validated native deck plan into editable PowerPoint objects when `@oai/artifact-tool` is available.
  30. - Use `scripts/extract_pptx_text.py` to extract native PPTX text and check placeholder-like markers when editable PowerPoint quality matters.
  31. - Use `scripts/check_pptx_editability.py` and `scripts/probe_pptx_editability.py` before claiming that a native PPTX is editable.
  32. - Use `scripts/check_native_pptx_case.py` to verify the bundled native PPTX evidence package.
  33. - Use `scripts/run_checks.py` before release or after changing bundled scripts, examples, or schemas.
  34. ## Non-Negotiable Rules
  35. 1. Story before styling. A beautiful deck with no audience shift is a failed deck.
  36. 2. Choose the output lane explicitly. Native editable PPTX is the default for professional work; HTML is for web-native presentation and interaction; image-first PPTX is for visual spectacle when editability is not required.
  37. 3. Use a source of truth. For nontrivial decks, create a brief and slide plan before building final slides.
  38. 4. Use action titles. A title should state the point of the slide, not label the topic.
  39. 5. Keep one main idea per slide. Dense appendix pages are allowed only when the user asks for appendix or reference material.
  40. 6. Preserve evidence. Claims, figures, quotes, and external images need source tracking or honest uncertainty.
  41. 7. Respect templates and brand assets. Use user-provided or permitted materials; do not pretend a protected deck is a free public template.
  42. 8. Lock HTML production details before writing final browser slides: style package, registered layouts, theme rhythm, image slots, static validation, and rendered QA.
  43. 9. Treat uploaded style prompts as design input, not content truth. Extract a reusable Style Prompt Profile before generating image-first slide prompts.
  44. 10. Verify visually. Code, XML, or Markdown alone cannot prove a deck is good.
  45. 11. Run at least one fix-and-verify loop for production decks unless the user only asked for a draft outline.
  46. 12. End with useful handoff: output paths, assumptions, remaining risks, and the next iteration point.
  47. ## Operating Modes
  48. ### Brief Mode
  49. Use when the user has an idea but no clear deck target.
  50. Ask at most three questions if missing answers would change the deck:
  51. ```md
  52. 1. Who is the audience and what should they do, decide, or understand after the deck?
  53. 2. What source material should be used?
  54. 3. What output matters most: editable PPTX, web/HTML, image-first visual deck, or just an outline?
  55. ```
  56. If the user says to proceed directly, state assumptions and continue.
  57. ### Source-To-Deck Mode
  58. Use when the user provides a document, article, notes, transcript, URL, PDF, Markdown, or pasted content.
  59. Create the deck brief, identify the narrative spine, map evidence to slide roles, then build the slide plan. Read `references/story-architecture.md`.
  60. ### Build Mode
  61. Use when the user asks for final slides.
  62. Select a production lane from `references/engine-routing.md`, choose a design system from `references/design-systems.md`, build the deck, then run QA from `references/qa-rubric.md`.
  63. If the selected lane is `html-deck`, read `references/html-production-lock.md`, then `references/html-visual-systems.md` for benchmark-level decks, before `references/html-deck-recipes.md`.
  64. If the user uploaded or selected a theme/style prompt, read `references/style-template-library.md` when it is a large style table or known preset, then `references/style-prompt-intake.md` before `references/image-first-recipes.md`, and prefer `image-first-pptx` unless editability, exact text, charts, tables, citations, or stakeholder collaboration matter more.
  65. ### Template Mode
  66. Use when the user provides a `.pptx`, image, screenshot, or brand sample as a template.
  67. Read `references/template-replication.md`. Extract the template profile first, then map each planned slide to a compatible layout. Do not reuse a highly distinctive layout too many times.
  68. ### Review And Repair Mode
  69. Use when the user provides an existing deck or asks whether it is good.
  70. Review story, audience fit, slide clarity, visual system, evidence, editability, and technical defects. Lead with prioritized issues, then propose or perform repairs.
  71. ### Publishing Mode
  72. Use when the user needs speaker notes, handouts, PDF export, video narration, social cards, Xiaohongshu carousel, WeChat cover, or other downstream formats.
  73. Keep the original deck source of truth intact and derive outputs from it.
  74. ### Productization Mode
  75. Use when improving this skill itself, preparing a public repository, writing release docs, or evaluating open-source readiness.
  76. Read `references/open-source-product.md` and `references/benchmark-quality-gates.md`. Keep `SKILL.md` concise, move detailed production guidance into references, and run bundled checks before claiming release readiness.
  77. ## Core Workflow
  78. ### 1. Triage The Request
  79. Classify:
  80. - Deck type: investor, sales, strategy, teaching, academic, consulting, product, keynote, internal report, social carousel, courseware, or other.
  81. - Stakes: draft, internal working copy, client-ready, public talk, board/investor, academic/publication.
  82. - Output lane: native-pptx, html-deck, image-first-pptx, or review-only.
  83. - Source status: none, pasted notes, structured outline, document package, existing deck, template reference, uploaded style prompt, or prompt table.
  84. - Deadline and iteration budget.
  85. Open with:
  86. ```md
  87. Deck type:
  88. Audience:
  89. Outcome:
  90. Output lane:
  91. Source status:
  92. Primary risk:
  93. Next action:
  94. ```
  95. For small requests, this can be one short paragraph.
  96. ### 2. Build The Deck Brief
  97. For nontrivial decks, produce:
  98. ```md
  99. Title:
  100. Audience:
  101. Moment:
  102. Desired audience shift:
  103. Decision or learning outcome:
  104. Main promise:
  105. Scope:
  106. Output lane:
  107. Format:
  108. Page count:
  109. Source materials:
  110. Style prompt source:
  111. Design posture:
  112. Must include:
  113. Must avoid:
  114. QA level:
  115. ```
  116. Do not over-ask. Infer safe defaults where possible.
  117. ### 3. Synthesize The Story
  118. Choose a spine:
  119. - Situation -> tension -> insight -> proof -> action
  120. - Problem -> failed old approach -> new mechanism -> evidence -> next step
  121. - Context -> finding -> implication -> recommendation
  122. - Question -> method -> result -> limitation -> conclusion
  123. - Hook -> transformation -> steps -> proof -> call to action
  124. Then write the ghost deck: the action titles alone should tell the story.
  125. ### 4. Create The Slide Plan
  126. Each slide should have:
  127. ```md
  128. Slide:
  129. Layout:
  130. Action title:
  131. Role:
  132. Key message:
  133. Evidence:
  134. Visual:
  135. Speaker note:
  136. Source refs:
  137. Asset needs:
  138. ```
  139. For JSON plans, validate with:
  140. ```bash
  141. python3 scripts/validate_deck_plan.py path/to/deck-plan.json
  142. ```
  143. Fix validation failures before building final slides.
  144. ### 5. Choose The Production Lane
  145. Use the decision matrix in `references/engine-routing.md`.
  146. Default decisions:
  147. - Business, investor, consulting, academic, training, legal, finance, or collaborative decks -> native editable PPTX.
  148. - Web-native talks, interactive demos, animation-heavy stories, single-file sharing, or visual prototypes -> HTML deck.
  149. - Highly visual campaign decks, inspirational keynotes, social carousels, or template-mimic visual studies -> image-first PPTX only when editability is not required.
  150. - Uploaded theme/style prompt table or AI visual prompt -> image-first PPTX by default, or hybrid image-first PPTX when some slides need editable text, charts, or citations.
  151. - Existing deck feedback -> review-only first, then repair if asked.
  152. After choosing the lane, load the matching recipe:
  153. - Native editable PPTX -> `references/native-pptx-recipes.md`
  154. - Browser-based deck -> `references/html-production-lock.md`, then `references/html-deck-recipes.md`
  155. - Image-first PPTX -> `references/style-prompt-intake.md` when a user style prompt exists, then `references/image-first-recipes.md`
  156. ### 6. Build The Design System
  157. Select a design posture from `references/design-systems.md`. Define:
  158. - Layout rhythm
  159. - Typography scale
  160. - Color tokens
  161. - Evidence treatment
  162. - Image style and crop ratios
  163. - Chart style
  164. - Motion level, if any
  165. - Accessibility constraints
  166. Avoid generic AI aesthetics: random gradients, decorative orbs, over-rounded cards, low-contrast gray text, inconsistent spacing, and repeated title-plus-bullets.
  167. ### 7. Produce The Deck
  168. Use the best available local capability for the selected lane. If a specialized presentation, PPTX, browser, image, or document skill is available, compose with it rather than rewriting its job here.
  169. Maintain a source-of-truth file when possible:
  170. - `deck-brief.md` for strategy and constraints
  171. - `deck-plan.md` or `deck-plan.json` for slide structure
  172. - output files in a predictable project folder
  173. - `qa-report.md` for production decks
  174. For HTML decks, prefer the bundled starter:
  175. ```bash
  176. python3 scripts/init_deck_project.py path/to/project --title "Deck Title"
  177. python3 scripts/validate_html_deck.py path/to/project/index.html
  178. ```
  179. Each final HTML slide must declare `data-layout`, `data-title`, `data-role`, and `data-theme`. Local images must use `images/` paths plus `data-image-slot` and target ratio metadata. Treat static validation errors as blockers.
  180. For native PPTX, follow `references/native-pptx-recipes.md`. A validated plan can use the bundled builder when the current environment provides `@oai/artifact-tool`:
  181. ```bash
  182. node scripts/build_native_pptx.mjs \
  183. --plan path/to/deck-plan.json \
  184. --output path/to/output.pptx \
  185. --workspace path/to/prepared-artifact-workspace \
  186. --preview-dir path/to/screenshots \
  187. --inspection path/to/inspection.ndjson
  188. ```
  189. The builder reopens the exported PPTX before producing previews and inspection evidence. If the dependency is unavailable, compose with a verified native-PPTX skill or renderer and keep the same QA contract. For native PPTX, run:
  190. ```bash
  191. python3 scripts/extract_pptx_text.py path/to/output.pptx --fail-on-placeholders
  192. python3 scripts/check_pptx_editability.py path/to/output.pptx --fail-on-image-only-slides
  193. python3 scripts/probe_pptx_editability.py path/to/output.pptx
  194. ```
  195. For image-first PPTX, follow the lane-specific recipe and state the editability tradeoff.
  196. ### 8. QA And Iterate
  197. Use `references/qa-rubric.md`.
  198. Minimum production QA:
  199. 1. Content QA: title order, missing content, typos, unsupported claims, placeholder text.
  200. 2. Visual QA: render slides or open the HTML, inspect for overflow, contrast, alignment, collision, spacing, and image crop issues.
  201. 3. Story QA: ghost deck, audience shift, duplicated ideas, weak ending.
  202. 4. Format QA: file opens, assets resolve, fonts are reasonable, links work when promised.
  203. 5. Native editability QA: inspect object types, reject image-only impostors, and run a reversible edit probe when editability is promised.
  204. 6. Fix and recheck affected slides.
  205. For release or repository work, also run:
  206. ```bash
  207. python3 scripts/run_checks.py
  208. ```
  209. If the first pass finds no problems, inspect again more critically.
  210. When claiming benchmark-level quality, use `references/benchmark-quality-gates.md` and provide the evidence artifacts behind the score.
  211. ## Output Protocols
  212. ### Deck Brief
  213. ```md
  214. Deck type:
  215. Audience:
  216. Outcome:
  217. Main promise:
  218. Narrative spine:
  219. Output lane:
  220. Format:
  221. Page count:
  222. Source materials:
  223. Style prompt source:
  224. Design posture:
  225. Assumptions:
  226. Next action:
  227. ```
  228. ### Slide Plan
  229. ```md
  230. | # | Layout | Action title | Role | Key message | Evidence | Visual | Notes |
  231. |---|---|---|---|---|---|---|---|
  232. ```
  233. ### Review Report
  234. ```md
  235. Overall score:
  236. P0 issues:
  237. P1 issues:
  238. P2 improvements:
  239. Story diagnosis:
  240. Visual diagnosis:
  241. Evidence diagnosis:
  242. Technical diagnosis:
  243. Recommended repair sequence:
  244. ```
  245. ### Delivery Note
  246. ```md
  247. Created:
  248. Output lane:
  249. Files:
  250. QA performed:
  251. Key assumptions:
  252. Known limitations:
  253. Best next iteration:
  254. ```
  255. ## Boundaries
  256. - Do not fabricate facts, sources, market sizes, citations, or user metrics.
  257. - Do not flatten slides into images when the user needs editable PowerPoint.
  258. - Do not force native PPTX when the user clearly wants a web-native presentation.
  259. - Do not create a huge final deck before agreeing on the story unless the user explicitly asks for a first draft.
  260. - Do not overuse the same layout, theme, transition, or visual trick.
  261. - Do not treat a template as permission to copy copyrighted assets.
  262. - Do not hide tradeoffs. If the chosen lane sacrifices editability, animation, fidelity, accessibility, or portability, say so.
  263. - Do not claim final quality without a QA pass.
  264. ## Quality Standard
  265. Score production outputs out of 100:
  266. - Audience and outcome fit: 15
  267. - Narrative spine and ghost deck: 20
  268. - Slide clarity and action titles: 15
  269. - Evidence quality and source traceability: 15
  270. - Visual system and layout discipline: 15
  271. - Output-lane correctness and technical reliability: 10
  272. - QA loop and handoff: 10
  273. Below 70: do not deliver as final. 70-84: workable draft. 85-94: client-ready with minor risk. 95+: benchmark-level only when the gate evidence in `references/benchmark-quality-gates.md` is present.
  274. Before final response, confirm:
  275. - Did the deck have a clear audience shift?
  276. - Did the output lane match the user's real need?
  277. - Did each slide have one main job?
  278. - Did the visual system serve the argument?
  279. - Did evidence remain traceable?
  280. - Did at least one visual/content QA loop happen for final decks?
README.md · README · 432 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Knowledge Cat PPT Skill
  2. Story-first presentation production for AI agents.
  3. [English](README.md) | [简体中文](README_CN.md) | [Bilingual](README_BILINGUAL.md)
  4. Knowledge Cat PPT is an open-source Agent Skill for creating, reviewing, and repairing presentation decks. It is designed for Codex, Claude Code, and other skill-aware coding agents. Instead of acting like a generic "make pretty slides" prompt, it gives the agent a production system: clarify the audience shift, choose the right output lane, build a slide plan, generate the deck, and verify the result.
  5. Current version: `0.10.0`
  6. ## Highlights
  7. - Story-first deck planning with audience, outcome, narrative spine, and action titles.
  8. - Output-lane routing for native editable PPTX, HTML decks, image-first PPTX, and review-only workflows.
  9. - Evidence tracking for claims, quotes, data, assumptions, screenshots, and source materials.
  10. - HTML deck starter template with keyboard navigation, print CSS, light/dark themes, and no external dependencies.
  11. - JSON deck-plan validator and HTML deck validator.
  12. - HTML production lock for registered layouts, theme rhythm, image slots, screenshots, and rendered QA.
  13. - Uploaded theme/style prompt intake for Image2/GPT-Image-first PPT workflows.
  14. - Curated 44-style template library with common PPT style-site radar and Guizang-surpass signature-pack targets.
  15. - Portfolio Minimal HTML signature pack with a 14-layout registry, 12-slide case study, QA artifacts, and a dedicated pack checker.
  16. - Native deck-plan-to-PPTX generator with editable text, shapes, charts, tables, and speaker notes.
  17. - Real native PPTX case study with re-imported slide renders, contact sheet, object inspection, editability report, and reversible text-object probe.
  18. - Open-source repository hygiene checks, GitHub Actions workflow, issue templates, and release checklist.
  19. - Compatible with both Codex local skills and Claude Code style skills.
  20. ## Three Production Modes
  21. | Native PPTX | HTML Deck | Image-First PPTX |
  22. |---|---|---|
  23. | ![Native PPTX mode preview](docs/images/mode-native-pptx.png) | ![HTML deck mode preview](docs/images/mode-html-deck.png) | ![Image-first PPTX mode preview](docs/images/mode-image-first.png) |
  24. | Editable PowerPoint work for real teams, client handoffs, charts, tables, and speaker notes. | Browser-native decks with keyboard navigation, print CSS, fast iteration, and visual QA. | High-impact visual decks for social carousels, campaigns, and keynote-style moments. |
  25. ## Compatibility
  26. | Agent environment | Status | Install path |
  27. |---|---|---|
  28. | Codex | Supported | `~/.codex/skills/knowledge-cat-ppt-skill` |
  29. | Claude Code | Supported | `~/.claude/skills/knowledge-cat-ppt-skill` |
  30. | Other skill-aware agents | Should work if they read `SKILL.md` plus bundled resources | Agent-specific |
  31. The skill itself is plain Markdown, Python, JavaScript, JSON, and HTML. Validators use only the Python standard library. The optional bundled native PPTX builder requires Node.js plus `@oai/artifact-tool` in a prepared workspace.
  32. ## What It Does
  33. Knowledge Cat PPT helps an agent:
  34. - Turn rough ideas, notes, documents, transcripts, URLs, PDFs, or research into a deck brief.
  35. - Build a slide plan with action titles, slide roles, evidence, visuals, notes, and source references.
  36. - Choose the correct output lane before production.
  37. - Parse uploaded theme/style prompts into an image-first Style Prompt Profile.
  38. - Generate or guide production of HTML decks, editable PowerPoint decks, or image-first visual decks.
  39. - Review existing decks for story, evidence, visual system, editability, and technical risks.
  40. - Run validation before claiming a deck is ready.
  41. ## Why It Exists
  42. Most AI slide workflows fail for three reasons:
  43. 1. They start with visual style before defining the audience outcome.
  44. 2. They choose the wrong output format, such as flattened images when the user needs editable PowerPoint.
  45. 3. They skip rendered QA and ship slides that only looked correct in code.
  46. Knowledge Cat PPT treats a deck as a production system. Story, engine, design, evidence, and QA must agree.
  47. ## Install
  48. Repository URL:
  49. ```txt
  50. https://github.com/gnipbao/knowledge-cat-ppt-skill.git
  51. ```
  52. ### Codex
  53. ```bash
  54. git clone https://github.com/gnipbao/knowledge-cat-ppt-skill.git ~/.codex/skills/knowledge-cat-ppt-skill
  55. ```
  56. Restart Codex or refresh local skills.
  57. From a cloned repository:
  58. ```bash
  59. python3 scripts/install_skill.py --agent codex --force
  60. ```
  61. ### Claude Code
  62. ```bash
  63. git clone https://github.com/gnipbao/knowledge-cat-ppt-skill.git ~/.claude/skills/knowledge-cat-ppt-skill
  64. ```
  65. Restart Claude Code or refresh local skills.
  66. From a cloned repository:
  67. ```bash
  68. python3 scripts/install_skill.py --agent claude --force
  69. ```
  70. ### Manual Install
  71. Copy the whole folder into your agent's skills directory:
  72. ```bash
  73. cp -R knowledge-cat-ppt-skill ~/.codex/skills/
  74. ```
  75. or:
  76. ```bash
  77. cp -R knowledge-cat-ppt-skill ~/.claude/skills/
  78. ```
  79. ## Quick Start
  80. Ask your agent:
  81. ```md
  82. Use $knowledge-cat-ppt-skill to turn my notes into an 8-slide client-ready deck. I need editable PPTX unless you think another output lane is better.
  83. ```
  84. For a deck review:
  85. ```md
  86. Use $knowledge-cat-ppt-skill to review this deck. Focus on story, evidence, visual clarity, and whether it is actually ready to send.
  87. ```
  88. For an HTML deck:
  89. ```md
  90. Use $knowledge-cat-ppt-skill to build a browser-based HTML deck from this outline. Make it keyboard navigable and run the bundled HTML validator.
  91. ```
  92. For the 44-style template library:
  93. ```md
  94. Use $knowledge-cat-ppt-skill. Choose the best style from the template library for my topic, explain the lane tradeoff, then create a deck brief and slide plan.
  95. ```
  96. For the Portfolio Minimal signature pack:
  97. ```md
  98. Use $knowledge-cat-ppt-skill. Build a browser-based HTML deck using the kc-24 Portfolio Minimal signature pack. Use the pack layout registry, include a local image slot, produce screenshots/contact sheet, and run the signature-pack checks.
  99. ```
  100. ## Output Lanes
  101. | Lane | Use when | Main tradeoff |
  102. |---|---|---|
  103. | `native-pptx` | PowerPoint editability, team collaboration, charts, tables, notes, client decks | Bundled builder requires a prepared `@oai/artifact-tool` workspace; imported-deck repairs still need a verified native editor |
  104. | `html-deck` | Web-native presentation, rapid visual iteration, browser preview, single-file sharing | Not a true editable PowerPoint file |
  105. | `image-first-pptx` | Social carousel, campaign deck, visual keynote, AI-generated slide surfaces | Lower editability |
  106. | `review-only` | Existing deck critique, repair planning, story/evidence diagnosis | Does not create a final deck until repair is requested |
  107. ## Native Editable PPTX Case
  108. The bundled native lane now includes an executable deck-plan builder and a real evidence package:
  109. ```txt
  110. examples/case-studies/native-editable/
  111. +-- deck-brief.md
  112. +-- deck-plan.json
  113. +-- knowledge-cat-native-editable.pptx
  114. +-- inspection.ndjson
  115. +-- editability-report.json
  116. +-- edit-probe.json
  117. +-- qa-report.md
  118. +-- screenshots/
  119. +-- slide-01.png ... slide-06.png
  120. +-- slide-01.layout.json ... slide-06.layout.json
  121. +-- contact-sheet.png
  122. ```
  123. The example contains native text, shapes, one chart, one table, and speaker notes on every slide. It contains no full-slide images.
  124. Validate the complete evidence package:
  125. ```bash
  126. python3 scripts/check_native_pptx_case.py
  127. ```
  128. Build another native deck from a validated plan after preparing an `@oai/artifact-tool` workspace:
  129. ```bash
  130. node scripts/build_native_pptx.mjs \
  131. --plan path/to/deck-plan.json \
  132. --output path/to/output.pptx \
  133. --workspace path/to/prepared-artifact-workspace \
  134. --preview-dir path/to/screenshots \
  135. --inspection path/to/inspection.ndjson
  136. ```
  137. Then run text, object, and reversible edit checks:
  138. ```bash
  139. python3 scripts/extract_pptx_text.py path/to/output.pptx --fail-on-placeholders
  140. python3 scripts/check_pptx_editability.py path/to/output.pptx --fail-on-image-only-slides
  141. python3 scripts/probe_pptx_editability.py path/to/output.pptx
  142. ```
  143. ## HTML Deck Starter
  144. Create a sample HTML deck:
  145. ```bash
  146. python3 scripts/init_deck_project.py /tmp/kc-demo-deck --title "Knowledge Cat Demo"
  147. python3 scripts/validate_html_deck.py /tmp/kc-demo-deck/index.html
  148. ```
  149. Open:
  150. ```txt
  151. /tmp/kc-demo-deck/index.html
  152. ```
  153. The starter includes:
  154. - 16:9 desktop slide canvas
  155. - Mobile stacked fallback
  156. - Keyboard navigation
  157. - Print CSS
  158. - Light/dark theme switching
  159. - Action-title aware slide structure
  160. - No external dependencies
  161. ## Style Template Library
  162. Knowledge Cat includes a curated 44-style template library in `references/style-template-library.md`. The library turns pasted PPT style prompts into a routing system:
  163. - style seeds such as `kc-24` Portfolio Minimal, `kc-25` Minimal Data Story, `kc-28` Bold Editorial Magazine, `kc-26` Dark SaaS Product, and `kc-11` Architectural Blueprint
  164. - default output lanes for each style
  165. - protected-style normalization rules
  166. - a priority path for building signature packs that can compete with Guizang-style HTML deck depth
  167. Copy-ready prompts live in:
  168. ```txt
  169. docs/TEMPLATE_LIBRARY_PROMPTS.md
  170. ```
  171. ## Portfolio Minimal Signature Pack
  172. The first implemented signature pack is `kc-24` Portfolio Minimal:
  173. ```txt
  174. assets/html-signature-packs/portfolio-minimal/
  175. +-- README.md
  176. +-- layout-registry.json
  177. +-- template.html
  178. ```
  179. It includes 14 registered `custom-pm-*` layouts and a 12-slide case study:
  180. ```txt
  181. examples/case-studies/portfolio-minimal/
  182. ```
  183. Run the pack gate:
  184. ```bash
  185. python3 scripts/check_signature_pack.py portfolio-minimal
  186. ```
  187. The Portfolio Minimal case study includes browser-captured PNG slide screenshots and a browser contact sheet, so quality claims are backed by visual artifacts rather than code inspection alone.
  188. ## Deck Plan Validation
  189. Validate a JSON deck plan:
  190. ```bash
  191. python3 scripts/validate_deck_plan.py examples/sample-deck-plan.json
  192. ```
  193. The expected structure is documented in:
  194. ```txt
  195. assets/deck-plan.schema.json
  196. ```
  197. ## Full Validation
  198. Run all bundled checks:
  199. ```bash
  200. python3 scripts/run_checks.py
  201. ```
  202. Run repository hygiene checks:
  203. ```bash
  204. python3 scripts/check_repo.py
  205. ```
  206. The checks validate:
  207. - sample deck plan
  208. - generated sample HTML deck
  209. - HTML structure
  210. - Portfolio Minimal signature pack and case study
  211. - native PPTX text extraction, object inspection, and reversible edit-probe self-tests
  212. - real native PPTX case, re-imported renders, contact sheet, and QA evidence
  213. - required repository files
  214. - changelog/version consistency
  215. - cache and generated-file hygiene
  216. ## Repository Layout
  217. ```txt
  218. knowledge-cat-ppt-skill/
  219. +-- SKILL.md
  220. +-- README.md
  221. +-- README_CN.md
  222. +-- README_BILINGUAL.md
  223. +-- VERSION
  224. +-- CHANGELOG.md
  225. +-- CONTRIBUTING.md
  226. +-- SECURITY.md
  227. +-- LICENSE
  228. +-- .github/
  229. | +-- workflows/validate.yml
  230. | +-- ISSUE_TEMPLATE/
  231. +-- agents/
  232. | +-- openai.yaml
  233. +-- assets/
  234. | +-- deck-plan.schema.json
  235. | +-- html-template/
  236. | +-- index.html
  237. | +-- html-signature-packs/
  238. | +-- portfolio-minimal/
  239. +-- examples/
  240. | +-- retest-prompts.md
  241. | +-- sample-deck-plan.json
  242. | +-- sample-html-deck/
  243. | +-- case-studies/
  244. | +-- portfolio-minimal/
  245. | +-- native-editable/
  246. +-- references/
  247. | +-- benchmark-synthesis.md
  248. | +-- design-systems.md
  249. | +-- engine-routing.md
  250. | +-- html-deck-recipes.md
  251. | +-- html-production-lock.md
  252. | +-- image-first-recipes.md
  253. | +-- native-pptx-recipes.md
  254. | +-- open-source-product.md
  255. | +-- qa-rubric.md
  256. | +-- story-architecture.md
  257. | +-- style-prompt-intake.md
  258. | +-- style-template-library.md
  259. | +-- template-replication.md
  260. +-- scripts/
  261. | +-- check_repo.py
  262. | +-- build_native_pptx.mjs
  263. | +-- check_native_pptx_case.py
  264. | +-- check_pptx_editability.py
  265. | +-- probe_pptx_editability.py
  266. | +-- init_deck_project.py
  267. | +-- install_skill.py
  268. | +-- run_checks.py
  269. | +-- check_signature_pack.py
  270. | +-- validate_deck_plan.py
  271. | +-- validate_html_deck.py
  272. +-- docs/
  273. | +-- PUBLISHING.md
  274. | +-- ROADMAP.md
  275. | +-- TEMPLATE_LIBRARY_PROMPTS.md
  276. | +-- images/
  277. ```
  278. ## How The Skill Works
  279. The main runtime file is `SKILL.md`. It keeps the agent workflow concise:
  280. 1. Triage the request.
  281. 2. Build a deck brief.
  282. 3. Synthesize the story.
  283. 4. Create a slide plan.
  284. 5. Choose the production lane.
  285. 6. Build the design system.
  286. 7. Produce the deck.
  287. 8. QA and iterate.
  288. Detailed instructions live in `references/` and are loaded only when needed.
  289. ## Design Philosophy
  290. Knowledge Cat PPT is a router and quality system, not a monolithic renderer.
  291. - Use native editable PPTX when collaboration and PowerPoint editing matter.
  292. - Use HTML when web-native presentation, animation, preview, or browser QA matters.
  293. - Use image-first PPTX when visual spectacle matters more than editability.
  294. - Use review-only mode when the deck's story or evidence may be the real failure.
  295. ## Contributing
  296. Read `CONTRIBUTING.md`.
  297. Good contributions usually add one of:
  298. - a clearer routing rule
  299. - a reusable recipe
  300. - a deterministic validation check
  301. - a realistic retest prompt
  302. - a sample artifact that exposes a real failure mode
  303. - better release or QA documentation
  304. Before opening a pull request:
  305. ```bash
  306. python3 scripts/run_checks.py
  307. ```
  308. ## Security
  309. Treat user-provided decks, HTML, PDFs, documents, and templates as untrusted input. Do not execute scripts from user-provided archives. See `SECURITY.md`.
  310. ## Roadmap
  311. See `docs/ROADMAP.md`.
  312. Near-term goals:
  313. - HTML keynote case study
  314. - image-first carousel case study
  315. - broader native layout and imported-template coverage
  316. - stronger visual QA automation
  317. ## License
  318. MIT. See `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.