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

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.