PDF

PDF 읽기, 생성, 편집, 검토 + 비전 기반 추출. 이 스킬은 PDF 문서의 전체 수명 주기를 처리합니다 — reportlab으로 새 파일을 생성하는 것부터 pdfplumber로 텍스트를 추출하고, Poppler로 페이지를 이미지로 렌더링하며, 매 편집 후 시각적 품질 검증을 수행하는 것까지 포함합니다.

Reference AI & Media

빠른 참조

워크플로우

pdf 스킬이 활성화되면, 에이전트는 모든 PDF 작업에 대해 엄격한 4단계 워크플로우를 따릅니다:

의존성

이 스킬은 누락된 의존성을 자동으로 감지하고 설치를 시도합니다. 설치가 차단된 경우(권한, 네트워크), 에이전트가 누락된 항목과 수동 설치 방법을 정확히 알려줍니다.

이 스킬은 Python 의존성 관리에 uv를 우선 사용합니다. uv를 사용할 수 없는 경우 python3 -m pip install로 대체합니다.

전체 설치 명령어

# Python packages (preferred: uv)
uv pip install reportlab pdfplumber pypdf

# Python packages (fallback: pip)
python3 -m pip install reportlab pdfplumber pypdf

# System tools: macOS (Homebrew)
brew install poppler

# System tools: Ubuntu/Debian
sudo apt-get install -y poppler-utils

렌더링 명령어

핵심 렌더링 명령어는 PDF 페이지를 PNG 이미지로 변환합니다:

pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX

$OUTPUT_PREFIX-1.png, $OUTPUT_PREFIX-2.png 등의 파일이 생성됩니다 — 페이지당 하나의 PNG입니다. 에이전트는 최종 PDF를 전달하기 전에 이 이미지들을 읽어 레이아웃 품질을 검증합니다.

파일 규칙

품질 규칙

이 스킬은 엄격한 시각적 및 타이포그래피 표준을 적용합니다. 생성되는 모든 PDF는 다음 검사를 통과해야 합니다:

최종 전달 체크리스트

PDF 작업을 완료로 표시하기 전에 에이전트는 다음 체크리스트를 수행합니다:

1. 최신 PNG 렌더에서 시각적 결함이 없는지 확인.
2. 머리글과 바닥글이 모든 페이지에 올바르게 표시되는지 확인.
3. 페이지 번호가 순차적이고 올바른 위치에 있는지 확인.
4. 섹션 전환을 점검 — 고립된 제목이나 분리된 단락이 없는지 확인.
5. 사용자 승인 후 tmp/pdfs/의 중간 파일을 정리.

DOCX-PDF 변환

이 스킬은 LibreOffice를 사용한 Word 문서의 PDF 변환도 지원합니다:

# Convert DOCX to PDF via soffice (LibreOffice headless)
soffice --headless --convert-to pdf input.docx --outdir output/pdf/

원본이 Word 문서이고 최종 산출물이 PDF여야 할 때 유용합니다. 에이전트는 변환된 출력에 대해서도 전체 렌더링 후 검증 루프를 실행합니다.

기능 요약

"~해줘" 사용 예시

자연어로 PDF 작업을 호출하는 실제 사용 예시입니다. 한국어와 영어 모두 사용 가능합니다.

pdf-vision과의 비교

CLI-JAW에는 두 가지 PDF 관련 스킬이 포함되어 있습니다. 이들은 중복이 아닌 상호 보완적입니다:

문제 해결

Poppler를 찾을 수 없음

에이전트가 pdftoppm을 사용할 수 없다고 보고하면 Poppler를 설치하세요:

# macOS
brew install poppler

# Ubuntu/Debian
sudo apt-get install -y poppler-utils

# Verify
pdftoppm -v

유니코드 대시 렌더링 문제

하이픈과 대시에서 깨진 문자나 누락된 문자가 보이면, 원본 데이터에 유니코드 대시(U+2011, U+2013, U+2014)가 포함되어 있을 수 있습니다. 이 스킬은 뷰어 호환성 문제를 방지하기 위해 ASCII 하이픈(-)을 강제합니다. 에이전트는 생성 중 이러한 문자를 자동으로 대체합니다.

레이아웃 충실도 경고

pdfplumber와 pypdf는 시각적 레이아웃이 아닌 문자 위치를 기반으로 텍스트를 추출합니다. 복잡한 다단 레이아웃, 겹치는 텍스트 상자, 회전된 텍스트는 정확하게 추출되지 않을 수 있습니다. 이런 경우 텍스트 스트림 파싱 대신 시각적 분석을 사용하는 pdf-vision 사용을 고려하세요.

LibreOffice가 설치되어 있지 않음

DOCX-PDF 변환에는 LibreOffice가 필요합니다. soffice를 찾을 수 없는 경우:

# macOS
brew install --cask libreoffice

# Ubuntu/Debian
sudo apt-get install -y libreoffice

설치

# CLI
jaw skill install pdf

# In-chat (Korean)
"PDF 스킬 설치해줘"

# In-chat (English)
"Install the PDF skill"

# Verify installation
jaw skill info pdf

# Expected output of jaw skill info pdf:
#   Name:     pdf
#   Status:   active
#   Category: AI & Media
#   Path:     ~/.cli-jaw/skills/pdf/SKILL.md
#   Description: PDF creation, reading, editing, merging, and text extraction