Claude Code

Point a project at an instruction, and Claude Code follows it: the text is there when a session starts, and when someone releases a new version, the session gets it at your next prompt, with a line telling you so. Nothing to restart, and no copy of the instruction to keep up to date by hand.

What you need: Node.js 18 or later. The commands on this page run the instruction.md package from npm with npx; nothing else to install.

Using another tool? See Other coding agents.

Set it up

In your project's folder, signed in (instruction login), run:

Shell
instruction connect --host claude-code instruction://acme/support-agent@stable --with-hooks --write

It writes three things, keeping anything already there:

  • .instruction/follow.json: which instruction the project follows. Commit it, so everyone on the project follows the same one.
  • Two hooks in .claude/settings.json: one when a session starts, one each time you send a prompt.
  • .instruction/.gitignore, so the copy the hooks keep (.instruction/current.md) stays out of git.

Without --write, the command prints the same files for you to add yourself.

The first time, Claude Code asks you to approve the project's hooks. Approve them once; they then run on their own.

The binding file

.instruction/follow.json
{
  "follow": "instruction://acme/support-agent@stable",
  "requireSignature": true,
  "refreshSeconds": 60,
  "maxInjectChars": 9000
}
FieldWhat it says
followthe instruction, at a ref (@stable, @latest) or one version (@v3). A ref moves when someone releases; a version never does.
requireSignatureapply only versions signed by the instruction's publisher. An unsigned or wrongly signed version is refused, and the last good one stays.
refreshSecondshow long a fetched version is used before asking again (default 60)
maxInjectCharsthe most text the hook gives Claude in one go (default 9,000; Claude Code takes up to 10,000)

The hooks

.claude/settings.json
{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup|resume|clear|compact",
        "hooks": [{ "type": "command", "command": "npx -y instruction.md hook claude-code", "timeout": 10 }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "npx -y instruction.md hook claude-code", "timeout": 5 }] }
    ]
  }
}
  • When a session starts, and again after /clear or /compact, the hook gives Claude the instruction's whole text, introduced as this project's instructions from instruction.md, with its name and version.
  • Each time you send a prompt, the hook checks whether the version changed since it last gave this session the text. Most of the time it hasn't, and the hook adds nothing at all: no words, no cost. When it has, the new version goes with your prompt.

What you see when the instruction changes

One line in the session, from the hook:

Claude Code
instruction.md: acme/support-agent v4 → v5 (signature verified)

And Claude receives the new version, marked as replacing the old one in full:

What Claude receives
<instruction-update uri="instruction://acme/support-agent@stable" from="v4" to="v5" digest="sha256:9f2c…">
These instructions replace the earlier version of acme/support-agent in full.

# Support agent

MUST: answer every customer within one working day.
…
</instruction-update>

The earlier version stays in the conversation's history until it is compacted, but Claude is told the new one replaces it. A new version reaches a running session at your next prompt, not in the middle of an answer.

Offline, slow or signed out

The hook never holds up a prompt. It asks the registry for at most a second and a half; if the answer doesn't come, or you are offline, it uses the last good version it kept in .instruction/current.md and tries again next time. If it has never fetched a version at all, it says nothing and your prompt goes as usual.

Where a session must not run without its instruction, add --fail-closed to the hook's command: then a prompt with no instruction to give is stopped, with the reason.

A long instruction

Claude Code takes up to 10,000 characters from a hook. A longer instruction is given in part, with a line asking Claude to read the whole text in .instruction/current.md, which always holds all of it.

Signatures

With "requireSignature": true, the hook applies a version only when its signature checks out against the publisher's keys, and says (signature verified) in its line. See signing and trust.

Plans and live updates

The hook reads the instruction; it doesn't hold a live connection. Reading is never limited, on any plan, so every session on every machine can follow. Only instruction watch and the plugin's monitor keep a live connection, and on the Community plan one agent or app has one at a time (live updates and reading).

Other ways

A CLAUDE.md import

Claude Code reads CLAUDE.md when a session starts, and again after /clear or /compact. One line imports the file instruction watch keeps current:

Shell
# in CLAUDE.md, one line
@.instruction/current.md

# and, in a terminal of its own, keep that file current
instruction watch instruction://acme/support-agent@stable --out .instruction/current.md

A change reaches the next session, not a running one; the hooks above are what make it live.

The MCP server and its follow prompt

Shell
claude mcp add instruction-md --transport http https://instruction.md/mcp
# then, in a session, take an instruction as this conversation's instructions:
/instruction-md:follow instruction://acme/support-agent@stable

/instruction-md:follow gives this conversation the instruction you name, as it is now. Claude Code doesn't subscribe to updates of MCP resources, so a new version doesn't reach the session by itself this way: run the prompt again, or use the hooks.

The command line's own MCP server also follows the binding file's instruction and offers it as the resource instruction://current:

Shell
claude mcp add instruction-md -- npx -y instruction.md mcp --follow instruction://acme/support-agent@stable

The plugin

One plugin carries the hooks, the MCP server, a skill on working with instructions, and a monitor that wakes an idle session when a version arrives. Install it from instruction.md's marketplace (github.com/instruction-md/plugins):

Claude Code
/plugin marketplace add instruction-md/plugins
/plugin install instruction-md@instruction-md

As a subagent or a skill

An instruction can also become one of Claude Code's subagents (its own system prompt, which Claude delegates to) or a skill (which Claude loads when it fits the task). Run it again to take a newer version; Claude Code notices the change.

Shell
instruction sync instruction://acme/support-agent@stable --as claude-agent     # .claude/agents/support-agent.md
instruction sync instruction://acme/support-agent@stable --as claude-skill     # .claude/skills/support-agent/SKILL.md

In your own agent, with the Claude Agent SDK

TypeScript
import { query } from "@anthropic-ai/claude-agent-sdk";
import { follow } from "instruction.md/agent";

const ins = await follow("instruction://acme/support-agent@stable", { requireSignature: true });

for await (const message of query({
  prompt: "Answer the open tickets",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code", append: ins.text },
    hooks: {
      // a new version reaches the running agent at its next prompt
      UserPromptSubmit: [{ hooks: [async () => (await ins.changedSinceLastTurn())
        ? { hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: ins.updateBlock() } }
        : {}] }],
    },
  },
})) { /* … */ }

Who follows it, from where

Each session's hook reports the version it applied, and that it was in Claude Code. The instruction's Agents card in the editor counts them by app ("By app: 3 in Claude Code and 1 in Codex"), and its activity says "applied v5 in Claude Code". See managed agents for the whole organization.