hwpx-plugin

📄 hwpx-plugins

AI 에이전트가 HWPX 문서를 바로 읽고, 바꾸고, 점검하게 만드는 공식 온보딩 스킬

순수 Python · 한컴오피스 불필요 · 크로스 플랫폼

---

🧩 HWPX Stack (3종)

계층	레포	역할
📦 라이브러리	python-hwpx	순수 파이썬 HWPX 파싱·편집·생성 코어
🔌 MCP 서버	hwpx-mcp-server	MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작
🎯 에이전트 스킬	hwpx-plugins	에이전트가 HWPX를 바로 쓰게 해주는 공식 온보딩 스킬

---

hwpx-plugins은 python-hwpx 기반의 공식 에이전트 스킬이다. HWPX를 잘 모르는 사용자도 스킬 설치 후 바로 문서 읽기, 텍스트 추출, 템플릿 치환, 기본 점검까지 갈 수 있게 만드는 데 초점을 둔다. .hwpx 문서를 열고, 텍스트를 추출하고, 표를 포함한 양식을 채우고, 플레이스홀더를 치환하는 작업을 에이전트가 바로 수행할 수 있게 설계했다.

즉, 이 저장소는 단순 설명서가 아니다.

• 에이전트가 따라갈 SKILL.md
• 바로 실행해볼 수 있는 예제
• 입문자가 첫 성공을 확인하는 보조 CLI 를 함께 제공하는 HWPX 자동화 입구다.

대상 포맷은 Open XML 기반 .hwpx다. 레거시 바이너리 .hwp 직접 편집은 범위 밖이다.

지원 에이전트 생태계

• Claude Code Skills — .claude/skills/hwpx-plugins/에 넣어 바로 트리거할 수 있다.
• Cursor Skills / Rules — .cursor/skills/와 .cursor/rules/ 조합으로 온보딩할 수 있다.
• Codex CLI Skills — .agents/skills/hwpx-plugins/ 경로 기준으로 바로 붙일 수 있다.

이 저장소가 바로 해결하는 일

• HWPX 문서 텍스트를 빠르게 추출한다.
• 표를 포함한 문서의 플레이스홀더를 일괄 치환한다.
• 설치 직후 환경이 맞는지 한 번에 확인한다.
• 에이전트가 HWPX 작업에서 어떤 흐름을 따라야 하는지 알려준다.

3분 설치

기본 명령:

python3 -m pip install -U python-hwpx lxml

현재 권장 기준:

• Python 3.10+
• 기본 편집 최소 호환 기준: python-hwpx >= 2.6
• document-plan 생성 권장 기준: python-hwpx >= 2.9.1
• 최근 로컬 검증 기준: python-hwpx 2.9.1

5분 성공 확인

설치 후 이 명령 하나부터 돌린다.

python3 scripts/quickcheck.py

이 스크립트는 다음을 한 번에 확인한다.

• Python 버전
• python-hwpx, lxml import
• 예제 문서 생성
• 생성 문서 구조 점검
• CLI 텍스트 추출

정상이라면 마지막에 아래 문구가 나온다.

[OK] basic hwpx skill workflow passed

선언형 document-plan 생성까지 확인하려면:

python3 scripts/quickcheck.py --document-plan

운영 계획서 품질 프로필까지 확인하려면:

python3 scripts/quickcheck.py --operating-plan
python3 scripts/quickcheck.py --visual-review
python3 scripts/quickcheck.py --visual-review --operating-plan

양식 보존 form-fit 경로까지 확인하려면:

python3 scripts/quickcheck.py --template-formfit

Multi-host plugin bundles

This repository is the canonical source for the HWPX skill and builds one bundle per agent host:

Host	Bundle	Install entry point
Claude Code	plugins/claude/hwpx-plugin	.claude-plugin/marketplace.json (repo root)
Codex	plugins/codex/hwpx-plugin	.codex-plugin/plugin.json
OpenClaw	plugins/openclaw/hwpx-plugin	openclaw.plugin.json + INSTALL-mcp.md
Hermes Agent	plugins/hermes/hwpx	hermes skills publish + INSTALL-mcp.md

Edit the canonical SKILL.md, references/, examples/, and scripts/ at the repo root, then rebuild and validate:

python3 scripts/build_hwpx_plugins.py
python3 scripts/validate_hwpx_plugin.py
git diff --exit-code -- plugins .claude-plugin   # build must be reproducible and committed
uv run --with lxml --with ../python-hwpx python scripts/quickcheck.py --document-plan --operating-plan --template-formfit --visual-review

Host differences (frontmatter, manifests, MCP wiring, skill paths) are declared in packaging/hosts.json with templates in packaging/templates/. The MCP launcher prefers local sibling checkouts (../hwpx-mcp-server, ../python-hwpx), honors HWPX_MCP_SERVER_REPO / PYTHON_HWPX_REPO, and otherwise falls back to uvx --from hwpx-mcp-server==2.2.6 hwpx-mcp-server.

Claude Code installs via claude plugin marketplace add airmang/hwpx-plugins then claude plugin install hwpx-plugin@hwpx. Codex installs from the local marketplace as before. Start a fresh agent session after installing so new skills and MCP tools load.

가장 많이 쓰는 작업

1) 문서 텍스트 바로 추출

python3 scripts/text_extract.py input.hwpx
python3 scripts/text_extract.py input.hwpx --format json --include-nested --out output.json

2) 플레이스홀더 전역 치환

python3 scripts/zip_replace_all.py template.hwpx output.hwpx --replace "{학교명}=테스트초" "{담당자}=홍길동" --auto-fix-ns

3) 예제 문서 생성 후 구조 확인