virgiliojr94/book-to-skill

Turn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.

📚 book-to-skill – 어떤 기술 서적(또는 유사한 문서 컬렉션)을 AI 어시스턴트가 필요 시에 질의할 수 있는 에이전트 스킬로 변환합니다.

기능

입력: PDF, EPUB, DOCX, MD, HTML, RTF, MOBI, 폴더, 또는 그 글로브 패턴.
출력: 오픈된 에이전트 스킬 표준을 따르는 디렉터리 (SKILL.md + 각 챕터용 마크다운 파일, 용어집, 패턴, 체크리스트 등).
생성된 스킬은 호스트의 스킬 폴더에 저장됩니다 (~/.copilot/skills/…, ~/.agents/skills/…, ~/.claude/skills/…).
LLM 에이전트(GitHub Copilot CLI, Amp, Claude Code)가 /my-book replication 같은 명령을 받으면 관련 챕터 파일만 로드하므로, 전체 책을 프롬프트에 넣는 것보다 24~51배 적은 토큰으로 질의가 가능합니다.

왜 중요한가

책을 한 번 읽고 세부 사항을 잊는 것은 흔한 일입니다. PDF를 검색해도 페이지 번호만 나올 뿐이고, LLM에 질문하면 종종 환각이 발생합니다.
책을 구조화된 지식(프레임워크, 의사결정 규칙, 반패턴, 인덱싱된 챕터)으로 정제함으로써, 에이전트는 매번 전체 파일을 다시 스캔하지 않고도 정확하고 즉시 원본 콘텐츠에 접근할 수 있습니다.
에이전트 스킬 사양을 지원하는 모든 호스트와 호환되어 Copilot CLI, Amp, Claude Code 등에서 스킬을 이식 가능합니다.

생성하는 내용 (예시 구조)

파일	역할	약간의 크기
`SKILL.md`	핵심 사고 모델 + 챕터 인덱스	~4k 토큰
`chapters/ch01-*.md` …	챕터별 마크다운 파일, 요청 시에만 로드	각 ~1k 토큰
`glossary.md`	키워드 알파벳 목록과 챕터 참조	~1.5k 토큰
`patterns.md`	수집된 기법, 알고리즘, 디자인 패턴	~2k 토큰
`cheatsheet.md`	의사결정 테이블 / 빠른 참조 규칙	~1k 토큰

작동 방식 (개요)

추출기 (Python): 파일 유형을 감지하고 적절한 도구(pdftotext, docling, ebooklib, python-docx 등)를 선택해 각 소스를 깨끗한 텍스트 + 최소한의 메타데이터로 변환.
분석기: 텍스트를 챕터로 분할하고, 제목을 추출하며, 핵심 용어, 패턴, 의사결정 규칙을 식별.
생성기: 사양 기반 템플릿을 따르며 위에서 설명한 SKILL.md 번들 생성. 챕터 파일은 별도로 유지되어 에이전트가 필요한 것만 로드합니다.
옵션 후처리: 호스트별 규칙에 따라 스킬 검증(tools/validate_skill.py) 및 개인 GitHub 리포지토리에 게시해 쉬운 공유 가능.

설치 및 빠른 시작

# 컨버터를 크로스에이전트 스킬로 설치 (원라인)
npx skills add virgiliojr94/book-to-skill

# 또는 수동으로 호스트의 스킬 디렉터리에 클론
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

그런 다음 명령어 실행 (도구는 /book-to-skill를 CLI 엔트리로 등록):

/book-to-skill ./my-book.pdf            # 파일 이름으로 스킬 이름 생성
/book-to-skill ./docs/ --skill docs-kit # 전체 폴더 변환

생성된 스킬은 즉시 사용 가능:

/my-book replication   # 적절한 챕터를 사용해 에이전트에 답변 요청

책 외 일반적인 사용 사례

내부 문서 (런북, ADR, 온보딩 가이드) → 코딩 중에 질의 가능한 단일 스킬.
브랜드/디자인 시스템 → 스타일 가이드를 검색 가능한 스킬로 변환해 컨텐츠 작가 활용.
연구 자료 컬렉션 → 논문과 개인 노트를 하나의 업데이트 가능한 스킬로 통합.
규격 및 표준 → PDF를 열지 않고도 RFC나 API 계약을 질의 가능.

프라이버시 및 라이선스

모든 추출은 로컬에서 실행되며, 파일은 업로드되지 않습니다.

TL;DR: book-to-skill는 Python 기반의 컨버터로, 어떤 기술 서적이나 구조화된 문서 컬렉션을 컴팩트하고 표준 준수 에이전트 스킬로 변환하여, LLM 기반 어시스턴트가 원본 자료에서 질문에 정확하게 답변할 수 있도록 합니다. 토큰 사용량은 극적으로 줄어들고, 환각도 발생하지 않습니다.