Altitude — learn to code by building

Agent skills that turn an AI coding agent into a tutor instead of a ghostwriter: begin a journey planned with Altitude, or use the standalone free method to pick (or adopt) a real project and plan it locally — then build it one small, fully-understood step at a time.

Where it takes you

Wherever you're starting from, the destination is the same — a real product you can explain line by line:

• Nothing yet → from an empty folder to a deployed MVP you built yourself, understanding every line as it's written.
• A project you can't fully explain (an AI wrote it, or a tutorial carried you) → to a deployed MVP, plus ownership of what's already there: the plan keeps building your app forward while you reclaim the code you didn't write, piece by piece.
• A shipped MVP → keep shipping new features with a tutor at your side — each one placed in the plan, built in small steps, and understood before it goes out.

The metaphor: concepts learned in isolation are loose leaves — hard to sort, easy to lose. A real project is a tree. The trunk is the project's core components, the branches are the build plan, and the leaves are every concept you learn along the way, attached where they belong.

Learning skills

Skill	What it does
/begin	Starts a journey planned on the Altitude web app, binds it to a local workshop, writes its plan locally, and welcomes you with a tour of your journey
/start-project	Interviews you for a project idea sized to your experience, defines the MVP, maps the trunk
/plan-journey	Walks every design decision with you (and checks you understand it), builds the sectioned learning plan, seeds your knowledge graph
/next-lesson	Executes one task in either mode: local plans keep evidence in your knowledge graph; bound subscriber journeys sync progress and mastery with Altitude
/adopt-project	Already have a project? Honest triage, an understanding inventory, a file map with no mystery boxes, and a forward plan with reclaim tasks — replaces the first two skills, feeds the same /next-lesson loop

Rather not install anything? PROMPTS.md has the copy/paste version of the standalone free method.

Already started a project?

If you've got an existing codebase — especially one an AI wrote for you that you can't fully explain — don't start over. Run /adopt-project in that folder. It triages the project honestly (adopt it, trim it first, or — rarely — rebuild with your old repo as the spec), inventories what you actually understand (an inventory, not an exam), maps every file so nothing on disk is a mystery box, and writes a plan that keeps building your app forward while you reclaim the code you already have, piece by piece. From there, /next-lesson works exactly the same.

In the standalone free method, all state lives in a learning/ folder in your project — plain markdown you own:

• learning/project.md — your project, MVP, and trunk
• learning/plan.md — the sectioned plan with locked decisions
• learning/knowledge-graph.md — the living map of what you actually know
• learning/file-map.md — why every file and folder in your repo exists
• learning/scratch/ — the small exercises you wrote to meet each new concept before it went into the project

The free method is complete and works standalone: /start-project + /plan-journey (or /adopt-project), then /next-lesson. An Altitude subscription adds a journey planned on the web, the server-side learning map, scheduled reviews, and progression gates. /begin materializes that journey as a readable local learning/plan.md; /next-lesson refreshes it and syncs completed tasks while you remain entitled. If a subscription pauses, the local plan remains yours and lessons continue in free mode with local knowledge-graph evidence — except a task that carries Altitude's own lesson requirements, which waits for an active subscription with your plan and progress untouched (a separate standalone project stays open to you).

Install

As a plugin (recommended — it updates with the repo). Open a terminal and run claude to start Claude Code:

claude

Then type these two lines inside that session:

/plugin marketplace add jasonku09/altitude-skills
/plugin install altitude@altitude

/plugin exists only in the terminal app. Pasted into an IDE extension's chat panel it answers "plugin isn't available in this environment" — that's the wrong window, not a broken install. (The VS Code and JetBrains extensions are documented to have their own graphical /plugins manager — note the plural — which should also get you there; the terminal route above is the one we test.)

When the install asks where to put the plugin, choose the user scope — the "for yourself, across all projects" option. Starting your journey makes a brand-new project folder, and a project- or local-scoped install writes into the folder you're standing in right now, so it would stay behind exactly when the skills are needed. If the install summary asks you to run /reload-plugins, run it; newer versions activate the plugin in place and tell you "Plugin is now active" instead.

In Codex, run both lines in your terminal:

codex plugin marketplace add jasonku09/altitude-skills
codex plugin add altitude@altitude

The first codex launch after installing shows a one-time "Hooks need review" prompt — choose Trust all and continue to enable Altitude's session hooks. (They stay dormant outside bound journey projects; see below.) Trusting them matters more in Codex than it looks: Codex runs the agent's commands in a sandbox with no internet access, so the skills read your journey from a local copy — and the hooks, which run outside the sandbox, are what keep that copy fresh. You'll see the same prompt again after a plugin update that changes a hook; answer it the same way.

A subscribed journey also needs this session's own identity, so that a second agent window open on the same machine can never answer for this one. Codex exposes it as CODEX_THREAD_ID — observed on Codex CLI 0.153.4 carrying the same value its hooks report as session_id — and the skills pass it explicitly on every journey read. If no real session marker can be read, a bound lesson says so and waits instead of guessing; the free standalone method and every editor tool keep working either way.

The plugin also bundles Altitude's session hooks (hooks/). They stay fully dormant unless you're working inside a project bound to a subscribed journey (altitude bind / /altitude:begin) — no events, gates, or context injection anywhere else. With a bound project, they capture session evidence for your journey and run the plan/diff/retro gates. Gates fail open: a crashed hook never blocks your work. The /altitude:connect and /altitude:status skills manage the link.

Once it's installed: for the free standalone method, open a new Claude Code session in an empty folder and run /start-project. If you planned a subscribed journey on Altitude, install its CLI, connect with /altitude:connect, and run /altitude:begin instead.

Plugin 0.7.0 uses altitude watch from CLI 0.10.0 to notice finished saves. Older supported CLIs use the shell fallback; lessons keep working. See workshop compatibility for required versions and rollout order.

Plugin 0.10.0 opens paid lessons on a web lesson page in your browser and needs CLI 0.13.0. Where a page can't open (over SSH, for example), the lesson stays in the terminal.

Or copy the skills directly — for the free standalone method only (Claude Code):

git clone https://github.com/jasonku09/altitude-skills.git
cp -r altitude-skills/skills/* ~/.claude/skills/

That copies the skills and nothing else: no session hooks, and no auto-update (re-run the clone + copy for new versions). The free method needs neither, so this route is complete for /start-project → /plan-journey → /next-lesson. With an Altitude subscription, install the plugin instead. The hooks are what capture session evidence and run the gates, they live outside skills/, and a copied install has no /altitude: commands to connect or begin with — and nothing would tell you: gates fail open, so the only symptom is a learning map that never fills.

Using Cursor instead? Cursor desktop and terminal have a development preview: this repository now includes a native Cursor plugin in .cursor-plugin/plugin.json. It loads the same seven shared skills plus hooks/cursor.json; copying only skills/ still provides only the standalone free method. Use /connect, /begin, and /next-lesson in Cursor, selecting Altitude in the skill picker if another plugin uses the same name.

Recorded source trials include macOS desktop/terminal and an Ubuntu terminal lesson with live browser grading; they do not establish every platform or model. Automatic recall uses native prompt context on the versions verified in the acceptance notes; the plugin emits no generated learner turns. After installing or updating the full plugin, run /connect to update the CLI and refresh its exact plugin registration while preserving ordinary existing pairing. See Cursor development and acceptance for installation, exact session handling, and remaining release checks. PROMPTS.md remains available for any agent without installation.

For the free standalone method only, copying the shared skills to ~/.cursor/skills/ remains available. A skills-only copy has no session hooks and cannot establish subscribed journey support. Use the complete native plugin for development acceptance of that route.

Using GitHub Copilot instead? This repository includes a native Copilot plugin for the Copilot CLI and Copilot in VS Code, sharing the same seven skills. It needs Altitude CLI 0.12.0 or later. Use /connect, /begin, and /next-lesson in Copilot. See Copilot setup for setup details and what has been verified.

How to use it

• Starting from zero? Make an empty folder, open Claude Code in it, run /start-project. When it's done, run /plan-journey. One sitting each.
• Starting a journey planned on Altitude? Connect your account, run /begin, and follow the folder and binding steps. It ends with a welcome from your tutor and tells you how to open your new journey folder in its own chat, where /next-lesson runs your first server-planned task.
• Already have a codebase? Open Claude Code in that folder and run /adopt-project instead — it replaces both of the above.
• From then on, it's /next-lesson, over and over. That's the whole loop in both free and paid modes, for months. One lesson is one small task — expect 30–60 minutes, 3–5 sittings a week.
• One lesson per sitting — really. Don't binge five in a night. The gap between sessions is where memory consolidates, and it's exactly what the next lesson's review quiz tests. Hungry for more is the perfect place to stop.
• Start each sitting in a fresh session. In free mode, the tutor picks up from learning/; in paid mode, it refreshes the bound journey first. Either route restores exactly where you left off.
• Do the typing yourself. When the tutor dictates a command, you run it in your terminal. When a concept is new to you, you meet it outside the project first: a short explanation with a tiny example, then a couple of small exercises you write in learning/scratch/, predicting the output before the tutor runs each one, then a question: another one, or into the project? In the project, you write every line of what it's teaching; the tutor only writes the structure it isn't teaching (imports, a function's signature, config), tells you what each piece is for, and marks the places for your code with TODO(you) lines. Replace each marker line with your code in your editor and hit save — it's watching the file, not the chat, and it looks the moment the markers are replaced with your code. Stuck? Say "hint" and you get one rung at a time — where to look, then the shape of the answer, then the code — never the answer unasked. The one exception: a chunk built entirely from concepts you've already mastered may be written for you — then you review the diff before it's committed, like a teammate's PR. And a task built entirely from concepts you've marked known opens with an offer to do exactly that; say yes, or say you'd rather type it — it never just does it.
• Tune how you're taught. On a subscribed journey, three settings travel with it: how many drills per new concept (0 to 3), the step size (how much the tutor spells out before you write: a line, a function, or a whole feature), and prediction checks (only on runs that use new material, or every run). Change them in the journey's settings on the web, or just tell the tutor in plain words ("stop the drills", "just tell me what each line should do"). If you like exact commands, the same three are , , and . At the end of each paid lesson, the tutor offers an optional feedback question. The tutor can act on requests to change these settings. Switching between Beginner and Intermediate stays on the web.

Ground rules baked into the skills

• One small step at a time. The pause between lessons is the pedagogy.
• You write every line of what you're learning. New concepts get drilled in a scratch file before they touch your project; the tutor writes only the structure it isn't teaching, and says so.
• Predict before you run anything that uses a concept you're learning. A wrong prediction is the best teacher you'll meet, and "not sure" is an honest answer.
• Review questions come only from what you've already learned, never from the lesson you're about to have.
• Quizzes, predictions, and scaffolds come from your evidence — the local graph in free mode or your server-side learning map in paid mode — so demonstrated, still-fresh concepts do not become busywork, and anything you've marked known on the Altitude map is simply used, not re-taught.
• No mystery boxes: every file in your repo is either explained or explicitly parked. When a scaffold dumps fifteen files into your folder, you get the tour before you build on them.
• Never ship a single line of code you cannot explain.

The free method's one limitation

In the standalone method, the learning/ folder is the agent's memory of what you know: every session reads it, quizzes come from it, and nothing changes without evidence. A local skill cannot start a session on its own, so the scheduling loop is you.

An Altitude subscription adds that server loop: the journey, learning map, scheduled reviews, and progression gates live with your account while the readable plan stays in your project. The teaching method itself remains available here for free.

License

MIT. Fork it, remix it, teach with it. PRs welcome — see CONTRIBUTING.md.