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 is rejected — running the command reports an unsupported shell expansion. The body contains !`...` or a fenced ! block. → Remove it; use static text or $ARGUMENTS.
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.