How to Share Claude Agents Across Projects and Teammates

Sharing a Claude agent is not the same as sharing a chat. A chat is a record of one conversation; an agent definition is a reusable configuration that tells Claude what tools it can call, what it should and should not do, and what context to expect at the start of a session. Tools like fenbs keep the shared prompts and the project decisions that those agents read, separate from the configuration files themselves, so the agent behaves consistently across the people and projects that use it.

This matters because agent behavior depends on three things: the model, the configuration and the context. You can share the first two easily; the context is what changes between projects and teammates. A shared agent that reads a shared context record produces far more consistent results than one that starts from a different blank prompt each time.

What to include in a shareable agent definition

A shareable agent definition contains everything someone needs to run the agent in a new environment without asking you to explain the setup.

• The system prompt or CLAUDE.md instructions that define the agent's role and behavior.
• The tool list: which tools the agent is allowed to call and under what conditions.
• The scope boundaries: which files, directories or systems it may change.
• Any standing rules that apply regardless of the specific task.
• A description of the context it expects at the start of a session, so whoever runs it knows what to supply.

Keep the definition in version control alongside the project it serves. A definition that lives only in a chat history or a private tool config cannot be reviewed, updated collaboratively or rolled back if a change makes the agent behave unexpectedly.

How to share agent definitions with teammates

For Claude Code agents, the definition typically lives in CLAUDE.md at the project root or in a subdirectory. Sharing the repository shares the definition. Anyone who clones the project and connects Claude Code has the same agent behavior by default.

The does Claude Code read AGENTS.md guide explains how Claude Code picks up context from files in the project. For agents built with the Claude API, the shareable artifact is the system prompt file and the tool configuration, which you can include in the repository as a JSON or YAML file.

When you update the definition, tell teammates what changed and why. A shared agent whose behavior changes silently creates confusion: teammates cannot tell whether unexpected results come from their task description or from a change in the definition they were not aware of.

Keeping tool assumptions up to date

Agent definitions include tool assumptions: "the file editor tool accepts absolute paths" or "the search tool returns JSON with a results array." Those assumptions break when the tool API changes. The definition starts failing and the error is often not obvious until someone investigates why the agent produces unexpected output.

Review tool assumptions whenever the tools themselves are updated. If you share an agent with teammates who use a different version of a tool, include the version in the definition so they know what the agent was written against.

Separating agent configuration from work decisions

A common confusion when sharing agents is mixing two kinds of information: how the agent behaves (which belongs in the configuration) and what the current project requires (which belongs in the shared work record).

The agent configuration should be stable and apply consistently across all projects that use the agent. Work decisions are project-specific: the approved design, the agreed technology choices, the rules for this codebase. Mixing them means either the configuration grows without bound as it accumulates project-specific rules, or the same project-specific decision must be duplicated across every agent definition that needs it.

Keep the configuration minimal and stable. Store project-specific decisions in fenbs, where any agent that reads the project context picks them up automatically. The Claude Code memory guide explains how Claude Code loads and uses that context at the start of a session.

Reviewing and updating a shared agent definition

A shared agent definition needs a review process. Who decides when the system prompt should change? How are changes tested before they reach other people? Who is notified when a change ships?

Treat an agent definition update the same way you treat a code change: make it in a branch, test it against a real task, review it with the people who will use it, and merge it when you are confident it behaves as intended. An agent definition is code; the same discipline applies.

Record the decision to make a significant change, and the reason for it, as a Decisions and rules entry in fenbs. That way, a teammate who runs the agent and finds unexpected behavior can look up why the definition changed rather than having to ask you.

Testing a shared agent in a new project context

Before a teammate uses your agent definition in their project, test it yourself in a clean context. Start a fresh session with only the shared definition and a new project context. Observe whether the agent asks the right clarifying questions, uses the tools in the expected order, and produces output that matches the expected output you documented.

Pay attention to what the agent assumes without asking. Every assumption is an implicit requirement in the definition: a file path format, a naming convention, a specific tool version. If those assumptions are not stated, a different project context breaks the agent silently. Document them explicitly in the definition so teammates can either match them or know what to adjust.

Testing in a clean context also tells you how much of the agent's behavior comes from the definition and how much comes from accumulated session context. An agent that works well when it has a full project history but fails in a fresh session is a sign that the definition relies on context it does not carry on its own.

When sharing an agent definition is not the right approach

Sharing a definition makes sense when the same task applies to multiple projects or people. It makes less sense when the task is highly project-specific: an agent that depends on a unique architecture, a custom tool setup, or a specific codebase pattern will need significant adaptation for each new project. At that point, the definition is a template at best and a source of confusion at worst.

It also makes less sense for tasks that change frequently. A shared definition that gets updated every few days becomes hard for teammates to track and hard to keep in sync with the projects that use it. For fast-moving tasks, a well-maintained CLAUDE.md per project is more reliable than a shared definition that never quite matches any one project's current needs.

fenbs does not prevent you from sharing agent definitions; it keeps the project-specific decisions and prompts in a separate record so the definition itself can stay minimal and stable. When the definition grows to reflect project-specific details, that is usually a signal to move those details back into the project's context record.

How to do this with fenbs

1. Create a free account and add the project the agent serves. Record the project-level constraints and standing rules as Decisions and rules, separate from the agent's configuration file.
2. Add the reusable prompts and task templates to fenbs as Skills and prompts. Connected agents read them through an MCP connection rather than requiring copies in each config file.
3. Connect each agent over MCP from Integrations. At the start of each session, the agent reads the current project context: rules, active tasks and Where we left off.
4. When you update the agent definition, record the reason for the change as a Decisions and rules entry. Teammates can look up why the behavior changed without asking you.
5. If a shared agent produces unexpected results for a teammate, compare the context they supplied against the standard context. An agent that reads different starting context will behave differently even with the same definition.

For managing the session lifecycle across multiple agent runs, see the guide on how to use Claude managed agents.