인쇄용 PDF 문서 스킬 pdf-doc, 그리고 문서 스킬 고르기
pdf-doc 이 무엇을 만드는지, (2) 문서 생성 스킬들이 각각 언제 쓰이는지 판단하고, (3) pdf-doc 을 자기 프로젝트에 붙이는 법을 설명할 수 있다.standarda-template 에 문서 생성 스킬 pdf-doc 이 새로 들어왔다(변경 이력: 2026-08-13, PR #65). 이걸 계기로 "문서를 만드는 스킬이 여러 개인데 언제 뭘 쓰나" 를 정리한다.
1. pdf-doc 이 푸는 문제: 프로젝트와 무관한 범용 고객 문서
pdf-doc 은 HTML 을 자유롭게 디자인해 인쇄용(A4) PDF 를 만드는 스킬이다.
앞서 client-usage-guide 와 manual 은 둘 다 이 프로젝트의 기능·화면을 문서로 옮긴다. 그런데 온보딩 안내서, 제안서, 외부 서비스 가입 가이드처럼 우리 앱 화면과 상관없는 고객 전달 문서도 반복해서 만든다. pdf-doc 은 그 자리를 채운다. 표지, 콜아웃 박스, 단계 헤더, 화면 일러스트(SVG), 페이지네이션을 갖춘 문서를 headless chromium 으로 PDF 로 변환하고, 각 페이지를 PNG 로 렌더해 잘림·겹침을 눈으로 검증한다.
스킬은 세 파일로 구성된다(standarda-template 이 제공하는 경로).
.claude/skills/pdf-doc/SKILL.md # 워크플로우 정의
.claude/skills/pdf-doc/template.html # 표지·콜아웃·단계헤더·SVG 디자인 시스템 스캐폴드
.claude/skills/pdf-doc/build_pdf.sh # chromium 자동탐색 변환 + 페이지별 PNG 렌더 검증
이 흐름은 server_agent 에서 비개발자 고객사용 "AWS 계정 생성·권한 위임 안내서" 를 만들며 정립해 스킬로 승격한 것이다.
2. manual 과 pdf-doc 의 갈림: 프로젝트 화면이 들어가나
두 스킬 다 PDF 를 낸다. 갈림길은 문서에 이 프로젝트의 실제 화면이 들어가느냐다.
manual: 이 프로젝트의 실제 화면을 Playwright 로 캡처한 슬라이드형 사용 매뉴얼. 클릭 위치를 주황 박스로 강조한다.pdf-doc: 이 프로젝트 화면과 무관한 범용 문서. 캡처가 어려운 화면(예: 외부 서비스 콘솔)은 인라인 SVG 일러스트로 대체한다.
여기서 정직성 규칙이 하나 붙는다. 캡처가 어려운 화면을 "진짜 캡처인 척" 만들지 않고, SVG 일러스트에 참고용 예시 화면 태그를 달아 실제 셋업 때 진짜 캡처로 교체 가능함을 알린다.
Q. 그럼 스크린샷을 SVG 로 그럴듯하게 지어내는 건가?
A. 아니다. 실제 캡처를 못 하는 화면임을 표기한 일러스트다. 실제 화면인 것처럼 위장하지 않는 게 이 스킬의 원칙이다.
3. 문서 생성 스킬 지도
지금 문서를 만드는 스킬은 대상·형태로 갈린다. 아래 표로 어느 것이 지금 필요한지 고른다.
| 스킬 | 누구에게 | 무엇을 |
|---|---|---|
feature-doc |
개발자(내부) | 구현된 기능의 사실 중심 설명 문서 |
client-usage-guide |
고객(비개발자) | feature 문서 기반 사용법 md + Word 배포본 |
client-test-guide |
고객(비개발자) | 테스트·합격 체크리스트 |
manual |
고객·운영자 | 이 프로젝트 화면 캡처 슬라이드/PDF |
pdf-doc |
고객(외부) | 프로젝트와 무관한 범용 인쇄 PDF(SVG 일러스트) |
create-docx |
공용(저수준) | Word(.docx) 파일 자체. 위 스킬들이 재사용 |
고르는 기준 한 줄: 개발자용이면 feature-doc, 고객 사용법이면 client-usage-guide, 합격 확인이면 client-test-guide, 우리 화면을 짚는 발표 매뉴얼이면 manual, 우리 화면과 무관한 범용 배포 문서면 pdf-doc 이다.
4. HTML to PDF 함정과 붙이는 법
pdf-doc 을 쓸 때 가장 자주 나는 실수는 페이지 수가 두 배로 튀는 것이다. @page{size:A4;margin:0} 와 변환 시 --no-pdf-header-footer 조합이 아니면, 브라우저 기본 여백과 297mm 높이가 충돌해 섹션마다 빈 페이지가 껴 장수가 배로 늘어난다. 그래서 완성 판단 전에 페이지별 PNG 를 실제로 눈으로 봐야 넘침·잘림·푸터 겹침을 잡는다.
이 프로젝트(education)에는 아직 pdf-doc 이 없다. 붙이려면 /sync-from-template 로 스킬 파일만 선별 반영한다(Django 모델과 무관). 형제 스킬(manual·create-docx)과 이름이 비슷해도 서로 밀려나지 않는 건 각 스킬 description 에 경계를 박아 뒀기 때문이다(그 원리는 스킬 description 라우팅).
마무리
- 핵심 정리: 문서 스킬은 대상(개발자/고객)과 형태(md·Word·슬라이드·범용 PDF)로 갈린다.
pdf-doc은 그중 "이 프로젝트 화면과 무관한 범용 인쇄 문서" 자리를 채우며, 캡처 대신 SVG 일러스트를 정직하게 표기한다. - 주의 사항:
@page여백·--no-pdf-header-footer를 빠뜨려 빈 페이지로 장수가 두 배가 되는 것. 페이지별 PNG 로 눈검증한다. - 다음 시간: standarda-template 의 변경이 어떻게 각 프로젝트로 전파되는지는 standarda 변경 이력 추적과 sync-from-template로 잇는다.