docx

docx 스킬 개요

docx 스킬은 무엇에 쓰이나요

docx 스킬은 에이전트가 Microsoft Word .docx 파일을 더 적은 사각지대와 함께 생성, 점검, 수정할 수 있도록 돕습니다. 일반적인 프롬프트보다 DOCX 작업 흐름을 더 정확히 다루며, 완성도 있는 Word 결과물을 만들어야 하거나, 검토용으로 내용을 추출해야 하거나, 기존 파일을 수정해야 하거나, 댓글과 변경 내용 추적을 처리해야 하거나, Office XML 구조를 직접 다뤄 패키지 수준 문제를 복구해야 하는 사용자에게 특히 잘 맞습니다.

어떤 경우에 docx를 설치해야 하나요

다음 작업이 자주 필요하다면 docx 스킬 설치를 고려할 만합니다.

• 일반 텍스트가 아니라 실제 Word 문서를 만들어야 한다
• Word를 일일이 클릭하지 않고 기존 .docx를 수정해야 한다
• 제목 구조, 댓글, 수정 기록 같은 문서 구조를 유지해야 한다
• 후속 처리 전에 구형 .doc 파일을 변환해야 한다
• 일반 텍스트 추출만으로는 부족해 패키지 내부를 직접 확인해야 한다

특히 AI 보조 문서 작업에서 결과물이 단순한 markdown 초안이 아니라 실제로 사용 가능한 .docx여야 할 때 docx 스킬의 가치가 큽니다.

docx가 일반 프롬프트와 다른 점

가장 큰 차별점은 작업 흐름이 구체적이라는 점입니다. 이 스킬은 DOCX를 “그냥 텍스트”로 취급하지 않습니다. .docx가 XML 파일들로 이루어진 ZIP 아카이브라는 점을 전제로, 작업 목적에 따라 에이전트를 적절한 경로로 유도합니다.

• 텍스트 중심 읽기와 추출에는 pandoc
• 구조 편집에는 unpack/edit/repack
• 일부 형식 변환과 변경 내용 수락에는 LibreOffice 자동화
• XML 수정으로 파일이 깨질 수 있는 경우 검증 및 복구 절차

그래서 docx는 단순한 “보고서 작성” 지시보다 실제 DOCX 워크플로에서 훨씬 신뢰할 수 있습니다.

특히 잘 맞는 작업

실제 해야 할 일이 아래 중 하나라면 docx를 쓰는 편이 좋습니다.

• “섹션과 전문적인 서식을 갖춘 Word 보고서를 만들어 줘.”
• “이 .docx를 읽고 변경 내용 추적까지 포함해서 요약해 줘.”
• “기존 Word 파일 내부의 내용을 교체하거나 구조를 재정리해 줘.”
• “댓글을 추가하거나 수정 이력을 프로그래밍 방식으로 처리해 줘.”
• “안전하게 편집할 수 있도록 .doc를 .docx로 변환해 줘.”

도입 전에 알아둘 중요한 한계

이 스킬은 만능 오피스 제품군이 아닙니다. .docx를 명확히 대상으로 하는 작업에서 가장 강합니다. 반대로 아래 같은 경우에는 적합성이 떨어집니다.

• PDF
• Google Docs 중심의 협업
• 스프레드시트 비중이 큰 워크플로
• Word 데스크톱에서 수동 검수가 필요한 수준의 시각적 레이아웃 정밀도
• pandoc나 LibreOffice 같은 로컬 도구를 전혀 쓸 수 없는 환경

실무적인 트레이드오프는 분명합니다. docx는 더 많은 제어권을 주지만, 패키지 수준 편집에는 그만큼 주의가 필요합니다.

docx 스킬 사용 방법

명령어보다 먼저 설치 환경을 확인하세요

저장소의 SKILL.md 안에는 단일한 공식 docx install 명령이 명시돼 있지 않습니다. 따라서 Anthropic skills repository에서 추가하는 스킬로 보고, 이후에는 로컬 헬퍼 스크립트와 외부 도구를 함께 사용하는 방식으로 이해하는 것이 맞습니다. 실제로 docx usage를 검토하는 사용자라면 보통 아래 환경을 전제로 생각해야 합니다.

• Python
• 읽기 및 변환 중심 추출을 위한 pandoc
• .doc 변환과 변경 내용 수락을 위한 LibreOffice soffice
• 포함된 Python 스크립트를 실행할 수 있는 셸 환경

환경에서 GUI 성격의 오피스 도구 실행이나 네이티브 subprocess 호출이 막혀 있다면, 그 부분부터 먼저 확인하세요. 실제 도입을 가로막는 핵심 이유가 바로 이것인 경우가 많습니다.

먼저 읽어야 할 파일

가장 빠르게 전체 구조를 파악하려면 아래 순서대로 읽는 것이 좋습니다.

1. skills/docx/SKILL.md
2. skills/docx/scripts/office/unpack.py
3. skills/docx/scripts/office/pack.py
4. skills/docx/scripts/accept_changes.py
5. skills/docx/scripts/comment.py
6. skills/docx/scripts/office/soffice.py

이 순서대로 보면 docx skill의 실제 동작 모델이 보입니다. 읽기, unpack, 편집, 검증, repack를 기본으로 하고, XML만으로 처리하기 부적절한 작업에만 LibreOffice를 쓰는 구조입니다.

작업에 맞는 워크플로를 먼저 고르세요

좋은 docx guide는 우선 어느 경로로 갈지 결정하는 것부터 시작합니다.

• 내용 읽기 또는 분석: pandoc을 쓰거나 unpack한 XML을 확인
• 새 문서 만들기: SKILL.md에서 안내하는 문서 생성 경로 사용
• 기존 문서 수정: unpack → XML/asset 수정 → repack
• .doc를 .docx로 변환: 먼저 LibreOffice 변환 사용
• 변경 내용 추적 수락: 제공된 LibreOffice 매크로 헬퍼 사용
• 댓글 추가: comment 스크립트와 올바른 XML marker 사용

이 판단을 건너뛰고 곧바로 편집부터 시작하면 품질이 빠르게 떨어집니다.

좋은 결과를 위해 docx 스킬에 제공해야 할 입력

안정적인 docx usage를 원한다면 “Word 문서 하나 만들어 줘”만으로는 부족합니다. 보통 아래 정보가 있으면 결과가 훨씬 좋아집니다.

• 수정 작업이라면 원본 파일 경로
• 원하는 출력 파일 경로
• 작업 유형이 생성, 읽기, 변환, 주석 추가, 수정 중 무엇인지
• 제목, 페이지 번호, TOC, 표, 레터헤드 같은 서식 요구사항
• 변경 내용 추적이나 댓글을 유지해야 하는지
• 이미지, 표, 템플릿이 손상 없이 유지돼야 하는지

약한 프롬프트:

• “이 Word 문서 수정해 줘.”

더 강한 프롬프트:

• “contract_review.docx를 열고 변경 내용 추적은 유지한 채 모든 댓글을 요약한 뒤, H1/H2 제목 구조, 짧은 위험 표, 마지막 권고 섹션이 들어간 새 executive_summary.docx를 만들어 줘.”

사용자가 실제로 궁금해하는 실전 명령

저장소에서 바로 확인할 수 있는 가치 높은 작업 예시는 다음과 같습니다.

먼저 구형 .doc를 변환:

python scripts/office/soffice.py --headless --convert-to docx document.doc

변경 내용 맥락을 유지한 채 텍스트 추출:

pandoc --track-changes=all document.docx -o output.md

XML 수준 편집을 위해 DOCX unpack:

python scripts/office/unpack.py document.docx unpacked/

편집 후 repack:

python scripts/office/pack.py unpacked/ output.docx --original document.docx

이 명령들은 docx for DOCX Workflows의 핵심 가치를 잘 보여줍니다. 단순히 텍스트를 쓰는 것이 아니라, Word 패키지를 안전하게 다루는 데 초점이 있습니다.

에이전트가 docx를 제대로 타도록 프롬프트하는 법

요청에 파일 형식과 작업 종류가 분명히 드러날수록 스킬이 제대로 활성화될 가능성이 높습니다. 아래 내용을 포함하세요.

• .docx
• 원하는 최종 상태
• 기존 파일 작업인지, 처음부터 만드는지
• 반드시 보존해야 하는 것

좋은 트리거 예시:

• “이 노트를 바탕으로 완성도 있는 .docx 이사회 메모를 만들어 줘.”
• “이 .docx를 읽고 변경 내용 추적까지 포함해 텍스트를 추출해 줘.”
• “unpack해서 표지를 수정한 뒤 .docx로 다시 repack해 줘.”
• “이 Word 문서의 특정 문단에 검토용 댓글을 추가해 줘.”

실제로는 패키지 안전 편집이 필요한데 “문서를 더 좋게 만들어 줘”처럼 모호하게 말하면 피해야 할 경로로 빠지기 쉽습니다.

언제 pandoc을 쓰고, 언제 XML을 unpack해야 하나요

이건 실무에서 가장 중요한 판단 중 하나입니다.

아래 목적이라면 pandoc이 적합합니다.

• 읽기 쉬운 텍스트 추출
• markdown 변환
• 변경 내용 추적 검토를 더 쉽게 하고 싶을 때
• 레이아웃 수술보다 내용 분석이 중요할 때

반대로 아래 목적이라면 unpack/edit/repack이 맞습니다.

• 댓글 처리
• 변경 내용 추적을 고려한 구조 편집
• 이미지 또는 패키지 파트 교체
• word/ XML 및 relationships 내부의 저수준 수정

목표가 의미 기반 읽기라면 XML 편집은 과합니다. 목표가 정확한 DOCX 변형이라면 일반 텍스트 추출만으로는 부족합니다.

변경 내용 추적과 댓글은 별도 취급이 필요합니다

이 저장소는 이 부분을 꽤 실용적으로 지원합니다.

• scripts/accept_changes.py는 LibreOffice를 이용해 변경 내용 추적을 수락합니다
• scripts/comment.py는 unpack된 문서에 댓글을 삽입하는 데 도움을 줍니다
• scripts/office/helpers/의 헬퍼 코드는 run 병합과 redline 단순화를 다룹니다

이게 중요한 이유는 수정 이력이 들어간 DOCX XML이 훨씬 더 복잡해지기 때문입니다. 문서가 법률 검토, 편집 코멘트, 협상 초안처럼 revision 중심이라면, docx skill은 기본 문서 생성기보다 훨씬 설득력 있는 선택지입니다.

XML 특유의 품질 함정을 주의하세요

놓치기 쉬운 실패 패턴이 몇 가지 있습니다.

• 댓글 marker는 document.xml 안의 올바른 위치에 들어가야 합니다
• 댓글 텍스트는 XML escaping이 되어 있어야 합니다
• DOCX 수정은 relationships나 schema 유효성을 깨뜨릴 수 있습니다
• run fragmentation 때문에 search/replace가 예상대로 동작하지 않을 수 있습니다
• 변경 내용 추적이 겉으로 보이는 텍스트 흐름을 왜곡할 수 있습니다

포함된 pack/validate 경로가 위험을 줄여주긴 하지만, 작업 자체를 신중하게 정의해야 한다는 점까지 없애주지는 않습니다.

도입을 막을 수 있는 환경 이슈

docx install을 판단할 때 현실적인 장애물은 오피스 자동화입니다. 저장소의 soffice.py에는 Unix socket이 실패할 수 있는 샌드박스 환경을 고려한 로직이 들어 있고, 경우에 따라 LD_PRELOAD shim이 필요할 수 있습니다. 이는 작성자들이 실제 환경 마찰을 충분히 예상하고 있다는 강한 신호입니다.

배포 환경에서 LibreOffice를 실행할 수 없다면 일부 워크플로는 여전히 가능하지만, 다음 제약이 생깁니다.

• .doc 변환이 더 어려워집니다
• 제공된 스크립트를 통한 변경 내용 수락은 사용할 수 없습니다
• “Word처럼 동작하게 자동화해 달라”는 일부 요청은 다른 툴체인이 필요할 수 있습니다

일관된 결과를 위한 권장 워크플로

좋은 기본 docx guide 워크플로는 다음과 같습니다.

1. 원본이 .doc인지 .docx인지 확인합니다.
2. 필요하면 먼저 .doc를 .docx로 변환합니다.
3. 작업이 텍스트 추출인지 패키지 편집인지 결정합니다.
4. 구조 수준 수정이 필요한 경우에만 unpack합니다.
5. 광범위한 regex식 XML 재작성보다, 목표가 분명한 수정만 적용합니다.
6. 가능하면 원본과 비교하는 검증을 포함해 repack합니다.
7. 마지막으로 Word 또는 LibreOffice에서 결과물을 열어 시각적으로 빠르게 smoke test합니다.

이 흐름을 따르면 가장 흔한 파일 손상과 기대 불일치 문제를 줄일 수 있습니다.

docx 스킬 FAQ

docx는 초보자에게도 괜찮나요?

네. 변환, 추출, 소규모 수정처럼 목적이 분명하고 범위가 제한적이라면 충분히 쓸 만합니다. 다만 고급 docx usage는 빠르게 패키지 수준 XML 작업으로 넘어갑니다. 초보자도 안내된 워크플로 안에서 움직이고 Word 파일을 단순 텍스트 덩어리처럼 다루지만 않는다면 성공적으로 사용할 수 있습니다.

일반적인 글쓰기 프롬프트보다 docx가 나은 때는 언제인가요?

출력물이 실제 Word 파일이어야 하거나, 기존 .docx의 구조를 보존해야 할 때는 docx를 쓰는 것이 좋습니다. 일반 글쓰기 프롬프트도 초안 작성은 가능하지만, 변환, unpack, 검증, 댓글 및 수정 이력의 안전한 처리 방법까지 에이전트에 알려주지는 못하는 경우가 많습니다.

docx 스킬로 새 문서를 처음부터 만들 수 있나요?

네, 가능합니다. 다만 저장소에서 가장 강하게 확인되는 부분은 단순한 글 생성보다 실용적인 파일 작업과 편집 워크플로입니다. 핵심 요구가 “내용 작성”이라면 대체 가능한 도구가 많습니다. 반대로 “실제로 쓸 수 있는 .docx를 납품하거나 수정”하는 것이 목적이라면 이 스킬이 더 잘 맞습니다.

docx는 오래된 .doc 파일에도 작동하나요?

직접적으로는 아닙니다. 구형 .doc 파일은 먼저 LibreOffice로 변환해야 합니다. 이 경계는 중요합니다. docx skill은 .docx 워크플로를 위한 것이지, 네이티브 .doc 편집을 위한 도구는 아닙니다.

docx는 법률 문서나 검토 중심 문서에 적합한가요?

경우에 따라 그렇습니다. 저장소에서 변경 내용 추적, 댓글, 검증을 핵심 관심사로 다루기 때문입니다. 다만 검토 비중이 큰 문서는 생성 또는 수정 후 반드시 다시 열어 Word 호환 편집기에서 눈에 보이는 동작이 예상대로인지 확인해야 합니다.

언제 docx를 쓰지 말아야 하나요?

아래에 해당하면 이 docx skill은 건너뛰는 편이 낫습니다.

• 일반 텍스트 출력만 필요하다
• 최종 결과물이 Word가 아니라 PDF다
• 워크플로가 Google Docs 중심이다
• 의존하는 로컬 도구를 실행할 수 없다
• 편집 가능한 DOCX 구조보다 픽셀 단위의 데스크톱 출판 품질이 더 중요하다

docx 스킬 개선 방법

docx에 출력 제약을 명확히 주세요

docx 결과를 가장 빠르게 개선하는 방법은 주제만 말하는 것이 아니라 완성물의 조건을 분명히 주는 것입니다. 예를 들면 다음을 포함하세요.

• 대상 파일명
• 원본 파일명
• 보존할지 재작성할지에 대한 지침
• 필수 섹션
• 스타일 제약
• 댓글, 수정 이력, 이미지, 표를 그대로 유지해야 하는지 여부

이렇게 하면 도구 선택 실수를 줄일 수 있고, 에이전트가 텍스트 전용 경로로 잘못 빠지는 것도 막을 수 있습니다.

실행 전에 어떤 워크플로를 쓸지 먼저 말하게 하세요

더 나은 docx usage를 위해, 작업 전에 에이전트가 어떤 경로를 쓸지 먼저 밝히도록 요청하세요.

• pandoc
• unpack/edit/repack
• LibreOffice 변환
• comment 또는 revision 도구

예:

• “편집하기 전에 이 작업이 pandoc 추출을 써야 하는지, 아니면 unpack/repack을 써야 하는지와 그 이유를 먼저 말해 줘.”

이 단순한 한 단계만으로도 많은 잘못된 방향 전환을 초기에 잡아낼 수 있습니다.

검색/치환 작업은 구조 힌트를 주면 더 잘됩니다

치환이 필요하다면, 해당 내용이 어디에 있는지 지정해 주세요.

• 본문 텍스트
• 머리글/바닥글
• 댓글
• 표
• 표지
• 특정 섹션 제목

왜 도움이 되냐면 DOCX 텍스트는 여러 run으로 쪼개져 있는 경우가 많기 때문입니다. “모든 언급을 바꿔 줘”처럼 모호한 요청은 일부를 놓치거나 서식을 깨뜨릴 수 있습니다.

댓글과 XML escaping은 특히 조심하세요

댓글을 추가할 때는 XML에 안전한 깔끔한 텍스트를 제공하세요. 저장소에서도 댓글 텍스트를 미리 escape해야 한다고 명시하고 있습니다. 댓글 안에 ampersand, smart quote, 특수 기호가 있다면 escape 또는 normalize가 필요하다고 분명히 적어 두는 것이 좋습니다.

사소해 보이지만, 결과 파일이 문제 없이 열리는지에 실제로 큰 영향을 주는 부분입니다.

가능하면 항상 원본 파일 기준 검증을 사용하세요

repack할 때 원본 파일이 있다면 --original을 포함하세요. 그러면 validator가 더 많은 맥락을 활용할 수 있어 기존 문서 편집에서 docx skill을 더 안전하게 쓸 수 있습니다. 이 스킬 워크플로에서 가장 투자 대비 효과가 큰 습관 중 하나입니다.

첫 결과물 뒤에는 파일 인식형 피드백으로 반복하세요

“이상해 보여요”에서 멈추지 마세요. 더 좋은 후속 피드백은 이런 식입니다.

• “문서는 열리는데 Word에서 댓글이 보이지 않습니다.”
• “변경 내용 추적이 평탄화됐습니다. 유지해 주세요.”
• “본문은 업데이트됐지만 머리글 브랜딩은 예전 그대로입니다.”
• “XML은 pack됐지만 표 구간에서 서식이 깨졌습니다.”

이런 피드백이 있어야 에이전트가 무작정 다시 시도하는 대신, 다음 복구 단계를 제대로 선택할 수 있습니다.

초기에 잡아야 할 흔한 실패 패턴

워크플로를 크게 돌리기 전에 아래 문제를 먼저 점검하세요.

• 출력 파일은 열리지만 댓글이 없다
• 변경 내용 추적이 의도치 않게 수락되거나 사라졌다
• 수정이 눈에 보이는 본문에만 적용되고 머리글/바닥글에는 적용되지 않았다
• smart quote나 특수 기호가 XML을 깨뜨린다
• repack된 파일이 ZIP으로는 통과하지만 Word에서는 열리지 않는다

대량 처리에 들어가기 전에 작은 문서 하나로 빠르게 smoke test하는 것이 충분히 가치 있습니다.

복잡한 docx 파일에서 더 좋은 결과를 얻는 방법

복잡한 docx for DOCX Workflows라면 작업을 나누는 편이 좋습니다.

1. 추출하고 점검한다
2. 수정 지점을 결정한다
3. 한 번에 한 종류의 변경만 적용한다
4. repack하고 검증한다
5. 시각적으로 확인한다

한 번에 끝내는 프롬프트보다 느리지만, 템플릿, 계약서, 보고서, 수정 이력이 많은 파일에서는 훨씬 더 안정적입니다.

docx 스킬 자체를 확장한다면 무엇을 개선해야 하나요

docx skill 자체를 개선하려는 관점이라면, 가장 가치 있는 추가 사항은 다음과 같습니다.

• 자주 쓰는 작업별로 더 명확한 documented entrypoint
• 각 워크플로 경로에 대응되는 예시 프롬프트
• 더 촘촘한 설치/사전 요구사항 체크리스트
• 새 문서 생성과 기존 문서 편집의 차이를 더 명확히 설명하는 가이드
• 댓글, redline, 이미지 교체에 대한 end-to-end 예제

이런 개선이 있으면 일반적인 문장 설명을 늘리는 것보다 도입 마찰을 훨씬 더 크게 줄일 수 있습니다.