The third time you paste the same review instructions into a chat, you are designing an interface by repetition. The instructions have inputs, an intended output, and assumptions about the project. A slash command makes those assumptions visible enough to name, edit, and reuse.
The community Commands plugin by Alessandro Frau (3clyp50) implements that idea with a small file format: one YAML definition and one text template or Python hook. The more interesting story, in the Agent Zero checkout reviewed here, is that a built-in _commands plugin now carries the workflow forward. Understanding the migration matters more than installing a second slash picker. Community Commands Built-in Commands implementation
Research basis: We reviewed community Commands 0.5.0 at
6958c0e3628dand built-in_commandsat Agent Zeroff2a5b9c9c4e. The Hub snapshot still lists the community plugin. Its framework regression run produced 14 passed and 2 failed, discussed below. This article treats the community release and the current built-in implementation as distinct versions.
The short version
- A command is a small interface. Its name, inputs and promised output should make repeated work easier to inspect.
- Scope chooses the winning definition. A project override can change the meaning of a familiar global command.
- A Python hook executes code. Its side effects are separate from the prompt text it returns.
For the built-in successor at the reviewed core revision:
| Precedence | Definition |
|---|---|
| 1 | Project override |
| 2 | Global override |
| 3 | Bundled default |
| 4 | Other plugin-distributed command |
A command has a contract
A text command separates configuration from content. The YAML names the command, describes it, supplies an argument hint, declares type: text, and points to its template. The template can reference the parsed arguments. This gives the command a discoverable name without hiding its actual instructions. File model and examples
For example, a project-specific review command could ask for the concrete problem, the relevant paths, the smallest proposed change, and the evidence required to accept it. Its output should be a review, rather than an implicit instruction to make changes. The difference belongs in the template itself.
The parser supports positional arguments, quoted strings, long flags, equals-style flags, and short flag bundles. Templates can access fields such as args.positional.0 and args.flags.git_url. These are structured inputs to a template; they are not an automatically validated business schema. Parser and renderer
A good command therefore does three things in plain language: states the task, defines the inputs it expects, and describes what the agent should return or do. A memorable name is useful only after that contract is clear.
Scope makes the same name useful in different projects
Community Commands resolves project commands before global commands and also discovers definitions supplied by plugins. The project can tailor a familiar command to its own repository without changing the global copy. Scope resolution
The built-in successor defines a fuller order: project overrides global, global overrides the bundled defaults, and bundled defaults override commands distributed by other plugins under the same name. Its manager treats bundled and plugin-distributed commands as read-only; editing a bundled command creates a higher-precedence copy. Built-in discovery and persistence
That is a practical form of configuration inheritance. A global /review can provide general editorial discipline. The version in a particular project can add its testing command and important architectural constraints. The operator should be able to inspect which definition wins, because identical names do not imply identical behavior.
Scope also has a maintenance cost. A project override can continue masking an improved bundled definition. Keep the override narrow, and revisit it when the underlying command changes. That recommendation follows from the precedence mechanism; the plugin does not automatically reconcile the meaning of two templates.
Why the built-in migration changes installation advice
This checkout includes a startup migration that copies legacy community command and skill files into the _commands namespace without overwriting existing files. It also disables legacy command plugin roots to avoid duplicate interface elements. Migration source
The important first step is therefore to inspect the installed Agent Zero version and its Plugins list. If _commands is already present, use its manager and verify the migrated commands before adding the community release. The community repository remains valuable as the source of the earlier design, but Hub availability alone does not establish that every checkout needs a separate installation.
Do not move command files by guesswork between namespaces. The reviewed community paths use usr/plugins/commands/commands/; the built-in paths use usr/plugins/_commands/commands/, with corresponding project-scoped locations. Back up custom definitions before investigating a migration. Community storage paths Built-in migration and scope rules
A Python command is executable code
A script hook exposes run(payload). Its payload contains parsed arguments and context information; optional history is included when configured. It can return replacement text and frontend effects such as replacing or appending composer input and showing a notification. Script contract
The implementation loads the Python file with runpy.run_path. That is execution inside the framework process, not a harmless macro expansion. The script can also receive the active agent through its context payload. An installed command definition is therefore code that deserves review, especially when supplied by another person. Script execution
There are two separate questions to ask. What does the hook execute while constructing the command? What does the resulting prompt ask the agent to execute afterward? A safe-looking rendered prompt does not prove the hook had no side effects. Conversely, a simple text template can still request a consequential action. Choose the simpler text form when substitution is all you need.
The built-in implementation supports additional effects, including immediate message submission. Avoid assuming that every command pauses as editable text in the composer. Inspect the effect contract of the version you actually run. Built-in command effects
The small parser edge case worth knowing
Our community test run found that the input ending in -v 30% assigned the string 30% to the short flag v, while its test expected a boolean True. That is a specific ambiguity between a short flag with a value and a boolean flag followed by a positional argument. It is not evidence that all parsing fails. Parser regression test
When a command has an important input, prefer an explicit named flag with an equals value, such as --depth=brief, and verify the parsed result. Treat the command's argument hint as part of its usability, not decoration. A command that only works when its author remembers the parsing edge cases is not yet a good interface.
The other failed assertion expected the authoring skill to come from the community plugin directory. In this checkout, discovery returned the built-in _commands copy instead. That result is consistent with the version transition and should not be reported as “skill discovery is broken.” The skill was found; its owning path differed.
A useful command library stays small
Start with one repeated workflow. Make its expected output concrete. Try it with a normal input, a missing input, a quoted argument, and a value containing punctuation. Check the winning scope and inspect the rendered text before relying on it.
A command should reduce the amount of context the operator must remember while preserving the context the agent needs. Ten nearly identical commands can make selection harder than pasting a prompt. A few commands with clear contracts, sensible scope, and transparent implementation can become a stable working vocabulary.
The lasting contribution of Commands is that vocabulary layer: a way to turn recurring work into a file-backed interface that both a person and the agent can inspect.
Sources
Commands 0.5.0, Alessandro Frau /
3clyp50, reviewed at6958c0e3628d.Built-in
_commandscontract and implementation, coreff2a5b9c9c4e.All motion illustrations are original and derived from the reviewed sources. Illustrative data is labeled.