commands-create-slash-command

name	commands-create-slash-command
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.
version	1.0.0
tags	["commands","slash-commands","plugin","yaml","python","templates"]
triggers	["create slash command","add slash command","update slash command","edit slash command","commands plugin"]

Commands Plugin Slash Command Authoring

Use this skill when the user wants a reusable /command for Agent Zero's built-in _commands plugin.

Source Of Truth

• Slash commands are file-backed, not database rows.
• Each command uses:
  • one config file: <slug>.command.yaml
  • one content file:
    • text template: <slug>.txt, or
    • python hook: <slug>.py
• Required config keys:
  • name
  • description
  • type (text or script)
• Optional config keys:
  • argument_hint
  • include_history (script commands)
• Preserve unknown config keys when editing existing commands.

Scope Resolution

Choose the target folder from the requested scope:

• Project: usr/projects/<project>/.a0proj/plugins/_commands/commands/
• Global fallback: usr/plugins/_commands/commands/

If the user does not specify a scope, prefer the active chat scope when it is clear. Otherwise use the global scope.

File Rules

• Config file format: <slug>.command.yaml
• Slash command name should be lowercase and hyphenated, for example explain-code
• For text commands, keep the .txt template concise and directly reusable
• For script commands, implement run(payload) in the .py file
• If the command expects trailing input, use {raw}, {args.positional.0}, or {args.flags.some_flag}

Use the bundled templates in template.command.yaml and template.command.txt when creating a new text command from scratch.

Editing Workflow

1. Determine scope and final slash command name.
2. Check whether a command file already exists in that scope.
3. If it exists, load the file first and preserve unknown frontmatter keys.
4. Update YAML config and template/script content.
5. Save the file in the correct scope folder.
6. Report:
   • the saved config path
   • the saved content path
   • the slash command name in /name form

Output Contract

After saving, explicitly state the final file path and the exact slash command invocation, for example:

• Saved config: /a0/usr/plugins/_commands/commands/explain-code.command.yaml
• Saved content: /a0/usr/plugins/_commands/commands/explain-code.txt
• Invoke with: /explain-code