ZCode Configuration Guide

ZCode supports five types of extension resources, plus AGENTS.md instruction files. This skill is the map: it tells you where each resource is configured and how conflicts are resolved. For "something is not working, how do I fix it," follow the routing to the diagnosing-* skills at the end.

How things are configured

There are two ways to work with configuration in the ZCode client, and this plugin serves both:

• A person manages resources through the client's graphical interface — Settings → Plugin Management, Settings → Skills, Settings → Subagents, Settings → MCP, and the / menu in the input box.
• An agent repairs configuration by reading and editing the underlying files directly with its file tools. The locations and rules below are what an agent uses to find the right file and field.

Scopes and the main configuration files

• User scope — lives under your home directory and applies to every workspace.
• Workspace scope — lives inside a repository and applies only to that project; can be shared with a team through version control.
• User configuration file: ~/.zcode/cli/config.json. Holds MCP servers, hooks, plugin enable/disable state, and skill/command disable overrides.
• Workspace configuration file: <repo>/.zcode/config.json (or <repo>/zcode.json).
• User instruction file: ~/.zcode/AGENTS.md. Applies as default instructions for every workspace.
• Workspace instruction file: <repo>/AGENTS.md. Applies only to that project; the current workspace path is searched upward until the project root.