PDF 처리

[PDF 처리 스킬 활성화]

목표

PDF 파일에 대한 모든 작업을 처리함. 텍스트/테이블 추출, PDF 병합/분할, 회전, 워터마크 추가, 신규 PDF 생성, 폼 작성, 암호화/복호화, 이미지 추출, OCR을 통한 스캔 PDF 검색 가능화 등을 포함.

활성화 조건

사용자가

.pdf

파일을 언급하거나 PDF 관련 작업 요청 시 활성화.

에이전트 호출 규칙

에이전트 FQN

에이전트	FQN	티어
pdf-handler	`claude-skills:pdf-handler:pdf-handler`	MEDIUM

프롬프트 조립 절차

```
agents/pdf-handler/
```
에서 3파일 로드 (AGENT.md + agentcard.yaml + tools.yaml)
```
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]
```
  제외
- 최종 도구 = (구체화된 도구) - (제외 도구)
프롬프트 조립: 공통 정적(runtime-mapping) → 에이전트별 정적(3파일) → 동적(작업 지시)

Task(subagent_type="claude-skills:pdf-handler:pdf-handler", model="claude-sonnet-4-5", prompt=조립된 프롬프트)

호출

오케스트레이션 스킬 활용

워크플로우 Phase	추천 스킬	적용
Phase 1 (작업 유형 판별)	`ulw` 매직 키워드	필수
Phase 2-A (PDF 읽기/추출)	`ulw` 매직 키워드	필수
Phase 2-B (새 PDF 생성)	`/oh-my-claudecode:ralph`	필수
Phase 2-C (병합/분할)	`ulw` 매직 키워드	필수
Phase 2-D (폼 작성)	`/oh-my-claudecode:ralph`	필수
Phase 2-E (이미지 변환)	`ulw` 매직 키워드	필수
Phase 3 (결과 검증)	`ulw` 매직 키워드	필수

워크플로우

Phase 1: 작업 유형 판별 (

ulw

활용)

사용자 요청을 분석하여 작업 유형을 읽기/생성/편집/폼/변환 중 하나로 분류.

Phase 2-A: PDF 읽기/추출 → Agent: pdf-handler (

ulw

활용)

TASK: pypdf, pdfplumber를 활용하여 PDF에서 텍스트, 테이블, 메타데이터 추출
EXPECTED OUTCOME: 추출된 텍스트/테이블 데이터, 메타데이터
MUST DO: pdfplumber로 테이블 추출 시 레이아웃 보존, 스캔 PDF는 OCR 필요 여부 안내
MUST NOT DO: 스캔 PDF를 일반 추출로 처리하지 않음 (OCR 필요)
CONTEXT: 원본 PDF 경로, 추출 대상(텍스트/테이블/메타데이터),
```
PYTHONPATH=gateway/tools
```
환경변수 설정 필수

Phase 2-B: 새 PDF 생성 → Agent: pdf-handler (

/oh-my-claudecode:ralph

활용)

TASK: reportlab를 활용하여 신규 PDF 생성
EXPECTED OUTCOME: 유효한 PDF 구조를 가진 신규 PDF 파일
MUST DO: Paragraph 객체에서
```
<sub>
```
,
```
<super>
```
태그 사용 (Unicode 첨자 금지), 여러 페이지 생성 시 Platypus 프레임워크 활용
MUST NOT DO: Unicode 첨자/위첨자 문자 (₀₁₂, ⁰¹²) 사용 금지 (검은 박스 렌더링됨)
CONTEXT: 콘텐츠 요구사항, 페이지 레이아웃,
```
PYTHONPATH=gateway/tools
```
환경변수 설정 필수

Phase 2-C: 병합/분할 → Agent: pdf-handler (

ulw

활용)

TASK: pypdf + qpdf로 PDF 병합/분할
EXPECTED OUTCOME: 병합된 PDF 또는 분할된 PDF 파일들
MUST DO: qpdf 활용하여 구조 무결성 보존
MUST NOT DO: 메타데이터 손실 금지
CONTEXT: 원본 PDF 경로, 병합/분할 범위,
```
PYTHONPATH=gateway/tools
```
환경변수 설정 필수

Phase 2-D: 폼 작성 → Agent: pdf-handler (

/oh-my-claudecode:ralph

활용)

TASK: 전략 판별(필드 방식 vs 주석 오버레이) 후 PDF 폼 작성
EXPECTED OUTCOME: 작성 완료된 PDF 폼, 바운딩 박스 검증 통과
MUST DO: check_fillable_fields.py로 필드 확인, fill_fillable_fields.py(필드 방식) 또는 fill_pdf_form_with_annotations.py(주석 오버레이) 선택, check_bounding_boxes.py로 좌표 검증
MUST NOT DO: 전략 판별 없이 폼 작성 시도 금지, 바운딩 박스 검증 없이 결과 전달 금지
CONTEXT: 원본 PDF 경로, 폼 데이터, agents/pdf-handler/references/pdf-forms-guide.md 참조,
```
PYTHONPATH=gateway/tools
```
환경변수 설정 필수

스크립트 호출 패턴:

bash

python gateway/tools/pdf/check_fillable_fields.py input.pdf
python gateway/tools/pdf/fill_fillable_fields.py input.pdf output.pdf
PYTHONPATH=gateway/tools python gateway/tools/pdf/fill_pdf_form_with_annotations.py input.pdf output.pdf

Phase 2-E: 이미지 변환 → Agent: pdf-handler (

ulw

활용)

TASK: PDF를 PNG 이미지로 변환
EXPECTED OUTCOME: 각 페이지가 PNG 이미지로 변환됨
MUST DO: convert_pdf_to_images.py 활용
MUST NOT DO: 이미지 품질 저하 금지
CONTEXT: 원본 PDF 경로, 출력 디렉토리,
```
PYTHONPATH=gateway/tools
```
환경변수 설정 필수

스크립트 호출 패턴:

bash

PYTHONPATH=gateway/tools python gateway/tools/pdf/convert_pdf_to_images.py input.pdf output_dir/

Phase 3: 결과 검증 (

ulw

활용)

PDF 읽기 가능 여부 확인 (pypdf)
폼 작성인 경우 check_bounding_boxes.py로 좌표 검증
create_validation_image.py로 시각적 검증 이미지 생성
모든 검증 통과 후에만 완료 선언

스크립트 호출 패턴:

bash

python gateway/tools/pdf/check_bounding_boxes.py output.pdf
PYTHONPATH=gateway/tools python gateway/tools/pdf/create_validation_image.py output.pdf validation.png

완료 조건

생성/편집된 PDF가 유효한 PDF 구조를 가짐
폼 작성 시 check_bounding_boxes.py 검증 통과
시각적 검증 이미지(create_validation_image.py)로 확인 가능
사용자 요청의 모든 항목이 반영됨

검증 프로토콜

PDF 읽기 가능 여부 확인 (pypdf)
폼 작성인 경우 check_bounding_boxes.py로 좌표 검증
create_validation_image.py로 시각적 검증 이미지 생성
모든 검증 통과 후에만 완료 선언

상태 정리

완료 시 임시 이미지 파일 생성 시 사용자에게 안내. 상태 파일 미사용 (단건 작업).

취소

cancelomc

또는

stopomc

키워드로 즉시 중단.

재개

원본 PDF가 보존되어 있으므로 처음부터 재시작 가능.

MUST 규칙

#	규칙
1	폼 작성 시 반드시 전략 판별 (필드 방식 vs 주석 오버레이) 선행
2	시각적 검증 이미지를 생성하여 결과 확인
3	모든 Phase에 오케스트레이션 스킬 활용 필수 명시
4	에이전트 위임 시 5항목 (TASK, EXPECTED OUTCOME, MUST DO, MUST NOT DO, CONTEXT) 포함
5	PDF 커스텀 도구 호출 시 `PYTHONPATH=gateway/tools` 환경변수 설정 필수

MUST NOT 규칙

#	금지 사항
1	폼 전략 판별 없이 직접 폼 작성 시도 금지
2	바운딩 박스 검증 없이 폼 결과 전달 금지
3	에이전트의 내부 사고 방식이나 단계별 절차를 스킬에서 기술하지 않음
4	reportlab 사용 시 Unicode 첨자/위첨자 문자 사용 금지

검증 체크리스트

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

pdf

NPX Install

Tags

SKILL.md Content

PDF 처리

목표

활성화 조건

에이전트 호출 규칙

에이전트 FQN

프롬프트 조립 절차

오케스트레이션 스킬 활용

워크플로우

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

Phase 2-A: PDF 읽기/추출 → Agent: pdf-handler (
`ulw`
활용)

Phase 2-B: 새 PDF 생성 → Agent: pdf-handler (
`/oh-my-claudecode:ralph`
활용)

Phase 2-C: 병합/분할 → Agent: pdf-handler (
`ulw`
활용)

Phase 2-D: 폼 작성 → Agent: pdf-handler (
`/oh-my-claudecode:ralph`
활용)

Phase 2-E: 이미지 변환 → Agent: pdf-handler (
`ulw`
활용)

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

완료 조건

검증 프로토콜

상태 정리

취소

재개

MUST 규칙

MUST NOT 규칙

검증 체크리스트

pdf

NPX Install

Tags

SKILL.md Content

PDF 처리

목표

활성화 조건

에이전트 호출 규칙

에이전트 FQN

프롬프트 조립 절차

오케스트레이션 스킬 활용

워크플로우

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

Phase 2-A: PDF 읽기/추출 → Agent: pdf-handler (ulw 활용)

Phase 2-B: 새 PDF 생성 → Agent: pdf-handler (/oh-my-claudecode:ralph 활용)

Phase 2-C: 병합/분할 → Agent: pdf-handler (ulw 활용)

Phase 2-D: 폼 작성 → Agent: pdf-handler (/oh-my-claudecode:ralph 활용)

Phase 2-E: 이미지 변환 → Agent: pdf-handler (ulw 활용)

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

완료 조건

검증 프로토콜

상태 정리

취소

재개

MUST 규칙

MUST NOT 규칙

검증 체크리스트

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

Phase 2-A: PDF 읽기/추출 → Agent: pdf-handler (
`ulw`
활용)

Phase 2-B: 새 PDF 생성 → Agent: pdf-handler (
`/oh-my-claudecode:ralph`
활용)

Phase 2-C: 병합/분할 → Agent: pdf-handler (
`ulw`
활용)

Phase 2-D: 폼 작성 → Agent: pdf-handler (
`/oh-my-claudecode:ralph`
활용)

Phase 2-E: 이미지 변환 → Agent: pdf-handler (
`ulw`
활용)

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