Configure ZCode resources such as skills, commands, MCP servers, hooks, plugins, and AGENTS.md instructions. Learn where user and workspace settings live, how discovery and merge rules resolve conflicts, and which scope fits each resource.
Use when configuring ZCode's extension resources (MCP servers, slash commands, skills, hooks, and plugins) or instruction files such as AGENTS.md in the ZCode client. Explains where each resource is configured at the user and workspace scope, the discovery order, precedence, and merge rules, plus guidance on which location to choose. Use when someone asks how to add an MCP server, command, skill, hook, plugin, or AGENTS.md instructions, where a configuration file lives, why a configuration is not taking effect, or needs routing to a specific diagnostic skill.
Run score Not tested
See how to installThis guide explains where ZCode stores settings for skills, slash commands, MCP servers, hooks, plugins, and AGENTS.md instruction files. It describes the difference between user settings and workspace settings, where each resource is discovered, and how duplicates or overlapping settings are resolved. You can use it to choose whether a setting should apply across your workspaces or live in a repository for a team to share. When a configuration is not taking effect, the guide points to a relevant diagnostic skill.
Use it when adding a skill or command, setting up an MCP server or hook, or deciding where to keep personal and project-level settings. It also helps when several settings conflict and you need to know which one applies, or when you want to keep secret values out of a repository. The guidance applies to the ZCode client.
AGENTS.md work together?”Workspace settings can automatically connect MCP servers. Open only projects you trust. Keep secrets out of version control; use environment variables or local settings instead.
This overview was written by AI (OpenAI Codex) from the public SKILL.md. Check the original below for the exact behavior.
AI checked the SKILL.md for operations that need care and for setup requirements. The score comes only from actually running the skill (hands-on test).
Not counted in the score. Rated by AI (OpenAI Codex) as of Oct 24, 2026. Treat it as a guide and read the original before installing.
Review the instructions the agent will receive before you install.
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.
There are two ways to work with configuration in the ZCode client, and this plugin serves both:
/ menu in the input box.~/.zcode/cli/config.json. Holds MCP servers, hooks, plugin enable/disable state, and skill/command disable overrides.<repo>/.zcode/config.json (or <repo>/zcode.json).~/.zcode/AGENTS.md. Applies as default instructions for every workspace.<repo>/AGENTS.md. Applies only to that project; the current workspace path is searched upward until the project root.| Resource | Form | User scope | Workspace scope | Conflict rule |
|---|---|---|---|---|
| Skills | Directory + SKILL.md | ~/.zcode/skills/, ~/.agents/skills/ | <repo>/.zcode/skills/, <repo>/.agents/skills/ | Identity is the file path; on load the first same-named skill wins (user scope has priority) |
| Commands | .md file | ~/.zcode/commands/, ~/.agents/commands/ | <repo>/.zcode/commands/, <repo>/.agents/commands/ | Deduplicated by normalized command name; first match wins (user scope overrides workspace), the loser is ignored |
| MCP | JSON object | ~/.zcode/cli/config.json → mcp.servers (fallback ~/.agents/mcp.json → mcpServers) | <repo>/.zcode/config.json → mcp.servers (fallback <repo>/.agents/mcp.json → mcpServers) | User overrides workspace for a same-named server; workspace-scoped servers are trusted and auto-connected by default, same as user-scoped |
| Hooks | hooks.json / config object | ~/.zcode/cli/config.json → hooks | <repo>/.zcode/config.json → hooks | Configuration-file hooks require hooks.enabled: true; plugin hooks are appended |
| Plugins | Directory + plugin.json | Installed from a marketplace; enable/disable state stored in ~/.zcode/cli/config.json | — | A plugin contributes skills, commands, hooks, MCP servers, and agents |
| Instructions | AGENTS.md file | ~/.zcode/AGENTS.md | <repo>/AGENTS.md | User default instructions load first, then workspace instructions load later so the workspace can narrow or override broad defaults |
Note:
.agents/mcp.jsonis a compatibility fallback for MCP. Within each scope the client reads.zcodefirst; only if that scope has no MCP servers does it fall back to.agents/mcp.json(which uses a top-levelmcpServerskey, whereas.zcodeuses nestedmcp.servers).
AGENTS.md is not a skill, command, hook, MCP server, or plugin. It is the instruction file ZCode loads into the model context for broad behavior rules.
~/.zcode/AGENTS.md. Use this for personal defaults that should apply in every workspace, such as preferred language, review style, or local workflow conventions.<repo>/AGENTS.md. Use this for repository-specific rules that should be shared with the project, such as architecture boundaries, logging rules, testing requirements, and commit/MR policy.AGENTS.md from the current working directory upward until the detected project root. The user default file is resolved from the user's home directory.~/.zcode/AGENTS.md first, then the resolved workspace AGENTS.md. Workspace instructions appear later, so they can narrow or override broad user defaults for that repository.~/.claude/CLAUDE.md into ~/.zcode/AGENTS.md. The built-in /init command targets the current workspace AGENTS.md, creating or updating repository instructions instead of editing the user default file.Locations are scanned in this order (earlier locations take precedence):
~/.zcode/skills (or commands)~/.agents/skills.zcode/skills (from the current directory up to the repository root; every level counts).agents/skillsWithin a level, .zcode is scanned before .agents. A deeper working-directory location takes precedence over a repository-root location.
review/code.md becomes /review:code (not /review/code).SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop.hooks.enabled: true to run (disabled by default). When any plugin contributes a hook, the hook runner is enabled automatically..zcode-plugin/plugin.json (the compatibility names .claude-plugin/ and .codex-plugin/ are also recognized). The minimal manifest requires only name (matching ^[a-z0-9][a-z0-9._-]{0,127}$).commands, skills, hooks, mcpServers, agents (each may be a directory name, an array, or inline). The fields channels, lspServers, outputStyles, and settings are recorded but not executed.plugins in ~/.zcode/cli/config.json. A built-in plugin can be disabled but not uninstalled.+ button on the Discover tab) from a GitHub repository, a Git URL, a local directory, or a file.~/.zcode/... or ~/.agents/...).<repo>/.zcode/... or .agents/...).~/.agents/skills/ → put skills there; to override a same-named skill only inside ZCode, use .zcode/skills/.~/.zcode/AGENTS.md; repository-specific instructions → <repo>/AGENTS.md. If both exist, keep broad preferences in the user file and project rules in the workspace file.When a configuration is read but has no effect, or reports an error, load the matching skill. Each provides a symptom → cause → check → fix workflow, covering both what to click in the client and which file and field an agent should edit:
diagnosing-mcpdiagnosing-skills/command is missing, overridden, has a frontmatter error, or arguments do not substitute → diagnosing-commandsdiagnosing-hooksdiagnosing-pluginsNo reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Create a 3D object with three.js, inspect it from every angle in an interactive viewer, and download it as OBJ + MTL or GLB for use in other 3D applications.
Maintain a private task list with deadlines, next steps, waiting parties, and blockers. Update progress and dependencies, merge duplicate items, and archive closed tasks so ongoing commitments stay clear and easy to follow.
Coordinate a task from a verifiable goal through completion. Handle work directly or split independent tasks across separate agent sessions, track progress, verify results, and arrange pull request merging when included in the goal.
Create animated HTML pages with smooth scene transitions and playback controls. An editable timeline lets users adjust scene lengths and speeds, with fixed landscape or portrait layouts prepared for video export.
Review synced Apple Health records, including steps, heart rate, sleep, and workouts. Retrieve daily summaries or detailed samples for a chosen period, and check sync status and missing data before interpreting the results.
Create and edit Word documents and templates, reorganize text, replace images, and work with tracked changes or comments. Apply proper headings and lists, then render every page to check its appearance before delivery.