Zed

Vendor: Zed Industries Install name: zed Status: GA Native config: <project>/.rules

InstallationCopy Anchor Link

apothem install --harness zed --project /path/to/project

The adapter writes one project-scope Zed instruction file from the shared Apothem rules and governance surface. Zed reads one project instruction file, the first match in this list:

.rules
.cursorrules
.windsurfrules
.clinerules
.github/copilot-instructions.md
AGENT.md
AGENTS.md
CLAUDE.md
GEMINI.md

There is no per-tool rules directory, so the whole Apothem surface lands in the flat .rules file at the top of that list.

It also writes Apothem's skills, and the rules and templates they cite, to your user home, before it touches the project (see Files outside the project).

Files written:

• <project>/.rules, the instruction file.
• ~/.agents/skills/<name>/SKILL.md for each Apothem skill and command, in your user home.
• ~/.config/apothem/rules/ and ~/.config/apothem/templates/, in your user home.

Files outside the projectCopy Anchor Link

The install also writes Apothem's skills to your user home, before it changes anything in the project:

These folders are shared. They are not private to the project:

• Every project you install zed into, and every other Apothem install that names the folder, uses the same copy and writes the same files, so the order you install in does not matter. Several other tools read ~/.agents/skills/ too; the harness registry lists them.
• --project chooses the instruction file to write and which project the install belongs to. It does not change where the skills go.
• The install adds no skill or rule file to your repository. The project gets the instruction file, plus the .apothem/ data folder every project install creates.
• The home folders are written first. If that fails, for example because a folder in the path is a link that leaves your home directory (a link that stays inside it is followed) or cannot be written, the install stops with the error before anything in the project changes.
• A skill folder with an Apothem skill's name that Apothem did not write is left alone, and the install prints a warning that names it. Rename or move it, then run apothem update. apothem verify fails while that name is held.
• The files add up to a few megabytes.

The install prints a note that names the folders it writes outside --project, and --dry-run lists them.

Profile-to-native-config mappingCopy Anchor Link

The adapter reads Apothem's shared profile and renders the project .rules file on every apothem install or apothem update run. The shared profile is the source of truth; any pre-existing .rules (or project-local edits to the generated file) is backed up before the next sync replaces the Apothem-managed content.

Compatibility notesCopy Anchor Link

Zed names AGENTS.md its primary instruction file and keeps project .rules as a supported compatibility file (Zed instructions). Because Zed reads only the first match, a new .rules hides an AGENTS.md, a CLAUDE.md, or any other file lower in the list that the project already relies on. The install never edits those files. When .rules holds only the Apothem block and a lower-priority file holds your text, install and update print a warning that names the hidden file; copy the instructions you need into .rules outside the Apothem block to keep them in Zed.

The global ~/.config/zed/AGENTS.md instruction file and the MCP context-server block (.zed/settings.json context_servers) are operator-owned; Apothem does not write them.

Zed loads global skills only from ~/.agents/skills/, in a flat layout with one folder per skill, which is the layout the install writes. Zed gates project-local skills on a trusted worktree, and its documentation ties no such gate to the global folder. One report put a size limit on the skill catalog Zed sends to the model; Apothem has not confirmed it, or whether a skill that turns off model invocation counts toward it. The names and descriptions of Apothem's skills add up to about 20 KB. Apothem has also not confirmed how Zed treats a SKILL.md header key it does not list.

VerificationCopy Anchor Link

apothem verify --harness zed --project /path/to/project

The verify command confirms that:

1. The native config exists at the expected path.
2. Each managed target exists; managed files are non-empty, and JSON or YAML configs parse. Add --profile PATH to also confirm that the installed files match that profile.
3. Every Apothem skill folder is in place with a SKILL.md, whichever install wrote it, and no skill folder with an Apothem name belongs to something Apothem did not write. A failed check names the missing or foreign folders.
4. The adapter-specific verification routine reports success.

UpdatingCopy Anchor Link

apothem update --harness zed --project /path/to/project

Re-derives the project .rules file from the current shared profile state.

The update also rewrites any skill folder whose files differ from the current ones. If you installed with an earlier release that wrote no skills, the update adds them.

UninstallingCopy Anchor Link

apothem uninstall --harness zed --project /path/to/project

Removes Apothem's managed block from the native config file .rules and keeps your own text. The file is deleted only when nothing else remains in it. Before the change, a timestamped copy of the file is saved under ~/.apothem/backups/; no backup file is left in the project. The shared profile YAML and Apothem engine are unaffected.

The uninstall also removes the skill folders it wrote in ~/.agents/skills/ and the rules and templates in ~/.config/apothem/, but only when no other Apothem install still uses them. Another project, or another tool that shares the folder, may. In that case the uninstall keeps the folders, prints which install uses them, and the last uninstall removes them. Files you added to those folders stay, and a folder left empty is removed. Each folder is backed up under ~/.apothem/backups/ before it is removed.

Conformity gateCopy Anchor Link

python -m apothem.conformity.gate --all .

TroubleshootingCopy Anchor Link

Configuration knobsCopy Anchor Link

See alsoCopy Anchor Link

• All harnesses — the full catalog of supported tools
• Install guide — install Apothem into this harness
• apothem harnesses reference — list and inspect adapters from the CLI