zai-org/zcode/diagnosing-commands

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.md becomes /review:code, not /review/code); and a command is a .md file whose file name is the command name.

1. Discovery order (earlier locations take precedence)

1. Explicitly configured roots
2. User ~/.zcode/commands
3. User ~/.agents/commands
4. Workspace .zcode/commands (from the current directory up to the repository root; every level counts)
5. Workspace .agents/commands
6. 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, and disable-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 description is absent, the first non-empty body line is used.
• Argument substitution: $ARGUMENTS is the full argument string; $1/$2 are positional (out of range is empty). When arguments are supplied but no placeholder is present, they are appended under a "User arguments:" heading.
• skills are 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 .md files 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)

1. Missing — wrong directory — the .md is 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/.
2. 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.
3. 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.
4. 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.
5. Empty command is dropped — both the description and the body are empty. → Add a description: or at least one non-empty body line.
6. Unknown frontmatter key (misspelling) — model/skills/allowed-tools have no effect. → Use the hyphenated keys: allowed-tools (not allowed_tools), argument-hint, disable-noninteractive.
7. `$ARGUMENTS`/`$1` does not substitute — the placeholder appears literally or is empty. The body has no placeholder (arguments are appended under "User arguments:" by design), $1 is out of range, or a form like ${ARGUMENTS} is not recognized. → Use the exact $ARGUMENTS/$1 tokens.
8. Dynamic shell does not run on its own — a ` !... or fenced ! block is not executed when the command is invoked, and its output is not pasted in beforehand. ZCode rewrites each block into an instruction for the model to run that command with the Bash tool, so it appears as a normal tool call with the usual approval prompt (and plan mode can deny it). → Expect that tool call; if the command must not depend on shell output, use static text or $ARGUMENTS` instead.
9. 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.
10. 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 enable to true or remove it.
11. `/` versus `:` confusion — /review/code reports not found although review/code.md exists. Subdirectories map to :, so the real name is review:code. → Invoke /review:code.
12. 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 or compress. → Rename to a non-reserved name.

6. Localization workflow (in order)

1. Is it in the `/` menu? Open the Commands group. Absent → step 2. Present but the wrong content runs → step 4 (a duplicate).
2. Confirm the file and its root. Ensure the .md sits directly under a scanned commands root for the current working directory — pitfall 1 — and that its name is valid — pitfall 2.
3. 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).
4. 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.
5. Check the body. Verify the argument placeholders (pitfall 7) and whether a dynamic shell block is handed to the model as a tool call (pitfall 8).
6. 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).