learn.ninja

Vibe learn anything with your agent.

Give your AI agent an article, notes, docs, a transcript, or code. It writes one short, interactive lesson and gives you a link to share. Free, no account.

Website · Docs · Try a lesson · Contributing

Make a lesson

Install the skill in your agent (Claude Code, Codex, Cursor, Gemini CLI, and more):

npx skills add https://learn.ninja -g

Then ask it for a lesson from anything: "Make me a lesson from this article", "Teach my team how our deploy works", "Quiz me on chapter 3". The agent writes the lesson, checks it, and publishes it to a link that plays in any browser.

Chat apps (Claude, ChatGPT) connect to the MCP server at https://learn.ninja/mcp instead. The docs cover both.

What a lesson is

A lesson is made of katas, one per screen, Duolingo- or Brilliant-style: concept katas teach, and question katas (choice, compare, hotspot, sort, order, match, blank, scenario) check what stuck, with instant feedback and hints from the ninja. Lessons are written in any language, right-to-left included, and play on phones.


Every lesson plays on phones	A concept kata teaches one idea	A wrong answer gets a hint, not the answer

Try the example lessons (their files are in examples/):

How compound interest works (beginner)
JavaScript map vs forEach (beginner)
Basic Spanish greetings (beginner)
Correlation isn't causation (intermediate)
Why the Bronze Age collapsed (advanced)

This repository is the whole thing: the website, the lesson player, the lesson format, the learn command, and the skill agents install.

Run it locally

You need Node 24 (see .nvmrc) and npm. Nothing else: no database, no accounts, no keys.

npm install
npm run dev

The web app runs at http://localhost:3000: the home page, the docs at /docs, and the test lessons at /lessons/{slug}. Lessons you publish locally are kept in PGlite (Postgres in WebAssembly) under apps/web/.data/pglite, rate limits are counted in memory, and sign-in codes and feedback are printed to the server console. .env.example lists the variables a hosted deployment uses; none of them are needed here.

To publish to your local server from an agent, set LEARN_API_URL=http://localhost:3000 before running the skill.

Commands

Command	What it does
`npm run dev`	Start the web app (webpack)
`npm run check`	Lint, type-check, and tests across every package. Run it after every change; CI runs it too, plus a production build
`npm run build`	Production build
`npm run storybook`	Storybook at http://localhost:6006, with every kata type in every state
`npm run skill:build -w @workspace/cli`	Rebuild `skills/learn` (bundled CLI, schema, examples) after changing the spec, the CLI, or the examples
`npm run schema -w @workspace/spec`	Re-export `packages/spec/schema/lesson.schema.json` after changing the spec
`npm run map -w @workspace/player`	Rebuild the map visual's country shapes from Natural Earth
`npm run bento -w web`	Redraw the home page's lesson visuals after changing `apps/web/lib/bento-visuals.ts`
`npm run favicon -w web`	Rebuild the favicon from `apps/web/app/icon.svg`
`npm run share -w web`	Re-render the share images in `brand/`

A test fails when a generated file is stale, so npm run check tells you which of these to run.

Structure

Path	What it is
`apps/web`	Next.js app: home page, docs, lesson player pages, publish API, MCP server
`apps/storybook`	Storybook for the player and UI components
`docs/`	The docs pages, as Markdown and MDX
`packages/spec`	The lesson format: Zod schema, JSON Schema, and the checker's rules
`packages/player`	The lesson screens and every kata
`packages/ui`	shadcn/ui components on React Aria, shared styles
`packages/db`	The Postgres schema (Drizzle) and its migrations
`packages/cli`	The `learn` command: sync, validate, and publish lessons
`skills/learn`	The installable lesson skill and its teaching guide
`examples/`	Test lessons, used as fixtures

Contributing

learn.ninja is built by a few people, so help goes a long way. These are the places we'd most like it:

Languages: translate the player's interface into your language, or fix right-to-left issues.
Visuals: new map regions, charts, diagrams, chess boards, molecules.
Sounds and motion: better sound effects, transitions, and celebration moments.
The teaching guide: help agents write better lessons, and add example lessons.
Docs, bugs, and accessibility: always welcome as a pull request, no proposal needed.

New to the code? Pick one of the good first issues. Changes to the lesson format, new kata types, agent round trips, and the ninja's voice start as an Idea issue. CONTRIBUTING.md has the details, the conventions, and how review works; agent-written pull requests are welcome too.

Found a security issue? See SECURITY.md. Everyone taking part follows the Code of Conduct.

License

The code is Apache-2.0. The example lessons in examples/ and the docs in docs/ are CC-BY-4.0. The learn.ninja name, the logo, the files in brand/, and the ninja character are trademarks of Uxcel Inc; see TRADEMARK.md for what forks may and may not do with them.