| 1 | --- |
| 2 | name: commands-create-slash-command |
| 3 | description: Create or update Agent Zero slash commands for the built-in Commands plugin. Use when the user asks to add, edit, duplicate, or refine a reusable /command backed by YAML config plus text/python content files. |
| 4 | version: 1.0.0 |
| 5 | tags: ["commands", "slash-commands", "plugin", "yaml", "python", "templates"] |
| 6 | triggers: |
| 7 | - create slash command |
| 8 | - add slash command |
| 9 | - update slash command |
| 10 | - edit slash command |
| 11 | - commands plugin |
| 12 | --- |
| 13 | |
| 14 | # Commands Plugin Slash Command Authoring |
| 15 | |
| 16 | Use this skill when the user wants a reusable `/command` for Agent Zero's built-in `_commands` plugin. |
| 17 | |
| 18 | ## Source Of Truth |
| 19 | |
| 20 | - Slash commands are file-backed, not database rows. |
| 21 | - Each command uses: |
| 22 | - one config file: `<slug>.command.yaml` |
| 23 | - one content file: |
| 24 | - text template: `<slug>.txt`, or |
| 25 | - python hook: `<slug>.py` |
| 26 | - Required config keys: |
| 27 | - `name` |
| 28 | - `description` |
| 29 | - `type` (`text` or `script`) |
| 30 | - Optional config keys: |
| 31 | - `argument_hint` |
| 32 | - `include_history` (script commands) |
| 33 | - Preserve unknown config keys when editing existing commands. |
| 34 | |
| 35 | ## Scope Resolution |
| 36 | |
| 37 | Choose the target folder from the requested scope: |
| 38 | |
| 39 | - Project: `usr/projects/<project>/.a0proj/plugins/_commands/commands/` |
| 40 | - Global fallback: `usr/plugins/_commands/commands/` |
| 41 | |
| 42 | If the user does not specify a scope, prefer the active chat scope when it is clear. Otherwise use the global scope. |
| 43 | |
| 44 | ## File Rules |
| 45 | |
| 46 | - Config file format: `<slug>.command.yaml` |
| 47 | - Slash command name should be lowercase and hyphenated, for example `explain-code` |
| 48 | - For text commands, keep the `.txt` template concise and directly reusable |
| 49 | - For script commands, implement `run(payload)` in the `.py` file |
| 50 | - If the command expects trailing input, use `{raw}`, `{args.positional.0}`, or `{args.flags.some_flag}` |
| 51 | |
| 52 | Use the bundled templates in `template.command.yaml` and `template.command.txt` when creating a new text command from scratch. |
| 53 | |
| 54 | ## Editing Workflow |
| 55 | |
| 56 | 1. Determine scope and final slash command name. |
| 57 | 2. Check whether a command file already exists in that scope. |
| 58 | 3. If it exists, load the file first and preserve unknown frontmatter keys. |
| 59 | 4. Update YAML config and template/script content. |
| 60 | 5. Save the file in the correct scope folder. |
| 61 | 6. Report: |
| 62 | - the saved config path |
| 63 | - the saved content path |
| 64 | - the slash command name in `/name` form |
| 65 | |
| 66 | ## Output Contract |
| 67 | |
| 68 | After saving, explicitly state the final file path and the exact slash command invocation, for example: |
| 69 | |
| 70 | - `Saved config: /a0/usr/plugins/_commands/commands/explain-code.command.yaml` |
| 71 | - `Saved content: /a0/usr/plugins/_commands/commands/explain-code.txt` |
| 72 | - `Invoke with: /explain-code` |