dmoshehun-prog/learn-from-materials

learn‑from‑materials – Turning Documents into Traceable, Interactive Study Guides

What it does

• A skill (plug‑in) for AI‑agent platforms (WorkBuddy, Claude Code, GitHub Copilot CLI, etc.) that can read files and run Python code.
• Takes any kind of learning material—PDF, EPUB, MOBI, DOCX, PPTX, HTML, Markdown, TXT, RTF, or a collection of such files—and produces three artefacts:
  1. A .learnkb/ knowledge‑base that records every fact together with the exact source location (page number, slide, chapter, etc.).
  2. An offline interactive HTML page that lets a human browse the material, search a glossary, run self‑check questions, and see source citations.
  3. A synced Markdown version of the same content.
• Supports two study depths:
  • Quick Overview – a high‑level summary with per‑source citations.
  • Systematic Study – a deeper, structured breakdown (core framework, guided content, glossary, action rules, dynamic self‑check, notes).

Why it matters

• Traceability – every statement is linked back to the original page/slide, making it easy to verify and audit.
• Offline‑first – all processing runs locally; no automatic network calls, which protects privacy and works without internet.
• Least‑privilege design – the skill only needs read‑access to the material and a place to write its output; it never executes arbitrary code embedded in the documents.
• Agent‑centric – built on the open Agent Skills specification, so any compatible agent can invoke it with a simple prompt like:

  Please use learn-from-materials to systematically study this PDF and generate a traceable knowledge base and a learning page.
  

How to get started

1. Install – clone the repo into the skill directory of your agent (examples given for WorkBuddy, Codex, Claude Code, Copilot CLI). No automatic dependency installation; you must provide any optional tools you need (e.g., pdftotext, OCRmyPDF, Calibre’s ebook-convert).
2. Run the skill – in a chat with the agent, ask for a quick overview or systematic study and attach the document. The skill will guide you through the workflow defined in SKILL.md.
3. Command‑line utilities – the repo also ships scripts for developers:
   • scripts/extract.py – test parsing capabilities and extract raw text.
   • scripts/verify_coverage.py – audit that the generated knowledge base covers the source material.
   • scripts/render_page.py – turn a JSON page description into HTML or Markdown.
   • Optional Playwright/Node verification of the rendered page.

Key technical details

• Parsing stack: uses the Python standard library where possible; optional back‑ends include PyPDF2/pdfminer.six for PDFs, docling for technical PDFs, ebooklib for EPUBs, python‑docx for DOCX, striprtf for RTF, and Calibre’s ebook‑convert for MOBI/AZW.
• OCR support: if a PDF is scanned, you can plug in OCRmyPDF + pdftotext; otherwise the affected sections are flagged as unverified.
• Coverage & validation: after extraction the skill runs a series of audits—source hashing, incremental‑update checks, bidirectional mapping between summary and source, and reverse‑spot checks—to ensure the knowledge base is faithful.
• Output structure: the generated .learnkb/ folder contains JSON pages (core‑framework, glossary, etc.) plus the HTML template assets. The interactive page includes a local‑storage‑only learner profile and a dynamic self‑check that records wrong answers without sending data anywhere.
• Security & privacy: all inputs are treated as untrusted; no prompts or commands inside the source documents are executed. ZIP files are sanitized, and the optional browser verification blocks any network requests beyond data: and blob: URLs.

Who it’s for

• Researchers, students, or professionals who have large PDFs, slide decks, or e‑books and want a reproducible, source‑backed study guide without uploading the content to a cloud service.
• Developers of AI agents who need a ready‑made skill to add “learn‑from‑material” capability to their product.
• Privacy‑conscious users who want to keep proprietary or sensitive documents on‑device while still leveraging LLM reasoning for summarisation and self‑testing.

Current status

• Version v0.1.0‑beta – functional core features, unit tests, and regression fixtures are in place. The README notes that real‑world results may still vary depending on the agent’s context window, vision/OCR capabilities, and installed optional parsers.

License

• MIT‑licensed, with derivative work from two other MIT projects (book-to-skill and book-to-webpage).

---

All information above is taken directly from the repository’s README; no additional features have been inferred.