diagnosing-commands
Use to diagnose and fix ZCode custom slash-command (/command) configuration problems in the ZCode client. Applies when a command is missing, is overridden by a higher-precedence command of the same name, has a frontmatter parse error, is dropped for having an empty body, has an invalid name, does not substitute $ARGUMENTS/$1, uses a colon rather than a slash for nested names, has a misspelled frontmatter key, or disappears because the plugin providing it is disabled. Provides the discovery order, how to inspect commands in the client, common pitfalls, and a step-by-step localization and repair workflow.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 253
- Forks
- 20
01 前言 Front Matter
- name
- diagnosing-commands
- description
- Use to diagnose and fix ZCode custom slash-command (/command) configuration problems in the ZCode client. Applies when a command is missing, is overridden by a higher-precedence command of the same name, has a frontmatter parse error, is dropped for having an empty body, has an invalid name, does not substitute $ARGUMENTS/$1, uses a colon rather than a slash for nested names, has a misspelled frontmatter key, or disappears because the plugin providing it is disabled. Provides the discovery order, how to inspect commands in the client, common pitfalls, and a step-by-step localization and repair workflow.
03 SKILL.md 正文
Diagnosing Command Configuration
Goal: reduce any /command problem to a single concrete fix.
A person inspects commands from the / menu (the Commands group) in the input box; an agent inspects by reading the command files at the locations below.
Two points that are often misunderstood: nested command names join with a colon (
review/code.mdbecomes/review:code, not/review/code); and a command is a.mdfile whose file name is the command name.
1. Discovery order (earlier locations take precedence)
- Explicitly configured roots
- User
~/.zcode/commands - User
~/.agents/commands - Workspace
.zcode/commands(from the current directory up to the repository root; every level counts) - Workspace
.agents/commands - Enabled plugin command roots (lowest precedence)
Within a level, .zcode is scanned before .agents. Subdirectories are scanned recursively, and a nested path joins into the command name with a colon.
2. Deduplication rule (first match wins)
The key is the normalized command name (the relative path with .md removed, separators replaced by :, lowercased). The first occurrence — the highest-precedence location — wins: user overrides workspace, .zcode overrides .agents, and local files override plugins. Duplicates are ignored.
There is also an interactive-surface-only filter: a command whose name matches a built-in slash command (or compress) is filtered out of the live / menu, though it is still present on disk.
3. Command .md format
- The command name comes from the file name and must match
^[a-z0-9][a-z0-9_:-]{0,63}$(lowercase alphanumeric start; no spaces, dots, or leading-/_; at most 64 characters). A violation drops the command. - Frontmatter (a flat parser; indented lines are ignored) recognizes
description,argument-hint,allowed-tools,model,skills, anddisable-noninteractive(all hyphenated). An unknown key is ignored but the command still loads. - A description or a non-empty body is required — otherwise the command is dropped. When
descriptionis absent, the first non-empty body line is used. - Argument substitution:
$ARGUMENTSis the full argument string;$1/$2are positional (out of range is empty). When arguments are supplied but no placeholder is present, they are appended under a "User arguments:" heading. skillsare auto-mounted. Inline dynamic shell (!`cmd`or a fenced!block) is rejected.
4. How to inspect commands
- In the client: type
/in the input box and open the Commands group; you can search by keyword. Each entry shows its name and description. - As an agent: read the
.mdfiles at each location in discovery order. Derive each command's name from its path (subdirectories become:), and remember that for a same-named command the first in discovery order is the one that runs.
5. Common pitfalls (symptom → cause → fix)
- Missing — wrong directory — the
.mdis not under a scanned root (for example a singular.zcode/command/, or above the repository root). → Move it into~/.zcode/commands/or<repo>/.zcode/commands/. - Missing — invalid name — the file exists but no command appears. The file name violates the pattern (uppercase, spaces, dots, leading
-/_, or over 64 characters). → Rename to a valid lowercase name; namespace with subdirectories (which become:), not dots. - Overridden by a higher-precedence duplicate — a different command runs, or your edits have no effect. First match wins. → Find the higher-precedence copy in discovery order and rename or remove it. Local files always beat plugins.
- Frontmatter parse error — a key is silently missing. The flat parser reads only single-line top-level keys; indented lines and multi-line arrays are dropped. → Keep every value on one line; write lists inline, e.g.
allowed-tools: Read, Bash. - Empty command is dropped — both the description and the body are empty. → Add a
description:or at least one non-empty body line. - Unknown frontmatter key (misspelling) —
model/skills/allowed-toolshave no effect. → Use the hyphenated keys:allowed-tools(notallowed_tools),argument-hint,disable-noninteractive. $ARGUMENTS/$1does not substitute — the placeholder appears literally or is empty. The body has no placeholder (arguments are appended under "User arguments:" by design),$1is out of range, or a form like${ARGUMENTS}is not recognized. → Use the exact$ARGUMENTS/$1tokens.- Dynamic shell is rejected — running the command reports an unsupported shell expansion. The body contains
!`...`or a fenced!block. → Remove it; use static text or$ARGUMENTS. - A plugin command is missing — a disabled plugin contributes no command roots, or a local same-named file is shadowing it. → Enable the plugin in Settings → Plugin Management, and ensure no local duplicate shadows it.
- Disabled by configuration — a valid command silently disappears. The configuration disables it by the command file's absolute path (not the command name). → Set that path's
enabletotrueor remove it. /versus:confusion —/review/codereports not found althoughreview/code.mdexists. Subdirectories map to:, so the real name isreview:code. → Invoke/review:code.- Reserved-name collision (interactive only) — the command exists on disk but cannot be triggered in the live
/menu, because its name matches a built-in slash command orcompress. → Rename to a non-reserved name.
6. Localization workflow (in order)
- Is it in the
/menu? Open the Commands group. Absent → step 2. Present but the wrong content runs → step 4 (a duplicate). - Confirm the file and its root. Ensure the
.mdsits directly under a scanned commands root for the current working directory — pitfall 1 — and that its name is valid — pitfall 2. - Check the frontmatter. A missing/garbled key points to the flat-parser rules (pitfall 4) or an empty command (pitfall 5); a key with no effect is likely a misspelling (pitfall 6).
- Resolve a duplicate. For a given name, the winner is the first in discovery order; find and rename or remove the copy you do not want.
- Check the body. Verify the argument placeholders (pitfall 7) and that there is no rejected dynamic shell (pitfall 8).
- Still missing with no obvious cause? Check for a configuration disable (pitfall 10, by absolute file path), a disabled plugin (pitfall 9), or reserved-name filtering (pitfall 12).
04 同仓库更多 Skills
plugin-mcp-ping
E2E workspace Plugin skill marker
zcode-configuration-guide
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.
diagnosing-skills
Use to diagnose and fix ZCode skill configuration problems in the ZCode client. Applies when a skill is not discovered, is installed but does not trigger automatically, is shadowed by a higher-precedence skill of the same name, is disabled by configuration, has a SKILL.md frontmatter error, fails to load because its description is too long, or disappears because the plugin providing it is disabled. Provides the discovery order, how to inspect skills in the client, common pitfalls, and a step-by-step localization and repair workflow.
diagnosing-plugins
Use to diagnose and fix ZCode plugin and marketplace problems in the ZCode client. Applies when a plugin is not listed, adding a marketplace or installing a plugin fails, a plugin is enabled but its skills or commands are missing, a built-in plugin still appears after being disabled, a plugin is not enabled as expected, a plugin.json manifest has a parse error, a plugin name is invalid, a dependency is unresolved or blocked across marketplaces, or a sensitive configuration value cannot be entered in the interface. Provides the plugin lifecycle, manifest schema, how to manage plugins in the client, and a step-by-step localization and repair workflow.
diagnosing-mcp
Use to diagnose and fix ZCode MCP (Model Context Protocol) server configuration problems in the ZCode client. Applies when an MCP server will not connect, its tools (mcp__server__tool) do not appear, it shows as disabled or failed, connections time out, a command cannot be found, template variables are not expanded, or a server defined in a configuration file has no effect. Provides configuration locations, how to inspect status in Settings, common pitfalls, and a step-by-step localization and repair workflow.
diagnosing-hooks
Use to diagnose and fix ZCode hook configuration problems in the ZCode client. Applies when a hook does not trigger, an event name is wrong, a matcher does not match a tool name, a script is not executable, template variables are not expanded, a timeout unit is mistaken (seconds versus milliseconds), the command and process field styles are mixed, a hook's JSON output fails validation, a hook blocks the session unexpectedly, or configuration-file hooks are not enabled. Provides configuration sources, the hooks.json schema, how to inspect hooks in the client, and a step-by-step localization and repair workflow.