Цю сторінку ще не перекладено.

Move from AGENTS.md, CLAUDE.md and pasted prompts

This page is for teams whose AI tools already get their rules from files such as AGENTS.md or CLAUDE.md, or from a prompt pasted into an app. It shows how to bring those rules into one instruction, publish it, and point every tool at it.

Why move

Today the same rules are often kept in several places: one file for Claude Code, another for Codex, a third for Cursor, and a prompt pasted into a chat app. Each copy drifts. Nobody knows which one is right, or what changed last week.

An instruction puts the rules in one place:

  • One text. You change a rule once, in the editor, and every tool that follows the instruction gets it.
  • Versions. Each time you publish, you make a numbered version (v1, v2, v3). You can see what changed, and go back to an earlier one.
  • The same version everywhere. Every tool follows the same version, so Claude Code, Codex and Cursor get the same rules on the same day.
Many copies of the same rules become one instruction with versions.

Before you start

Collect the files you have

Make a list of every place your AI tools get rules from. Look in each project's main folder and in each app's settings. Common ones are:

Where Which tool reads it
AGENTS.md Codex, and many other coding agents
CLAUDE.md Claude Code
GEMINI.md Gemini CLI
.cursorrules, or files in a .cursor/rules folder Cursor
A prompt pasted into a chat app's settings or a project Claude, ChatGPT and other chat apps

Ask the developers on each project which of these they use. A project often has more than one, with the same rules copied into each.

Turn each file into rules

The editor's Paste a prompt turns lines that read like rules into rules. Lines such as "Always run the tests" become MUST rules, and "Never commit secrets" becomes a NEVER rule. The rest stays as ordinary text, which the agent still reads as guidance.

  1. Copy the file's text

    Open the file, select all its text and copy it. If the file starts with lines between two --- marks, as Cursor's rule files do, leave those lines out.

  2. Open Paste a prompt

    In the editor, open the command palette (Ctrl+K, or ⌘K on a Mac) and choose Paste a prompt…. Or open Templates… and press the first card, Paste your prompt.

  3. Paste and convert

    Paste the text into Prompt to convert and press Convert. A new instruction opens, and the editor says how many rules it found, for example Converted — 5 rules found. If the file started with a heading, such as "# Acme shop", that heading becomes the instruction's name.

  4. Check every line

    Read the new instruction from top to bottom. Some lines that are rules don't start with a rule word, so they stay as text. Rewrite each of those as a rule yourself, for example MUST: use the team's formatter.

Convert turns lines that read like rules into rules and keeps the rest as text.

Start from a template, a prompt or a file lists the words that make a line a rule.

A CLAUDE.md, before and after

Here is a project's CLAUDE.md, as many teams write it:

CLAUDE.md
# Acme shop

This is the code of Acme's online bike shop: the website, the checkout and the order database.

## How we work

- Always run the tests before you commit.
- You must keep each change small: one fix or one feature at a time.
- You should write a test for every bug you fix.
- Use the team's formatter on every file you change.
- Never commit passwords, keys or other secrets.
- Don't change the order database without asking the team lead.

## Good to know

The checkout is the part customers pay through. Treat changes there with extra care.

Convert makes five rules of it. The line "Use the team's formatter…" doesn't start with a rule word, so it stays as a list line:

After Convert
---
spec: "1"
title: "Acme shop"
---

# Acme shop

This is the code of Acme's online bike shop: the website, the checkout and the order database.

## How we work

MUST: run the tests before you commit.

MUST: keep each change small: one fix or one feature at a time.

SHOULD: write a test for every bug you fix.

- Use the team's formatter on every file you change.

NEVER: commit passwords, keys or other secrets.

NEVER: change the order database without asking the team lead.

## Good to know

The checkout is the part customers pay through. Treat changes there with extra care.

After a few minutes of checking, the leftover line is a MUST rule, and the rule about secrets says why with BECAUSE. A reason helps the agent decide what to do in a case the rule doesn't name:

The instruction, checked
---
spec: "1"
title: "Acme shop"
---

# Acme shop

This is the code of Acme's online bike shop: the website, the checkout and the order database.

## How we work

MUST: run the tests before you commit.

MUST: keep each change small: one fix or one feature at a time.

SHOULD: write a test for every bug you fix.

MUST: use the team's formatter on every file you change.

NEVER: commit passwords, keys or other secrets.
BECAUSE: anything committed stays in the project's history, even after it is deleted.

NEVER: change the order database without asking the team lead.

## Good to know

The checkout is the part customers pay through. Treat changes there with extra care.

The lines between the two --- marks at the top hold the instruction's title. The rest is what the agent reads. What an instruction can say shows every kind of rule.

Opening the file instead

You can also open a Markdown file with Open files…, or drag it onto the editor. The file then becomes a new instruction exactly as it is: its lines are not turned into rules. Pasting its text into Paste a prompt is the way to get the rules made for you. A plain text file (ending in .txt) is the exception: its lines are turned into rules as if you had pasted them.

The editor opens only files ending in .md, .markdown or .txt. For a file such as .cursorrules, or a Cursor rule ending in .mdc, copy its text into Paste a prompt instead.

Asking a connected AI app

If Claude or ChatGPT is connected to your account, you can paste the file into the chat and ask it to make an instruction of it. When the app uses instruction.md's own converter, the result differs from the editor's: every rule goes under one Rules heading, all the other text becomes one paragraph, and the file's own headings are not kept. Check the result in the editor. Connect Claude or ChatGPT shows how to connect.

Merge the copies into one instruction

When you have converted every file, you usually find the same rules several times. Keep one instruction for each set of rules that belongs together, such as one for a project or one for a team.

  • Start from the fullest file. Convert it first. Then copy into it the rules the other files add.
  • Remove duplicates. Keep each rule once. Where two copies say different things, decide which is right with your team, and keep that one.
  • Make the differences parameters. When two files differ only in a value, such as a limit or a team's name, write the rule once with a parameter. Use parameters shows how. A project that follows the instruction gets each parameter's default, so give every parameter a good default.
  • Leave out what belongs to one project only. A coding agent's project follows one instruction. Facts only one project needs, such as where its files are, can stay in that project's own file (see What to do with the old files).

The editor checks the text as you write. Fix every problem it shows before you publish (Check your instruction before you publish).

Publish it and create stable

  1. Publish the first version

    Choose Publish. The first time, a sheet asks who can read it. Only you is chosen to start with. Choose Your organization, so your teammates' tools can read it too, then Publish v1. The first version always goes live.

  2. Create stable

    stable is a name for the version you trust. Nobody makes it for you. Open the command palette, choose Publish gates…, then Add stable at v1. Now each new version you publish reaches the tools that follow stable only when you move stable to it.

Publish a version and A stable version explain both in full, with every choice.

Point each tool at the instruction

Now each tool should get the instruction from instruction.md, not from its old file.

  • Coding agents (Claude Code, Codex, Cursor and others). Open the instruction and choose Share ▸ Follow in your coding agent…. Pick the tool and the version to follow, then copy the setup and give it to a developer on the project. They add it once. From then on, the tool gets the instruction at the start of every session, and new versions as you publish them. Make your team's coding agents follow an instruction explains each choice.
  • Tools that only read a file. Some tools, such as Aider or Goose, read nothing but a file in the project. For those, the setup has a small helper, which the developer leaves running, keep a file up to date with the instruction.
  • Keeping an old file in use. A developer can also have instruction.md keep the instruction in a marked part of a file the tools already read, such as AGENTS.md. Only that part is rewritten at each new version, and the rest of the file stays as your team wrote it. For Cursor, the instruction can be one of the project's Cursor rules instead. This is set up by the developer, not in the editor: Migrate rules files shows how.
  • Chat apps (Claude, ChatGPT). Connect the app and ask it to follow the instruction (Ask it to follow an instruction). Then remove the old prompt from the app's settings, so it doesn't get the rules twice.

A developer who sets this up for many projects at once has a step-by-step page for it: Migrate rules files.

What to do with the old files

Once a project follows the instruction, its tools get the rules from two places if the old file still holds them. When the two disagree, you can't tell which one the agent obeys. So take the moved rules out of the old files.

  • Delete a file that held only rules you moved. Ask the developer to remove it from the project, with the change that adds the setup.
  • Keep a file that also holds facts about the project, such as where things are or how it is built. Remove the rules you moved and keep the rest. If a developer has the instruction kept in a marked part of that file, leave that part alone: it is rewritten at each version.
  • Keep a copy for your records if you like, but outside the project, so no tool reads it.

To change a rule from now on, change it in the editor and publish. Don't edit the old files: the change wouldn't reach the other tools, and the marked part of a file is replaced at the next version.

Check it worked

  • Open the instruction's Agents card. Each tool that reports back shows there, with the version it has and the app it runs in (See which agents follow an instruction).
  • Publish a small change. A running session shows a line such as instruction.md: acme/support-agent v4 → v5, or the change reaches the tool when stable moves, if it follows stable.

Undo or stop

  • Go back to the old files. The developer removes the setup the editor gave and puts the old file back. Nothing on instruction.md changes.
  • Go back to an earlier version. Agents follow published versions, so you can move them back without touching any project (Roll back).
  • Don't want the instruction. Remove the setup from each project first, then delete the instruction from the Instructions page. It stays in Trash for 30 days, and you can restore it from there (Delete and restore).

If it doesn't work

What you see What to do
Imported — mark your rules with MUST:, SHOULD: or NEVER: No line started with a rule word, or the text started with lines between two --- marks. Leave those lines out and paste again, or start the lines you mean as rules with one of those words.
You opened the file and no rules were made A Markdown file you open is kept as it is. Copy its text into Paste a prompt instead.
A rule you expected is still plain text It didn't start with a rule word, such as "Use…" or "Prefer…". Rewrite it with MUST, SHOULD or NEVER in front.
Publish it first: a project follows it by its address on instruction.md. Publish a version, then open Follow in your coding agent… again.
stable isn't offered as the version to follow stable doesn't exist yet. Create it with Publish gates… ▸ Add stable at v….
The agent follows old rules, or mixes old and new The old file still holds them. Remove the moved rules from it. In a project with both AGENTS.md and AGENTS.override.md, Codex reads only the override file.

Still stuck? See Something isn't working, or ask us.

Questions

How do I turn an existing system prompt or CLAUDE.md into an instruction?

Copy its text into Paste a prompt and press Convert. Lines that start with words such as "Always", "Must" or "Never" become rules, and the rest stays as text. How lines become rules lists the words.

Should I make one instruction or several?

Make one for each set of rules that belongs together, such as one per project or one per team. A project's coding agents follow one instruction, so put everything that project needs from instruction.md into it.

Do my developers have to sign in?

Only if the instruction isn't public. Each developer signs in once on their computer with their instruction.md account. Get the setup from the editor shows what the dialog asks for.

Can I keep AGENTS.md for things that aren't rules?

Yes. Keep the project's own facts in it and remove the rules you moved. If a developer has the instruction written into that file, only its own marked part changes.

What happens to my agents if instruction.md can't be reached?

They keep the last version they had and go on working. A computer that never got a copy goes on without the instruction until it can reach instruction.md. See What a developer sees when a version changes.

Last checked against the product:

Was this page helpful? Report a problem