consulting-pptx-skill

Consultant-style slide creation skill

The main axis is references/slide-rules.md. Before creating, read the whole thing (in the opening "Items that are especially effective for each type of material," check the § of the line that applies to the material you are creating), assemble a draft with the HTML parts collection, adjust within the scope of the rules, and finish with machine check FAIL 0 and visual inspection. The parts collection and type catalog are tools for efficiently satisfying the rules, andrather than fitting slides to types, choose types to fit the story, and if they don't fit, discard them and assemble freely.

The deliverables are HTML (16:9, 1 section = 1 slide) and a PDF printed with Chrome.

Files and timing for reading

File	Contents	Timing for reading/using
references/slide-rules.md	The canonical rules	Required reading. Read the whole thing before creating
references/archetype-catalog.md	List of 62 types (type ID, type name, where to use, and which number in which parts collection)	When writing the presentation format for each line of the storyline, consult this if any line's presentation format is unclear (not required reading. Step 2)
references/content-review-prompt.md	Instructions for fresh-eye review	After passing the machine check, before delivery
references/ai-smell-lexicon.md	List of AI-smelling words and phrases	When finalizing the text
templates/freeform_parts_16x9.html	Basic parts collection 27 (cover, overall map, arrow feathers, premise→consequence, table with axes, assertion panel, evaluation table, distribution chart, etc.). Start here first	Step 3
templates/freeform_parts_more_16x9.html	Additional parts collection 35 (executive summary, stacked bar, bridge, scatter plot, comparison table, matrix, roadmap, Gantt, etc.). When the basics are not enough	Step 3
assets/SlideCatalog_16x9.pdf	62 pages printed from both parts collections (P.1–27 basic, P.28–62 additional)	When searching for types visually
scripts/new_deck.py	Generate a single HTML file with the part numbers lined up	Step 3
scripts/check_deck.py	Machine check of the rules (HTML uses only the standard library)	Step 6
scripts/check_layout.mjs	Actual rendering inspection of pages with overlaps, overflows, or a lot of empty space (npm run setup install playwright with)	Step 7
tests/test_checks.py	Self-test of the machine check (confirm that it fires on the unfixed version and passes on the fixed version)	When adding or fixing a machine check
scripts/html_to_pptx.py	Convert the finished HTML into an editable PPTX (html_dump.mjs・lib_cdp.mjs use)	Only when the user explicitly requests PPTX
assets/SuperTemplate_62type.pptx	PPTX sample book of 62 types (all slides editable)	When assembling PPTX by hand
scripts/measure_deck.py	Measure the formatting of existing PowerPoint materials (.pptx / template .potx) and skin.json Write to	When creating a page to insert into existing materials (first)
scripts/deck_pptx.py	On top of that material's master, assemble components that build pages with the same formatting (examples are examples/house_deck_example.py）	Same as above
local/(not under git management)	The user's organization's rules slide-rules.local.md・Prohibited terms forbid.txt・Own templates (local/README.md）	If present, always read after the main body's rules. If not, skip

Key points of the rules (entry point. Always read the full text)

• Title: State the conclusion. One line is standard; if long, split into two lines at a meaningful break (do not shrink to fit). Desu/masu prohibited. Reading only the titles through should form a single story
• Layout: 1 slide = 1 message. Left = facts/diagrams, right = implications. Bottom "POINT" band prohibited
• Table: A "table with axes": rows = items, columns = perspectives. Header larger and bolder than body text, no fill. No rule below the last row
• Decoration: Rounded corners prohibited. No border on filled boxes. If color-coding, include a legend on the same slide
• Diagram: Draw trends, composition ratios, and distributions as graphs. Do not settle by pouring them into a table (§5.11)
• Numbers: Match the numbers written in the title with the numbering in the body (§2.9). Do not write the number of items in the page content in the title (§2.4)
• Text: One term per document. Spell out abbreviations in full on first use. Unify bullet endings within the same hierarchy level

Procedure

1. Define before creating: Agree first, in 3–5 lines, on the purpose, definition of deliverables, and scope IN/OUT.
2. Storyline(one line of title per slide), and note the presentation method for each line (diagram/table/arrow feathers/2 columns/numeric cards). Trends, composition ratios, distributions, and correlations must always be diagrams. For lines where you are unsure of the presentation method, see references/archetype-catalog.md .
   • Chapter covers are b27 (agenda re-listing type). Do not count section pages in page numbers with s chap (§4.45). If there are around 10 slides, chapter covers are unnecessary.
   • Table column widths: If the column contents are of the same kind (time point, option, department), use <table class="eq"> to make them equal width, and do not let only the last column absorb the whitespace. Only when there is a description/bullet column, give the whitespace to that column.
   • When there is a maximum number of slides, the order of cutting: chapter covers/table of contents → body text duplicating the overall map → supplementary notes/appendix. Keep the cover, overall map, conclusion page, and back cover. List risks on the same slide as the countermeasures (§4.29).
3. Generate a draft:

   python3 scripts/new_deck.py --list                                   # 番号と型名（b01〜b27 基本／m01〜m35 追加）
   python3 scripts/new_deck.py --parts b01,b02,m05,b06,b09,b10 --title "資料名" -o mydeck.html
   

   The script performs CSS merging of both parts collections, unification of heading styles, and renumbering of pages. Do not copy by hand and assemble. After generation, replace placeholders (Text N / ラベル N / YYYY) with the actual content. Source line (.src・.source) is included by default, so remove it unless the material is one where sources should be placed (§4.47) (in principle, do not place it for sales proposals or regular meetings).
4. For pages that need graphs, draw them yourself instead of pouring them into table parts.
5. Adjustment: Split a table into two, rewrite the right column into a consequential form, rewrite parallel items with inconsistent granularity. For each one, question whether it can remain in its current form. Add each piece of feedback received as one line in slide-rules.md, and for measurable feedback, also make it a mechanical check (slide-rules §8 "Make feedback both a one-line rule and a mechanical check").
6. python3 scripts/check_deck.py mydeck.html → FAIL 0 (the "empty title" WARN for the cover, back cover, and chapter title pages is acceptable). Read through the list of output titles. Placeholders left in the body, titles left as type names, and text blocks packing in two or more sentences also become FAIL.
   • For decks shown outside the company, apply a list (kept outside the repository) of customer names, internal terms, and project codes written one word per line: python3 scripts/check_deck.py mydeck.html --forbid ~/.config/deck-forbidden-terms.txt. Also catch words left in HTML comments or attributes, and do not output the words themselves.
7. node scripts/check_layout.mjs mydeck.html → OK (if playwright is in a different location, point to it with PLAYWRIGHT_MODULE_DIR ). Pages with more than 40% of the layout area left blank also become FAIL. Grids with empty columns remaining and title sizes that differ between pages also become FAIL, and an element at the bottom that looks like a conclusion band appears as a WARN.
8. Fresh-eyes review: references/content-review-prompt.md Pass the instructions to another agent that has not been told how it was made, and have it read the deck files. Turn the feedback into an accept/reject table (accept / reject / hold + reason), fix only the accepted items, and rerun steps 6 and 7.
9. Convert to PDF and visually inspect all pages. Mechanical checks only look for overlaps, overflow, and rule violations. Bars being crushed, diagrams becoming empty, the lower half being empty, bad page breaks, and misaligned left and right bottom edges can only be found visually. You may fix part CSS on your own deck side (if you fix it, also reflect it in templates/). Look at all pages after converting them to images (do not convert only some pages to images and report "all pages confirmed"). In the report, write the numbers of the pages actually inspected.

   "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless --disable-gpu \
     --no-pdf-header-footer --print-to-pdf=mydeck.pdf mydeck.html
   

When PowerPoint (.pptx) is required

Finish materials in HTML. Convert to PPTX only when the user explicitly says "in PPTX" or "make it PowerPoint." Run all revision and review cycles in HTML, and convert only once at the end. HTML is faster both to fix and to mechanically check, and fixing in PPTX causes the content to diverge from the HTML. If revisions come after delivering the PPTX, fix the HTML and convert again. If there is no explicit request, deliver as PDF.

1. Complete steps 6–9 in HTML (mechanical check FAIL 0, fresh-eyes review, PDF visual inspection)
2. Conversion: python3 scripts/html_to_pptx.py mydeck.html → mydeck.pptx in the same folder (requires Node 22+, Chrome, andpip3 install python-pptx )
3. python3 scripts/check_deck.py mydeck.pptx Make it FAIL 0. Open it in PowerPoint (or export it to PDF) and visually inspect text wrapping and overlaps
4. If sending outside the company, delete the file properties (author, company name, etc.)

What conversion covers and its limits (details in slide-rules.md §8.6):

• Reproduced in an editable form: text (font, size, color, line spacing, wrap width, bullet formatting), fills and borders (rounded corners, clip-path polygons, CSS triangles), rules, tables (merged cells, cell fills, borders, padding, vertical writing)
• Becomes an image (text and numbers inside cannot be edited): SVG charts and diagrams, img, background images
• Fonts are replaced with Yu Gothic for Japanese gothic and Yu Mincho for mincho. Differences in character width can shift the line end by one character, so do not skip the visual check
• Not reproduced: rotation and transforms (CSS transform),::before/::after decorations drawn with (such as circled numbers with a background. The characters of line-head symbols are reproduced as bullet formatting). Do not use these in the parts, or fix them in PowerPoint after conversion

As a sample for building a PPTX by hand from scratch, assets/SuperTemplate_62type.pptx(62-type, all slides editable) is also provided.

Pages to insert into existing materials

When you are given a destination PowerPoint document (an internal standard deck, a proposal in progress), do not convert it; build directly on that document's master. A converted PPTX has its own fonts and layout, so it stands out when inserted (slide-rules §8.7). The rules for prose, table axes, and one message per slide stay the same.

1. Measure: python3 scripts/measure_deck.py house.pptx → house.skin.json(You can pass it as is even when the format is distributed as .potx). Read the summary, look at the document with your eyes, and correct the values
2. Build: examples/house_deck_example.py using as a model, build with scripts/deck_pptx.py . Do not write the font, background color, or page number on the slide / titles are placeholders / tables are text boxes + rules (table()) / colors are the document's theme colors
3. python3 scripts/check_deck.py pages.pptx --house house.skin.json → FAIL 0。Always run before opening in PowerPoint(if you make it open an invalid file, a repair dialog remains in the user's PowerPoint)
4. Visually check every page (the method is the same as the visual QA in slide-rules §8)
5. Hand over only the file of the pages to insert. It is the user who puts it into the document ("use destination theme")

Annotation for use of this skill

The sentence "This document was created with consulting-pptx-skill (github.com/carnot-tech/consulting-pptx-skill)" is included by default in the source line at the bottom left of the back cover (b10). It can be placed only inthe source line of the final page. If the tool name appears on other pages, check_deck.py will FAIL it (a format that can be shown to clients). For decks that do not use a back cover, add it to the source line of the final page.

Grow the skill (updates, your own rules, PRs)

This skill improves through the rules and the feedback of people who use the mechanical checks. Do the following three as part of the work.

1. Pull in the latest. At the start of the session, if the skill folder is a git clone, git fetch and origin/main if it is behind, ask once, "Do you want to pull in the latest version of the skill?" (roughly once a week).git pull to pull it in. The user's changes go in local/ , so there is no conflict. If you are editing the main files directly, first move those diffs to local/ or a PR
2. Put your own rules in local/ . If a user points out "this is how we do it at our company," do not rewrite the main references/slide-rules.md , but add one line to local/slide-rules.local.md . Put customer names and project codes in local/forbid.txt and check them with --forbid . Your own parts collection, the destination materials,skin.json は local/templates/
3. Turn feedback that can be generalized into a PR. During work, if you encounter a false positive or missed detection in the main rules, or a new point that would work for any organization, after delivery suggest once, "Would you like to submit this fix to the main repo as a PR?" How to submit it is CONTRIBUTING.md(one line of rules +check_deck judgment + a test that FAILs before the fix and passes after the fix).Before creating a PR, read CONTRIBUTING.md "Things not to include in a PR": customer names, project codes, amounts, assignee names, actual project files,skin.json must not be included in diffs, commit messages, or PR descriptions (context from projects mentioned in conversation easily gets mixed in, so review the diff and description before pushing). Rules that are one company's preference or for which you cannot write a rationale go to local/ , not the main repo. Rules that change defaults should be written conditionally. If the user agrees, go as far as gh pr create . If they decline, do not propose it again until the next session

Colors and typefaces

The defaults for both parts collections are the same warm color scheme (off-white background, dark brown text, brown accents. Gothic body text, Mincho headings). Tokens are at the beginning of each file's <style> opening :root. If you change one, match the other as well. Navy values are included as comments. Do not change colors that carry meaning (such as the red of ✕). Keep the distinction between the two series to two colors: main color × gray. Screenshots of the product UI are unprocessed.