Book-to-Skill 변환기
요약을 생성하는 대신 구조를 추출하여, 서면 지식을 실행 가능한 에이전트 스킬로 변환합니다.
철학
서적에는 수년간 개발된 결정화된 전문 지식(프레임워크, 원칙, 기법)이 담겨 있습니다. 이 스킬은 해당 지식을 GitHub Copilot CLI, Amp, Claude Code 또는 기타 호환 가능한 에이전트가 반복적으로 활용할 수 있는 형식으로 추출합니다.
요약이 아닌 구조를 추출하세요. 스킬은 독후감이 아닙니다. 다음과 같은 도구 모음입니다:
- 명명된 프레임워크 (명확한 적용이 가능한 정신 모델)
- 실행 가능한 원칙 (의사 결정을 안내하는 규칙)
- 기법 (단계별 방법)
- 안티패턴 (피해야 할 것과 그 이유)
- 음성 보정 (저자의 사고 및 의사소통 방식)
저자의 정확성을 유지하세요. 프레임워크에는 종종 특정한 이유로 이름이 있습니다. "5 Whys"는 "왜를 여러 번 묻는 것"과 상호 교환될 수 없습니다. 정확한 표현을 포착하세요.
깊이를 적절히 계층화하세요. 간단한 서적 → 간단한 스킬. 10개 이상의 프레임워크가 있는 복잡한 서적 → 참조 파일과 주문형 장(chapter)이 있는 스킬.
작동 모드
4가지 경로를 제공합니다. 사용자 요청에 따라 경로를 선택하세요:
1. 전체 변환 (기본값)
트리거: 사용자가 특별한 지시 없이 하나 이상의 문서/디렉토리/글로브 경로를 제공하는 경우 작업: 아래 모든 단계(단계 0~9)를 실행합니다. 출력: SKILL.md, chapters/, glossary, patterns, cheatsheet를 포함한 완전한 스킬
2. 분석 전용
트리거: 사용자가 "analyze", "just extract" 또는 "I want to review before generating"라고 말하는 경우 작업: 단계 0~3을 실행한 후 구조화된 추출 보고서(발견된 프레임워크, 원칙, 기법)를 생성합니다. 중단합니다. 스킬 파일을 생성하지 않습니다. 출력: 사용자 검토를 위한 분석 보고서
3. 이전 분석 결과로 생성
트리거: 사용자가 기존 분석 노트를 가지고 있거나 이전에 분석 전용을 실행한 경우
작업: 단계 03을 건너뛰고 제공된 분석을 입력으로 사용하여 단계 49를 실행합니다.
출력: 제공된 분석에서 생성된 스킬 파일
4. 업데이트 / 통합 (기존 스킬)
트리거: 사용자가 하나 이상의 새 소스 경로를 제공하고 기존 스킬을 업데이트하려고 함을 표시하는 경우(기존 스킬 폴더를 가리키거나, SKILLS_HOME에 이미 존재하는 스킬 슬러그를 제공하거나, 명시적으로 업데이트를 요청).
작업: 단계 0(범위 외 검사), 단계 1(입력 유효성 검사), 단계 1.5(책 유형 식별), 단계 2(새 파일 추출)를 실행합니다. 그런 다음 단계 5(기존 스킬 경로 식별/탐지)로 건너뛰고 업데이트 / 통합 워크플로를 실행하여 새 콘텐츠를 기존 스킬 파일에 병합합니다.
출력: 새롭거나 수정된 장 요약과 병합된 인덱스/용어집으로 업데이트된 기존 스킬
스킬 위치
이 변환기는 여러 스킬 시스템에서 실행될 수 있습니다. 이 변환기의 도우미 스크립트를 찾거나 생성된 북 스킬을 작성할 때 다음 위치를 우선 순위 순으로 선호합니다:
- GitHub Copilot CLI 개인 스킬:
~/.copilot/skills/ - 크로스-에이전트 개인 스킬 (Copilot + Amp):
~/.agents/skills/ - Claude Code 개인 스킬:
~/.claude/skills/ - 프로젝트-로컬 Copilot 스킬:
.github/skills/ - 프로젝트-로컬 Claude 스킬:
.claude/skills/ - 프로젝트-로컬 Amp / Copilot 스킬:
.agents/skills/ - Amp 전역 스킬:
~/.config/agents/skills/ - Amp 레거시 전역 스킬:
~/.config/amp/skills/
생성된 북 스킬의 경우, 사용자의 호스트 에이전트가 실제로 찾을 수 있는 대상을 선택하세요(단계 5 참조). 둘 이상의 유효한 루트가 있는 경우, 사용자에게 한 번 묻고 세션 동안 답변을 기억하세요. 자동으로 기본값을 사용하지 마십시오.
단계 0 — 범위 외 검사
인수가 제공되지 않으면 중단하고 응답하세요:
"book-to-skill requires a supported document path, folder, or glob pattern. Usage:
book-to-skill <문서-폴더-또는-글로브-경로>... [스킬-이름-슬러그]"
워크플로 전반에 걸쳐:
- 입력 경로와 선택적 스킬 슬러그를 식별합니다.
- 마지막 인수가 파일, 폴더 또는 존재하거나 파일과 일치하는 글로브가 아니고 스킬 슬러그처럼 보이는 경우(예: 소문자 하이픈, 영숫자),
SKILL_NAME으로 처리합니다. - 다른 모든 인수를
INPUT_PATHS목록으로 처리합니다. - 입력 경로 중 하나라도 기존 스킬 디렉토리(
SKILL.md및chapters/하위 폴더 포함)이거나SKILL_NAME이SKILLS_HOME의 기존 스킬 슬러그와 일치하는 경우, 이 실행을 업데이트/통합 작업(모드 4)으로 표시합니다.
단계 1 — 입력 유효성 검사
INPUT_PATHS 중에 지원되는 파일, 디렉토리 또는 글로브 패턴이 하나 이상 있는지 확인합니다.
디렉토리 및 글로브의 경우 확장하여 일치하는 지원 파일(.pdf, .epub, .docx, .txt, .md, .markdown, .rst, .adoc, .html, .htm, .rtf, .mobi, .azw, .azw3)을 찾습니다.
지원되는 파일이 없으면 명확한 오류 메시지와 함께 중단합니다.
단계 1.5 — 콘텐츠 유형 식별
추출하기 전에 사용자에게 물어보세요:
"이 소스들의 콘텐츠 유형은 무엇입니까? 이 정보는 최적의 추출 방법을 선택하는 데 도움이 됩니다.
- 기술 문서 — 코드 블록, 표, 수식, 다이어그램 포함 (예: 프로그래밍 서적, 학술 논문, 아키텍처 가이드)
- 텍스트 위주 — 대부분 산문, 표/코드 거의 없음 (예: 경영, 생산성, 논픽션 내러티브)
- 잘 모르겠음 — 빠른 방법을 사용하고 품질이 제한적으로 보이면 경고합니다"
BOOK_TYPE으로 답변을 저장합니다:
- 옵션 1 →
BOOK_TYPE=technical - 옵션 2 →
BOOK_TYPE=text - 옵션 3 →
BOOK_TYPE=text
BOOK_TYPE=technical인 경우, 진행하기 전에 사용자에게 알립니다:
"📐 기술 모드 선택됨 — Docling을 사용하여 구조 인식 추출 수행(표, 코드 블록, 수식을 마크다운으로 보존). 페이지당 약 1.5초 소요되므로 긴 소스의 경우 몇 분 정도 예상하십시오. 지금 시작합니다…"
BOOK_TYPE=text인 경우, 알립니다:
"📄 텍스트 모드 선택됨 — 각 파일 유형에 가장 적합한 빠른 추출기를 사용합니다. 일반 텍스트/마크다운/HTML은 일반적으로 몇 초 내에 준비됩니다. PDF는 가능한 경우 pdftotext를 사용합니다."
단계 2 — 소스 문서에서 텍스트 추출
입력 경로를 전달하여 추출 스크립트를 실행합니다:
SCRIPT_PATH=""
for candidate in \
"$HOME/.copilot/skills/book-to-skill/scripts/extract.py" \
"$HOME/.agents/skills/book-to-skill/scripts/extract.py" \
"$HOME/.claude/skills/book-to-skill/scripts/extract.py" \
".github/skills/book-to-skill/scripts/extract.py" \
".claude/skills/book-to-skill/scripts/extract.py" \
".agents/skills/book-to-skill/scripts/extract.py" \
"$HOME/.config/agents/skills/book-to-skill/scripts/extract.py" \
"$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
do
if [ -f "$candidate" ]; then
SCRIPT_PATH="$candidate"
break
fi
done
if [ -z "$SCRIPT_PATH" ]; then
echo "Could not find scripts/extract.py for book-to-skill" >&2
exit 1
fi
PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
PYTHON_BIN="python"
fi
"$PYTHON_BIN" "$SCRIPT_PATH" $INPUT_PATHS --mode <BOOK_TYPE> --install-missing ask
추출 전에 스크립트는 감지된 형식에 필요한 선택적 Python 패키지를 확인합니다. 더 나은 추출기가 누락된 경우 사용 가능한 대체 수단을 사용자에게 알립니다. 비대화형 세션은 설치 모드가 명시적으로 yes가 아닌 한 기본적으로 대체 수단을 사용합니다.
팁 — 환경 사전 점검: "$PYTHON_BIN" "$SCRIPT_PATH" --check를 실행하면 어떤 파일도 처리하지 않고 설치된 추출기와 누락된 항목을 설치하는 정확한 명령을 형식별로 보고합니다. 사용자가 설정 또는 품질 문제를 보고할 때 유용합니다.
이렇게 하면 다음이 생성됩니다:
<tempdir>/book_skill_work/full_text.txt— 모든 소스의 결합된 추출 텍스트로, 시각적으로 명확하게 구분된 경계가 있습니다.<tempdir>/book_skill_work/metadata.json— 전체 결합 크기, 단어 수, 페이지 수, 토큰 수 및 개별 처리된sources의 상세 목록.
<tempdir>/book_skill_work/metadata.json을 읽어 결과를 검사합니다.
단계 2.5 — 사전 비용 추정
<tempdir>/book_skill_work/metadata.json을 읽고 생성 작업 전에 사용자에게 추정치를 제시합니다:
📖 감지된 소스: <총_소스> 개
<소스 메타데이터 목록에서 각 소스 파일명 및 형식 나열>
📄 결합된 페이지/섹션: ~<N> | 단어 수: ~<N> | 총 토큰: ~<N>K
💰 예상 토큰 비용 (전체 변환 / 업데이트):
입력 (읽기 + 프롬프트): ~<N>K 토큰
출력 (생성/업데이트된 스킬 파일): ~<N>K 토큰
합계: ~<N>K 토큰
비용: 위의 토큰 수에 현재 모델의 입력/출력
백만 토큰당 요금을 곱하십시오 (가격과 모델 이름은 자주 변경됩니다 —
하드코딩하지 말고 오늘의 요율을 인용하고 추정치로 표시하십시오).
⏱ 예상 시간: ~<N>분
📁 생성/업데이트될 파일:
SKILL.md + 장 파일 + 용어집 + 패턴 + 치트시트
➡ 전체 변환 / 업데이트를 진행하시겠습니까? (또는 "analyze only"를 입력하여 미리 보기)
추정 방법:
- 입력 토큰 ≈ 메타데이터의
estimated_tokens× 1.3 (장당 프롬프트 오버헤드) - 출력 토큰 ≈ 장 수 × 장당 예산 + 4,000 (SKILL.md) + 4,500 (용어집 + 패턴 + 치트시트)
BOOK_TYPE에 따른 장당 예산 중간값 (DEPTH는 단계 4에서 결정되며 올릴 수 있음):text≈ 1,000,technical≈ 1,800. 사용자가 이미 참조 전용 또는 심층 학습을 표시한 경우 단계 7 매트릭스의 해당 행을 사용하십시오.
- 비용: 토큰 수를 보고 사용자의 현재 백만 토큰당 입력/출력 요율을 곱하십시오. 달러 금액을 하드코딩하지 마십시오 — 모델 이름과 가격은 변경됩니다. 표시하는 경우 추정치로 레이블을 지정하고 날짜를 기입하십시오.
진행하기 전에 사용자의 확인을 기다리십시오. 사용자가 "analyze only"라고 말하면 모드 2로 전환합니다.
단계 2.6 — 대용량 서적(> 50k 토큰)을 위한 REPL 스타일 접근
RLM(Recursive Language Model) 패러다임에서 영감을 받음: full_text.txt를 단일 읽기 대상이 아닌 질의 가능한 말뭉치로 취급하십시오. 전체 파일을 컨텍스트에 로드하면 나중에 생성에 필요한 예산이 소모됩니다.
약 50k 토큰이 넘는 서적의 경우, 제한 없는 Read(full_text.txt)보다 프로그래밍 방식 프로브를 선호하십시오:
# 읽기 전에 크기 확인
wc -w "$FULL_TEXT_PATH"
# 전체 파일을 로드하지 않고 장 오프셋 찾기
grep -n -E "^\s*(Chapter|CHAPTER)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40
# 필요한 장만 가져오기 (시작 줄..끝 줄 포함)
sed -n '<시작>,<끝>p' "$FULL_TEXT_PATH"
# SKILL.md에서 주장하기 전에 프레임워크가 실제로 언급되었는지 확인
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"
# 오프셋/제한이 있는 대상 읽기는 전체 파일 덤프를 피합니다
# Read(file_path=full_text.txt, offset=<줄>, limit=<줄>)
단계 3(구조 분석), 단계 7(장별 요약), 단계 8(용어집/패턴 추출)에 이 접근 방식을 사용하십시오. 50k 토큰 미만 서적의 경우 단일 Read로 충분합니다.
이것이 중요한 이유: 200페이지 분량의 책은 약 75k 토큰입니다. 장마다 한 번씩 다시 읽으면(28번 패스) 약 2M 입력 토큰이 소모됩니다. grep + sed를 사용하여 필요한 슬라이스만 가져오면 생성 비용을 소스가 아닌 출력에 비례하게 유지할 수 있습니다.
단계 3 — 책 구조 분석
추출된 full_text.txt의 처음 8,000자를 읽어 다음을 식별합니다:
- 책 제목 및 저자
- 장 구조 ("Chapter N", "PART I", 번호 매겨진 제목, 목차 찾기)
- 핵심 테마 및 주제 도메인
- 대략적인 장 수
그런 다음 목차 섹션이 있으면 읽어 모든 장을 매핑합니다.
모드가 "Analyze Only"인 경우: 지금 추출 보고서를 생성하고 중단합니다. 구조:
## 추출 보고서 — <제목>
### 저자의 핵심 프레임워크
- **<프레임워크 이름>**: <정의 및 적용 시기>
### 주요 원칙
- <원칙>: <실행 가능한 규칙>
### 기법 및 방법
- <기법>: <단계별 또는 방법>
### 안티패턴
- <피해야 할 것>: <이유>
### 제안된 스킬 이름
`{저자성-핵심개념}` — 예: `cialdini-influence`
### 감지된 장
| # | 제목 | 주요 프레임워크 |
단계 4 — 목적 묻기 (전체 변환 전용)
생성하기 전에 사용자에게 물어보세요:
"이 스킬이 어떤 작업을 도와주길 원하십니까? (하나 이상 선택)
- 작업 중 저자의 프레임워크 적용
- 저자의 정신 모델로 사고
- 특정 장 및 개념 참조
- 위 모두"
답변을 사용하여 SKILL.md 핵심 섹션에서 강조할 내용에 가중치를 부여합니다.
답변에서 DEPTH를 도출합니다 (추가 프롬프트 없음):
- 답변이 오직 옵션 3(참조)인 경우 →
DEPTH=reference— 간결하고 빠른 조회 장. - 답변에 옵션 1, 2 또는 4가 포함된 경우 →
DEPTH=study— 더 많은 상세 작업 내용, 예제 및 추론이 포함된 심층 장.
DEPTH와 BOOK_TYPE이 함께 단계 7의 장당 토큰 예산을 설정합니다. 별도의 "study vs reference" 질문을 하지 마십시오 — 여기서 유추됩니다. (모드 2/3에서는 단계 4를 건너뛰므로 기본 DEPTH=study를 사용합니다.)
단계 5 — 스킬 이름 결정
SKILL_NAME이 제공된 경우 스킬 슬러그로 사용합니다.
그렇지 않으면 두 가지 옵션을 제안하고 사용자가 선택하도록 합니다:
- 저자-개념별:
{저자성}-{핵심개념}(예:cialdini-influence,meadows-systems) - 제목별: 책 제목에서 소문자 하이픈 (예:
designing-data-intensive-apps)
책이 강력한 방법론적 정체성을 가진 경우 저자-개념 형식을 기본값으로 합니다.
대상 스킬 루트(SKILLS_HOME)를 선택합니다. 사용자의 파일 시스템에서 기존 스킬 홈을 탐색하고 사용자가 실행 중인 호스트에 따라 선택합니다:
| 호스트 에이전트 | 개인
(원문 SKILL.md가 중단된 부분이므로 번역도 여기서 중단합니다.)