Every turn re‑reads everything you left lying around.

How to read this. The rungs are cumulative, not alternatives. Skipping to rung seven with an unmaintained CLAUDE.md gives four teammates the same bad context in parallel.

Two of these inputs also change what you pay. The file reference narrows the search before it starts, so the agent reads three files instead of forty. The bash prefix does the opposite: it puts command output permanently into the conversation, which is exactly what you want when you plan to refer back to it and exactly what you do not want otherwise. Run unrelated commands in a separate terminal window.

Two version notes. The image-paste binding differs by platform and terminal, so ask in-session which combination applies to yours rather than trusting any written guide. Vim editing is enabled through /config; the standalone vim command was removed. Bindings themselves can be remapped in ~/.claude/keybindings.json.

The commands worth knowing by name

Type / and read the local picker rather than memorising a list. Not every built-in appears for every account, because plan, provider and organisation policy all filter it. The ones below earn their place in muscle memory.

The cheapest optimisation available to you is to send less. Every other lever is downstream of that one.

Two consequences fall straight out of the arithmetic. The first is that a long session is not free merely because you are not typing; the resident payload is billed on every turn, so a bloated thread taxes work you have not done yet. The second is subtler. Cache hits are charged at a fraction of standard input, but caching depends on the front of the conversation staying byte‑stable. Switch model in the middle of a long thread and that prefix is invalidated, so the history you were getting cheaply gets re‑billed at full price. The practical rule is to finish a phase, write the outcome to disk, clear, and then switch.

Posted rates move. Introductory pricing expires, tiers get repriced, and availability varies by plan, provider and region. Treat the numbers above as the shape of the decision and confirm the current sheet before you build a budget on it. Two discounts usually matter more than the model you picked: cache hits bill at a tenth of standard input, and batched work at half.

One trap hides inside per‑token comparison. Token counts are not portable across model generations, because a newer tokenizer can emit more tokens for identical text. A lower posted rate can still produce a larger invoice. Measure your own workload before you migrate on price alone.

Effort is a depth dial, not a token cap

Effort changes how long the model works a problem before it defers to you. At low effort, an agent that finds four plausible utility functions is more likely to stop and ask which one you meant. At high effort it will read all four and decide. Neither is correct in general; the question is whether your time or its tokens are scarcer right now.

Two corrections worth internalising. /effort auto resets to the selected model's default level; it does not select the highest one available. And ultrathink buys a single deeper turn without changing the saved effort setting, which makes it the right tool for one hard step inside otherwise cheap work.

The arithmetic behind the questions is unglamorous. Sequential duration is roughly the sum of the tasks. Parallel duration is roughly the longest task plus coordination. Parallelism therefore pays only when the longest task is much shorter than the sum and coordination stays cheap. People reliably remember the first condition and forget the second, which is why teams get reached for on work that a fan‑out would have finished quietly.

The mechanism people skip: worktrees

Subagents get all the attention, and for coupled work one session gets the rest, which leaves the middle case underserved. When you have one transformation to apply across many independent targets, what you want is neither: you want several real sessions, each in its own git worktree on its own branch, so that nothing shares a filesystem and the merge is where disagreement surfaces.

There is a command for the decomposition. Point it at a large repository change and it proposes a split into a set of worktree tasks, which you approve before anything runs. The approval step is the feature. You get to see the partition and reject it while rejecting is free, which is the same move as plan mode one level up.

The cost is honest and worth stating: one whole session per target. That is more expensive than a fan-out and cheaper than a team, and it is the right answer whenever the targets would otherwise fight over the same files.

Where hooks fire, and what they can run

The event catalogue is wider than any slide will show and it grows between releases. The families worth knowing are the tool lifecycle, the session and agent lifecycle, and environment changes. Handler types include a shell command, an HTTP endpoint that receives and answers JSON, a direct MCP tool call with no glue script, and prompt or agent handlers.

Treat a hook as privileged code. It runs with your permissions and receives structured JSON that you did not write. Quote inputs, keep the blast radius small, and never assume a payload string is shell‑safe. This is exactly why many organisations restrict hooks before they restrict anything else.

Every installed skill contributes its name and description to the window on every session, and nothing else. The body loads only once Claude decides the skill applies, or once you name it. So the description is doing two jobs at once: it is the trigger, and it is the part you pay for continuously. A vague description is expensive twice, because it occupies space and fails to fire.

A skill that audits its own source material

Here is a worked example that does something slightly unusual: it teaches a subject while treating its own reference material as suspect. The workshop notes it was built from contained several commands that no longer exist, so the skill routes every version‑sensitive claim through a separate audit file and instructs the model to check current documentation before asserting anything.

---
name: teach-claude-code
description: Teach current Claude Code from fundamentals through advanced
  agentic workflows. Use when a user asks for a tutorial, onboarding,
  workshop, lesson plan, feature explanation, or help choosing an
  orchestration mechanism. Also use to audit Claude Code instructions
  for outdated commands or configuration.
---

# Workflow
1. Establish the learner's OS, terminal, claude --version, provider,
   repository type and desired outcome. Ask only what changes the lesson.
2. Read references/workshop-notes.md for curriculum and demo context.
3. Read references/version-audit.md when the request touches commands,
   shortcuts, pricing, settings, front matter or managed policy.
4. Check the current official documentation before stating a
   version-sensitive fact.
5. Teach the smallest useful rung of the ladder.
6. Structure each lesson: concept, syntax, safe example, exercise,
   success criteria, pitfalls, source link.

Why the split matters. The description carries trigger language and stays resident. The workflow and the two reference files are dead weight until the skill fires, at which point they are exactly what you want. Splitting a large skill into supporting files is not tidiness; it is how you keep the resident cost proportional to the frequency of use.

When to write one

Where a skill defines what to do, a custom subagent defines how it runs: which model, which effort, how many turns before it gives up, which tools it may not touch, which servers it can reach. Two required fields, name and description, and a long list of optional ones. Pairing them is the pattern worth remembering: put the procedure in the skill, put the execution envelope in the subagent, then ask the subagent to run the skill.

---
name: reviewer
description: Review an open diff for correctness and untested edge cases
  without editing files.
model: opus
effort: high
maxTurns: 20
isolation: worktree
background: true
disallowedTools: [Write, Edit]
---

Flag edge cases the tests do not cover. Check error paths.
Report findings only. Do not edit.

A caution carried over from older material. context: fork is a skill field, not subagent front matter. If you want a child that inherits the whole conversation, use the current forked‑subtask command instead. And maxTurns earns its place the moment you start running agents in the background, because it is the only thing standing between an ambiguous instruction and a very long night.

Model Context Protocol is a protocol for exposing typed tools, prompts and resources to a client. An MCP server sits between the agent and a real system and presents a tool list with descriptions, which the agent then selects from exactly as it selects a built-in tool. Servers exist for the systems you would expect: issue trackers, code hosts, wikis, chat, databases, alerting, feature flag stores.

The part that gets misunderstood is authorisation. The server uses credentials it was configured with. There is no privileged path around your existing access controls, which means your normal authorisation and audit posture carries over rather than being bypassed. That is the reassuring answer and also the constraint: a server can do exactly what its credentials permit, so scope them like you would scope any service account.

The demonstration worth running once

Give the agent read access to five unrelated systems, hand it one incident identifier, and forbid it from reading the source code at all. Then watch what happens.

Configuration that actually matters

The write-access question. Read access across many systems is where nearly all the value sits and where nearly all of the risk does not. Creating tickets, closing incidents and pushing branches are separate decisions, and they are worth making separately rather than as one switch.

The question people ask about plugins is when to use a plugin instead of a skill or a subagent, and it does not have an answer, because a plugin is not an alternative to either. It is a folder with a manifest that bundles the things you already made: skills, agent definitions, hooks, server definitions, language server configuration, themes, and supporting executables. It is a distribution mechanism.

flag-toolkit/
├── .claude-plugin/plugin.json
├── skills/rollout/SKILL.md
├── agents/reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── bin/

You have four options for sharing, and one of them is not using plugins at all. A repository of markdown files that people copy into place works, and is what most teams should start with. Above that sits a private internal marketplace, which is well documented and takes real effort to stand up. Above that sit public marketplaces, official and community. Validate before you distribute anything: the abbreviated manifest printed in most training material is conceptual rather than copy-ready.

claude plugin validate flag-toolkit    # require a green result before sharing

Trust deserves a sentence of its own. A skill is a prompt that will run with your permissions in your repository, and a plugin can carry hooks, which is arbitrary code. Read what you install. The provenance question is the same one you would ask of any dependency, and the fact that it is markdown makes it easier to audit, not less important to.

Why a feature you just read about is not there

Almost every gap between documentation and your terminal is a policy decision rather than a bug. Run /status first, then work down this list.

One thing worth internalising about surfaces. The terminal, the editor extensions, the desktop application, the browser version and the mobile application are different front ends over the same agent and the same models. There is no task that only one of them can do. Pick the one that fits where you are, and expect the capability differences you hit to be policy, not architecture.

A pattern in that list. Most of these are not model failures. They are placement failures, or a soft rule being asked to do a hard rule's job, or a missing stop condition. The diagnostic question that resolves the majority of them is the same one: what is in the window, and what did I expect the model to be unable to negotiate?

The habit this should produce. Before you standardise a team workflow on a command, a settings key or a front‑matter field, check it against the official reference and pin the version you verified. A stale instruction file is worse than an empty one, because it is trusted.

Build the practice repository

There is a scaffold script beside this page. It writes a small fulfilment service with no npm dependencies, six passing tests on Node's built-in runner, a deliberately bloated instruction file, a release-managed directory for the hook lab, and a baseline git commit.

# from the folder holding setup-lab.sh
bash setup-lab.sh claude-code-lab
cd claude-code-lab

# verify it yourself, before Claude sees it
node --version      # 18 or newer
npm test            # 6 passing
npm run zones       # prints the unroutable percentage

That last command is the one that matters. It reports the share of the catalogue that routes to a warehouse zone which does not exist. On the shipped scaffold it is exactly 1.00%, twelve SKUs out of twelve hundred. Write the number down. It is your ground truth for lab 3, and it is how you will know whether the agent found the real cause or a plausible-sounding neighbour.

If you would rather not run a script, the alternative is to ask for it. This is itself a reasonable first exercise, because it forces you to specify an outcome precisely:

Create a throwaway JavaScript practice repo with no npm dependencies, tests on
node's built-in runner, and three deliberate defects: a modulus that routes to a
zone outside the real range, a documented order cap that nothing enforces, and a
route with no test coverage. Add a runbook that hints at all three without naming
them. Do not fix the defects. Commit a baseline.

Preflight, in this order

Record your own baseline

Permission posture: start paranoid, relax on evidence

Set the session to ask before every action for the first few labs. It is slower and it is the only way to build an accurate mental model of what the agent actually does, as opposed to what it says it will do. Shift+Tab cycles the modes, including plan mode.

Widen autonomy after you have watched the agent do a class of task correctly several times, not before. The failure pattern to avoid is granting broad permissions early, because the tool then outruns your ability to follow what happened, and you lose the one thing you cannot delegate: being able to explain the code you now own.

Between every lab. git add -A && git commit -m "lab N". The in-session checkpointer snapshots the agent's own file edits, but it does not track changes made by Bash commands, hooks, or your editor. Git is the real undo. Checkpoints are a convenience on top of it.

Most disappointing sessions fail at move one. Someone describes an implementation instead of an outcome, the agent complies, and both parties spend the next forty minutes refining a solution to the wrong problem. The loop below is designed to delay commitment until the option space has been seen, and to make the commitment explicit enough that drift is detectable.

Goal: 1% of the catalogue never receives a restock order and I need that
to be zero.

Constraints: the fix must not change the zone count, must not touch prod/,
and must be verifiable by running npm run zones.

Do not propose a fix yet. First tell me what you would need to read to be
confident about the cause, and what you expect to find.

Give me three materially different approaches. For each one: what changes,
what it costs to verify, what breaks if the assumption behind it is wrong,
and what it forecloses later.

Do not recommend one. Do not rank them. I will choose.

What would have to be true for option two to be the wrong choice?

Which of your assumptions is load bearing, and which one is weakest?

If this ships and something breaks a week later, what is the most likely
thing and where would it surface?

What are you assuming about the data that you have not verified?

Restate the plan as: files you will touch, the order you will touch them,
the check you will run after each step, the rollback if a check fails, and
three things you will explicitly not do.

Keep it under 30 lines. Write it to docs/plan-zones.md.

/clear
/model            # step down to your daily driver
Execute docs/plan-zones.md exactly. Stop after step 2 and show me the diff.

Iterating on a plan costs a markdown file. Iterating on generated code costs a re-read, a diff, a test run and your attention, on every cycle.

How to analyse the options once you have them

Move three assumes you can compare candidates. Five axes carry most of the weight, and the one people skip is the last one.

Anti-patterns in this loop. Asking for a recommendation during move two. Accepting the first plan because it was articulate. Letting the agent choose the orchestration mechanism, which it will do enthusiastically and usually one rung too high. Leaving the plan in the transcript instead of on disk. And treating a confident tone as evidence, which it is not.

Progress is held in the page only and resets on reload, by design. The checklist is a working surface, not a record.