745 ／ 749
learn-from-materials, PDF·책·논문을 공부하는 웹페이지로 바꾸는 에이전트 스킬
PDF나 책을 AI에게 요약시키면 읽은 기분은 들지만 정작 머리에 남는 것은 적다. learn-from-materials는 자료를 요약문 대신 공부하는 웹페이지로 바꿔 주는 AI 에이전트 스킬이다. 책·PDF·논문·슬라이드를 넣으면 원문 출처를 따라가 확인하고, 퀴즈를 풀고, 노트를 적을 수 있는 학습 페이지가 나온다. 자료에 실제로 있던 내용과 모델이 덧붙인 설명을 엄격하게 나눠 둔다는 점이 이 도구의 핵심이다. MIT 라이선스로 공개된 저장소이며 2026년 10월 초 기준 깃허브 별은 약 840개다.
어디서 돌아가나
이 스킬은 오픈 Agent Skills 규격을 따른다. 파일을 읽고 로컬 명령을 실행하며 SKILL.md를 인식하는 에이전트 환경에서 제대로 작동한다. README가 예로 드는 것은 WorkBuddy, Codex, Claude Code, GitHub Copilot CLI다. 파일 시스템 접근이나 파이썬 실행이 없는 순수 채팅 환경에서는 프롬프트 흐름 일부만 쓸 수 있고, 자료 추출과 커버리지 검증, HTML 렌더링은 하지 못한다.
입력 형식은 PDF, EPUB, MOBI/AZW/AZW3, DOCX, PPTX/PPTM, HTML, Markdown, TXT, RTF와 여러 파일을 묶은 자료 세트다. 결과물은 세 가지다. 출처를 추적할 수 있는 .learnkb/ 지식 기반, 파일 하나로 열리는 인터랙티브 HTML 학습 페이지, 같은 콘텐츠 데이터에서 뽑은 마크다운이다. PDF는 쪽, PPT는 슬라이드, EPUB는 장 단위까지 출처를 짚는다.
학습 페이지는 여섯 모듈로 이뤄진다. 핵심 프레임워크, 안내형 콘텐츠, 용어집, 실행 규칙, 동적 자기 점검, 로컬 노트다. 페이지는 자료 근거가 있는 사실, 자료가 다루지 않는 영역, 모델이 덧붙인 내용, 외부에서 검증한 항목을 서로 구분한다.
주요 기능
자료 전체를 꿰는 방법론
작업은 자료의 중심 질문과 목표를 뽑는 데서 시작한다. 이어 논증, 프레임워크, 실행 규칙을 하나의 구조로 정리한다. 주 흐름, 의사결정 분기, 인과·위계 관계, 근거가 있는 피드백 루프를 다루되 단계 수를 정해 두지 않으며, 모든 자료를 8단계 과정에 억지로 맞추지도 않는다. 노드를 고르면 그 노드의 입력, 행동, 출력, 확인 조건, 관련 학습 단위, 출처가 보인다.
이 전체 구조는 methodology.json·methodology.md로 따로 저장된다. 자료가 직접 말한 것과 자료 전체를 종합한 결과를 섞지 않기 위해서다. 안내형 콘텐츠에서는 핵심 아이디어와 결론 위에 마우스를 올리거나 키보드로 초점을 옮기면 출처 힌트가 뜬다. 검증된 세부 위치가 있으면 쪽 번호를, 없으면 단위·결론 수준의 범위를 그대로 보여 준다.
쌓여 가는 방법 라이브러리
새 자료를 분석하면 재사용할 수 있는 방법을 지식 기반의 methods.json에 저장하고, 여기서 읽기 쉬운 patterns.md를 만든다. 카드마다 목적, 전제 조건, 한계, 단계, 효과 확인 방법, 짧은 원문 인용, 고정 ID와 버전이 붙는다. 자료에 방법론이 없으면 없다고 적을 뿐 지어내지 않는다.
지정한 여러 방법 파일을 누적해 색인할 수 있고, 중국어나 영어 키워드로 후보 방법을 찾는다. 원래 방법과 이전 버전은 남겨 두며, 종합해서 만든 방법에는 새 ID와 부모 방법 참조를 붙여 원문이 뜻한 바를 조용히 덮어쓰지 않는다.
언어와 페이지 안의 상호작용
본문, 인터페이스, 마크다운, 복사용 프롬프트는 중국어와 영어를 지원한다. 명시적 지시를 가장 먼저 따르고, 그다음 현재 요청과 대화의 언어를 따른다. 국적이나 브라우저 로캘로 언어를 짐작하지 않으며 원문 인용과 출처명은 그대로 둔다.
핵심 프레임워크 카드는 검색·확대·전체 화면을 지원하는 접이식 마인드맵으로 전환된다. 노드나 연결선에 마우스를 올리면 설명과 출처가 나온다. 새 페이지는 Sea Salt, Ink Wash, Bamboo Moon 세 테마 중 하나를 쓴다.
‘이 방법론 적용하기’ 기능에 질문과 목표, 제약 조건을 넣으면 프롬프트가 만들어진다. 이 프롬프트를 자료를 다루던 에이전트 대화에 붙여 넣으면, 에이전트는 먼저 적용 가능성을 따진 뒤 출처를 단 분석과 제안을 내놓는다. 페이지가 직접 AI를 돌리지는 않는다.
두 가지 학습 깊이
빠른 개요와 체계적 학습 중 하나를 고른다. 요청에 깊이를 밝히지 않으면 스킬이 한 번 묻는다.
| 항목 | 빠른 개요 | 체계적 학습 |
|---|---|---|
| 내용 | 주요 섹션의 핵심 논증, 필수 용어, 조건과 한계 | 출처 블록을 하나씩 읽고 독립적인 지식·논증·근거·방법을 최대한 보존 |
| 출처 검사 | quick-audit.json에서 전체 구조 스캔과 표시된 인용 검토 |
전체 커버리지, 요약 원장, 규칙·관계 원장, 독립적인 내용 검토 |
| 방법 파일 | 방어 가능한 핵심 방법과 통합 구조 | 자료 전체에 비춰 검토한 방법과 통합 구조 |
| 문제 은행 | 미리 만든 전체 문제 은행 없음. 퀴즈를 시작할 때 고른 범위의 원문 문제를 검토 | 체계적 학습 절차로 문제를 색인 |
두 깊이 모두 같은 여섯 모듈, 중국어·영어 지원, 세 가지 테마, 관계 지도, finalize.py 전달 방식을 쓰고 출처 해시를 검사한다. 다만 빠른 개요는 자료를 빠짐없이 다뤘다고 보장하지 않는다. 체계적 학습도 카드 개수만으로 완전성이 입증되지는 않는다고 README는 밝힌다.
역할 분담도 분명하다. 스크립트는 추출, 결합, 검증, 전달을 맡고, 학습 페이지의 내용(page.json, methods.json, methodology.json)은 에이전트가 원문을 읽고 직접 쓴다.
설치와 사용
파이썬 3.10 이상이 필요하고, 자료와 스킬 디렉터리를 읽고 로컬 파이썬 명령을 실행할 수 있는 에이전트여야 한다. 대부분의 형식은 파이썬 표준 라이브러리나 시스템 기능으로 처리한다. 스캔한 PDF나 이미지가 많은 슬라이드는 OCR이나 비전 기능이 있어야 하고, 없으면 해당 범위를 미확인으로 표시한다. 선택 의존성은 자동으로 설치하지 않는다.
1.0 릴리스 압축 파일을 풀어 learn-from-materials/ 폴더를 에이전트의 스킬 검색 경로에 통째로 넣거나, 저장소를 클론한다. 클론은 기본 브랜치를 받으므로 릴리스 압축본과 다를 수 있다. 같은 이름의 스킬이 이미 있으면 먼저 백업한다.
| 에이전트 | 사용자 수준 설치 경로 |
|---|---|
| WorkBuddy | ~/.workbuddy/skills/ |
| Codex | ~/.agents/skills/ |
| Claude Code | ~/.claude/skills/ |
| GitHub Copilot CLI | ~/.copilot/skills/ 또는 ~/.agents/skills/ |
설치한 뒤에는 대화에서 이렇게 요청한다.
- “learn-from-materials로 이 PDF를 체계적으로 공부하고, 출처를 추적할 수 있는 지식 기반과 학습 페이지를 만들어 줘.”
- “이 PPT를 빠르게 개괄하고, 슬라이드별 출처를 남긴 오프라인 학습 HTML을 만들어 줘.”
보안과 개인정보
입력 자료는 언제나 신뢰할 수 없는 데이터로 다룬다. 자료 안에 들어 있는 프롬프트, 명령, 역할 재정의는 지시로 실행하지 않는다. ZIP 기반 형식은 경로, 항목 수, 압축 해제 크기, 압축률, 암호화 여부를 검사한다. 브라우저 검증은 대상 HTML과 data:·blob: 리소스만 허용하고 나머지 요청을 막는다.
생성 메타데이터는 기본적으로 상대 경로나 파일 이름만 써서 로컬 사용자 디렉터리가 드러나지 않게 한다. 이 프로젝트의 스크립트는 자료를 네트워크로 보내지 않는다. 그러나 AI 에이전트에 넘긴 내용이 어떻게 저장·처리되고 모델 개선에 쓰이는지는 사용하는 플랫폼과 계정 설정, 약관에 달려 있다. 페이지에는 계정, 클라우드 동기화, 온라인 채팅이 없고, 개인 노트와 독자 프로필, 오답 기록은 브라우저 로컬 저장소에만 남는다. 사용할 권리가 있는 자료만 처리하고, 저작권 있는 원문이나 내부 문서, 민감한 개인정보가 담긴 지식 기반은 공개 배포하지 말라고 README는 당부한다.
바탕이 된 프로젝트
learn-from-materials는 MIT 라이선스 프로젝트 두 개를 바탕으로 한 파생 저작물이다. 자료 추출과 지식 분해, 기본 지식 기반 구조는 virgiliojr94/book-to-skill에서, 인터랙티브 학습 페이지와 테마 체계, 출처 표시, 후속 질문 설계는 crayon-ai/book-to-webpage에서 왔다. 새로 더하고 고친 부분도 MIT로 공개했으며, 원 프로젝트 작성자들이 이후 확장을 보증하지는 않는다고 밝혀 두었다.
출처
- dmoshehun-prog, learn-from-materials. GitHub. https://github.com/dmoshehun-prog/learn-from-materials