Skip to main content

Sharing Agents and Skills

A project can share one of its agents, or one of its skills, with other projects in your organization. A project that wants it imports it, and can then run it, start it from its triggers, and call it from its own agents. Nothing is copied: every run reads the sharing project's latest version.

Use sharing when one team builds an agent that other teams need, such as an incident triage agent or a Kubernetes debugging skill.

Words used here​

  • Owning project: the project the agent belongs to. Its files, its history and every change stay there.
  • Receiving project: a project the agent is shared with.
  • Import: what a receiving project does to start using a shared agent. The project gets a link to it, not a copy.
  • Full reference: how a receiving project names a shared agent, the owning project's ID before its address: shared-project/agents:ai-sre.

What a receiving project runs​

There are no versions to publish. Sharing an agent shares every branch and every commit of it, old and new. A run in a receiving project reads the owning project's default branch as it stands when the run starts, unless a trigger names a branch or a commit of the agent; the run records the commit it used. A commit to the owning project's default branch reaches every receiving project at its next run, with no notice.

Everything the agent uses comes with it: its subagents, its skills, its scripts, and the evals and artifact templates it links. An agent that leaves skills out of its definition uses every skill of its project, so sharing it shares all of them; the Share dialog says so. Skills its project imported from other projects don't come with it. Where it runs, it is also offered the skills of the project it runs in: that project's own, and those it imported.

A run belongs to the receiving project: its runs list, its permissions, its integrations, its secrets, its memory and its project instructions. The owning project never sees it. Tool filters that name an integration the receiving project doesn't have leave those tools out.

A secret the agent names, such as ${{ secrets.github_token }}, is the receiving project's secret with that ID; the owning project's secrets never come with it. When the receiving project has no secret with that ID, a variable in the agent's env is left unset, and a step that names it in its own env fails with "Secret not found".

Share an agent or a skill​

  1. In the owning project, open the agent, then More actions → Share (or Edit sharing once it is shared).
  2. Choose who can import it:
    • All projects: every project in your organization, including projects created later.
    • Specific projects: tick each project that needs it. You can only pick projects you can see.
  3. Choose Share.

You can also share from Settings → Shared resources → Shared by this project → Share resources: choose Agents or Skills, then the agent or skill, and Next to choose the projects. Pick several, of any type, to share them with the same projects at once: each one you pick shows as a tag, and sharing several only adds projects, so each keeps who it is already shared with.

One level of sharing: an agent that uses another project's agent or skill can't be shared. Share is turned off, and says which reference is the reason.

Import a shared agent​

  1. In the receiving project, open Settings → Shared resources → Imported from other projects.
  2. Choose Import on the agent's row, marked Available (the Type filter can show agents only). The dialog says where the agent will appear and which branch of the owning project its runs use.
  3. Choose Import.

The agent then appears in the project's Agents list, with the owning project under Created by. Imported skills appear in the Skills list with the owning project under Last changed. On the agent's page, Edit opens its files in the Editor, read-only.

Use it​

  • Run it from its page, from Slack with /agent ai-sre, or with the CLI: autoheal run shared-project/agents:ai-sre "Why is checkout slow?". Add --branch release or --commit 9e1a447 to run one of the owning project's branches or commits; name the agent in full when you do.
  • Start it from a trigger: in the trigger editor, imported agents are suggested in their own group. A trigger runs it at the owning project's default branch, or at the branch or commit it names with run.branch or run.commit. The editor suggests the owning project's branches that hold the agent; type a commit's SHA. Name the agent in full when you set either, and set only one of them.
  • Call it from your own agent: name it in full, for example agent: shared-project/agents:ai-sre as a subagent, or shared-project/skills:kubernetes-debug under skills.
  • Use an imported skill like your own: your project's agents that leave skills out of their definition are offered every skill your project imported, next to your own skills, from their next run. An agent that lists its skills gets only the ones it names, so add the imported skill there in full.

Short names​

A short name you type, such as ai-sre or agents:ai-sre, in the trigger editor, the CLI or Slack, means your project's own agent of that name first, and otherwise the one agent of that name your project imported. If you imported two agents with that name, type the full reference. A trigger saves an imported agent by its full reference, so an agent of that name your project creates later never takes it over. It saves your project's own agent by its short name, which always means your project's agent.

In your project's files, a short name always means your project's own agent or skill. Name a shared one in full.

The Editor​

The Editor shows your project's files on top and, below them, one read-only folder for each project you import from. It holds only what you imported and what that uses, as committed on that project's default branch now: what your project's next run reads.

There is no branch to pick for a shared agent or skill. The sidebar's branch picker is always your project's own. A shared agent's page, the Editor, New run and Run again all use the owning project's default branch; only a trigger, the CLI or the API can name another branch or a commit.

Stop sharing, or delete​

  • Stop sharing: open the agent's sharing (More actions → Edit sharing) and remove projects, or stop sharing it. Each project that imported it and is no longer included sees No longer shared. Its import stays until its admin removes it, so sharing with it again makes the agent work there again.
  • Delete: deleting or renaming a shared agent's folder in the Editor asks you to type the agent's name, and names the projects that imported it. Each of them sees Deleted. A re-created folder is a new agent, which isn't shared.

In a receiving project, runs, triggers and subagent calls of an agent that is no longer shared, or was deleted, fail and say why. A run already in progress isn't stopped, but its later subagent calls are refused.

Remove an import​

In the receiving project, open the agent's page and choose Remove. An agent that is no longer shared, or was deleted, can also be removed from its row in Shared resources. The dialog lists the triggers that start it, which stop working. Nothing changes in the owning project.

Who can do what​

ActionPermissionChecked on
Share, change who it is shared with, stop sharingsharing:updateThe owning project
See an agent's sharingregistry:readThe owning project
See what is shared with the project, read the shared filesregistry:readThe receiving project
Importregistry:createThe receiving project
Remove an importregistry:deleteThe receiving project
Run it, start it from a triggerregistry:run, and the trigger permissionsThe receiving project

Controls you can't use stay visible and turned off, with the reason. Every share, stop, import and removal is recorded in the access log (share, unshare, link and unlink), with the agent and the project concerned. Read it through the API, GET /api/v1/rbac/audit-events, with audit:read on the organization (see Managing Access).

Things to know​

  • Anyone who can commit to the owning project's default branch, or to a branch a trigger names, changes what runs in the receiving project, with that project's integrations and secrets. A trigger at a commit keeps running that commit. Your agent policies and tool filters still govern every tool call, but not a command's environment: an agent can name any of your project's secrets by its ID and use its value in a command. Before you import an agent, check which secrets it names, in its env and in its steps' env.
  • The owning project's Shared resources page lists, under Imported by, the branches and commits each project's triggers run the agent at. If the owning project deletes a branch a trigger names, the trigger fails until someone changes it.
  • Automatic evals don't score runs of an imported agent: its evals belong to the owning project.
  • To share integrations, see Sharing Integrations.