From agent4ppt
Parse a PPTX template file and generate an annotated markdown template. Each slide's placeholders are identified by python-pptx idx-based indexing and annotated with <!-- ph:idx type:TYPE --> comments. Markdown is the canonical document — the PPTX template is a read-only source. Compatible with Claude Code, OpenClaw, and Codex CLI.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent4ppt:parse-ppt-templateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**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 frontmatte...
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에 대한 유일한 권위 있는 참조입니다.
/parse-ppt-template <pptx_file> [--output <output.md>] [--lang ko|en] [--layouts-only]
Executed via: python skills/parse-ppt-template/parse_template.py
| 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. |
| Input | Type | Description |
|---|---|---|
pptx_file | File path | A valid PPTX file readable by python-pptx. Must exist on disk. |
A markdown file written to --output (or <input>.md by default).
| 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)
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:
--- YAML frontmatter with template: field pointing back to the source PPTX---<!-- ph:\d+ type:\w+ --> comment[agent4ppt] Verification passed ✓ message is present in stdoutArtifact 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"
The generated markdown file contains:
template, fname, title, subTitle, date, author, lang fields--- (one section per slide or layout, depending on --layouts-only)> layout: N at the top of each slide section<!-- ph:idx type:TYPE pos:(x,y) size:WxH --> with content ready to fill<!-- Enter the ... --> (in the selected language) explaining each placeholder| 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 |
The placeholder annotation encodes two distinct concerns:
type:TYPE): what a placeholder demands — the kind of content it accepts (title, body, picture, chart, table, etc.)pos:, size:): where the placeholder lives on the slide — informational metadata, preserved passthrough---
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
| 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 |
# 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
| 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
| 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.
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
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, oruv pip install(strategy 4) whenuvis 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
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 |
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
# 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)"
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 commentsLANG=en or --lang en → English guide comments (default)Precedence: --lang flag > LANG environment variable > default (en)
npx claudepluginhub jinwangmok/agent4ppt --plugin agent4pptCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.