learn-from-materials, an agent skill that keeps sources and guesses apart

A skill, not an application, and what that means for who can use it

learn-from-materials is a cross-agent learning skill built on the open Agent Skills specification. The important structural fact is what it is not. There is no web service to sign up for and no pipeline to run on a schedule. It is a set of instructions and scripts that an agent reads, and the agent does the work.

The README names the environments it works in: WorkBuddy, Codex, Claude Code and GitHub Copilot CLI, described as agent environments that can read files, run local commands and recognise SKILL.md. It also states the negative case clearly, and this is a distinction worth taking seriously before you install it. Pure chat environments without file-system access or Python execution can only use parts of the prompting workflow, and they cannot perform material extraction, coverage validation, or HTML rendering.

Those three excluded capabilities are the heart of the project. Extraction is turning a document into structured data, coverage validation is checking that nothing was skipped, and HTML rendering is producing the interactive page. Without a filesystem you get a prompt template, not a learning system.

The repository layout matches the description. There is a SKILL.md at the root, which is the file an agent reads to know what the skill does, a scripts/ directory for the Python that does the extraction and rendering, references/ for the protocol documents, templates/ for the output shapes, examples/ for worked runs including a synthetic three-page teaching PDF, a CHANGELOG.md, a SECURITY.md, a NOTICE.md, a LICENSE.md and both an English and a Chinese README. The version badge reads 1.0 release and there is a matching v1.0 tag from 2026-10-01, with the last push on 2026-10-19.

Two depths, and the difference between them is an audit

The skill offers two learning depths, Quick Overview and Systematic Study, and the README is careful about what each one guarantees.

Systematic study reads to the end. It runs full coverage, summary mapping and reverse checks, and it audits the disposition of every method candidate. The README states plainly that card counts do not establish completeness across books, papers, industry reports, slides and other materials, which is a sentence that reads like a correction of a common mistake. The number of cards produced is not a measure of how much was understood.

Quick overview extracts the core argument and scans the complete structure, auditing the citations that are displayed. Both modes check source hashes, so a page can be tied to the exact document version that produced it.

The output is always the same trio, derived from one content dataset rather than written separately. There is a traceable .learnkb/ knowledge base, a self-contained interactive HTML page, and Markdown. That derivation is what makes the outputs consistent with each other, and it is also what allows the HTML to be regenerated later without re-extracting the document.

The supported inputs are wide: PDF, EPUB, MOBI/AZW/AZW3, DOCX, PPTX/PPTM, HTML, Markdown, TXT, RTF, and multi-material collections. Fine-grained source mapping is available for PDF pages, PPT slides and EPUB chapters, so a claim can point at a page, a slide or a chapter rather than at a document as a whole.

The whole-material methodology, deliberately without a step count

The first feature section describes something that is easy to misread as a generic summary tool. The methodology starts by extracting the central question and the goal of the document, then organizes the argument, frameworks and action rules into one complete structure. It supports the main flow, decision branches, causal and hierarchical relations, and evidence-backed feedback loops.

Then come two refusals that tell you what kind of tool this is. It does not fix a step count and does not force every document into an eight-step process. And the overview is not split into groups by node count. That is an explicit rejection of the format that made a previous generation of note generators feel uniform: a fixed number of stages, whatever the source actually contains.

Instead, selecting a node shows its inputs, actions, outputs, check conditions, related learning units and sources. A node is therefore a small, complete unit of meaning rather than a bullet point.

The whole structure is saved separately as methodology.json and methodology.md, which the README explains keeps what the source document itself does clearly distinct from the whole-document synthesis. The Apply This Methodology feature carries the entire structure by default, letting the agent locate your entry point and advance you condition by condition, though a single card can still be chosen instead.

The protocol is documented in references/whole-material-methodology.md, and the examples directory holds a systematic study example at examples/overview-systematic-demo.json that includes coverage, action-rule, content-review and original-heading records. The README notes that its short length is for demonstration and regression testing, not an extraction ceiling for real documents.

A method library that accumulates instead of restarting

The second feature is the one that changes how the tool behaves over time. After parsing a new document, reusable methods are saved to the knowledge base's methods.json, and a readable patterns.md is generated from it. Each card records purpose, prerequisites, limits, steps, effect checks, a short source quotation, a stable ID and a version. When a document contains no methodology, that is stated plainly rather than invented, which is the same honesty rule that governs the rest of the system.

The page bindings and the method prompts are derived from that same data, so a method library becomes the substrate for several features at once. Several method files can be indexed cumulatively, candidate methods can be found by Chinese or English keywords, and comparison records can be exported.

The versioning rules are strict in a way that matters. Original methods and earlier versions are retained. A synthesized method receives a new ID and an explicit parent-method reference, and never silently overwrites or blends into what the document actually meant. In practice that means the library is append-only with lineage, which is what lets you ask later where a method came from.

The reference for this part is references/method-library.md, and the examples directory includes a method file at examples/methods-demo.learnkb/methods.json, the readable cards in patterns.md, and a demo page bound to a method library at examples/methods-library-demo.html.

The page itself, and the honesty rules it shows the reader

The generated page is the part the learner actually touches, and the README describes it in detail.

Guided content shows source hints for core ideas, key points and conclusions on mouse hover and on keyboard focus, plus an expandable Source panel for touch screens. These hints stay available after switching units. When a verified fine-grained location exists, the matching page number is displayed, and otherwise the unit-level or conclusion-level range is reported as is, which is a quiet admission that sometimes the evidence is coarser than a page number.

Logical relationship maps let core framework cards switch to a collapsible framework mind map with search, zoom and fullscreen, and hovering or focusing a node or link shows its explanation and its source. Independent branches and cross-links keep their original relationships. Reader themes are named, Sea Salt, Ink Wash and Bamboo Moon, with a compact horizontal layout, larger diagrams, readable floating explanations and an optional motion switch, and both diagrams retain their links when motion is off.

The Apply This Methodology control takes your question, goal and constraints, lets you choose the whole structure, a specific method or automatic selection, and produces a copyable prompt to paste into your conversation with the document. The prompt asks the agent to assess applicability before giving sourced analysis and suggested actions. The README stresses that the page does not run an AI itself, so nothing leaves your machine when you use that button.

The separation being enforced is the core promise, and the README lists four categories the outputs distinguish: material-backed facts, areas not covered by the document, model-added content, and externally verified items. A learner can therefore see the difference between what a claim rests on and what the model supplied, which is the thing most summarisation tools collapse.

Offline by default, and language that follows the request

Two operational choices close out the design.

The first is offline by default with no automatic dependency installation. Page notes, learner profiles and wrong-answer records stay in the local browser only. There is no telemetry in the picture, and the skill does not pull packages onto your machine behind your back, which matters for an agent that is about to read your documents. The cost is that you install what the scripts need yourself, and the README does not enumerate them here.

The second is language handling, and the rule is unusually careful. An explicit instruction comes first, then the current request and the conversation, and Chinese and English are supported for body text, the interface, Markdown and copyable prompts. Original quotations and source names are preserved. Language is never guessed from nationality or browser locale, and existing HTML is never auto-translated.

Those two sentences prevent a specific failure. A method that quotes a document in its original language and then translates the surrounding analysis has a different structure from one that translates everything, and forcing the second shape onto a document whose source is in a third language loses the citation trail. Keeping quotations intact and translating only the scaffolding is what lets the source mapping survive translation.

The skill also names a strict separation between document facts and model-added content, verifiable sources, offline-first operation and least privilege as requirements rather than aspirations, and the security documentation is a SECURITY.md at the repository root alongside the NOTICE.md and the MIT licence file.

Editorial conclusion

learn-from-materials suits students and researchers who need to check where every claim in a summary came from, and it suits teams that want a repeatable method for turning a document into teaching material, because the method library accumulates across documents rather than starting from scratch each time. It is the wrong tool for a plain chat window with no file access, since the README is explicit that such environments can use only parts of the prompting workflow, and it is the wrong tool for one-off summaries, since the coverage audits, source hashing and knowledge base structure cost real effort. Before adopting it, check that your agent environment can read files, run local commands and recognise SKILL.md, and expect to read references/whole-material-methodology.md and references/method-library.md, since the README treats those two protocol documents as the actual specification.

Frequently asked questions

Official sources

1. dmoshehun-prog/learn-from-materials on GitHub
2. Issues
3. License: MIT
4. README
5. Releases