Operate Zed Agent

Operate Zed Agent

Choose the Zed agent path before editing settings. Read references/zed-surface-map.md when the request crosses native and external agent configuration.

Choose the Agent Path

• Use Zed Agent when Zed should own the model, provider, tools, profiles, permissions, instructions, skills, and MCP configuration.
• Use an External Agent when an ACP agent such as Codex, Claude, OpenCode, or Hermes should own its runtime, model, authentication, native skills, and persistent state while Zed owns the editor UI.
• Use a Terminal Thread when the original CLI or TUI behavior matters more than ACP-native diffs, approvals, or session rendering.

Do not apply Zed Agent Skills or profiles to an External Agent by assumption. The external agent keeps its own configuration unless its ACP implementation explicitly accepts a forwarded capability.

Configure Zed Agent

1. Confirm the worktree is trusted before expecting project-local skills.
2. Use Zed's Skills Manager to create or import a skill when interactive management is appropriate. A GitHub URL import is an installation copy, not a remote runtime dependency.
3. Keep manually managed skills as direct children of global ~/.agents/skills/ or project .agents/skills/; Zed does not discover nested or arbitrary search roots.
4. Keep names and descriptions concise because Zed has a catalog budget.
5. Use /skill or @skill for explicit invocation. Use disable-model-invocation only when the skill must never be selected implicitly.
6. Treat zed://skill links as sharing/import affordances, not proof of a centrally hosted runtime registry.
7. Use Zed Instructions for always-on guidance, Agent Profiles for tool selection, Tool Permissions for approval policy, and Zed MCP configuration for external tools.
8. Expect installed skill changes to reload without restarting, then verify the catalog entry and one harmless invocation.

Configure an External Agent

1. Check the live canonical ACP Registry instead of trusting a product page or an agent's source manifest.
2. Prefer the registry only when the requested agent is actually present.
3. Otherwise add a custom agent_servers entry using the agent's official executable and arguments. Do not substitute an unreviewed third-party launcher merely to make a registry row appear.
4. Configure provider credentials and native agent state in the external agent unless its integration documents another owner.
5. Start a new thread and verify the agent identity, working directory, model, skills, MCP tools, and approval behavior.
6. Use dev: open acp logs to inspect Zed-to-agent protocol traffic.

For Hermes, use operate-acp-agent-integration to check the canonical registry and validate hermes acp --check before adding a custom entry. The manual command is hermes with args: ["acp"]; prefer an accepted official registry entry if one becomes available later.

On the locally verified 2026-08-10 setup, Hermes 0.20.0 passed hermes acp --check and Zed used a custom agent_servers.hermes-agent entry with command hermes and argument acp. Keep that as dated local evidence; the canonical registry remains the publication authority.

Guards

• Do not install or update Zed, an external agent, a skill, or an MCP server without user intent.
• Do not claim a registry entry exists because a source repository contains an agent.json; verify the published registry feed.
• Do not expose secrets in Zed settings when the agent supports its own secure authentication flow.
• Do not automate visible Zed interaction without approval when a settings or thread check requires the app UI.

Report

Report the selected path, Zed version when relevant, configuration owner, authentication owner, skill and MCP sources, registry or custom launch path, runtime evidence, and remaining editor-side checks.