nimblescape Course

Keeps the files of a course in a Git repository in one form for people, AI agents and programs: the README of the course, the README of each chapter with its learning objectives, the README of each assignment with its requirements, the feedback file of each assignment, and the files for people: the tutorial pages, the walkthroughs for the teacher, the course plan, the cheat sheet and the overviews of the folders. The form is specified once, in the format of the files of a course, and a course does not copy it. A comment at the top of each file names the format and tells AI agents the command that prints its rules, followed by the own rules of the course from its hidden folder .course/instructions/.

The view "Course" in the explorer shows the chapters of a course with their learning objectives, and the assignments with their objectives, requirements, criteria and feedback. The text editor shows each place where a file differs from its form as a warning.

What the extension does on your computer

• When it works. The extension starts only with a workspace that holds .course/course.yml; in every other workspace it does nothing. It does not run in VS Code for the Web.
• Files. The extension reads the Markdown files of each course of the workspace and its settings .course/course.yml. A course is a folder of the workspace with .course/course.yml; npx -y @nimblescape/course create writes the file for a new course. A repository with README files of chapters or assignments but without this file, for example a course from before the format, is no course for the extension. It changes the text of a file only when you save a file of a course without the comment of the format, and then only adds that comment at the top (setting nimblescape.course.addFormatComment), or when you run "Add Format Comments". Undo takes the change back. It never changes a feedback file, and never a file whose comment names a newer format.
• Network. The extension connects to no address, runs no program and collects no telemetry.
• Restricted Mode. The extension works with all features, because it only reads the files of the course and adds the comment as described above, and runs no program of the workspace.

Features

• View "Course". A tree in the explorer: the chapters with their learning objectives, number, level and text; each assignment of a chapter with its learning objectives, requirements, criteria and the score of its last feedback. A click opens the line of the file. The button at an assignment with a feedback file opens FEEDBACK.md.
• Warnings. Each place where a file differs from its form is a warning in the text editor and in the Problems view, after a pause in typing, also for text that is not saved yet. Examples: a missing section, an objective of an assignment that no chapter has, a level that differs from the level in the chapter, a requirement that is no item of the checklist, a mark of objectives in the wrong place, a tutorial page that the walkthrough of its chapter does not link, an input of more than 30 minutes, or a section of the cheat sheet over its limits.
• Comment of the format. A comment at the top of each file names the format nimblescape-course, its version, the kind of the file and the command that prints its rules for AI agents. The extension writes it when you save a file of a course without it.
• Learning objectives. Each objective has a number per chapter and one of the six levels of the revised taxonomy of Bloom (Krathwohl, 2002), from K1 – Erinnern / K1 – Remember to K6 – Erschaffen / K6 – Create.
• Languages. The sections of a course have German or English names. The language is set in .course/course.yml or follows the names in the files.

Usage

A course sets its own paths and language in .course/course.yml, for example:

course: ts-2
language: de
chapters: 10-course/10-tutorials/*/README.md
assignments: 20-assignments/*/*/README.md

Section 2 of the format names every field and its default.

Command line

The npm package @nimblescape/course has a command with the same reader and checks, for a terminal, for CI and for programs in other languages. AI agents and people run it with npx, without an installation:

npx -y @nimblescape/course instructions assignment   # prints the rules of an assignment README and of the course
npx -y @nimblescape/course check                     # reports each place where a file differs from its form
npx -y @nimblescape/course format                    # writes the comment of the format into each file
npx -y @nimblescape/course read 20-assignments/01-loops/01.01-count   # prints the assignment as JSON
npx -y @nimblescape/course create my-course --language de             # writes the files of a new course
npx -y @nimblescape/course feedback 20-assignments/01-loops/01.01-count answer.json   # writes FEEDBACK.md from the answer of an AI model

The README of the package describes each command and the library.

Settings

Limits

• The extension reads the files of the course from the disk of this computer, so it does not work in a virtual workspace.
• The feedback program writes the feedback files with the command feedback of the npm package. The extension shows a feedback file without the comment of the format as a warning, but does not add the comment, because a person or the extension does not change a feedback file.
• The adapter that gives the reflection tool of nimblescape the objectives, requirements and feedback of a course comes with the reflection extension, which does not exist yet.

Format · Change log · Contributing · Support · Issues · Source

© 2026 Hannes Stauss (scalarion@nimblescape.com) · MIT License.