Zed native reference
Start with the Zed setup.
Native mappings
Rules
Zed 1.4.2 retired its rules library. Sync writes the instructions that point to source specs, plus a marked ## Rules block, to .rules.
Zed reads the first matching file in this order:
.rules.cursorrules.windsurfrules.clinerules.github/copilot-instructions.mdAGENT.mdAGENTS.mdCLAUDE.mdGEMINI.md
- Nothing agnostic-ai writes ranks above
.rules. AGENTS.mdranks below Copilot's file that only points to source specs. With copilot enabled, rules inAGENTS.mdnever reach Zed.- Zed calls
AGENTS.mdprimary and.rulesa compatibility file. If Zed drops.rules, the rules move back toAGENTS.md. - For older Zed,
outputs.zed.rules-file: .rulesreplaces the pointer instructions with the legacy single document, agent bodies included.
Skills
Zed skills. Identical files are written once. Sync reports x-zed overrides that make two copies differ.
disable-model-invocation: trueis written toSKILL.md. Zed hides the skill from the agent's catalog, and it still runs as a slash command or @-mention (docs).- Commands become skills you run by name (tools without commands).
- When another target also writes the skills folder, files must match. The field is dropped with a note and commands are skipped.
- An
x-zed.disable-model-invocationvalue wins. - A separate
outputs.zed.skills-dirkeeps output apart during sync but adds no native search path. Zed loads skills only as direct children of~/.agents/skills/or<worktree>/.agents/skills/. - To use another backing folder, link it from a documented root. Sync does not create the link.
- Names are 1-64 lowercase letters or digits, with single hyphens between segments.
Deploy,my_skill, andmy--skillfail sync with the format. Sync does not rename them.
Agents
Zed has no per-agent support. Sync reports this unless outputs.zed.rules-file is set (the single document includes agent sections).
MCP
Servers go under context_servers, not mcpServers. Stdio uses flat command/args/env. Remote (HTTP or SSE) uses url/headers. Your other keys (theme, buffer_font_size) stay.
disabled: truebecomesenabled: false. Enabled servers get no key, because Zed defaults to true. Seedisabledsupport by target.- Set these through
x-zed; no other tool has them:timeout: both transports, seconds per tool call, default 60.oauth: HTTP.remote: stdio and extension servers.
Source for the MCP keys
Zed's MCP docs do not name the enabled toggle. Zed's settings source, crates/settings_content/src/project.rs, defines it, plus timeout, oauth, and remote.
Hooks
With outputs.zed.tasks-file set, hooks become Zed Tasks that run sh -c "<hook command>".
WorktreeCreatewriteshooks: ["create_worktree"], so the task runs after Zed creates a linked worktree. Import restores it.- Since Zed 1.28.1, that task is skipped in restricted mode. Trust the project first.
- Other tasks import as
OnDemand(command palette). - Sync controls
label,command,args, andhooks. Addingcreate_worktreekeeps other hook names. x-zedsets other fields:cwd,env,shell,reveal,hide,save,allow_concurrent_runs,use_new_terminal,tags,reevaluate_context.
Config keys
| Key | Default | Notes |
|---|---|---|
outputs.zed.skills-dir | .agents/skills | |
outputs.zed.agents | unset (agents are dropped) | skill writes each agent as an on-demand skill. Sync keeps it off with a note while another tool with subagents writes the same skills folder; see agents as skills |
outputs.zed.mcp-file | .zed/settings.json | |
outputs.zed.tasks-file | empty | opt-in |
outputs.zed.rules-file | unset | writes the legacy single document and skips the pointer instructions, so pointing it at .rules replaces the pointer file instead of clashing with it |
Global instructions
agnostic-ai sync --global --only zed writes home instructions and rules to Zed's personal instruction file. Each platform's path is in the global output table. Skills still use ~/.agents/skills/.
| Platform | File |
|---|---|
| macOS | ~/.config/zed/AGENTS.md (ignores XDG_CONFIG_HOME) |
| Linux and FreeBSD | $FLATPAK_XDG_CONFIG_HOME/zed/AGENTS.md when set, else $XDG_CONFIG_HOME/zed/AGENTS.md, else ~/.config/zed/AGENTS.md |
| Windows | %APPDATA%\Zed\AGENTS.md |
These roots follow Zed's native path selection. An empty or relative Flatpak root is rejected, so nothing is written under the working directory.
After a path correction:
- The first sync clears the managed block from the old XDG file, only when the ledger records it.
- Personal text and private permissions remain. A link to the active file is kept.
- Old files the ledger has not recorded stay unchanged.
explain --global rules/<name>.mdshows the current native file.- Global instruction import is not supported. Project
import zedkeeps its paths below.
Import
agnostic-ai import zed reads:
.rules..zed/tasks.json, as hook specs.- MCP servers from
.zed/settings.json. .agents/skills/<name>/SKILL.md, copied with all bundled files.
For MCP servers:
enabled: falseimports asdisabled: true.timeout,oauth, andremotemove underx-zed.- Removing a server from
.zed/settings.jsondrops it on the next import. - A server whose
oauthholds a client secret is left out with a warning, so no secret reaches a spec.