Host support: Zed Agent — instructions, flat skill packages, and direct MCP configuration

[ScriptedAlchemy]

Scope / research evidence

P2 feature expansion. Research date 2026-09-06; Agent Bundle baseline 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5. Official Zed documentation read; no editor or native invocation was run. This issue targets the Zed Agent. External agents over ACP and terminal threads use their own harness contracts and must not inherit Zed-native skill/rule support by assumption.

Primary specifications and configuration links

• Instructions and exact compatibility-file precedence
• Skill format, discovery, trust, activation and limits
• MCP configuration, features, authorization and tool permissions
• MCP server extension API and planned deprecation
• External-agent/ACP boundary
• Official host source
• Agent Skills format
• AGENTS.md convention

Use the new Instructions page rather than the obsolete /ai/rules link. Pin an actual Zed version and native implementation revision before advertising conformance; current documentation is not an immutable compatibility version.

Integration model

Zed already consumes instruction files and local skill packages and can launch a normal MCP executable. None of these requires a bespoke Zed runtime. Its MCP-extension mechanism uses extension.toml and a Rust context_server_command implementation, but the official page now plans its deprecation in favor of the MCP registry. Do not make that extension format the prerequisite for Agent Bundle support.

The requested initial adapter should generate content and an explicit installation/configuration binding for the canonical MCP executable. It should not create a Rust/Wasm editor extension merely to launch a Node server or read Markdown. Registry publication, if desired later, is a separate operator action and not an automatic side effect of build.

Instructions and composite precedence

Personal instructions are ~/.config/zed/AGENTS.md (Windows uses the native Zed configuration directory). Project discovery takes the first matching compatible file: .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, then CLAUDE.md and GEMINI.md.

This makes negative discovery essential: an existing Copilot instructions file in a composite can shadow the AGENTS.md intended for Zed without any filename collision. Do not emit an extra high-precedence .rules to defeat the user's existing instructions silently. Preserve authored content and make effective selection visible or reject an incompatible scoped combination.

Skills and proposed installed layout

project/
  AGENTS.md                         # only if explicitly owned/authored
  .agents/skills/review/SKILL.md
  .agents/skills/review/references/guide.md
installed-plugin/
  mcp/example.mjs                   # only for a declared MCP server

Skills are immediate children of project .agents/skills/ or global ~/.agents/skills/, not arbitrarily nested collections. The project copy wins duplicate names; untrusted worktrees are excluded. disable-model-invocation: true keeps manual activation without autonomous catalog exposure. Validate native name/description constraints and report the documented catalog budget rather than silently promising every skill is active.

The native Skill Manager can create/import skills and supports explicit user review. File changes reload; there is no runtime remote-registry lookup or configurable extra search root. A copy or supported symlink must therefore be tracked as an installation binding rather than assuming that composite-root/skills/ is discovered anywhere it sits.

MCP setup

Settings → AI → MCP Servers → Add Local Server is the documented native path. Equivalent selected-profile settings:

{
  "context_servers": {
    "example": {
      "command": "node",
      "args": ["/absolute/installed-plugin/mcp/example.mjs"],
      "env": {}
    }
  }
}

Remote servers use url and optional headers/native OAuth; do not embed secrets in generated artifacts. Native tool permissions use their own mcp:<server>:<tool> keys. A plugin install must not set a global auto-allow policy. Current MCP docs specifically promise tools/prompts and tool-list change handling; do not infer resources, sampling, elicitation or MCP Apps support without independent evidence.

The example is an operator configuration patch, not a file auto-discovered inside every plugin root. Merge only owned entries and preserve disabled servers, unrelated tools and native credentials. External agents may receive forwarded MCP through ACP, while terminal CLIs read their own config; list those as separate tested profiles.

Acceptance

• Pin the native instruction/skill/MCP contracts and supported Zed version.
• A static-only package installs and is inspectable with no MCP/Flight/state process.
• Test flat skill discovery, project/global precedence, manual-only activation, trust, name validation and catalog-overflow reporting.
• Test first-match instruction precedence against actual composite files, including a foreign Copilot file shadowing AGENTS.md.
• A declared MCP tool completes from a relocated source-free artifact with canonical schema/result/error/cancellation behavior and native authorization intact.
• List-change refresh and namespace collisions preserve operation identity.
• An unsupported MCP feature or external-agent-only capability is not advertised as Zed-native support.
• Update/uninstall affects only receipt-owned skill links/files and configuration entries; preserve user instructions, disabled state and durable data.
• Record real Zed Agent success separately from a running MCP status indicator or parser-only tests.
• Add Composite conformance: test cross-host auto-discovery and precedence, not only file collisions #651/Small-plugin acceptance: skills and plain hooks without an unnecessary MCP/RSC runtime or empty Workbench #652 composite/small-plugin coverage and English/Chinese configuration documentation.

Reuse existing content lowering, manifest/executable/launch records and receipt ownership. No new ACP agent implementation, Rust extension requirement, credential manager, permission bypass, global instruction replacement, or broad removal of AB4106.

[ScriptedAlchemy]

Resolved by #723 (4dc11a4a06).

Zed Agent — observed zed.dev/docs retrieved 2026-09-06; no page publishes a version or last-updated date. Supported at the skills tier: the emitted skill tree loads; the manifest does not.

Surface	State	Evidence
manifest	unavailable	2026-09-06: no Zed page documents a plugin manifest of any shape for the Zed Agent; skills are installed as folders and MCP servers are configured in Zed's settings, so the emitted plugin.json has no reader.
skills	degraded	2026-09-06: only the skill folders load, one copy at a time, and the catalog is capped — "50KB catalog budget… Skills that don't fit are dropped from the catalog with a warning in the UI" — so a large emitted skill set is not guaranteed to be wholly visible.
mcp	unavailable	2026-09-06: https://zed.dev/docs/ai/mcp configures servers under the context_servers key of Zed's own settings file, and no page documents auto-discovery of a project-local or plugin-root MCP file, so the emitted mcp.json has no reader.
placeholders	unavailable	2026-09-06: with no emitted MCP document read, none of the reserved ${PLUGIN_ROOT} or ${PLUGIN_DATA} placeholders of Agent Plugins 1.0.0 §9.1 is expanded.
hooks	unavailable	2026-09-06: none of the retrieved Zed Agent pages documents a lifecycle or hook mechanism, and Agent Plugins 1.0.0 defines no hooks, so this projection emits no hooks document either.

Paths it reads: skills.
Install: cp -R skills/<skill> ~/.agents/skills/<skill>.

Every row above is pinned to that client's own documentation on the date shown, is validated on every build, and renders in INSTALL.md and the generated hosts reference. A surface recorded unavailable or degraded names exactly what the client would need; no unsupported feature is projected silently.