anthropics · spm1001 · Dec 15, 2025
diff --git a/skills/pptx/SKILL.md b/skills/pptx/SKILL.md
@@ -10,6 +10,18 @@ license: Proprietary. LICENSE.txt has complete terms
 
 A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
 
+## Choosing Your Approach
+
+| Task | Approach | When to use |
+|------|----------|-------------|
+| Read/analyze | markitdown or XML | Extract text, inspect structure |
+| Create from scratch | html2pptx | Standard layouts, HTML/CSS handles positioning |
+| Create from scratch | Direct PptxGenJS | Fine-grained control, calculated positions, algorithmic layouts |
+| Edit existing | OOXML | Modify XML directly |
+| Create from template | rearrange → inventory → replace | Follow existing design |
+
+**html2pptx vs Direct PptxGenJS:** Start with html2pptx. If it fights your layout or you need precise coordinate control, drop down to direct PptxGenJS. See [Direct PptxGenJS Reference](references/direct-pptxgenjs.md).
+
 ## Reading and analyzing content
 
 ### Text extraction
@@ -63,6 +75,13 @@ When creating a new PowerPoint presentation from scratch, use the **html2pptx**
 - ✅ Ensure readability: strong contrast, appropriately sized text, clean alignment
 - ✅ Be consistent: repeat patterns, spacing, and visual language across slides
 
+**Design Constraints** (apply to all creation workflows):
+- **Stay on-palette**: Extract colors from template theme, don't introduce new ones
+- **Stay on-font**: Use template fonts or web-safe fallbacks that won't substitute
+- **Minimize objects**: One rich object beats layered simple objects (text box with border, not shape + text overlay)
+- **Validate visually**: Render thumbnails to catch overlap/cutoff problems coordinates won't reveal
+- **Internal harmony**: When consolidating objects, ensure properties work together (e.g., `inset` keeps text off borders)
+
 #### Color Palette Selection
 
 **Choosing colors creatively**:
@@ -95,51 +114,7 @@ When creating a new PowerPoint presentation from scratch, use the **html2pptx**
 
 #### Visual Details Options
 
-**Geometric Patterns**:
-- Diagonal section dividers instead of horizontal
-- Asymmetric column widths (30/70, 40/60, 25/75)
-- Rotated text headers at 90° or 270°
-- Circular/hexagonal frames for images
-- Triangular accent shapes in corners
-- Overlapping shapes for depth
-
-**Border & Frame Treatments**:
-- Thick single-color borders (10-20pt) on one side only
-- Double-line borders with contrasting colors
-- Corner brackets instead of full frames
-- L-shaped borders (top+left or bottom+right)
-- Underline accents beneath headers (3-5pt thick)
-
-**Typography Treatments**:
-- Extreme size contrast (72pt headlines vs 11pt body)
-- All-caps headers with wide letter spacing
-- Numbered sections in oversized display type
-- Monospace (Courier New) for data/stats/technical content
-- Condensed fonts (Arial Narrow) for dense information
-- Outlined text for emphasis
-
-**Chart & Data Styling**:
-- Monochrome charts with single accent color for key data
-- Horizontal bar charts instead of vertical
-- Dot plots instead of bar charts
-- Minimal gridlines or none at all
-- Data labels directly on elements (no legends)
-- Oversized numbers for key metrics
-
-**Layout Innovations**:
-- Full-bleed images with text overlays
-- Sidebar column (20-30% width) for navigation/context
-- Modular grid systems (3×3, 4×4 blocks)
-- Z-pattern or F-pattern content flow
-- Floating text boxes over colored shapes
-- Magazine-style multi-column layouts
-
-**Background Treatments**:
-- Solid color blocks occupying 40-60% of slide
-- Gradient fills (vertical or diagonal only)
-- Split backgrounds (two colors, diagonal or vertical)
-- Edge-to-edge color bands
-- Negative space as a design element
+For design inspiration (geometric patterns, borders, typography, charts, layouts, backgrounds), see [Visual Details Options](references/visual-details-options.md).
 
 ### Layout Tips
 **When creating slides with charts or tables:**

diff --git a/skills/pptx/references/direct-pptxgenjs.md b/skills/pptx/references/direct-pptxgenjs.md
@@ -0,0 +1,173 @@
+# Direct PptxGenJS Reference
+
+When html2pptx doesn't give you enough control, work directly with PptxGenJS coordinates.
+
+## When to Use Direct Control
+
+| Situation | Use html2pptx | Use Direct PptxGenJS |
+|-----------|---------------|----------------------|
+| Standard text layouts | ✓ | |
+| Bullet lists, tables | ✓ | |
+| Precise coordinate placement | | ✓ |
+| Algorithmic/calculated positions | | ✓ |
+| Collision detection needed | | ✓ |
+| html2pptx fighting your layout | | ✓ |
+
+## Core Principle: Object Minimization
+
+**Prefer fewer, richer objects over layered simple objects.**
+
+```javascript
+// ✗ WORSE - two objects, alignment can drift
+slide.addShape(pptx.shapes.ROUNDED_RECTANGLE, {
+  x: 1, y: 1, w: 3, h: 1,
+  fill: { color: 'FFFFFF' },
+  line: { color: 'F5D76E', width: 0.75 }
+});
+slide.addText('Quote text', { x: 1, y: 1, w: 3, h: 1 });
+
+// ✓ BETTER - single object with all properties
+slide.addText('Quote text', {
+  x: 1, y: 1, w: 3, h: 1,
+  fill: { color: 'FFFFFF' },
+  line: { color: 'F5D76E', width: 0.75 },
+  rectRadius: 0.04,  // rounded corners
+  inset: 0.08        // internal padding
+});
+```
+
+One object means:
+- User can select/edit as a unit in PowerPoint
+- No alignment drift between layers
+- Cleaner XML, smaller file
+- Simpler to position programmatically
+
+When you consolidate to a single object, ensure internal properties work together (e.g., `inset` keeps text from touching the border).
+
+## API Gotchas
+
+### Internal Padding: Use `inset`, Not `margin`
+
+```javascript
+// ✗ WRONG - fails silently, no padding applied
+slide.addText(text, { margin: 0.1 });
+
+// ✓ CORRECT - 0.1 inches padding on all sides
+slide.addText(text, { inset: 0.1 });
+```
+
+PowerPoint UI calls these "internal margins" but PptxGenJS uses `inset`.
+
+### Text AutoFit Options
+
+| PowerPoint Setting | PptxGenJS Property | Behavior |
+|-------------------|-------------------|----------|
+| Do not Autofit | (default) | Text may overflow |
+| Shrink text on overflow | `shrinkText: true` | Reduces font size to fit |
+| Resize shape to fit text | `autoFit: true` | Expands box to fit content |
+
+```javascript
+// Shrink text if it overflows
+slide.addText(longText, { shrinkText: true, ...position });
+
+// Expand box to fit text
+slide.addText(longText, { autoFit: true, ...position });
+```
+
+### Borders on Text Boxes
+
+Use `line` property for borders, `rectRadius` for rounded corners:
+
+```javascript
+slide.addText('Bordered text', {
+  x: 1, y: 1, w: 4, h: 1,
+  fill: { color: 'FFFFFF' },
+  line: { color: 'C5A880', width: 1 },  // 1pt gold border
+  rectRadius: 0.05,                      // rounded corners (inches)
+  inset: 0.1                             // keep text off the border
+});
+```
+
+## Text Dimension Estimation
+
+To size boxes before PowerPoint's autofit, estimate text dimensions:
+
+```javascript
+// Approximate character width (Georgia font)
+const charWidth = fontSize * 0.007;  // inches per character
+
+// Estimate lines needed
+const charsPerLine = Math.floor(boxWidth / charWidth);
+const linesNeeded = Math.ceil(text.length / charsPerLine);
+
+// Line height
+const lineHeight = fontSize * 0.017;  // inches per line
+const estimatedHeight = linesNeeded * lineHeight;
+```
+
+These are rough estimates - use `autoFit: true` or `shrinkText: true` to let PowerPoint adjust.
+
+## Visual Validation Workflow
+
+Coordinates don't reveal overlap or cutoff problems. Always validate visually:
+
+```bash
+# Generate thumbnail grid
+python scripts/thumbnail.py output.pptx workspace/check --cols 4
+
+# Then read and inspect the image
+```
+
+The feedback loop: **code → render → look → adjust**
+
+For complex coordinate work, prototype in SVG first (see below).
+
+## SVG Prototyping Pattern
+
+For algorithmic layouts, prototype in SVG before converting to PptxGenJS:
+
+1. **Write algorithm generating SVG** - faster iteration than regenerating .pptx
+2. **Render to PNG**: `rsvg-convert -w 1280 -h 720 input.svg -o /tmp/test.png`
+3. **Inspect and iterate** until layout works
+4. **Port to PptxGenJS** - convert pixels to inches: `px / 96`
+
+SVG iteration is ~10x faster than PPTX generation. Once the algorithm works, translating to PptxGenJS is mechanical.
+
+## Example: Calculated Placement with Collision Detection
+
+```javascript
+const pptxgen = require('pptxgenjs');
+const pptx = new pptxgen();
+
+// Track placed objects for collision detection
+const placed = [];
+
+function overlaps(a, b, padding = 0.1) {
+  return !(a.x + a.w + padding < b.x ||
+           b.x + b.w + padding < a.x ||
+           a.y + a.h + padding < b.y ||
+           b.y + b.h + padding < a.y);
+}
+
+function placeBox(slide, text, preferredX, preferredY, w, h) {
+  const box = { x: preferredX, y: preferredY, w, h };
+
+  // Adjust if overlapping existing boxes
+  for (const existing of placed) {
+    if (overlaps(box, existing)) {
+      box.y = existing.y + existing.h + 0.2;  // Move below
+    }
+  }
+
+  placed.push(box);
+
+  slide.addText(text, {
+    x: box.x, y: box.y, w: box.w, h: box.h,
+    fill: { color: 'FFFFFF' },
+    line: { color: 'F5D76E', width: 0.75 },
+    inset: 0.08,
+    fontSize: 10,
+    valign: 'middle'
+  });
+}
+```
diff --git a/skills/pptx/references/visual-details-options.md b/skills/pptx/references/visual-details-options.md
@@ -0,0 +1,49 @@
+# Visual Details Options
+
+Design options to spark creativity when creating presentations.
+
+## Geometric Patterns
+- Diagonal section dividers instead of horizontal
+- Asymmetric column widths (30/70, 40/60, 25/75)
+- Rotated text headers at 90° or 270°
+- Circular/hexagonal frames for images
+- Triangular accent shapes in corners
+- Overlapping shapes for depth
+
+## Border & Frame Treatments
+- Thick single-color borders (10-20pt) on one side only
+- Double-line borders with contrasting colors
+- Corner brackets instead of full frames
+- L-shaped borders (top+left or bottom+right)
+- Underline accents beneath headers (3-5pt thick)
+
+## Typography Treatments
+- Extreme size contrast (72pt headlines vs 11pt body)
+- All-caps headers with wide letter spacing
+- Numbered sections in oversized display type
+- Monospace (Courier New) for data/stats/technical content
+- Condensed fonts (Arial Narrow) for dense information
+- Outlined text for emphasis
+
+## Chart & Data Styling
+- Monochrome charts with single accent color for key data
+- Horizontal bar charts instead of vertical
+- Dot plots instead of bar charts
+- Minimal gridlines or none at all
+- Data labels directly on elements (no legends)
+- Oversized numbers for key metrics
+
+## Layout Innovations
+- Full-bleed images with text overlays
+- Sidebar column (20-30% width) for navigation/context
+- Modular grid systems (3×3, 4×4 blocks)
+- Z-pattern or F-pattern content flow
+- Floating text boxes over colored shapes
+- Magazine-style multi-column layouts
+
+## Background Treatments
+- Solid color blocks occupying 40-60% of slide
+- Gradient fills (vertical or diagonal only)
+- Split backgrounds (two colors, diagonal or vertical)
+- Edge-to-edge color bands
+- Negative space as a design element