لم تُترجم هذه الصفحة بعد.

An engineering team's coding agents

This page is for an engineering lead who wants every coding agent on the team to work by the same rules. You will write one instruction with the team's rules, the tool its agents use and a skill, have every repository follow it, keep the agents away from a dangerous tool, and see whose agents are behind.

What you'll make

Acme's engineers use coding agents such as Claude Code and Codex. Each repository has its own notes for the agent, and they have drifted apart. At the end of this page, one instruction holds the team's rules, and every repository follows it:

  • every agent gets the same rules at the start of each session, and each new version at the developer's next prompt;
  • in Claude Code and Codex, the instruction also sets up the issue tracker the agents use, and a skill for writing a change's summary;
  • no agent may close an issue, even if someone asks it to;
  • the editor shows which agents have the latest version, and which are behind.

A coding agent is an AI tool that works on code in a project's folder. A skill is a short guide an AI follows for one kind of task.

The Agents card shows whose coding agents are behind, by app.

What you need

  • An instruction.md account, and an organization your engineers belong to. Invite people and choose their roles.
  • A developer who can add files to each repository. You don't run anything yourself: you copy the setup from the editor and give it to them.
  • For the organization's tool rules: the owner or an admin of the organization, and one of these plans:

Plans On Pro, Team, and Enterprise

  • About 30 minutes, plus the time it takes a developer to set up each repository.

The instruction

This is the whole instruction. It starts from the editor's Coding agent starter, with a tool and a skill added.

Coding agent
---
spec: "1"
title: Coding agent
---

# Coding agent

You make changes to Acme's repositories. You work in small, reviewed steps and you leave the code better tested than you found it.

## Rules

MUST: read the surrounding code and follow its conventions before writing new code.

MUST: run the full test suite before proposing a change, and say what you ran.

SHOULD: keep each change to one concern, with a one-paragraph summary.

NEVER: push to the main branch, force-push, or change CI configuration without a review.

> [!GUARDRAIL]
> Never commit secrets, keys or credentials, even in tests.

## Tools and skills

:::mcp{id=tracker title="Issue tracker" src="https://mcp.acme.example/tracker" tools="issues.read,issues.comment,issues.close" allow="issues.read,issues.comment" deny="issues.close"}
Read the issue a change is for, and comment on it when the change is ready. A person closes the issue.
:::

:::skill{id=change-summary title="Write a change summary" trigger="writing the summary of a change for review"}
1. Say what the change does in one sentence.
2. List what you tested, and how.
3. Name the issue it is for.
:::

Use :skill[Write a change summary]{ref=#change-summary} for every change you propose.

## Examples

:::example{title="A good summary"}
Adds retry with backoff to the payment client (3 attempts, jittered). Tests: unit suite green; new test covers the third-attempt failure. For issue PAY-214.
:::

What each part does:

  • The rules. The MUST:, SHOULD: and NEVER: lines are the team's review rules, the same for every agent. The guardrail is a rule the agent keeps whatever it is asked.
  • The issue tracker. The block that starts with :::mcp names an MCP server: a service that gives an AI tools to use. MCP is the common way AI tools reach outside services. This one names three of the tracker's tools: reading an issue, commenting on it and closing it. Reading and commenting are allowed without asking each time. Closing is never allowed.
  • The skill. The block that starts with :::skill is a skill the agent loads when it writes a change's summary. The line under it tells the agent to use it every time.
  • The example. A good summary shows what a reviewer wants to read. The agent never treats it as a rule.

Write it and publish it

  1. Start from the Coding agent starter

    Go to the editor. Open the command palette (Ctrl+K, or ⌘K on a Mac) and choose Templates…. Pick Coding agent ("Small, tested, reviewed changes").

  2. Add the tool and the skill

    Add the tracker and the skill, as in the instruction above. If your organization has added the tracker under Integrations, type & and pick it from the list instead of typing its address. Mention people, tools and other instructions.

  3. Agree on the rules

    Share it with the engineers who review code, as Contributors, and accept or reject what they suggest. Suggest changes and review them.

  4. Publish it, and create stable

    Choose Publish. Under Who can read it, choose Your organization if every engineer in the organization should be able to read it. Then choose Publish v1.

    Then open Publish gates… from the command palette and click Add stable at v1. Repositories that follow stable get a new version only when you move stable. Keep agents on a stable version.

Follow it in every repository

Each repository follows the instruction through a small file of its own, the follow file. A developer adds it once, and everyone who works on that repository follows the same instruction, at the same version.

  1. Open Follow in your coding agent

    Open the instruction and choose Share ▸ Follow in your coding agent….

  2. Pick the tool and the version

    Under 1. Your coding tool, pick Claude Code or Codex. Under 2. The version to follow, pick stable (now v1). The note under it says Your agent moves to each new version this name points to.

  3. Give the setup to a developer

    Under 3. Run this in your project's folder, choose Copy, and send it to the developer. They run it once in each repository, and add the follow file to the repository's shared code. If the instruction isn't public, they also sign in once on their computer with their instruction.md account.

The setup a developer runs once in each repository.

What the developer gets, in Claude Code and Codex:

  • The rules, at the start of every session, and each new version at the next prompt. The session shows one line, such as instruction.md: acme/coding-agent v1 → v2.
  • The issue tracker and the skill, written into the tool's own settings in that repository. Reading and commenting on an issue are allowed without asking. Closing an issue is listed as a tool the agent may not use.
  • Updates to them. When a new version changes the tools or the skills, they are written again in the background as a session starts. The coding tool uses them from its next session. The session then shows a line naming the servers and skills it set up.

Claude Code asks the developer, once, to approve the repository's settings and servers. Other coding agents, such as Cursor or Gemini CLI, get the rules, but not the tools or the skills. When a new version reaches a running session lists each tool.

If a tool needs its own sign-in, such as the tracker, the developer signs in to it on their own computer, and the sign-in stays there.

Roll it out to every computer

Following repository by repository leaves it to each team. For a rule every engineer must keep, such as a security policy, your IT team can install company-wide settings on every computer, for Claude Code and Codex. Developers can't turn them off.

  • Every session on those computers gets the instruction's rules, in every folder.
  • The tools and skills are still set up repository by repository, by the follow file.
  • IT installs them with the tools they already use to manage computers.

Roll out to developers explains the choice. Hand IT Managed agents.

Allow only approved tools, and block a dangerous one

An instruction may name any server, unless your organization says otherwise. An owner or admin of the organization decides which tools its agents may use. The rules hold for every instruction in the organization, not only this one.

  1. Add the tracker to your organization

    In the side bar, open Integrations ▸ MCP. Paste the tracker's address in Add server, and press Add. The row shows Pulling…, then Ready, with the tools it found.

  2. Block the dangerous tool

    On the tracker's row, press Tools. Choose Blocked for a tool no agent should use, such as one that deletes issues. Under New tools, choose Block until reviewed, so a tool the tracker adds later waits until someone allows it.

  3. Allow only approved integrations

    Open Integrations ▸ Overview. Under Rules, turn on Only approved integrations. You see Only approved integrations from now on.

    This rule needs one of these plans:

    Plans On Team and Enterprise

What changes for the team's coding agents:

  • A blocked tool joins the tools an agent may not use when its tools are written into Claude Code or Codex, even if the instruction allows it. In the editor, an instruction that names it shows a problem: The tool “…” is blocked in your organization, so the agent won't use it.
  • A server you didn't add isn't set up at all, once Only approved integrations is on. The developer's session says the server wasn't set up because the organization hasn't approved it.

Add the tools your agents may use explains every option.

See which machines are behind

Open the instruction, and choose the faces beside the publish button. The Agents card lists every coding agent that reported the version it has, with what it runs on, for example on build-server-2.

  • Up to date means it has the version it should have.
  • Behind means a newer version is out, and it doesn't have it yet, for example has v1, not v2. told, not switched means it was told and hasn't moved yet.
  • Paused means an Admin of the instruction paused its updates.
  • Problem means it can't follow the instruction as it should.

Under the list, By app counts them by tool, for example By app: 12 in Claude Code and 3 in Codex. You need to be an Admin of the instruction to see every engineer's agents. Anyone else sees only their own. See which agents follow an instruction explains every line of the card.

A coding agent takes a new version at the developer's next prompt. One that stays Behind for a long time is usually on a machine that is off, or in a session nobody has used since.

Check it worked

  • In a repository that follows it, a new session of Claude Code or Codex knows the team's rules. Ask it "What rules do you follow here?"
  • The tracker and the skill appear in the coding tool, and the tool refuses to close an issue.
  • The Agents card lists the developers' agents as Up to date and follows stable.

Clean up

  • To stop a repository following it, the developer removes the follow file and the instruction's entries from the repository. Hand them How following works.
  • To keep an agent on its version for a while, pause its updates in the Agents card.
  • To stop every agent at once, revoke the version they follow. Revoke a version.

If it doesn't work

What you see What to do
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 in the version list Create it in Publish gates…. Until then, pick latest.
The session says it couldn't read the instruction, and goes on without it The developer hasn't signed in on that computer, or can't read the instruction. Share it with them, or publish it to Your organization.
The tracker isn't in the coding tool Tools and skills are set up only in Claude Code and Codex. Otherwise, check the session's line: it says what wasn't set up, and why.
The editor marks a tool as blocked Your organization blocked it. Pick another tool, or ask an admin to allow it in Integrations ▸ MCP ▸ Tools.
An agent stays Behind Ask the developer to send a prompt or start a new session. Check that its updates aren't paused.
Still stuck Ask us, or see Something isn't working.

Questions

Do the instruction's tools and skills reach every coding agent?

Only Claude Code and Codex. Their tools and skills are written into the tool's own settings in each repository that follows the instruction. Other coding agents get the rules. See Follow it in every repository.

Can a developer use a tool our organization blocked?

Not through this instruction. A blocked tool is listed as one the agent may not use when the tools are written, and the editor marks any instruction that names it. See Allow only approved tools, and block a dangerous one.

How do I make sure every engineer follows the security rules?

Ask your IT team to install company-wide settings for Claude Code and Codex. Every session on those computers then gets the instruction, and developers can't turn it off. See Roll out to developers.

Does every engineer's agent count against the free plan's live updates?

No. A coding agent reads the instruction; it doesn't hold a live update. Reading is never limited. See Make your team's coding agents follow an instruction.

For developers: Servers, skills and accounts explains how tools and skills are written into each coding agent, and Claude Code and Codex cover each one's setup.

Last checked against the product:

Was this page helpful? Report a problem