Summary
How a CLI coding agent handles slash commands (/name) when invoked non-interactively — Claude Code's -p / print / headless mode. Headless mode is the entry point scripts and wrappers use, while slash commands are the entry point humans use interactively; how a CLI reconciles the two determines whether automation sees a real result or a silent, plausible-looking failure. The documented policy since v2.1.205 (Claude Code docs, 2026) is narrow and explicit: expand what can be expanded, refuse clearly what cannot — not a blanket refusal, and not silence. A confirmed upstream bug report (anthropics/claude-code issue #90515) shows the failure mode when that policy is not upheld: an unresolved command is passed through as ordinary text, the process still exits 0 with is_error: false, and callers see a plausible-looking string where a result should be. The same asymmetry generalises to any tool that guards its interactive entry point but not its scripted one.
Key Points
- Documented policy (Claude Code docs, 2026, v2.1.205+): in
-p/headless mode, user-invoked skills and custom commands do work — include/skill-namein the prompt string and Claude Code expands it before running. The policy is expand what can be expanded, refuse clearly what cannot; it is neither a blanket refusal nor silence. - Terminal-only built-ins are unavailable in
-pmode (e.g./login); they only make sense in the interactive terminal UI. - Argument-style built-ins are supported in headless mode:
/model,/effort,/fast,/color,/renameaccept a value as an argument;/mcpwith no argument prints a text summary of server status;/config key=valuechanges a setting. These forms require v2.1.205 or later. - Confirmed failure mode (anthropics/claude-code issue #90515, plugin slash-commands in
-pon 2.1.251): every plugin command returnedUnknown command: /x:ywith ; the process exited 0 with , so any wrapper checking the exit code saw success and got an error string where a result should be. It was caught only by an unrelated downstream sanity check on output length.