revise-ppt

revise-ppt

Description

English: Interactively revise slides through a 3-step interview workflow: select target slides, describe changes per slide, apply edits to the markdown source and regenerate the PPTX. The markdown file is the single source of truth — all changes are applied to markdown first. Optionally renders PNG slide previews via LibreOffice headless; falls back to markdown text when LibreOffice is unavailable. Revision state is tracked in a JSON file (<stem>_revision_state.json) for resumable multi-round editing.

한국어: 3단계 인터뷰 워크플로우를 통해 슬라이드를 대화형으로 수정합니다: 수정 대상 슬라이드 선택, 슬라이드별 변경 사항 설명, 마크다운 소스 수정 후 PPTX 재생성. 마크다운 파일이 단일 진실 공급원입니다 — 모든 변경 사항은 먼저 마크다운에 적용됩니다. LibreOffice headless를 통한 PNG 슬라이드 미리보기를 제공하며, LibreOffice가 없을 경우 마크다운 텍스트로 폴백합니다. 수정 상태는 JSON 파일(<stem>_revision_state.json)에 추적되어 다중 라운드 편집을 재개할 수 있습니다.

Interface

/revise-ppt <markdown_file> [--pptx <pptx_file>] [--output <output.pptx>] [--lang ko|en]

Executed via: python skills/revise-ppt/revise_ppt.py

Parameters

Parameter	Required	Default	Description
markdown_file	✅	—	Path to the markdown source file to revise (the single source of truth)
--pptx	❌	derived from frontmatter.fname or <markdown>.pptx	Path to the existing PPTX file used for PNG preview generation
--output, -o	❌	frontmatter.fname or <markdown>.pptx	Output path for the regenerated PPTX (passed to generate-ppt)
--lang, -l	❌	$LANG or en	Language for interview prompts (ko | en)

Inputs

Input	Type	Description
markdown_file	File path	Markdown source file to revise. Must exist and contain YAML frontmatter with a template: field.
--pptx	File path (optional)	Existing PPTX used only for PNG preview generation via LibreOffice. If absent, LibreOffice preview is skipped and text fallback is used.
Interactive prompts	stdin	User answers to the 3-step interview (slide selection, revision instructions).

Returns / Output Artifacts

The markdown_file is updated in place with the requested changes. A new PPTX is generated by delegating to generate-ppt.

Exit Codes

Code	Meaning
0	Success (including graceful Ctrl-C and "no slides selected" exit)
1	Error (file not found, generate-ppt subprocess failure, unexpected exception)

Success markers (printed to stdout, machine-checkable):

[agent4ppt] PPTX generated → <path>      ← emitted by the generate-ppt subprocess
Revision complete! Updated file: <path>   ← emitted by revise-ppt
  Markdown updated: <markdown_file>
  PPTX regenerated: <pptx_path>

Verifiable artifacts (all at deterministic, predictable paths):

Artifact	Path	When present
Updated markdown	<markdown_file> (in place)	Always after Step 3
Regenerated PPTX	<output> (from --output or frontmatter fname)	Always after Step 3
Revision state JSON	<markdown_stem>_revision_state.json (sibling of markdown)	After Step 1 and after Step 3
Step 1 previews (PNG)	<pptx_stem>_previews/slide_N.png	When LibreOffice is available
Step 1 previews (text)	<pptx_stem>_previews/slide_N.txt	When LibreOffice is unavailable

Artifact validation commands:

# After running revise-ppt in a pipeline (non-interactive), verify:
grep -q "Revision complete" output.txt    && echo "PASS: revision completed"
grep -q "\[agent4ppt\] PPTX generated"  output.txt && echo "PASS: PPTX generated"
python -c "
import json, sys
state = json.load(open('slides_revision_state.json'))
assert 'markdown_path' in state
assert 'pptx_path' in state
assert isinstance(state.get('iteration_count'), int)
print('PASS: revision state valid, iteration_count =', state['iteration_count'])
"
# Preview artifacts at deterministic path:
ls my_presentation_previews/slide_1.*   # PNG or TXT, verifiable

Workflow — 3 Steps

Step 1 — Select Target Slides

The skill displays an overview of all slides (count, layout per slide). If LibreOffice is available, PNG previews are generated to a deterministic path (<pptx_stem>_previews/) and their paths are printed.

=== Slide Revision Workflow ===
Your presentation has 8 slide(s).

STEP 1: Which slides would you like to revise?
Enter slide numbers separated by commas (e.g. 1,3,5), a range (e.g. 2-4), or 'all':
> 2,4-6

Selection syntax:

Input	Meaning
1,3,5	Slides 1, 3, and 5
2-4	Slides 2, 3, and 4
2~4	Same as 2-4
all	All slides
*	All slides
모두	All slides (Korean alias)

Step 2 — Describe Changes Per Slide

For each selected slide, the current slide content is displayed (PNG path or markdown text summary), then the user is prompted for revision instructions.

STEP 2: Let's go through each selected slide.

--- Slide 2 (layout: 1) ---
[Preview: /path/to/<pptx_stem>_previews/slide_2.png]

Describe your changes. Examples:
  - Change title to 'New Title'
  - Replace bullet 2 with 'Updated content'
  - Change layout to layout 3
  - Replace chart with new data
  - Add image path/to/image.png
Your instructions for slide 2:
> Change title to 'Updated Results'

Supported instruction patterns (applied automatically):

Pattern	Example	Effect
Change title	Change title to 'New Title'	Replaces title placeholder heading
Change layout	Change layout to 3	Updates > layout: N in the section
Free-form	Any other text	Appended as <!-- REVISION: ... --> comment for manual review

Step 3 — Apply and Regenerate

STEP 3: Applying changes and regenerating PPTX...
  Applying changes to slide 2...
  Applying changes to slide 4...
Regenerating PPTX...
[agent4ppt] PPTX generated → ./my_presentation.pptx

Revision summary (2 slide(s) modified):
  Slide 2: Change title to 'Updated Results'
  Slide 4: Change layout to 3

Revision complete! Updated file: ./my_presentation.pptx
  Markdown updated: ./slides.md
  PPTX regenerated: ./my_presentation.pptx

Revision State Tracking

A JSON state file <markdown_stem>_revision_state.json is created/updated after Step 1 and after Step 3.

{
  "markdown_path": "/absolute/path/to/slides.md",
  "pptx_path": "/absolute/path/to/output.pptx",
  "iteration_count": 1
}

• iteration_count increments after each successful revision cycle
• State persists across multiple invocations for resumable editing

PNG Preview

When LibreOffice is installed, slide previews are generated with:

libreoffice --headless --convert-to png --outdir <pptx_stem>_previews/ presentation.pptx

Preview artifacts are written to a deterministic directory (<pptx_stem>_previews/) next to the PPTX file — verifiable without prior knowledge of temporary directory names.

If LibreOffice is not found, a plain-text .txt file is written to the same deterministic path with a text summary of the slide's placeholder content.

Install LibreOffice:

# Ubuntu / Debian
sudo apt install libreoffice

# macOS (Homebrew)
brew install --cask libreoffice

Error Handling

Condition	Behaviour
markdown_file not found	Exits 1, prints error to stderr
No slides selected	Exits 0, prints advisory message
LibreOffice not found	Warning printed, falls back to text preview
generate-ppt subprocess fails	Stderr from subprocess printed, exits 1
KeyboardInterrupt (Ctrl-C)	Exits 0 with [agent4ppt] Cancelled.
Missing dependencies	Auto-installs via pip (with PEP 668 fallback); if still missing, exits 1 with bilingual install instructions to stderr
PPTX file not found	Warning printed to stderr; continues with markdown text previews (graceful degradation, no exit)
PPTX file inaccessible (permission / lock)	Warning + recovery guidance printed to stderr; continues with text previews (graceful degradation, no exit)

---

PPTX File Accessibility Fallback

The --pptx file is used only for PNG preview generation — the markdown source is the single source of truth. When the PPTX file cannot be accessed, the skill degrades gracefully rather than aborting:

Scenario	Detection	Behaviour
PPTX path not found	Path.exists() returns False	Warning on stderr; text previews used for all slides
PPTX read permission denied	OSError on open("rb")	Warning + recovery steps on stderr; text previews used
PPTX file locked by another process	OSError on open("rb")	Warning + recovery steps on stderr; text previews used

Key design principle: PPTX inaccessibility is a non-fatal condition. The revision workflow (Step 1 → 2 → 3) continues to completion using markdown text previews. The markdown source is never blocked by PPTX availability.

Warning Messages (English)

When PPTX is not found:

[agent4ppt] PPTX file not found: /path/to/file.pptx
[agent4ppt] Proceeding with markdown text preview (no PNG).

When PPTX is inaccessible (permission / lock):

[agent4ppt] Cannot access PPTX file: /path/to/file.pptx — [Errno 13] Permission denied
[agent4ppt] Falling back to markdown text preview.
[agent4ppt] Recovery options:
[agent4ppt]   1. Check file permissions: chmod 644 "/path/to/file.pptx"
[agent4ppt]   2. Check for file locks: lsof "/path/to/file.pptx" then kill the locking process
[agent4ppt]   3. Specify a different path: --pptx <correct_path>

경고 메시지 (한국어)

PPTX 파일을 찾을 수 없는 경우:

[agent4ppt] PPTX 파일을 찾을 수 없습니다: /path/to/file.pptx
[agent4ppt] PNG 미리보기 없이 마크다운 텍스트 미리보기로 진행합니다.

PPTX 파일 접근 불가 (권한 / 잠금):

[agent4ppt] PPTX 파일에 접근할 수 없습니다: /path/to/file.pptx — [Errno 13] Permission denied
[agent4ppt] 마크다운 텍스트 미리보기로 대체합니다.
[agent4ppt] 복구 방법:
[agent4ppt]   1. 파일 권한 확인: chmod 644 "/path/to/file.pptx"
[agent4ppt]   2. 파일 잠금 해제: lsof "/path/to/file.pptx" 으로 확인 후 해당 프로세스 종료
[agent4ppt]   3. 다른 경로 지정: --pptx <올바른_경로>

Recovery Guide / 복구 가이드

Option 1 — Fix file permissions:

# Check current permissions
ls -la /path/to/file.pptx

# Grant read permissions
chmod 644 /path/to/file.pptx
# or for stricter environments:
chmod u+r /path/to/file.pptx

Option 2 — Identify and release file locks:

# Find processes holding the file open
lsof /path/to/file.pptx

# On macOS, use:
lsof +D /path/to/directory/

# Close the application holding the lock, then retry

Option 3 — Specify a different PPTX path:

# Point to an accessible copy or previously generated PPTX
/revise-ppt slides.md --pptx /backup/file.pptx

# Or omit --pptx entirely to auto-derive from frontmatter (text preview mode)
/revise-ppt slides.md

Option 4 — Run without PPTX (text preview mode):

# Text preview works fully without any PPTX file
# All revision and regeneration features are still available
/revise-ppt slides.md
# PNG previews are skipped; markdown text summaries are shown instead

Agent Wrapper for PPTX Accessibility Check

When invoking this skill programmatically, agents should handle PPTX accessibility failures proactively:

# Check PPTX accessibility before invoking skill
PPTX_FILE="my_presentation.pptx"
if [ -f "$PPTX_FILE" ] && [ -r "$PPTX_FILE" ]; then
  python skills/revise-ppt/revise_ppt.py slides.md --pptx "$PPTX_FILE"
else
  # PPTX not accessible — run in text-preview mode (still fully functional)
  echo "[agent4ppt] PPTX not accessible; running in text-preview mode"
  python skills/revise-ppt/revise_ppt.py slides.md
fi

Examples

# Standard interactive revision (auto-detects PPTX from frontmatter fname)
/revise-ppt slides.md

# Provide PPTX path explicitly for PNG preview generation
/revise-ppt slides.md --pptx final_presentation.pptx

# Specify an explicit output PPTX path
/revise-ppt slides.md --output revised_v2.pptx

# Korean prompts
/revise-ppt slides.md --lang ko

Dependencies

Package	Min Version	Required	Purpose
python-pptx	>= 0.6.21	✅	PPTX slide manipulation and regeneration
pyyaml	>= 6.0	✅	YAML frontmatter parsing in markdown files
markdown-it-py	>= 3.0	✅	Markdown content parsing
libreoffice	any	❌ (optional)	PNG slide preview generation
anthropic	any	❌ (optional)	Claude-powered intelligent slide revision

Dependency Check & Auto-Install Fallback

The skill performs an automatic dependency check on startup, before any user interaction or file I/O begins. If required packages are missing, it follows a multi-step, 3-strategy fallback chain before exiting.

Fallback Chain (executed in revise_ppt.py::_check_dependencies())

Step	Action	Condition
1	Import check	Try import pptx, import yaml, import markdown_it. If all succeed → proceed normally.
2	Auto-install	If any package is missing, attempt pip install using three strategies in order: plain install → --user install → --break-system-packages (PEP 668 fallback). Each strategy has a 120-second timeout.
3	Re-verify	After auto-install, re-check imports. If successful → proceed normally.
4	Guided error	If auto-install fails, print bilingual (Korean/English) actionable install instructions to stderr and exit with code 1.

Check logic (executed at module load time — before any CLI argument parsing):

# Runs in revise_ppt.py::_check_dependencies(), called at module load (line 165)

# Step 1 — collect missing packages
missing: list[str] = []
for imp_name, pip_name, _ver in _REQUIRED_DEPS:
    try:
        __import__(imp_name)
    except ImportError:
        missing.append(pip_name)

# Step 2 — auto-install using 3-strategy chain
if missing:
    pkg_specs = [f"{name}>={ver}" for _, name, ver in _REQUIRED_DEPS if name in missing]
    base_cmd = [sys.executable, "-m", "pip", "install", *pkg_specs]
    strategies = [
        base_cmd,                                    # Strategy 1: plain (venvs)
        base_cmd + ["--user"],                       # Strategy 2: user-level
        base_cmd + ["--break-system-packages"],      # Strategy 3: PEP 668
    ]
    for cmd in strategies:
        result = subprocess.run(cmd, timeout=120)
        if result.returncode == 0:
            break  # strategy succeeded

# Step 3 — re-verify after install attempt
missing = _find_missing()
if not missing:
    print("[agent4ppt] Dependencies installed successfully.", file=sys.stderr)
    # proceed normally...

# Step 4 — guided error if still missing
if missing:
    # print bilingual error with 3 manual options → sys.exit(1)

Auto-install strategies (tried in order, each with a 120-second timeout via subprocess.check_call):

1. python -m pip install "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"
   # Standard install: works in virtual environments and most managed envs

2. python -m pip install --user "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"
   # User-level install: for system Python without an active venv

3. python -m pip install --break-system-packages "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"
   # PEP 668 fallback: for externally-managed Python (Ubuntu 23.04+, Homebrew Python)

Note: sys.executable is used to ensure the same Python interpreter's pip is invoked, matching the interpreter running the skill. Each strategy is tried in order; the first to succeed terminates the chain.

Bilingual messages:

• Language is auto-detected from $LANG environment variable (ko → Korean, otherwise English) before argparse runs, so messages appear even if CLI parsing fails.
• All dependency messages are printed to stderr so they don't interfere with stdout artifacts (success markers, JSON state, etc.).

Example output (auto-install success):

[agent4ppt] Missing dependencies detected: python-pptx, pyyaml
[agent4ppt] Attempting automatic installation...
[agent4ppt] Dependencies installed successfully.

한국어 출력 예시 (자동 설치 성공):

[agent4ppt] 누락된 의존성 발견: python-pptx, pyyaml
[agent4ppt] 자동 설치를 시도합니다...
[agent4ppt] 의존성 자동 설치 완료.

Example output (auto-install failure — manual guidance):

[agent4ppt] Auto-install failed for: python-pptx

  Install manually using one of these methods:

  Option 1 (recommended — virtual environment):
    python3 -m venv .venv && source .venv/bin/activate
    pip install "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"

  Option 2 (user-level install):
    pip install --user "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"

  Option 3 (project installer script):
    bash scripts/install.sh

한국어 출력 예시 (자동 설치 실패 시):

[agent4ppt] 의존성 자동 설치 실패: python-pptx

  다음 방법 중 하나로 수동 설치하세요:

  방법 1 (권장 — 가상환경):
    python3 -m venv .venv && source .venv/bin/activate
    pip install "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"

  방법 2 (사용자 디렉토리):
    pip install --user "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"

  방법 3 (프로젝트 설치 스크립트):
    bash scripts/install.sh

Fallback Resolution Order

When auto-install is skipped or fails, the following manual resolution methods are available in priority order:

Priority	Method	Command	When to use
1	Project installer (recommended)	bash scripts/install.sh	First-time setup; handles venv detection, --user fallback, and --break-system-packages for PEP 668
2	Direct pip install	pip install "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"	Inside an active virtual environment
3	User-level pip	pip install --user "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"	System Python without venv
4	uv (fast alternative)	uv pip install "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"	When uv is available
5	Check-only (dry run)	bash scripts/install.sh --check-only	CI pipelines that should fail rather than install

Auto-Install Hint for Agents

When invoking this skill programmatically, agents should attempt auto-recovery on dependency failure:

# Recommended agent wrapper pattern:
python skills/revise-ppt/revise_ppt.py slides.md 2>err.log
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ] && grep -q "Auto-install failed\|의존성 자동 설치 실패\|Missing dependencies" err.log; then
  # Dependency failure — run the project installer and retry once
  bash scripts/install.sh --no-register
  python skills/revise-ppt/revise_ppt.py slides.md
fi

Manual Installation

# Install required dependencies directly
pip install "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"

# Or use the project installer (recommended)
bash scripts/install.sh

Verifying Dependencies

# Quick verification (no install, exit 1 if any dependency is missing):
bash scripts/install.sh --check-only

# Or inline Python check — all 3 required packages:
python -c "import pptx, yaml, markdown_it; print('agent4ppt revise-ppt dependencies OK')"

# Check individual packages:
python -c "import pptx; print('python-pptx OK')"
python -c "import yaml; print('pyyaml OK')"
python -c "import markdown_it; print('markdown-it-py OK')"

Language Support

• --lang ko or LANG=ko → Korean interview prompts
• --lang en or LANG=en → English interview prompts (default)

Precedence: frontmatter.lang > --lang flag > LANG environment variable > default (en)