결론부터. 클로드 코드 pdf 스킬을 만들어주는 book-to-skill은 추출과 챕터 감지가 실제로 동작했고, 직접 만든 한국어 PDF와 법령형 장 번호도 인식했다. 다만 두 가지를 알고 시작해야 한다. 설치 문서가 안내하는 pip 경로는 지금 작동하지 않고, 토큰이 절약되는지는 “무엇과 비교하느냐”에 따라 답이 완전히 달라진다.
클로드 코드 pdf 스킬을 직접 설치해서 다섯 가지 문서 형태로 돌려보고, 프로젝트가 제공하는 측정 스크립트로 토큰 계산까지 재현했다. 아래는 전부 실행 결과다.
클로드 코드 pdf 스킬이란 무엇인가
book-to-skill은 내가 가진 문서를 에이전트 스킬로 바꿔주는 MIT 라이선스 변환기다. PDF, EPUB, DOCX, HTML, 마크다운, RTF를 넣으면 SKILL.md 코어 파일 하나와 챕터별 파일, 용어집, 패턴 파일, 치트시트를 만들어준다.
핵심은 전부를 들고 있지 않는다는 점이다. 질문이 들어오면 코어와 해당 챕터 파일만 읽는다. 개방형 에이전트 스킬 규격을 따르기 때문에 클로드 코드뿐 아니라 깃허브 코파일럿 CLI, Amp에서도 같은 결과물이 돌아간다.
아래 내용은 전부 Ubuntu 22.04, 파이썬 3.10.12, poppler 설치, docling 미설치 환경에서 커밋 442aaaa(2026-08-07, 버전 1.3.0) 기준으로 실행했다. 2026년 8월 9일 확인 시점에 별 약 1만 9천 개, 최신 정식 릴리스는 2026년 7월 30일 공개된 v1.3.0이다.
1. 클로드 코드 pdf 스킬, 한글 책과 법령은 되는가
한국 사용자가 가장 먼저 궁금해할 부분이라 여기부터 봤다. 된다. 그것도 곁다리 기능이 아니라 v1.3.0의 대표 기능이다.
릴리스 노트에 따르면 제N장과 함께 제N절, 제N관, 제N편을 인식하고, 한국 법령이 조항을 나중에 끼워 넣을 때 쓰는 제6장의2 형태까지 처리한다. 약 3천 건의 법령 말뭉치로 검증해 정밀도 0.999, 재현율 1.000을 보고하고 있다. 그리고 제 접두를 반드시 요구하도록 만들어서 “사진 10장” 같은 일상 표현이 챕터로 잘못 잡히지 않는다.
실제 정규식은 이렇게 생겼다.
제 + 숫자 + [장 편 절 관] + (의N)?직접 다섯 가지 형태를 넣어봤다.
| 입력 | 자동 감지 | 판정 |
|---|---|---|
영어 Chapter 1~Chapter 5 | 5 | 정상 |
한글 제1장~제5장 | 5 | 정상 |
법령형 제6장의2 포함 | 3 | 삽입 장까지 인식 |
조문 제1조~제5조 | 0 | 설계상 제외 |
| 제목만 (번호 없는 소제목) | 0 | 수동 매핑 필요 |
네 번째 줄이 중요하다. 조문을 장으로 세지 않는 것은 버그가 아니라 의도된 설계다. 근로기준법 하나만 해도 조가 수백 개인데 그걸 전부 챕터로 잡으면 파일이 수백 개로 쪼개진다.
한글 PDF도 넣어봤다. 다섯 쪽짜리 합성 PDF에서 챕터 5개를 모두 찾았고 44밀리초가 걸렸다. 원본 추출 결과 대비 문자 수 비율은 102.8퍼센트였다. 다만 이 숫자는 정확도 점수가 아니라 단순 글자 수 비교이고, 직접 만든 파일 하나로 실제 한국어 책이나 법령 PDF가 잘 된다고 말할 수는 없다.
2. 설치, pip 경로는 지금 작동하지 않는다
설치 문서는 두 가지 방법을 안내한다. 스킬 폴더로 git clone해서 슬래시 명령을 등록하는 방법과, pip install book-to-skill로 추출 엔진만 설치하는 방법이다. 저장소 README 자체는 clone 방법만 보여주고, pip 쪽은 별도 설치 문서에 있다.
후자가 실패한다.
$ pip install book-to-skill
ERROR: Could not find a version that satisfies the requirement book-to-skill
(from versions: none)네트워크 문제인지 확인하려고 같은 환경에서 pypdf를 설치해봤더니 정상이었고, 패키지 인덱스를 표기 세 가지로 직접 조회했더니 전부 404였다.
그렇다고 가짜 프로젝트는 아니다. pyproject.toml에 이름과 버전 1.3.0, 실행 스크립트가 다 정의돼 있고 로컬에서는 정상적으로 빌드되고 설치된다. 말할 수 있는 것은 2026년 8월 9일 테스트 시점에 인덱스 경로로 설치할 수 없었다는 것까지다. 과거에 올렸다가 내렸을 가능성은 404만으로 배제할 수 없다.
대응은 간단하다. clone 경로를 쓰면 된다. 문서대로 정상 작동한다.
3. 클로드 코드 pdf 스킬로 토큰이 정말 절약되는가
프로젝트가 내세우는 문구는 책 전체를 컨텍스트에 넣는 것 대비 24배에서 51배 절약이고, 실제 책으로 측정한 값이라고 밝히고 있다. 이번 실험에서도 책 전체를 넣는 방식 대비 절감 구조 자체는 재현됐지만, 아래 표의 최대치는 28.7배였다. 다만 대부분의 사람이 실제로 하는 행동은 책 전체를 붙여넣는 것이 아니다. 보통은 에이전트가 필요한 챕터 하나를 열어본다.
그래서 12장짜리 책을 만들어 장의 길이만 바꿔가며 프로젝트 자체 측정 스크립트를 여섯 번 돌렸다.
| 장당 토큰 | 책 전체 투입 대비 | 챕터 하나 열기 대비 | 판정 |
|---|---|---|---|
| 753 | 1.8배 | 0.2배 | 손해 |
| 1,500 | 3.6배 | 0.3배 | 손해 |
| 2,993 | 7.2배 | 0.6배 | 손해 |
| 5,233 | 12.6배 | 1.0배 | 교차 |
| 8,220 | 19.7배 | 1.6배 | 이득 |
| 11,953 | 28.7배 | 2.4배 | 이득 |
책 전체를 넣는 것과 비교하면 어떤 크기에서도 이득이다. 손해가 나는 쪽은 챕터 하나만 여는 경우와 비교했을 때이고, 그 교차점이 장당 약 5,200토큰 근처에 나타난다.
그런데 이 5,200은 보편적인 기준이 아니다. --skill-dir 없이 돌리면 스크립트는 실제 생성물을 재지 않고 코어 4,000 + 압축 챕터 1,000이라는 고정값을 대입한다. 출력에도 “design cap”이라고 찍힌다. 즉 위 여섯 번은 스킬 여섯 개를 벤치마크한 것이 아니라 고정 모델에 책 크기를 대입한 것이다. 게다가 실제 장당 예산은 책 종류와 깊이에 따라 800에서 3,000까지 움직인다.
한국어 자료에는 이 표를 그대로 쓰면 안 된다
여기가 한국 사용자에게 가장 중요한 부분이다. 같은 글을 두 계산기가 다르게 센다. 같은 문장을 반복한 텍스트를 두 함수에 각각 넣어봤다.
| 언어 | 추출 단계 추정기 | 토큰 측정 스크립트 | 차이 |
|---|---|---|---|
| 영어 | 800 | 800 | 일치 |
| 한국어 | 986 | 480 | 약 2배 |
| 일본어 | 826 | 1 | 826배 |
영어는 두 값이 정확히 맞는데 한국어는 절반으로 센다. 측정 스크립트가 tiktoken 없이 돌면 공백으로 나눈 단어 수를 기준으로 삼기 때문이다. 일본어처럼 단어 사이에 공백이 없는 언어에서는 아예 무너진다. 프로젝트도 이 문제를 알고 있고, 약 1000배 과소 계산이라며 수정 중이지만 아직 정식 릴리스에는 들어가지 않았다.
그래서 실무적으로는 이렇게 정리된다. 한글 책의 장 크기를 이 스크립트로 재면 실제보다 작게 나오고, 그만큼 손익 판단이 왜곡된다. 한국어 자료로 판단할 생각이라면 토큰 비교 스크립트를 돌리기 전에 tiktoken을 설치하는 편이 안전하다. 다만 이건 비교 스크립트에만 적용되고, 추출 단계의 자체 추정기는 별도로 유지된다.
4. 실패하는 조건
번호 없이 제목만으로 장을 나눈 책은 자동 분할이 되지 않는다. 다만 조용히 실패하지는 않는다. 추출기가 “0 detected”와 경고를 출력하고, 측정 스크립트는 아예 실행을 거부하면서 technical 모드를 권한다. 문서도 이런 경우 섹션을 직접 지정해 변환을 이어갈 수 있다고 안내한다. 자동 분할 실패이지 변환 실패가 아니다.
PDF 머리말 제거 로직에도 알아둘 점이 있다. 페이지 위아래에서 반복되는 줄을 머리말로 보고 지우는데, 지울 때는 위치를 확인하지 않는다. 바로 다음 줄에 있는 쪽번호 제거는 위치를 확인하는데 머리말 제거는 그렇지 않다. 모든 줄이 같은 문장인 극단적인 PDF를 만들어 넣었더니 7,380자가 181자만 남았다.
다만 이건 일부러 만든 조건이다. 문장이 제각각인 정상 PDF는 같은 실행에서 멀쩡했다. 이미 머리말로 분류된 문장과 똑같은 줄이 본문에 있을 때만 해당된다. 양식이나 반복 문구가 많은 문서를 넣는다면 추출 후 단어 수를 원본과 대조해보는 편이 좋다.
5. 보안 기능은 이미 들어와 있다
v1.3.0에는 생성된 스킬을 검사해 프롬프트 인젝션 문구를 찾아내는 스캐너, 보이지 않는 유니코드 제거, DOCX 엔티티 확장 공격 방어, 파일명이 하이픈으로 시작할 때의 인자 인젝션 방어가 들어 있다. 예정이 아니라 이미 배포된 기능이다.
이 기능이 있다는 사실 자체가 의미하는 바가 있다. 문서를 스킬로 바꾸는 과정에 공격면이 존재한다는 것을 프로젝트가 인정한 것이다. 남이 보내준 PDF를 변환할 생각이라면 한 번 멈춰서 생각해볼 지점이다. 문서 안에 에이전트를 향한 지시문을 심을 수 있고, 생성된 스킬은 내 에이전트 권한으로 로드되기 때문이다.
다른 방법과 비교하면
| 방법 | 비용 구조 | 적합한 경우 |
|---|---|---|
| 책 전체 붙여넣기 | 매 턴마다 전체 재청구 | 한 번 훑고 끝낼 때 |
| 에이전트가 PDF 직접 열기 | 목차 + 해당 챕터, 1회 | 장이 짧고 가끔 물어볼 때 |
| 클로드 코드 pdf 스킬로 변환 | 고정 코어 + 압축 챕터 | 장이 두껍고 반복해서 볼 때 |
| 여러 권을 검색 | 질의마다 조각 | 책이 많고 구절을 찾을 때 |
이 표는 설계 비교이지 벤치마크가 아니다. 검색 방식은 나란히 돌려보지 않았다.
클로드 코드 pdf 스킬 변환 전 확인할 것
- 저장소를 에이전트 스킬 폴더로 clone한다. pip 줄은 당분간 무시한다.
- 의존성 점검 명령을 먼저 돌린다. 어떤 추출기가 설치돼 있고 무엇이 빠졌는지 설치 명령까지 알려준다.
- 책의 장 제목에 번호가 붙어 있는지 확인한다. 번호 없는 제목뿐이면 자동 분할은 되지 않는다.
- 장 크기를 가늠한다. 장당 5,000토큰 아래라면 챕터를 직접 여는 쪽이 낫다는 모델 결과가 나온다. 책 전체 투입과 비교하면 어떤 크기든 이득이다.
- 추출 후 보고된 단어 수를 원본과 대조한다. 크게 줄었다면 머리말 제거가 본문을 지웠을 수 있다.
- 한글이나 일본어 자료라면 토큰 비교 스크립트를 돌리기 전에 tiktoken을 설치한다. 추출 단계의 자체 추정기는 이것과 무관하게 따로 동작한다.
- 내가 권리를 가진 문서만 변환한다. 남이 보낸 파일은 특히 조심한다.
다른 AI 도구를 같은 방식으로 재본 기록도 있다. 코덱스 디자인 플러그인은 설치 전에 확인할 것을 정리했고, 클로드와 챗GPT에 같은 10-K를 넣어본 대조도 해봤다.
누가 쓰면 좋고 누가 안 써도 되는가
클로드 코드 pdf 스킬을 설치할 만한 경우. 두꺼운 기술서를 계속 다시 펴보는 사람, 장이 길고 번호가 붙은 사내 문서를 팀이 반복해서 조회하는 경우, 그리고 번호 체계가 있는 규정과 법령을 다루는 경우다. 마지막 항목은 감지 자체는 확인했지만 실제 법령 PDF 변환까지 해본 것은 아니라 시험해볼 만하다는 정도다.
건너뛰어도 되는 경우. 장이 짧게 쪼개진 자료, 한 권에서 답 하나만 얻으면 되는 경우, 번호 없이 제목만으로 구성된 문서다. 이럴 때는 에이전트가 파일을 직접 여는 편이 싸고 간단하다.
자주 묻는 질문
클로드 코드 pdf 스킬은 무료인가
변환기 자체는 MIT 라이선스로 무료다. 비용이 드는 쪽은 변환 과정이다. 에이전트가 추출된 텍스트를 읽고 스킬 파일을 쓰기 때문에 그만큼 모델 사용료가 발생한다. 저장소는 책 한 권당 대략 1달러 수준이라고 밝히고 있는데 이 값은 직접 검증하지 않았다.
pip install이 안 되는데 어떻게 설치하나
2026년 8월 9일 기준으로 패키지 인덱스에서 배포판을 확인할 수 없었다. 저장소를 스킬 폴더로 clone하면 정상 작동한다. 프로젝트가 깨진 것은 아니고, 현재 인덱스에서 설치할 수 없는 상태다.
PDF를 그냥 첨부하는 것과 무엇이 다른가
PDF를 직접 읽는 방식은 질문할 때마다 목차와 필요한 원문 구간을 다시 찾아 들어간다. 스킬은 앞단에서 한 번 구조화해둔 코어와 관련 챕터를 불러온다. 대신 그 앞단 비용이 고정으로 들기 때문에 장이 짧으면 오히려 손해가 된다.
한글 책은 어느 정도까지 되나
장 번호가 제N장 형태면 영어와 동등하게 인식한다. 법령의 제6장의2 같은 삽입 장도 처리하고, 조문은 의도적으로 제외한다. 다만 확인한 것은 챕터 감지와 합성 PDF 한 개까지이고, 실제 출판 도서나 법령 PDF의 표와 레이아웃까지 검증하지는 않았다.
클로드 코드 pdf 스킬은 EPUB이나 워드 파일도 되나
된다. EPUB, DOCX, HTML, RTF, 마크다운, 일반 텍스트를 지원하고 MOBI와 AZW는 외부 변환기를 거친다. 선택 라이브러리를 설치하면 품질이 올라가고, 무엇이 빠졌는지는 점검 명령이 알려준다.
내 책이 어딘가로 업로드되나
추출은 내 컴퓨터에서 돌아간다. 다만 추출된 텍스트를 에이전트가 읽기 때문에, 그 이후는 사용하는 모델 제공자의 데이터 처리 조건을 따른다. 저장소 자체는 어떤 책 내용도 포함하지 않는다.
변환에 시간이 얼마나 걸리나
텍스트 추출은 다섯 장짜리 문서에 28에서 29밀리초, 다섯 쪽 PDF에 44밀리초였다. 이건 추출 단계만이다. 뒤따르는 에이전트 분석이 느린 구간이고, 표와 코드를 보존하는 technical 모드는 쪽당 1.5초 정도로 문서화돼 있는데 직접 재보지는 않았다.
확인하지 못한 것
클로드 코드 pdf 스킬의 추출 파이프라인과 토큰 모델까지는 실행해서 확인했다. 생성된 스킬의 품질은 평가하지 않았다. 스킬을 실제로 만들려면 변환기만으로는 안 되고 에이전트 세션이 필요하기 때문이다. technical 모드도 돌리지 않았고, 시중 기술서나 실제 법령 PDF를 변환해보지도 않았다. 생성된 요약이 좋다 나쁘다고 말하는 사람은 내가 하지 않은 무언가를 테스트한 것이다.
출처
- 테스트한 커밋: virgiliojr94/book-to-skill @ 442aaaa
- 토큰 표에 쓴 측정 스크립트: tools/discovery_tax.py
- 한국어 감지와 보안 기능 릴리스 노트: v1.3.0
최종 확인 2026년 8월 9일, 커밋 442aaaa 기준. 별 개수와 패키지 배포 여부, 남은 미배포 수정은 바뀔 수 있지만 고정 비용에서 나오는 교차점 구조 자체는 바뀌지 않는다. 다음 점검은 2026년 11월 예정.
