ko-lesson: a Codex skill that turns lecture slides into an Obsidian study workspace

The problem ko-lesson targets: course files that cannot be studied from

Most AI study workflows stop at "summarise this PDF". The ko-lesson README argues that is not enough for a real course, and the reasoning is easy to follow: a pile of slides, transcripts and assignments is a record of what a lecturer said, not a path through the material. Chapters arrive in teaching order, which is often the order that made sense in a lecture hall and not the order that works when you are alone at a desk three weeks before the exam.

ko-lesson is a Codex skill aimed at that gap. Its stated audience is university students revising for finals, particularly where the material is messy: mixed Chinese and English, code, formulas, cases, lab steps, or several subjects at once. The README is explicit about what it is not. It is not a prompt for summarising slides. It describes itself as a specification for generating course learning material, and the deliverable is a workspace you can keep using: a course entry page, knowledge-point cards, a study state file, a blocker-and-error log, a final exam, an answer sheet, and detailed answers.

That framing matters when you decide whether to adopt it. If you only want the gist of one lecture, this is the wrong shape of tool. If you want a revision system that survives past the exam, the file layout is the product.

How the skill works: boundary first, then a rebuilt learning order

The mechanism is a fixed sequence of generated Markdown files, and the first two are the ones that distinguish it from a summariser.

Before teaching anything, ko-lesson generates 课程材料记录.md. This file lists which course files are in scope, what each one contains, what role it plays in the course, and which content is explicitly excluded. The README gives the motivation directly: material can look complete while quietly missing a key file, and a study plan built on a partial file set is worse than no plan.

The second file is 课程脉络.md, which re-sequences the course rather than copying the slide order. The README describes three bands: foundational concepts, background, core terminology and prerequisites first; then main-line knowledge, typical cases, common tasks and basic exercises; then hard topics, complex cases, integrated projects and open questions. Each unit carries a difficulty label, its knowledge points, the source file it came from, its prerequisites, and the reason it sits where it does.

After that come the course home page, study state, feedback log and error log, then lesson content and knowledge-point cards. Knowledge points live in 知识点/, images and diagrams in 媒体库/, and cross-references use Obsidian [[wikilinks]] with filenames kept identical to link names to reduce broken links. The README also states a labelling rule: material taken from course files must be marked in 来源依据 with source file, location and how it was used, while AI-generated analogies, exercises and extra explanation must be marked AI补充. That rule is the project's central claim, and it is also the part a reader should test rather than assume.

Installing ko-lesson into the Codex skills directory

The README gives one install route: clone the repository into the Codex skills directory, then restart Codex so the skill is loaded. The repository contains SKILL.md, LICENSE and README.md, and there is no build step, so installation is the clone and nothing else.

On Windows the README uses the PowerShell environment variable for the user profile:

git clone https://github.com/Liunian06/ko-lesson.git "$env:USERPROFILE\.codex\skills\ko-lesson"

On macOS or Linux the target is the home directory equivalent:

git clone https://github.com/Liunian06/ko-lesson.git ~/.codex/skills/ko-lesson

After restarting Codex, the first real use is to point the skill at a folder of course material and a destination folder. The README's per-lesson example reads:

使用 ko-lesson，基于 学习材料/财务会计 生成课程学习资料。先生成课程脉络、课程首页、学习状态和第一课，输出到 学习历史/。

What you should expect from that first run is deliberately partial: a course map, a home page, a study state file and lesson one, not the whole course. The README's full-revision example swaps in a one-shot request for the complete final revision pack. The README also offers a copy-paste prompt for having an AI assistant download and install the skill for you, which is the fastest route if you would rather not touch the filesystem yourself.

Two generation rhythms and three lesson granularities, and why they are separate settings

ko-lesson splits a decision that most study prompts conflate. Generation rhythm decides whether you get lesson one or every lesson at once. Lesson granularity decides how much a single lesson holds, and whether it is taught through a story. The README states the two can be combined, giving "full generation plus one-knowledge-point-per-lesson" and "full generation plus story mode" as examples.

Granularity has three mutually exclusive modes. Default mode lets one lesson carry several knowledge points when they are strongly related and only make sense together; the README recommends it for ordinary course study and for material whose own structure is already clear. One-knowledge-point mode is triggered by explicit phrasing such as "一课一知识点" or "把知识点掰开揉碎讲", and restricts each lesson content file to a single core knowledge point apart from the final exam and review files. Story mode is also triggered explicitly, and builds a complete teaching story around one knowledge point before returning to the formal definition, formula, worked example, common mistakes and exercises.

The README is firm that none of the three turns the course into a summary. Every lesson file must stand alone as complete study material with learning questions, prerequisites, formal explanation, examples, diagram notes, exercises, a feedback entry point and source basis. It also draws a boundary around story mode: the story is only there to lower the entry barrier, and it must not reproduce, rewrite or extend the specific plot, characters or expression of any existing work. That is an unusual constraint to state in a README, and it tells you the author has thought about what a generated story can accidentally become.

The feedback loop and the final exam chain

The default rhythm is per-lesson feedback, and the loop is concrete. The skill generates the course map, home page, study state, feedback log, error log and lesson one, then waits. The learner studies lesson one and fills in the feedback entry point, whose fields the README spells out:

我能复述的内容：
我卡住的地方：
当前难度评分，1 到 5：
我希望下一步：
这个知识点让我联想到的已学内容：

Codex is then expected to update the study state, feedback log, error log, knowledge-point cards and learner background before deciding what to generate next. The branch options the README lists are continue, re-teach, change the example, add practice, step down a level, or reorder the sequence. That is a genuine design choice with a cost attached: you cannot get the whole course in one shot and also get it shaped by your own feedback, because the shaping depends on feedback that does not exist yet.

The exam side is a chain rather than a single file. Once the last lesson is done and confirmed through feedback, the skill produces 期末考试.md, 期末考试-答题卡.md and 期末考试-详细答案.md. After you fill in the answer sheet, it grades the paper and generates 期末考试-批改记录.md plus a second retake paper with its own answer sheet and grading record. If errors, partial credit or uncertain knowledge points remain, another retake paper follows. The README states the retake papers target weak points rather than repeating the whole final exam, which is the part that makes the loop worth running more than once.

Where ko-lesson is the wrong tool, and what to use instead

The README lists its own exclusions, and they are worth taking at face value. Do not use it for a one-sentence summary, a single-page translation, flashcards without source tracing, generic study advice not grounded in course files, or answers alone without the learning process, error log and retake loop. The output structure explains why: a run produces a directory tree with a learner background file, a timestamped course folder, lesson files, a knowledge-point folder and a media library. That is a lot of scaffolding for a task that wanted one paragraph.

The practical alternative for the narrow jobs is the assistant you already have. If you want a summary of a PDF, ask for a summary of a PDF; if you want a page translated, ask for a translation. Nothing in ko-lesson's design improves those tasks, because its value sits in the sequencing, the source labelling and the feedback files, none of which a one-off summary needs. A closer comparison is a spaced-repetition tool such as Anki: Anki schedules reviews of cards you write, and it is very good at that, but it does not read your lecture files, does not rebuild a learning order, and does not produce a mock final with a grading record. ko-lesson does not schedule anything; the README describes a feedback loop driven by you filling in a form, not an algorithm deciding when you next see a card. If your problem is retention of material you already understand, Anki is the better fit. If your problem is that you cannot see the shape of a course you have not studied yet, ko-lesson addresses that directly.

One more limitation sits in the repository itself. The README's roadmap lists example course material, a course-package structure validation script, template snapshots for common course types, bilingual sample output and a quick reference for the full-revision mode as future work. None of those exist yet, so today the only way to know whether the output is correct is to read it.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-07-03. There are no retrieved releases, so there is no versioned upgrade path to reason about; you track main.

The upgrade cost is low in the mechanical sense and higher in the practical one. There is no build step, and the repository holds three files: SKILL.md, which the README calls the actual Codex skill definition, plus LICENSE and README.md. Updating means pulling the new SKILL.md. But SKILL.md is prompt-level instruction, so a change to it can change the shape of everything you generate afterwards. The README's own development notes say to edit SKILL.md, keep instructions specific and traceable to local material, avoid unverifiable generation promises, test on a small course directory first, and check that Obsidian links, source basis, feedback files and error records stay consistent. That last item is the real regression risk: a skill edit that weakens source labelling will not break anything visibly, it will just quietly stop marking what came from your files and what the model invented.

The licence is MIT, which permits commercial and private use and modification, and requires the licence text and copyright notice to be kept with substantial portions of the software. That is a summary of the identifier, not legal advice; read LICENSE in the repository for the actual terms. For a student running this locally, the licence question is mostly theoretical. It would start to matter if you redistributed a modified SKILL.md or bundled the skill into something you ship.

Editorial conclusion

Adopt ko-lesson if you have a folder of real course files, use Codex, and want revision material you can keep in Obsidian rather than a one-off summary. Skip it if you need a single-page summary, a translation, or flashcards without source tracing, since the README lists those as out of scope. Before committing a term to it, run one small course directory through the per-lesson flow and check that 来源依据 and AI补充 labels actually appear in the generated Markdown, because that labelling is the project's core promise and the README documents no validation script for it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Liunian06/ko-lesson on GitHub
4. README