Cette page n’est pas encore traduite.

Migrate AGENTS.md, CLAUDE.md and rules files

For developers whose repository carries its agents' rules in files such as AGENTS.md, CLAUDE.md and .cursor/rules/: turn them into one instruction, release it, and make each tool follow it, so a rule changes in one place and every tool gets the new version.

Several rules files become one released instruction that each tool follows.

Before you start

  • The instruction CLI 0.11.0 or later (npm i -g instruction.md) and Node.js 20.19 or later.
  • An instruction.md account, signed in with instruction login. A new instruction is private unless you say otherwise, and counts against your plan's private instructions:

Plans Community 3 · Pro 100 · Team 1,000 · Enterprise unlimited

  • Write access to the repository, to replace the files.

Find the files

List the instruction files the repository tracks. The names below are the common ones; add any your tools read:

Shell
git ls-files | grep -E '(^|/)(AGENTS(\.override)?\.md|CLAUDE(\.local)?\.md|GEMINI\.md|QWEN\.md|\.cursorrules|\.windsurfrules|copilot-instructions\.md)$|^\.cursor/rules/|^\.clinerules|^\.github/instructions/'
Output
AGENTS.md
CLAUDE.md
.cursor/rules/testing.mdc
packages/api/AGENTS.md

Read them side by side before you convert anything. Rules repeated in several files become one rule. Rules that contradict each other need a decision. A file in a subfolder (packages/api/AGENTS.md) usually holds rules for that part of the code, which become a section of their own.

Convert each file

Two converters turn a prompt into the language's rule lines. They don't work the same way, so pick the one that suits the file.

The example file:

CLAUDE.md
# Repository rules

This is the web app of Acme's support desk, written in TypeScript.
Always run pnpm test before you commit.
Never commit secrets or .env files.
You should keep changes small and focused.
Avoid adding new dependencies without asking.
Use pnpm, not npm.

In the editor

Choose New instruction, then the Paste your prompt card, or run Paste a prompt… from the command menu. Paste the file into Prompt to convert and choose Convert. The editor keeps the file's headings and order. It turns each line that starts with must, must not, always, should, should not, never, do not or don't (optionally after "you") into a rule, and leaves every other line as written. A file with its own # heading is named by that heading:

The editor's result
---
spec: "1"
title: "Repository rules"
---

# Repository rules

This is the web app of Acme's support desk, written in TypeScript.

MUST: run pnpm test before you commit.

NEVER: commit secrets or .env files.

SHOULD: keep changes small and focused.

Avoid adding new dependencies without asking.
Use pnpm, not npm.

A text that already starts with front matter is opened as it is, unconverted.

With the MCP tool

spec_convert takes the text as prompt and an optional title, and returns the instruction as content (with its rule count and a check). Any MCP client connected to instruction.md can call it, as can the instruction mcp stdio server:

tools/call
{
  "name": "spec_convert",
  "arguments": { "prompt": "<the file's text>", "title": "Repo rules" }
}

It reads each sentence, not each line. It recognizes must, always, ensure, make sure, you have to and you need to (MUST); never, do not, don't, must not and under no circumstances (NEVER); should, prefer and try to (SHOULD); and avoid (SHOULD NOT). A sentence that starts with should not becomes SHOULD: Not …, so reword it. It gathers every rule under one ## Rules heading, and joins all other sentences, headings included, into one paragraph under the title you gave:

spec_convert's content
---
spec: "1"
title: "Repo rules"
---

# Repo rules

# Repository rules This is the web app of Acme's support desk, written in TypeScript. Use pnpm, not npm.

## Rules

MUST: Run pnpm test before you commit.

NEVER: Commit secrets or .env files.

SHOULD: Keep changes small and focused.

SHOULD NOT: Adding new dependencies without asking.

Use it for a prompt without structure. For a file with sections, use the editor, or restore the headings by hand.

Review the result

Neither converter understands the sentences. After converting, check each rule:

  • A line the converter didn't recognize stays prose. In the examples, "Use pnpm, not npm" and, in the editor, "Avoid adding…" are still text. Make each one a rule if it is one.
  • A rule word is stripped from the start of a sentence and the rest is kept as written. spec_convert turned "Avoid adding new dependencies" into SHOULD NOT: Adding new dependencies without asking. Reword it.

Merge into one instruction

Put the reviewed rules of every file into one file. Keep each subfolder's rules under a heading that names the folder:

repo-rules.md
---
spec: "1"
title: "Repo rules"
---

# Repo rules

This is the web app of Acme's support desk, written in TypeScript. Use pnpm, not npm.

## Rules

MUST: run `pnpm test` before you commit.

NEVER: commit secrets or `.env` files.

SHOULD: keep changes small and focused.

SHOULD NOT: add a dependency without asking first.

## The API package

MUST: keep `packages/api`'s public routes backwards compatible.

Check it offline. A release refuses what validate reports as an error:

Shell
instruction validate repo-rules.md
Output
ok       repo-rules.md

When several repositories share most rules, keep the shared rules in one instruction, and use parameters or composition for what differs. A follow file passes no parameter values, so give every parameter that hooks and watch deliver a default.

Release it and create stable

Shell
instruction login
instruction push repo-rules.md --org acme --name repo-rules --visibility private --publish --message "From CLAUDE.md, AGENTS.md and .cursor/rules"

push creates the instruction (--org names the organization that owns it), and --publish releases its draft as v1. The release asks you to confirm first. Without a terminal, add --yes. The command prints the instruction's instruction://ins_… address; its id is the <id> below.

stable is never made for you. Create it, so the tools follow the version you choose rather than every release:

Shell
instruction refs <id> set stable v1

From now on, a change is a release, then instruction refs <id> set stable v2 when you want the tools to have it. Refs explains latest and stable.

Replace each file

Each tool gets the instruction in the way it supports best.

Claude Code, Codex and other tools with hooks

The hooks give a session the whole text when it starts, and a new version at its next prompt. They read .instruction/follow.json, which --write creates:

Shell
instruction agents follow instruction://acme/repo-rules@stable --host claude-code --write
instruction agents follow instruction://acme/repo-rules@stable --host codex --write

--write merges the hooks into .claude/settings.json (Claude Code) or .codex/hooks.json (Codex), keeping what is there, and writes .instruction/.gitignore. When you are signed in, it also writes the instruction's MCP servers and skills into the tool's files; --no-apply leaves them out. Claude Code asks once to trust the project's hooks. Codex runs them once the project is trusted, and asks you to trust each hook definition (/hooks). Gemini CLI, Copilot, Cursor and the other tools with hooks take the same command with their own --host: see Other coding agents. Following an instruction describes the follow file.

The instruction is private, so each person who works in the repository signs in once, with instruction agents login. Without a sign-in, a hook reads only a public instruction.

A tool that reads AGENTS.md: a managed block

For a tool that only reads a file, watch --block keeps one region of that file equal to the instruction, and leaves the rest byte for byte:

Shell
instruction watch instruction://acme/repo-rules@stable --out AGENTS.md --block
AGENTS.md
Notes for people stay here, as you wrote them.

<!-- instruction.md:begin uri="instruction://acme/repo-rules@stable" version="v1" digest="sha256:…" -->
# Repo rules
…
<!-- instruction.md:end -->

The region is replaced at each version of the ref, and added at the end of the file when it isn't there. watch keeps running until you stop it. To write once, from a script or a git hook, add --once. It exits 6 when nothing was applied:

Shell
instruction watch instruction://acme/repo-rules@stable --out AGENTS.md --block --once

When an AGENTS.override.md sits beside the file, Codex reads it instead, and watch warns that the region won't reach Codex.

Cursor: a rule

watch --rule writes a Cursor rule that every chat applies, the delivered text under its own front matter:

Shell
instruction watch instruction://acme/repo-rules@stable --out .cursor/rules/instruction-md.mdc --rule
.cursor/rules/instruction-md.mdc
---
description: "This project's instructions from instruction.md (acme/repo-rules v1)"
alwaysApply: true
---
<!-- instruction.md: instruction://acme/repo-rules@stable v1 sha256:…; written by `instruction watch`, replaced at each version: don't edit -->

# Repo rules
…

The file is rewritten at each version. Don't edit it.

Keep or delete the old files

Once the tools follow the instruction, delete the files you merged, so no tool reads an old rule beside the new one. Keep a file only for what isn't a rule for agents, such as notes for people, outside any managed block. Commit the follow file and the hook settings:

Shell
git rm CLAUDE.md .cursor/rules/testing.mdc packages/api/AGENTS.md
git add .instruction/follow.json .instruction/.gitignore .claude/settings.json .codex/hooks.json
git commit -m "Follow acme/repo-rules from instruction.md"

.instruction/.gitignore keeps the fetched text and its state out of the repository:

.instruction/.gitignore
current.md
state.json
given/

A file that watch --block or watch --rule keeps (AGENTS.md, the Cursor rule) can be committed, so a tool works in a fresh clone before anything runs, or added to .gitignore, so the repository never holds a copy. If you commit it, it changes at each version you follow.

Check it worked

  • Start a Claude Code or Codex session in the repository. Its first context holds "These are this project's instructions from instruction.md (…)".
  • The instruction's Agents card lists each signed-in session with the version it applied.
  • Release v2, move stable, and send a prompt in the running session: one line says instruction.md: … v1 → v2.

If it doesn't work

What you see Why What to do
--block needs --out FILE: the file whose region it keeps --block without --out. Name the file: --out AGENTS.md.
--rule needs --out FILE (a Cursor rule: .cursor/rules/instruction-md.mdc), and not --block --rule without --out, or with --block. Give --out and only one of the two.
this registry needs a signed-in caller push, watch or refs without a sign-in. Run instruction login, or set INSTRUCTION_MD_TOKEN.
watch --once exits 6 No version was applied, for example a ref that doesn't exist. Create the ref with instruction refs <id> set stable v1.
A session still follows an old rule The old file is still in the repository. Delete it, or move the text into a managed block.
Still stuck Ask us.

Last checked against the product:

Was this page helpful? Report a problem