parse-ppt-template

parse-ppt-template

Description

English: Parse a PPTX template file and generate a markdown template with placeholder annotations. Each slide's placeholders are identified by python-pptx idx-based indexing and annotated with <!-- ph:idx type:TYPE --> comments. Spatial layout metadata (position, size) is embedded as informational comments. The generated markdown is the canonical document — template_path in frontmatter is the sole authoritative reference to the source PPTX.

한국어: PPTX 템플릿 파일을 파싱하여 플레이스홀더 주석이 포함된 마크다운 템플릿을 생성합니다. 각 슬라이드의 플레이스홀더는 python-pptx idx 기반으로 식별되며 <!-- ph:idx type:TYPE --> 주석으로 표시됩니다. 공간 레이아웃 메타데이터(위치, 크기)는 정보성 주석으로 포함됩니다. 생성된 마크다운이 정식 문서이며, frontmatter의 template_path는 원본 PPTX에 대한 유일한 권위 있는 참조입니다.

Interface

/parse-ppt-template <pptx_file> [--output <output.md>] [--lang ko|en] [--layouts-only]

Executed via: python skills/parse-ppt-template/parse_template.py

Parameters

Parameter	Required	Default	Description
pptx_file	✅	—	Path to the source PPTX template file
--output, -o	❌	<input>.md	Output path for the generated markdown template
--lang, -l	❌	$LANG or en	Language for guide comments in the output (ko | en)
--layouts-only	❌	false	Generate one section per layout definition instead of per slide. Useful when the template has no slide content yet.

Inputs

Input	Type	Description
pptx_file	File path	A valid PPTX file readable by python-pptx. Must exist on disk.

Returns / Output Artifacts

A markdown file written to --output (or <input>.md by default).

Exit Codes

Code	Meaning
0	Success — output written and all verification checks passed
1	Input / IO error (file not found, missing dependency, unreadable PPTX)
2	Verification failure — output was written but failed one or more structural invariant checks

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

[agent4ppt] Markdown template written → <path>
[agent4ppt] Verification passed ✓  (<N> section(s), template_path confirmed, idx annotations present)

Automated Verification (built-in)

After writing the output file the skill automatically verifies three structural invariants:

#	Invariant	Check
1	YAML frontmatter template key	Frontmatter exists, contains template: key, value is non-empty. This is the sole authoritative reference to the source PPTX.
2	Separator count	Number of --- lines after frontmatter == slide_count - 1
3	Placeholder idx annotations	Every non-empty, non-metadata-only section contains at least one <!-- ph:N type:TYPE … --> annotation

Verification failure yields exit code 2 (distinguishable from IO errors at exit code 1).

Verifiable artifacts:

• The output markdown file exists at the declared path
• Contains --- YAML frontmatter with template: field pointing back to the source PPTX
• Contains one or more slide sections separated by ---
• Each substantive slide section includes at least one <!-- ph:\d+ type:\w+ --> comment
• The skill's own [agent4ppt] Verification passed ✓ message is present in stdout

Artifact validation commands:

python skills/parse-ppt-template/parse_template.py template.pptx --output out.md
echo "Exit: $?"                                          # Must be 0
grep -q "^template:" out.md && echo "PASS: frontmatter"
grep -qP "ph:\d+ type:\w+" out.md && echo "PASS: placeholders found"

Output Format

The generated markdown file contains:

• YAML frontmatter with template, fname, title, subTitle, date, author, lang fields
• Slide sections separated by --- (one section per slide or layout, depending on --layouts-only)
• Layout indicator > layout: N at the top of each slide section
• Placeholder annotations <!-- ph:idx type:TYPE pos:(x,y) size:WxH --> with content ready to fill
• Guide comments <!-- Enter the ... --> (in the selected language) explaining each placeholder

Placeholder Type Values

Type	python-pptx placeholder kind
title	Title
center_title	Center Title
subtitle	Subtitle
body	Body
object	Object (generic)
picture	Picture
table	Table
chart	Chart / diagram
media	Media clip
ftr	Footer
dt	Date
sldnum	Slide number

Ontology: Template Contract vs. Spatial Layout

The placeholder annotation encodes two distinct concerns:

• Template contract (type:TYPE): what a placeholder demands — the kind of content it accepts (title, body, picture, chart, table, etc.)
• Spatial layout (pos:, size:): where the placeholder lives on the slide — informational metadata, preserved passthrough

Example Output

---
template: ./my_template.pptx
fname: output.pptx
title: ""
subTitle: ""
date: ""
author: ""
lang: en
---

> layout: 0
<!-- layout_name: Title Slide -->

<!-- ph:0 type:center_title pos:(0.9167",1.75") size:7.6548"×0.7547" -->
<!-- Enter the centered slide title -->
# Slide Title

<!-- ph:1 type:subtitle pos:(0.9167",2.6495") size:5.588"×0.8832" -->
<!-- Enter the subtitle -->
Subtitle text here

---

> layout: 1

<!-- ph:0 type:title pos:(0.4583",0.25") size:8.5"×1.2" -->
<!-- Enter the slide title -->
# Section Header

<!-- ph:1 type:body pos:(0.4583",1.5") size:8.5"×4.5") -->
<!-- Enter the main body content. Supports bullets, bold, italic. -->
- Bullet one
- Bullet two

Error Handling

Condition	Behaviour
pptx_file not found	Exits 1, prints error to stderr
File has no .pptx extension	Warning printed to stderr, continues
Missing dependency (python-pptx, pyyaml, markdown-it-py)	Attempts auto-install via pip (3 strategies); if all fail, exits 1 with bilingual install instructions to stderr
PPTX file is corrupt or unreadable	Exits 1, prints error to stderr

Examples

# Basic — output written to same directory as template
/parse-ppt-template "GIST NetAI PPT Theme.pptx"

# Specify output path and Korean guide comments
/parse-ppt-template "GIST NetAI PPT Theme.pptx" --output slides_template.md --lang ko

# One section per layout (for templates with no slide content)
/parse-ppt-template my_template.pptx --layouts-only --output layouts.md

Dependencies

Package	Version	Import	Role in this skill
python-pptx	>= 0.6.21	import pptx	Required — reads and inspects the PPTX template file
pyyaml	>= 6.0	import yaml	Required — serialises YAML frontmatter in the output markdown
markdown-it-py	>= 3.0	import markdown_it	Plugin-level — used by /generate-ppt and /revise-ppt to parse the markdown output produced by this skill; installed together with the plugin so the full agent4ppt workflow is ready

Quick install (all plugin dependencies):

pip install "python-pptx>=0.6.21" "pyyaml>=6.0" "markdown-it-py>=3.0"
# or use the bundled installer:
bash scripts/install.sh

Plugin-Level Dependency Matrix

Dependency	parse-ppt-template	generate-ppt	revise-ppt
python-pptx	✅ Runtime	✅ Runtime	✅ Runtime
pyyaml	✅ Runtime	✅ Runtime	✅ Runtime
markdown-it-py	ℹ️ Plugin-level	✅ Runtime	✅ Runtime

ℹ️ Plugin-level = installed as part of the agent4ppt plugin so that downstream skills (/generate-ppt, /revise-ppt) work immediately after running /parse-ppt-template.

CLI Tool Requirements

Before Python packages are checked, the skill verifies that the execution environment itself is usable.

Tool	Type	Min Version	Role	Fallback if absent
python3	Required	>= 3.10	Interpreter — executes the skill	Exit 1 with version install instructions
pip	Auto-install	any	Package installer — used for auto-install fallback	Skipped; uv tried next; exit 1 with get-pip.py instructions
uv	Optional	any	Fast pip alternative — tried as 4th auto-install strategy	Skipped silently if absent

Python version check (executed first, before any package import):

# _check_python_version() — runs at module load, before _check_dependencies()
if sys.version_info < (3, 10):
    # Print bilingual error with install link and exit(1)
    ...

Example output when Python is too old (English):

[agent4ppt] Error: Python 3.10 or higher is required. Current version: 3.9.7

  Install Python 3.10+:
    https://www.python.org/downloads/

  Or use pyenv:
    pyenv install 3.11 && pyenv local 3.11

Example output when Python is too old (Korean):

[agent4ppt] 오류: Python 3.10 이상이 필요합니다. 현재 버전: 3.9.7

  Python 3.10+ 설치 방법:
    https://www.python.org/downloads/

  또는 pyenv를 사용하세요:
    pyenv install 3.11 && pyenv local 3.11

Dependency Check & Auto-Install Fallback

The skill performs an automatic dependency check on startup before any PPTX parsing begins. The full startup sequence is:

_check_python_version()   ← Step 0: Python >= 3.10?
_check_dependencies()     ← Steps 1–4: packages importable?
main()                    ← CLI arg parsing and PPTX parsing

If required packages are missing, _check_dependencies() follows a multi-step fallback chain:

Step	Action	Condition
0	Python version gate	Checked by _check_python_version() before this function. If Python < 3.10, exits with code 1 immediately.
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 install automatically using four strategies (in order): plain pip → pip --user → pip --break-system-packages (PEP 668 fallback) → uv pip install (if uv is on PATH).
3	Re-verify	After auto-install, re-check imports. If successful → proceed normally.
4	Guided error	If all strategies fail, print bilingual (Korean/English) install instructions to stderr and exit with code 1.

Check logic (executed in parse_template.py::_check_dependencies()):

# Runs at module load time — before any CLI argument parsing.
# _check_python_version() has already run before this point.
#
# Checks runtime dependencies for this skill (pptx + yaml) AND the
# plugin-level dependency (markdown-it-py) so that the full agent4ppt
# workflow is available immediately after /parse-ppt-template runs.
missing = []
try:
    import pptx           # python-pptx  — required at runtime
except ImportError:
    missing.append("python-pptx")
try:
    import yaml           # pyyaml       — required at runtime
except ImportError:
    missing.append("pyyaml")
try:
    import markdown_it    # markdown-it-py — plugin-level (used by /generate-ppt)
except ImportError:
    missing.append("markdown-it-py")

if missing:
    _auto_install(missing)   # 4-strategy fallback (pip × 3 + uv)
    # ... re-check imports, then sys.exit(1) if still missing

Auto-install strategies (tried in order, first success wins):

1. pip install python-pptx pyyaml markdown-it-py
   # plain — works in virtual environments and most setups

2. pip install --user python-pptx pyyaml markdown-it-py
   # user-level — works for system Python without an active venv

3. pip install --break-system-packages python-pptx pyyaml markdown-it-py
   # PEP 668 environments (Debian 12+, Ubuntu 23.04+, macOS Homebrew Python)

4. uv pip install python-pptx pyyaml markdown-it-py
   # uv fast alternative — tried only when `uv` is available on PATH
   # skipped silently if `uv` is not installed

Note: All strategies use sys.executable -m pip (strategies 1–3) to ensure the correct interpreter's pip is invoked, or uv pip install (strategy 4) when uv is detected. Each strategy has a 120-second timeout to prevent hanging on network issues.

Example output (auto-install success):

[agent4ppt] 누락된 의존성 감지: python-pptx, markdown-it-py. 자동 설치를 시도합니다…   # ko
[agent4ppt] Auto-installed python-pptx, markdown-it-py via pip install               # en
[agent4ppt] Auto-installed python-pptx, markdown-it-py via uv pip install            # (uv path)

If all auto-install strategies fail, the skill prints clear instructions and exits with code 1:

[agent4ppt] Auto-install failed for: python-pptx, pyyaml, markdown-it-py

  Install manually using one of these methods:

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

  Option 2 (user-level install):
    pip install "python-pptx" "pyyaml" "markdown-it-py" --user

  Option 3 (uv — fast pip alternative):
    uv pip install "python-pptx" "pyyaml" "markdown-it-py"

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

  If pip is not available:
    curl https://bootstrap.pypa.io/get-pip.py | python3

Korean output (when LANG=ko_KR.UTF-8):

[agent4ppt] 의존성 자동 설치 실패: python-pptx, pyyaml, markdown-it-py

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

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

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

  방법 3 (uv — pip 대체 도구):
    uv pip install "python-pptx" "pyyaml" "markdown-it-py"

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

  pip를 찾을 수 없는 경우:
    curl https://bootstrap.pypa.io/get-pip.py | python3

Fallback Resolution Order

Complete priority table — first applicable method is recommended:

Priority	Method	Command	When to use
0	Python version check	python3 --version	Verify Python >= 3.10 before anything else
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" "pyyaml" "markdown-it-py"	System Python without venv
4	uv (fast alternative)	uv pip install "python-pptx" "pyyaml" "markdown-it-py"	When uv is installed; also tried automatically by the skill
5	Bootstrap pip	curl https://bootstrap.pypa.io/get-pip.py | python3	When pip itself is missing
6	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/parse-ppt-template/parse_template.py "$PPTX_FILE" --output "$OUT_MD" 2>err.log
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
  if grep -q "Python 3\.10\|Python 3.10" err.log; then
    echo "[agent4ppt] Python version too old — install Python 3.10+ first"
    exit 1
  fi
  if grep -q "Missing dependencies\|의존성\|Auto-install failed" err.log; then
    bash scripts/install.sh --no-register
    # Retry after installation
    python skills/parse-ppt-template/parse_template.py "$PPTX_FILE" --output "$OUT_MD"
  fi
fi

Verifying Dependencies

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

# Check Python version:
python3 -c "import sys; assert sys.version_info >= (3,10), f'Python 3.10+ required, got {sys.version}'; print('Python OK')"

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

# Or check only the runtime dependencies for this skill:
python -c "import pptx, yaml; print('parse-ppt-template runtime dependencies OK')"

# Check if uv is available (optional, used as 4th auto-install strategy):
command -v uv && echo "uv available" || echo "uv not found (optional)"

Language Support

Set the LANG environment variable or use --lang ko|en to control the language of guide comments in the generated markdown.

• LANG=ko or --lang ko → Korean guide comments
• LANG=en or --lang en → English guide comments (default)

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