How to share agent instructions with your team

To share agent instructions with your team, keep one canonical copy somewhere everyone can reach, then have each machine apply that copy where each tool expects to find it. Two places are worth putting it: your git repository, which is free, or a folder that syncs between people, which is what you need for rules that span every repo and every machine.

Start with the repo. If your team lives in one codebase, commit the instruction files, review changes in pull requests, and you are done. Reach for a shared folder only when the rules outgrow a single repo, which happens once they describe how your team works rather than how one codebase compiles. Doing that in Jotura means sharing an ordinary folder of markdown notes with named people, and it requires Jotura Sync on both sides at 4 pounds a month.

What counts as agent instructions

The filenames are converging. Codex, Cursor, and several other tools now read AGENTS.md, the closest thing to a standard. Claude Code reads CLAUDE.md, and skills and subagent definitions have no shared format, so those are the differences worth planning around.

Tool	What it reads	Managed by jotura agents sync
Claude Code	CLAUDE.md, plus skills and subagent definitions	Yes
Codex CLI	AGENTS.md	Yes
Gemini CLI	GEMINI.md	Yes
GitHub Copilot	copilot-instructions.md	Yes
Cursor, Windsurf, Zed, others	AGENTS.md, or a tool-specific rules folder	Only as a custom entry

Most of these files exist in two places: one inside the project, and one in your home directory that applies everywhere. The two paths differ, and Copilot’s project file sits at .github/copilot-instructions.md rather than the root. Repo files travel with the code for free. Home-directory files are personal to each machine, so nothing distributes those for you.

If you want a single file, write AGENTS.md and have CLAUDE.md import it with @AGENTS.md on the first line.

Where the committed file runs out

Committing instructions costs nothing, so use it as far as it goes. It runs out in three ways.

The first is repo count. A rule like “we never push directly to main” belongs to the team, not to one codebase. Commit it and you are pasting the same paragraphs into every repository, then watching most copies drift.

The second is global config. Personal skills, subagents, and the home-directory instruction files are never in a repo, so a new hire rebuilds a setup by asking colleagues what they run.

The third is non-code work. Operational runbooks, meeting conventions, and the customer language agents should follow all sit awkwardly in a code repository.

Options that do not involve Jotura

A dotfiles repo is the most common answer, and it is a good one. Put the home-directory instruction files in a private repo, then symlink them into place with stow or chezmoi. It is free, reviewable, and version controlled. The costs are that everyone has to remember to pull, non-developers rarely take part, and plaintext is a poor home for anything sensitive.

Pointing Syncthing or a cloud drive at the config directories is the lighter option. It is free and instant, with no review, no history, and file-level conflicts when two people edit at once.

The shared folder route

The alternative is to keep the canonical instructions as notes and share the folder holding them. In Jotura you share a folder or a single note with named people, as editors or as viewers. Viewers can read a rule but not change it. Both sides need Sync, so a teammate without it cannot receive the folder.

A received share lands under Shared with me/, not inside the recipient’s own config, so a shared note never silently becomes everyone’s global instructions. You bridge that gap with a pointer: a short line in each person’s own CLAUDE.md sending their agent to the team note before it acts.

Be clear-eyed about what you give up. Nothing reviews an edit before it reaches everyone’s agent, and version history tells you only afterwards who changed what. If a rule needs sign-off before it takes effect, keep that rule in the repo.

Setting it up end to end

1. The owner creates a Team Agents/ folder in their vault with a Conventions.md note inside.
2. The owner right-clicks that folder in the desktop app, shares it, and invites teammates by email as editors or viewers.
3. Each teammate installs the app, the CLI, and the agent skills with one command, signs in to Sync, and accepts the invite. The folder appears under Shared with me/.
4. Each teammate adds the pointer below to their own instruction files.
5. Anyone with the editor role edits the note, and the change reaches every teammate on their next sync.

curl -fsSL jotura.io/install.sh | bash

On Windows, run irm jotura.io/install.ps1 | iex instead. The installer wires up the agents it finds on the machine, so run jotura skill install all --force after adding a new one.

For Claude Code, the strongest pointer is an import, because it loads the file rather than asking the agent to go and read it.

@~/Vault/Shared with me/Team Agents/Conventions.md

Check it resolves on your vault path. For a runtime without imports, use a prose pointer, which is a request the agent can skip.

Before proposing an approach, read the team conventions at
"Shared with me/Team Agents/Conventions.md" and follow them.

Keeping your own config on your own machines

Sharing with people and syncing your own machines are different jobs. The command jotura agents sync does the second one: it reconciles the vault’s Agents/ folder against your home-directory config, in both directions, for one person. Add --dry-run to see the plan, and note that a file changed on both sides exits 16 until you pick --prefer vault or --prefer system. Custom entries in Agents/Agents.md cover tools outside the built-in four, and sync your CLAUDE.md between machines has the walkthrough.

Let the agents maintain the shared note

A conventions note is only useful while it stays current, so agents need to write to it, not just read it. Read first to get the current hash, then write with that hash, so a concurrent edit cannot be overwritten silently.

jotura read "Shared with me/Team Agents/Conventions.md" --json
jotura edit "Shared with me/Team Agents/Conventions.md" \
  --replace "Old rule text" --with "New rule text" \
  --if-hash <hash-from-read>

A stale hash exits 2 instead of clobbering the file, and --replace exits 4 if the string appears more than once, so an agent cannot fix one line and quietly rewrite four others. On a viewer’s machine that same write exits 15, so give the editor role to anyone whose agent should maintain the note.

There is a first-party version of this note too. Running jotura conventions creates and prints Agent Conventions.md at the vault root, but that copy is per-person and outside any share, so the team version stays a separate note inside the shared folder.

Decisions can live as their own notes, which keeps the conventions note short. Memory notes default to a private Memory/ folder at the vault root, so a team decision needs --root pointed inside the share. Recall finds them either way, because it matches any path segment named Memory.

jotura memory log --kind decision --title "Rust for the sync core" \
  --root "Shared with me/Team Agents/Memory" \
  --project "Platform" --body "We chose Rust because..."
jotura memory recall "sync core"

More on coordinating several agents is in shared memory across AI coding agents.

What this costs and what it does not do

Sharing runs on Jotura Sync at 4 pounds a month or 40 pounds a year per person, roughly 5 dollars a month, with no free trial. Obsidian Sync costs 4 to 8 dollars a month, so there is no saving here. It also solves a different problem, syncing one person’s devices rather than sharing a folder with named people.

Obsidian wins on ecosystem and reach. Its plugins cover git-backed vaults and self-hosted sync at no cost, there are far more community answers, and it runs on iPhone.

Jotura does not. There is no iOS app, and the Android app can read and edit a share it has joined but cannot invite, promote, or manage members. Inviting and accepting happen in the desktop app, so a machine with only the CLI cannot receive a new share, though it works fully once the share is mounted.

Two more limits matter. Jotura is closed source, so the encryption design is described rather than auditable, and a team whose policy requires a readable client should take the git route. Removing someone stops future updates reaching them, but they keep everything they already had, so rotate any credential that was ever in a shared note.

Frequently asked questions

Do we all get the same instructions, exactly? Only for the shared folder. Each person’s own config stays theirs, so people keep personal skills and habits while sharing the team layer.

What happens if two people edit a rule at the same time? Concurrent edits merge automatically, and the CLI’s hash-checked writes stop an agent overwriting a change it never read. Version history keeps three years with attribution, so you can see who changed a rule and what it said before. See how sharing and encryption fit together.

Is the shared folder readable by Jotura? No. Shared notes are end-to-end encrypted to you and the people you invited, and path names are hashed, so the server does not learn your folder structure either. The CLI reference covers what agents can and cannot reach.