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)
- 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, 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)
- 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/.
- 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-tools have no effect. → Use the hyphenated keys: allowed-tools (not allowed_tools), argument-hint, disable-noninteractive.
$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.
- 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
enable to true or remove it.
/ 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.
- 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)
- 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
.md sits 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).
1---2name: diagnosing-commands3description: 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.4metadata:5 source: https://skillmd.com/skills/tomjiu/diagnosing-commands6---78# Diagnosing Command Configuration910Goal: reduce any `/command` problem to a single concrete fix.1112A 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.1314> 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**.1516## 1. Discovery order (earlier locations take precedence)17181. Explicitly configured roots192. User `~/.zcode/commands`203. User `~/.agents/commands`214. Workspace `.zcode/commands` (from the current directory up to the repository root; every level counts)225. Workspace `.agents/commands`236. Enabled **plugin** command roots (lowest precedence)2425Within a level, `.zcode` is scanned before `.agents`. Subdirectories are scanned recursively, and a nested path joins into the command name with a colon.2627## 2. Deduplication rule (first match wins)2829The 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.3031There 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.3233## 3. Command .md format3435- 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.36- 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.37- **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.38- 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.39- `skills` are auto-mounted. Inline dynamic shell (`` !`cmd` `` or a fenced `!` block) is rejected.4041## 4. How to inspect commands4243- **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.44- **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.4546## 5. Common pitfalls (symptom → cause → fix)47481. **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/`.492. **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.503. **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.514. **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`.525. **Empty command is dropped** — both the description and the body are empty. → Add a `description:` or at least one non-empty body line.536. **Unknown frontmatter key (misspelling)** — `model`/`skills`/`allowed-tools` have no effect. → Use the hyphenated keys: `allowed-tools` (not `allowed_tools`), `argument-hint`, `disable-noninteractive`.547. **`$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.558. **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`.569. **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.5710. **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.5811. **`/` 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`.5912. **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.6061## 6. Localization workflow (in order)62631. **Is it in the `/` menu?** Open the Commands group. Absent → step 2. Present but the wrong content runs → step 4 (a duplicate).642. **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.653. **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).664. **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.675. **Check the body.** Verify the argument placeholders (pitfall 7) and that there is no rejected dynamic shell (pitfall 8).686. **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).