/operate-zed-agent

name: operate-zed-agent
description: Configure and troubleshoot Zed Agent, ACP External Agents, and Terminal Threads. Use for Zed Skills, MCP, profiles, permissions, registry installs, custom agents, and ACP logs.
metadata:
  hermes:
    category: agent-portability
    tags: [zed, acp, external-agents, agent-skills, mcp]

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.