pdf

Original：🇺🇸 English
Translated

PDF 처리 스킬 — 읽기, 생성, 편집, 폼 작성, 변환

1installs
Sourceunicorn-plugins/claude-skills
Added on

NPX Install

npx skill4agent add unicorn-plugins/claude-skills pdf

Tags

Translated version includes tags in frontmatter
pdf-processingagent-workflowdocument-manipulationskill-activationpdf-tools

SKILL.md Content

View Translation Comparison →

PDF 처리

[PDF 처리 스킬 활성화]

목표

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

활성화 조건

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

에이전트 호출 규칙

에이전트 FQN

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

프롬프트 조립 절차

  1. agents/pdf-handler/
    에서 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. 프롬프트 조립: 공통 정적(runtime-mapping) → 에이전트별 정적(3파일) → 동적(작업 지시)
  4. 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)로 확인 가능
  • 사용자 요청의 모든 항목이 반영됨

검증 프로토콜

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

상태 정리

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

취소

cancelomc
또는 
stopomc
키워드로 즉시 중단.

재개

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

MUST 규칙

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

MUST NOT 규칙

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

검증 체크리스트

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