Word 문서(DOCX) 처리 스킬

[DOCX 스킬 활성화]

목표

Word 문서(.docx) 생성, 읽기, 편집, 분석을 전문 에이전트에 위임하여 사용자 요청을 완수함.

활성화 조건

사용자가 .docx, Word, 워드, 문서 키워드를 언급하거나 보고서, 메모, 편지, 템플릿 등의 산출물을 Word 파일로 요청할 때 활성화.

워크플로우

Phase 1: 작업 유형 판별 (ulw 활용)

사용자 요청을 분석하여 읽기/생성/편집 작업 유형을 결정함.

이 Phase는 ulw 매직 키워드를 활용하여 수행함.

Phase 2-A: 새 문서 생성 → Agent: office-editor (/oh-my-claudecode:ralph 활용)

• TASK: docx-js npm 패키지를 사용하여 새 Word 문서 생성
• EXPECTED OUTCOME: 유효한 OOXML 구조를 가진 .docx 파일 생성. XSD 검증 통과
• MUST DO:
  • US Letter 페이지 크기 명시 설정 (A4 기본값 회피)
  • 리스트는 numbering config 사용 (유니코드 bullet 금지)
  • 테이블은 DXA 단위로 width 설정 (percentage 금지)
  • 생성 후 validate.py로 검증
• MUST NOT DO:
  • PageBreak를 Paragraph 밖에 배치하지 않음
  • ImageRun에서 type 파라미터 누락하지 않음
  • 스타일 정의 없이 커스텀 스타일 참조하지 않음
• CONTEXT:
  • PYTHONPATH=gateway/tools 환경변수 설정 필수
  • docx-js API 레퍼런스는 agents/office-editor/references/docx-api-reference.md 참조

이 Phase는 /oh-my-claudecode:ralph를 활용하여 수행함.

Phase 2-B: 기존 문서 읽기 → Agent: office-editor (ulw 활용)

• TASK: pandoc 변환 또는 unpack → XML 분석으로 문서 내용 추출
• EXPECTED OUTCOME: 텍스트, 서식, 구조 정보가 포함된 분석 결과
• MUST DO:
  • pandoc 사용 시 --track-changes=all 옵션 포함
  • XML 분석 시 unpack.py로 ZIP 해제
• MUST NOT DO: 직접 ZIP 바이너리 수정 시도하지 않음
• CONTEXT: PYTHONPATH=gateway/tools 설정, ooxml-structure.md 참조

이 Phase는 ulw 매직 키워드를 활용하여 수행함.

Phase 2-C: 기존 문서 편집 → Agent: office-editor (/oh-my-claudecode:ralph 활용)

• TASK: unpack → XML 편집 → validate → pack 워크플로우로 문서 수정
• EXPECTED OUTCOME: 수정된 유효 OOXML 문서. XSD 검증 통과. LibreOffice 열기 가능
• MUST DO:
  • 원본 서식, 스타일, 네임스페이스 보존
  • 변경 추적 시 WHAT만 마킹 (최소 편집)
  • 스마트 쿼트 XML 엔티티 사용 (’ 등)
  • pack.py 실행 전 validate.py 검증
• MUST NOT DO:
  • XSD 검증 없이 pack 실행 금지
  • <w:commentRangeStart>를 <w:r> 안에 배치하지 않음
• CONTEXT:
  • PYTHONPATH=gateway/tools 설정
  • XML 편집 시 Edit 도구 직접 사용 (Python 스크립트 작성 금지)
  • 변경 추적 author는 "Claude" 사용 (사용자 명시 없으면)

이 Phase는 /oh-my-claudecode:ralph를 활용하여 수행함.

Phase 3: 결과 검증 (ulw 활용)

생성/편집된 문서의 유효성 확인.

이 Phase는 ulw 매직 키워드를 활용하여 수행함.

에이전트 호출 규칙

에이전트 FQN

프롬프트 조립 절차

1. agents/office-editor/ 에서 3파일 로드 (AGENT.md + agentcard.yaml + tools.yaml)
2. gateway/runtime-mapping.yaml 참조하여 구체화:
   • 모델 구체화: agentcard.yaml의 tier: MEDIUM → tier_mapping.default.MEDIUM → claude-sonnet-4-5
   • 툴 구체화: tools.yaml의 추상 도구 → tool_mapping에서 실제 도구 결정
   • 금지액션 구체화: forbidden_actions: [user_interact, agent_delegate] → action_mapping에서 [AskUserQuestion, Task] 제외
   • 최종 도구 = (구체화된 도구) - (제외 도구)
3. 프롬프트 조립: 3파일을 합쳐 하나의 프롬프트로 구성
   • 구성 순서: 공통 정적(runtime-mapping) → 에이전트별 정적(3파일) → 동적(작업 지시)
4. Task(subagent_type="claude-skills:office-editor:office-editor", model="claude-sonnet-4-5", prompt=조립된 프롬프트) 호출

오케스트레이션 스킬 활용

스크립트 호출 패턴

모든 커스텀 도구 호출 시 PYTHONPATH 환경변수를 설정:

PYTHONPATH=gateway/tools python gateway/tools/office/unpack.py input.docx output_dir/
PYTHONPATH=gateway/tools python gateway/tools/office/pack.py input_dir/ output.docx
PYTHONPATH=gateway/tools python gateway/tools/docx/accept_changes.py input.docx output.docx

완료 조건

검증 프로토콜

1. pack.py 실행 시 validate.py가 자동으로 XSD 검증 수행
2. 생성된 문서를 soffice.py로 열기 가능 여부 확인
3. 모든 검증 통과 후에만 완료 선언

상태 정리

완료 시 임시 unpack 디렉토리 삭제. .omc/state/ 에 상태 파일 미사용 (단건 작업).

취소

cancelomc 또는 stopomc 키워드로 즉시 중단. 임시 unpack 디렉토리가 존재하면 삭제.

재개

임시 unpack 디렉토리가 남아있으면 해당 상태에서 재개 가능. 원본 파일이 보존되어 있으므로 처음부터 재시작도 가능.

MUST 규칙

MUST NOT 규칙

검증 체크리스트

• frontmatter에 name, description 포함
• 에이전트 호출 규칙 섹션 포함 (FQN, 프롬프트 조립 4단계, 오케스트레이션 활용)
• 모든 Phase에 스킬 부스팅 명시
• 완료 조건, 검증 프로토콜, 상태 정리, 취소/재개 섹션 포함
• MUST 규칙, MUST NOT 규칙 섹션 포함
• Agent 위임 단계에 5항목 포함