virgiliojr94/book-to-skill

Book-to-Skill 변환기

서면 지식을 구조를 추출하여 실행 가능한 에이전트 스킬로 변환합니다. 요약을 생성하는 것이 아닙니다.

철학

책에는 수년간 개발된 결정체화된 전문 지식(프레임워크, 원칙, 기법)이 담겨 있습니다. 이 스킬은 해당 지식을 GitHub Copilot CLI, Amp, Claude Code, Hermes Agent 또는 다른 호환 에이전트가 반복적으로 활용할 수 있는 형식으로 추출합니다.

구조를 추출하고, 요약을 생성하지 마십시오. 스킬은 독후감이 아닙니다. 이는 다음으로 구성된 도구 키트입니다:

• 명명된 프레임워크 (명확한 적용 방식이 있는 멘탈 모델)
• 실행 가능한 원칙 (의사 결정을 안내하는 규칙)
• 기법 (단계별 방법)
• 안티패턴 (피해야 할 것과 그 이유)
• 음성 보정 (저자가 생각하고 소통하는 방식)

저자의 정확성을 보존하십시오. 프레임워크는 종종 특정한 이유로 명명됩니다. "5 Whys"는 "여러 번 이유를 묻는 것"과 상호 교환될 수 없습니다. 정확한 공식을 포착하십시오.

깊이를 적절하게 계층화하십시오. 간단한 책 → 간단한 스킬. 10개 이상의 프레임워크가 있는 복잡한 책 → 참조 파일과 온디맨드 챕터가 있는 스킬.

---

작동 모드

네 가지 경로가 가능합니다. 사용자의 요청에 따라 경로를 결정하십시오:

1. 전체 변환 (기본값)

트리거: 사용자가 특별한 지시 없이 하나 이상의 문서/디렉토리/글로브 경로를 제공 작업: 아래 모든 단계 실행 (0~9단계) 출력: SKILL.md, chapters/, glossary, patterns, cheatsheet가 포함된 완전한 스킬

2. 분석 전용

트리거: 사용자가 "analyze", "just extract" 또는 "생성하기 전에 검토하고 싶다"고 말함 작업: 0~3단계 실행 후, 구조화된 추출 보고서(발견된 프레임워크, 원칙, 기법)를 생성. 중단 — 스킬 파일을 생성하지 않음. 출력: 사용자 검토를 위한 분석 보고서

3. 기존 분석에서 생성

트리거: 사용자가 기존 분석 노트를 가지고 있거나 이전에 분석 전용을 실행한 경우 작업: 03단계를 건너뛰고, 제공된 분석을 입력으로 사용하여 49단계 실행 출력: 제공된 분석에서 생성된 스킬 파일

4. 업데이트 / 통합 (기존 스킬)

트리거: 사용자가 하나 이상의 새 소스 경로를 제공하고 기존 스킬을 업데이트하려 함(기존 스킬 폴더를 가리키거나, SKILLS_HOME에 이미 있는 스킬 슬러그를 제공하거나, 명시적으로 업데이트를 요청하는 방식으로). 작업: 0단계(범위 외 확인), 1단계(입력 검증), 1.5단계(책 유형 식별), 2단계(새 파일 추출) 실행. 그런 다음 5단계(기존 스킬 경로 식별/감지)로 건너뛰고 업데이트 / 통합 워크플로를 실행하여 새 내용을 기존 스킬 파일에 병합. 출력: 새/수정된 챕터 요약과 병합된 색인/용어집으로 업데이트된 기존 스킬

---

스킬 위치

이 변환기는 여러 스킬 시스템에서 실행될 수 있습니다. 이 변환기의 도우미 스크립트를 찾거나 생성된 책 스킬을 작성할 때는 다음 위치를 순서대로 선호하십시오:

1. GitHub Copilot CLI 개인 스킬: ~/.copilot/skills/
2. 크로스-에이전트 개인 스킬 (Copilot, Amp, Codex): ~/.agents/skills/
3. Claude Code 개인 스킬: ~/.claude/skills/
4. 프로젝트-로컬 Copilot 스킬: .github/skills/
5. 프로젝트-로컬 Claude 스킬: .claude/skills/
6. 프로젝트-로컬 Amp / Copilot 스킬: .agents/skills/
7. Amp 전역 스킬: ~/.config/agents/skills/
8. Amp 레거시 전역 스킬: ~/.config/amp/skills/
9. Hermes Agent 개인 스킬: $HERMES_HOME/skills/ (기본값 ~/.hermes/skills/)
10. Hermes Agent 프로젝트 스킬: .hermes/skills/ or .agents/skills/

생성된 책 스킬의 경우, 사용자 수준 크로스-에이전트 루트 ~/.agents/skills/를 선호하십시오. 하나의 물리적 복사본이 지원되는 모든 호스트에 제공됩니다. Copilot CLI와 Amp는 기본적으로 이를 발견합니다. Claude Code는 ~/.claude/skills/<skill_name>에서 심볼릭 링크가 필요합니다(10단계에서 생성, 규칙은 5단계 참조). 사용자가 요청하는 경우에만 호스트 전용 또는 프로젝트-로컬 루트를 선택하십시오.

---

0단계 — 범위 외 확인

인자가 제공되지 않으면 중단하고 응답:

"book-to-skill에는 지원되는 문서 경로, 폴더 또는 글로브 패턴이 필요합니다. 사용법: book-to-skill <path-to-document-folder-or-glob>... [skill-name-slug]"

워크플로 전반에 걸쳐:

• 입력 경로와 선택적 스킬 슬러그를 식별합니다.
• 마지막 인자가 파일, 폴더 또는 존재하거나 일치하는 글로브가 아니고 스킬 슬러그처럼 보이면(예: 소문자 하이픈, 영숫자) 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단계 — 콘텐츠 유형 식별

추출 전에 사용자에게 질문:

"이 소스들은 어떤 종류의 콘텐츠를 가지고 있나요? 이는 최상의 추출 방법을 선택하는 데 도움이 됩니다.

1. 기술 — 코드 블록, 표, 수식, 다이어그램 포함 (예: 프로그래밍 책, 학술 논문, 아키텍처 가이드)
2. 텍스트 위주 — 대부분 산문, 표/코드 거의 없음 (예: 경영, 생산성, 논픽션 이야기)
3. 잘 모르겠음 — 빠른 방법을 사용하고 품질이 제한적인 것 같으면 경고"

답변을 BOOK_TYPE으로 저장:

• 옵션 1 → BOOK_TYPE=technical
• 옵션 2 → BOOK_TYPE=text
• 옵션 3 → BOOK_TYPE=text

BOOK_TYPE=technical인 경우, 진행 전에 사용자에게 알림:

"📐 기술 모드 선택 — 구조 인식 추출을 위해 Docling 사용 (표, 코드 블록, 수식을 마크다운으로 유지). 페이지당 약 1.5초 소요되므로 긴 소스의 경우 몇 분 정도 예상하십시오. 지금 시작합니다…"

BOOK_TYPE=text인 경우, 알림:

"📄 텍스트 모드 선택 — 각 파일 유형에 가장 빠른 적합한 추출기 사용. 일반 텍스트/Markdown/HTML은 일반적으로 몇 초; PDF는 사용 가능한 경우 pdftotext 사용."

---

2단계 — 소스 문서에서 텍스트 추출

입력 경로를 전달하여 추출 스크립트 실행:

SCRIPT_PATH=""
HERMES_HOME_RESOLVED="${HERMES_HOME:-$HOME/.hermes}"
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
HERMES_PROJECT_TRUSTED=false
if [ -n "$PROJECT_ROOT" ] && [ "${HERMES_AGENT:-}" = true ] && \
  command -v hermes >/dev/null 2>&1 && \
  command -v python3 >/dev/null 2>&1 && \
  hermes config get skills.trusted_project_dirs --json 2>/dev/null | PROJECT_ROOT="$PROJECT_ROOT" python3 -c 'import json, os, pathlib, sys; root=pathlib.Path(os.environ["PROJECT_ROOT"]).resolve(); sys.exit(not any(pathlib.Path(p).expanduser().resolve() == root for p in json.load(sys.stdin)))' 2>/dev/null
then
  HERMES_PROJECT_TRUSTED=true
fi

CANDIDATES=(
  "$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"
  "$HERMES_HOME_RESOLVED/skills/book-to-skill/scripts/extract.py"
  "$HERMES_HOME_RESOLVED"/skills/*/book-to-skill/scripts/extract.py
)
if [ "${HERMES_AGENT:-}" != true ]; then
  CANDIDATES+=(
    ".github/skills/book-to-skill/scripts/extract.py"
    ".claude/skills/book-to-skill/scripts/extract.py"
    ".agents/skills/book-to-skill/scripts/extract.py"
  )
fi
CANDIDATES+=(
  "$HOME/.config/agents/skills/book-to-skill/scripts/extract.py"
  "$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
)
if [ "$HERMES_PROJECT_TRUSTED" = true ]; then
  CANDIDATES=(
    "$PROJECT_ROOT/.hermes/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.hermes/skills"/*/book-to-skill/scripts/extract.py
    "$PROJECT_ROOT/.agents/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.agents/skills"/*/book-to-skill/scripts/extract.py
    "${CANDIDATES[@]}"
  )
fi
for candidate in "${CANDIDATES[@]}"
do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

if [ -z "$SCRIPT_PATH" ]; then
  echo "book-to-skill용 scripts/extract.py를 찾을 수 없습니다" >&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-<pid>/ 또는 BOOK_SKILL_WORKDIR에 설정한 정확한 경로:

• full_text.txt — 모든 소스의 결합된 추출 텍스트가 명확하게 시각적으로 구분된 경계선과 함께 포함
• metadata.json — 전체 결합 크기, 단어 수, 페이지 수, 토큰 수, 삭제된 EPUB 이미지 수, 확인된 workdir, 처리된 개별 sources의 상세 목록

실행은 완료 시 세 경로를 모두 출력합니다(Workdir ->, Text ->, Meta ->). 고정 위치를 가정하지 말고 해당 출력(또는 metadata.json의 자체 workdir 필드)에서 경로를 가져오십시오 — 디렉토리 이름은 실행마다 다르므로 한 머신에서 동시 추출이 서로의 결과를 덮어쓰지 않습니다.

해당 실행의 metadata.json을 읽어 결과를 검사합니다.

생성하기 전에 항상 추출이 요청한 문서인지 확인하십시오: metadata.json의 filename / source_file 필드를 확인하거나 full_text.txt의 첫 번째 줄에 있는 SOURCE: 헤더를 확인하십시오. 백그라운드 실행을 기다리는 경우 해당 특정 workdir을 기다리십시오 — 공유 경로를 폴링하면 다른 실행의 출력이 표시될 수 있습니다.

---

2.5단계 — 사전 비용 추정

이 실행의 metadata.json(추출 출력의 Meta -> 경로)을 읽고 생성 전에 사용자에게 추정치를 제시:

📖 감지된 소스: <total_sources>개 소스
<소스 메타데이터 목록에서 각 소스 파일 이름과 형식 나열>
<images_dropped > 5인 경우: N개 소스 이미지를 읽지 못했음을 경고>
📄 결합된 페이지/섹션: ~<N> | 단어: ~<N> | 총 토큰: ~<N>K

💰 예상 토큰 비용 (전체 변환 / 업데이트):
   입력  (읽기 + 프롬프트): ~<N>K 토큰
   출력 (생성/업데이트된 스킬 파일):  ~<N>K 토큰
   합계:                           ~<N>K 토큰

   비용: 위의 토큰 수에 모델의 현재
   입력/출력 백만-토큰당 요율을 곱하십시오 (가격과 모델 이름은 자주 변경되므로
   하드코딩하지 말고 오늘의 요율을 인용하고 추정치임을 명시하십시오).

   ⏱  예상 시간: ~<N>분

📁 생성/업데이트될 파일:
   SKILL.md + 챕터 파일 + 용어집 + 패턴 + 치트시트

➡  전체 변환 / 업데이트를 진행하시겠습니까? (또는 먼저 미리보기 위해 "analyze only" 입력)

추정 방법:

• 입력 토큰 ≈ metadata의 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단계 — 대용량 책용 REPL 스타일 접근 (> 50k 토큰)

Recursive Language Model (RLM) 패러다임에서 영감을 받음: full_text.txt를 단일 읽기가 아닌 질의 가능한 코퍼스로 취급하십시오. 전체 파일을 컨텍스트에 로드하면 이후 생성을 위해 필요한 예산이 소모됩니다.

약 50k 토큰 이상의 책의 경우, Read(full_text.txt)보다 프로그래밍 방식 프로브를 선호하십시오 (범위 제한 없이):

# Read 전 크기 확인
wc -w "$FULL_TEXT_PATH"

# 전체 파일을 로드하지 않고 챕터 오프셋 찾기
grep -n -E "^\s*(Chapter|CHAPTER)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40

# 필요한 챕터만 가져오기 (라인 시작..끝 포함)
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"

# SKILL.md에서 주장하기 전에 프레임워크가 실제로 언급되었는지 확인
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"

# offset/limit으로 대상 Read 시 전체 파일 덤프 방지
# Read(file_path=full_text.txt, offset=<line>, limit=<lines>)

이 접근 방식을 3단계(구조 분석), 7단계(챕터별 요약), 8단계(용어집/패턴 추출)에 사용하십시오. 50k 토큰 미만 책의 경우 단일 Read로 충분합니다.

이것이 중요한 이유: 200페이지 분량의 책은 약 75k 토큰입니다. 챕터당 한 번씩 다시 읽으면(28번 패스) 약 2.1M 토큰(박스 카)이 소모됩니다. Grep+grep+sed 접근 방식은 약 5k 토큰만 사용하므로 추정 생성을 위한 예산이 보존됩니다.

---

3단계 — 구조 분석 (분석 전용 모드 중지 지점)

full_text.txt와 metadata.json을 사용하여 문서의 지형을 이해하십시오.

메타데이터에서 페이지/토큰 수 확인 → 스킬이 가져야 할 적절한 크기 결정.

목차 / 헤더 구조를 추출하여 챕터를 찾으십시오. 전체 텍스트를 로드해야 할 정도로 작지 않은 한 REPL 스타일 접근(2.6단계)을 사용하십시오.

찾은 내용에 대한 마크다운 구조 분석을 작성하십시오. 포함:

• 감지된 총 챕터 수
• 각 챕터 길이 (있는 경우 추정)
• 각 부분(있는 경우) 및 챕터 제목
• 특별 섹션 (부록, 참고 문헌, 용어집, 인덱스)

분석 전용 모드(모드 2)인 경우: 여기서 구조 분석을 생성하고 중단. 나머지 단계를 실행하지 마십시오. 사용자에게 분석 보고서를 제시하고 "계속해서 스킬 생성" 또는 추가 지침을 요청하십시오.

전체 변환(모드 1) 또는 업데이트(모드 4)인 경우: 분석 결과를 저장하고 다음 단계로 진행하십시오.

---

4단계 — 스킬 깊이 및 구조 결정

책 구조(3단계)와 BOOK_TYPE(1.5단계)에 따라 각각에 대한 적절한 깊이를 결정하십시오:

짧은 문서 (< 100 토큰): 이 책은 하나의 아이디어로 요약됩니다. 챕터를 생성하지 말고 'frameworks' 블록과 'cheatsheet'가 있는 단일 파일 스킬을 만드십시오. 5단계로 건너뛰십시오.

중간 문서 (100-5000 토큰): 이것은 아마도 기사나 문서입니다. 스킬 깊이를 얕게 유지하십시오. 다음과 같은 경우를 제외하고 챕터를 건너뛰십시오:

• technical 책: 정확한 인용을 위한 코드 블록이나 표를 포함할 명확한 섹션이 있는 경우에만 챕터를 만드십시오.
• text 책: 2개 이상의 뚜렷한 주제가 있는 경우에만 챕터를 만드십시오.

긴 문서 (> 5000 토큰): 일반 스킬 생성. 적절한 깊이를 결정:

• text 책: 챕터당 1000 토큰 참조 예산 (요약에 집중, 인용 적게). 이 예산을 초과하는 경우에만 깊이를 늘리십시오.
• technical 책: 챕터당 1800 토큰 참조 예산 (코드, 표, 인용 포함). 높은 정밀도가 필요한 프레임워크의 경우 깊이를 2500까지 늘리십시오.

사용자에게 결정한 깊이("얕은" / "보통" / "깊음")를 보고하고 확인을 요청하지 않고 다음 단계로 진행하십시오.

---

5단계 — 대상 디렉토리 및 스킬 이름 결정

이제 이 스킬의 파일이 저장될 위치를 결정하십시오.

SKILL_NAME 결정:

• 0단계에서 스킬 슬러그가 제공된 경우 이를 사용하십시오.
• 제공되지 않은 경우 책 제목에서 적절한 슬러그 생성: 소문자, 공백을 하이픈으로, 특수 문자 제거. 예: "Atomic Habits" → atomic-habits.

기존 스킬 업데이트 중(모드 4)인 경우:

• 기존 스킬 폴더가 제공되었다면(INPUT_PATHS를 통해 명시적으로 또는 이미 알려진 슬러그로) 이를 대상으로 사용하십시오.
• 제공되지 않았다면 사용자에게 "기존 스킬을 업데이트하고 있습니다. 기존 스킬 폴더의 경로 또는 슬러그를 제공해 주십시오:"를 요청하고 SKILL_NAME과 SKILL_DIR을 모두 설정하십시오.
• 업데이트를 위해 새 파일이 추출되었으므로(2단계) 대상이 올바른지 확인한 후 6단계로 진행하십시오.

새 스킬 생성 중(모드 1 또는 3)인 경우:

%SKILL_DIR% 결정:

# 선호하는 순서로 확인:
if [ -d "$HOME/.agents/skills" ]; then
  SKILL_DIR="$HOME/.agents/skills/<SKILL_NAME>"
elif [ -d "$HOME/.copilot/skills" ]; then
  SKILL_DIR="$HOME/.copilot/skills/<SKILL_NAME>"
elif [ -d "$HOME/.claude/skills" ]; then
  SKILL_DIR="$HOME/.claude/skills/<SKILL_NAME>"
else
  # fallback — 사용 가능한 첫 번째 개인 skills 루트를 생성하거나 사용
  SKILL_DIR="$HOME/.agents/skills/<SKILL_NAME>"
  mkdir -p "$HOME/.agents/skills"
fi

스킬 루트에 프로젝트-로컬을 요청하는 사용자나 .github/skills/ (또는 .claude/skills/, .agents/skills/, .hermes/skills/)가 이미 존재하는 프로젝트 루트에서 실행하는 사용자인 경우 해당 로컬 디렉토리를 대신 사용하십시오.

사용자에게 스킬이 저장될 위치를 알리십시오:

"📁 스킬이 다음 위치에 생성됩니다: %SKILL_DIR%"

생성된 스킬 디렉토리(나중에 9단계에서 생성)의 경우, 다음을 만드십시오:

• %SKILL_DIR%/SKILL.md
• %SKILL_DIR%/chapters/ (하나 이상의 챕터가 있는 경우)
• %SKILL_DIR%/glossary/
• %SKILL_DIR%/patterns/
• %SKILL_DIR%/cheatsheet/

중요: 생성된 책 스킬은 자체 scripts/ 디렉토리를 포함하지 않습니다. 추출에 scripts/extract.py가 필요한 유일한 스킬은 이 book-to-skill 스킬입니다.

---

6단계 — 스킬 구조 골격 생성

SKILL.md 생성을 위한 준비:

1. 3단계 분석을 사용하여 포함할 챕터 결정:

   • 짧은 문서 (< 100 토큰): 챕터 없음, 단일 스킬 섹션
   • 중간 길이: 필요한 경우에만 챕터
   • 긴 문서: 각 주요 섹션에 대한 챕터

2. 빈 스킬 구조 골격을 계획하십시오 (구체적인 내용은 7단계에서 채움):

# %SKILL_NAME%

<!-- 크로스-에이전트 메타데이터 (호스트 에이전트가 숨김) -->
---

## 개요
*(책/소스에 대한 2문장 개요)*

---

## 프레임워크

*(명명된 프레임워크 및 멘탈 모델 — 최소한의 인용과 함께 각각 2-4문장으로 정의)*

---

## 원칙

*(실행 가능한 규칙 — 각각 단일 문장)*

---

## 기법

*(단계별 방법 — 각각 3-5단계)*

---

## 안티패턴

*(피해야 할 것과 이유)*

---

## 챕터

*(중간/긴 책의 경우에만; 각 챕터는 아래 패턴을 따름)*

---

## 용어집

*(정의된 핵심 용어)*

---

## 패턴

*(재사용 가능한 솔루션 스니펫)*

---

## 치트시트

*(빠른 참조 요약)*

스킬 길이에 적합한 섹션만 포함하십시오. 짧은 스킬의 경우 프레임워크, 원칙, 기법, 치트시트만 있으면 됩니다.

---

7단계 — 챕터 요약 생성

각 챕터에 대해 챕터 파일을 %SKILL_DIR%/chapters/<chapter-slug>.md에 생성하십시오. 앞서 결정된 깊이 예산을 사용하십시오 (4단계).

# %CHAPTER_TITLE%

**출처:** `%SOURCE_FILE%`, 라인 %START_LINE%-%END_LINE%

---

## 요약

*(적용 가능한 경우 코드 블록, 표, 다이어그램 레이아웃과 함께 3-5문장 요약)*

---

## 핵심 프레임워크

*(이 챕터에 도입된 명명된 프레임워크 목록)*

---

## 핵심 원칙

*(이 챕터에 도입된 실행 가능한 원칙)*

---

## 핵심 기법

*(이 챕터에 도입된 단계별 방법)*

---

## 핵심 용어

*(정의가 포함된 새 용어)*

---

## 인용

*(가장 영향력 있는 원문 인용 — 각각 프레임워크 또는 원칙에 연결됨)*

참조 예산 초과를 방지하기 위해 각 챕터 파일을 결정된 깊이 예산 내로 유지하십시오. 예산이 허용하는 경우에만 추가 컨텍스트(코드 예제, 전체 인용)를 포함하십시오.

---

8단계 — 용어집, 패턴 및 치트시트 생성

용어집 (%SKILL_DIR%/glossary/)

모든 챕터의 새 용어를 역참조가 있는 중앙 용어집으로 통합하십시오:

# %SKILL_NAME% — 용어집

## A

**용어** — 정의. (출처: [챕터 챕터-이름](chapters/chapter-slug.md))

...

각 용어집 파일을 알파벳순으로 그룹화하십시오. 하나의 문자에 5개 이상의 용어가 있는 경우에만 문자당 하나의 파일을 만드십시오. 그렇지 않으면 결합하십시오.

패턴 (%SKILL_DIR%/patterns/)

재사용 가능한 솔루션 패턴을 추출하십시오. 각 패턴은 명확한 문제 설명, 적용 맥락, 해결책 단계를 가져야 합니다:

# 패턴: %PATTERN_NAME%

**문제:** *(이 패턴이 해결하는 것)*

**맥락:** *(언제 적용하는가)*

**해결책:**
1. *(단계 1)*
2. *(단계 2)*
3. *(단계 3)*

**출처:** [%CHAPTER_TITLE%](chapters/%CHAPTER_SLUG%.md)

치트시트 (%SKILL_DIR%/cheatsheet/index.md)

핵심 프레임워크, 원칙, 명령의 빠른 참조 표를 만드십시오:

프레임워크	요약	적용
%NAME%	%1-문장 정의%	%언제 사용하는가%

---

9단계 — SKILL.md 헤더 및 메타데이터 구축

모든 챕터와 보조 파일을 연결하는 SKILL.md 메인 파일을 구성하십시오.

SKILL.md 상단에 스킬 메타데이터를 위한 YAML 형식 프론트매터를 포함하십시오:

---
agent_skills:
  name: "%SKILL_NAME%"
  version: "1.0.0"
  description: >
    %원본 책/문서에 대한 1-2문장 설명%
  instruction: |
    이 스킬은 %AUTHOR_NAME%님이 저술한 "%BOOK_TITLE%"의 지식을 캡슐화합니다.
    사용자가 이 책의 컨텍스트 내에서 질문하거나 작업할 때 다음을 사용하십시오:
    1. %SKILL_DIR%/chapters/에서 관련 챕터 요약 참조
    2. %SKILL_DIR%/glossary/에서 용어 정의 확인
    3. %SKILL_DIR%/patterns/에서 재사용 가능한 패턴 적용
    4. %SKILL_DIR%/cheatsheet/에서 빠른 참조
  topics:
    - %TOPIC_1%
    - %TOPIC_2%
  compatible_agents:
    - github-copilot-cli
    - amp
    - claude-code
    - hermes-agent
  source:
    type: book
    title: "%BOOK_TITLE%"
    author: "%AUTHOR_NAME%"
    format: "%SOURCE_FORMATS%"
    pages: %PAGE_COUNT%
    extracted_tokens: %TOKEN_COUNT%
---

그런 다음 본문 섹션을 추가하십시오. 6단계의 골격을 사용하되, 이제 7단계와 8단계의 구체적인 내용으로 채우십시오.

마지막 섹션에는 모든 챕터에 대한 링크가 포함되어야 합니다:

## 챕터

- [%CHAPTER_1_TITLE%](chapters/%CHAPTER_1_SLUG%.md) — %1-문장 요약%
- [%CHAPTER_2_TITLE%](chapters/%CHAPTER_2_SLUG%.md) — %1-문장 요약%

---

10단계 — Claude Code에서 접근 가능하도록 설정 (해당하는 경우)

SKILL_DIR이 ~/.agents/skills/<SKILL_NAME>인 경우, Claude Code는 기본적으로 이 스킬을 발견하지 못할 수 있습니다. 이 문제를 해결하려면 ~/.claude/skills/<SKILL_NAME>에서 심볼릭 링크를 만드십시오:

ln -s "$SKILL_DIR" "$HOME/.claude/skills/<SKILL_NAME>"

Claude Code가 주 호스트로 사용되지 않는 경우(또는 사용자가 Claude Code를 사용하지 않는다고 말한 경우) 이 단계를 건너뛰십시오.

---

오류 처리

파일 찾을 수 없음: 지원되는 파일이 발견되지 않으면 "book-to-skill: %INPUT%에서 지원되는 문서를 찾을 수 없습니다. 지원되는 형식: PDF, EPUB, DOCX, TXT, MD, HTML, RTF, MOBI/AZW."로 응답

추출 실패: 추출이 실패하면 명확한 오류 메시지를 표시하고 대체 추출기를 제안하십시오 (사용 가능한 경우). "추출 실패: %ERROR%. 대체 방법: [대체 추출기 제안]."

권한 오류: 디렉토리 생성에 실패하면 "스킬 디렉토리 생성 실패: %PATH%. 수동으로 디렉토리를 생성하고 다시 시도하십시오."로 응답

토큰 제한 초과: 추정 총 토큰이 현재 컨텍스트 창을 초과하는 경우 (예: GPT-4의 경우 128K) 사용자에게 경고하고 다음을 제안:

1. 분석 전용 모드를 먼저 실행
2. 책을 더 작은 청크로 분할
3. 필요한 챕터만 선택적으로 처리

---

보안 고려 사항

이 스킬은 제공된 문서 경로에서 scripts/extract.py를 실행합니다. 이를 통해:

• 선택한 문서의 텍스트 콘텐츠 읽기
• 해당 콘텐츠를 로컬 스킬 파일로 작성
• 필요에 따라 Python 패키지 설치 요청 (--install-missing ask)

스킬 자체는 사용자 확인(2.5단계) 또는 분석을 통한 간접적 조치 없이는 콘텐츠를 수정하거나 코드를 실행하지 않습니다.

항상:

• 제공된 경로가 예상 소스 문서인지 확인
• 특히 대용량 책의 경우 생성 전에 비용 추정 검토
• 공유 환경에서 실행하는 경우 작업 디렉토리 고려 (동시 실행은 분리됨)