Skip to content

AGENTS.md

Latest commit

 

History

History
74 lines (57 loc) · 3.78 KB

AGENTS.md

File metadata and controls

74 lines (57 loc) · 3.78 KB

AGENTS.md

Project Overview

slides-grab is an agent-first PPT framework. AI agents write HTML slides directly, and a 3-stage pipeline (Planning → Design → Conversion) produces high-quality HTML/PDF output plus experimental / unstable PPTX and Figma export.

Core philosophy: HTML is the design language. Agents write HTML/CSS directly. The framework provides templates, validation, and conversion tools — not abstractions over HTML.

Key Paths

Path Purpose
skills/slides-grab-plan/SKILL.md Codex plan skill (outline workflow)
skills/slides-grab-design/SKILL.md Codex design skill (HTML slides + viewer loop)
skills/slides-grab-export/SKILL.md Codex conversion skill (PDF + experimental / unstable HTML→PPTX/Figma)
skills/*/references/ Published reference docs bundled with installable skills
scripts/build-viewer.js Builds viewer.html from slide-*.html files in selected --slides-dir
src/html2pptx.cjs Packaged HTML→PPTX conversion runtime
src/pptx-raster-export.cjs Packaged raster PPTX export runtime behind convert.cjs
slides/ (default) or custom --slides-dir path Generated HTML slide workspace
slide-outline.md Presentation outline (generated by organizer-agent)
package.json Node.js dependencies (playwright, sharp, pptxgenjs)
convert.cjs Legacy experimental / unstable HTML→PPTX converter

Slide Specifications

  • Size: 720pt × 405pt (16:9)
  • Font: Pretendard (CDN: https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css)
  • Text tags: Only <p>, <h1>-<h6>, <ul>, <ol>, <li> — never put text directly in <div> or <span>
  • Colors in CSS: Use # prefix (#FF0000)
  • Colors in PptxGenJS: No # prefix (FF0000)
  • No CSS gradients: Rasterize to PNG with Sharp instead

Agent System

Agent Role Model Tools
organizer-agent Structure presentation outline Claude Sonnet Read, Write, Edit
research-agent Web research and data gathering Claude Sonnet WebSearch, WebFetch, Read, Grep, Glob

Skill System

Skill Role Stage
slides-grab-plan Codex Stage 1 outline planning Stage 1
slides-grab-design Codex Stage 2 slide design/review Stage 2
slides-grab-export Codex Stage 3 conversion (PDF + experimental / unstable PPTX/Figma) Stage 3

Dependencies

Node.js (package.json)

  • pptxgenjs ^3.12.0 — PowerPoint generation
  • playwright ^1.40.0 — Browser automation (Chromium)
  • sharp ^0.33.0 — Image processing

Python

  • markitdown — Markdown conversion
  • defusedxml — XML parsing
  • pillow — Image processing

System (optional)

  • LibreOffice (soffice) — PPTX thumbnail generation
  • Poppler (pdftoppm) — PDF to image conversion

Rules for Agents

  1. Do not modify SKILL.md philosophy sections — design principles, rules, and constraints must be preserved when editing SKILL.md files.
  2. All new scripts go in scripts/ unless they are skill-specific (then skills/<name>/scripts/).
  3. Use ES modules — import/export syntax, not require(). Exception: .cjs files for CommonJS compat.
  4. JavaScript, not TypeScript — Use JSDoc for type hints if needed.
  5. Test scripts by running them — Use node scripts/<name>.js to verify they work.
  6. Playwright browser reuse — When processing multiple slides, keep the browser instance open and reuse it across slides for performance.
  7. Environment variables for API keys — GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY. Never hardcode keys.
  8. CSS-safe HTML — All text in semantic tags (<p>, <h1>-<h6>, <ul>, <ol>), backgrounds only on <div> elements.
⚡