name	Command Define
description	Validates and registers command manifest files (YAML) to integrate new slash commands into Betty.

command.define Skill

Validates and registers command manifest files (YAML) to integrate new slash commands into Betty.

Purpose

The command.define skill acts as the "compiler" for Betty Commands. It ensures a command manifest meets all schema requirements and then updates the Command Registry (/registry/commands.json) with the new command.

This skill is part of Betty's Layer 1 (Commands) infrastructure, enabling developers to create user-facing slash commands that delegate to agents, workflows, or skills.

Usage

python skills/command.define/command_define.py <path_to_command.yaml>

Arguments

Argument	Type	Required	Description
manifest_path	string	Yes	Path to the command manifest YAML to validate and register

Behavior

Schema Validation – Checks that required fields (name, version, description, execution) are present and correctly formatted (e.g., name must start with /).
Parameter Verification – Verifies each parameter in the manifest has name, type, and description, and that the execution target (agent/skill/workflow) actually exists in the system.
Registry Update – On success, adds the command entry to /registry/commands.json with status active.

Validation Rules

Required Fields

name: Command name (must start with /, e.g., /api-design)
version: Semantic version (e.g., 0.1.0)
description: Human-readable description of what the command does
execution: Object specifying how to execute the command

Execution Configuration

The execution field must contain:

type: One of skill, agent, or workflow
target: Name of the skill/agent/workflow to invoke
- For skills: Must exist in /registry/skills.json
- For agents: Must exist in /registry/agents.json
- For workflows: File must exist at /workflows/{target}.yaml

Optional Fields

parameters: Array of parameter objects, each with:
- name (required): Parameter name
- type (required): Parameter type (string, number, boolean, etc.)
- required (optional): Whether parameter is required
- description (optional): Parameter description
- default (optional): Default value
status: Command status (draft or active, defaults to draft)
tags: Array of tags for categorization

Outputs

Success Response

{
  "ok": true,
  "status": "registered",
  "errors": [],
  "path": "commands/hello.yaml",
  "details": {
    "valid": true,
    "status": "registered",
    "registry_updated": true,
    "manifest": {
      "name": "/hello",
      "version": "0.1.0",
      "description": "Prints Hello World",
      "execution": {
        "type": "skill",
        "target": "test.hello"
      }
    }
  }
}

Failure Response

{
  "ok": false,
  "status": "failed",
  "errors": [
    "Skill 'test.hello' not found in skill registry"
  ],
  "path": "commands/hello.yaml",
  "details": {
    "valid": false,
    "errors": [
      "Skill 'test.hello' not found in skill registry"
    ],
    "path": "commands/hello.yaml"
  }
}

Example

Valid Command Manifest

# commands/api-design.yaml
name: /api-design
version: 0.1.0
description: "Design a new API following enterprise guidelines"

parameters:
  - name: service_name
    type: string
    required: true
    description: "Name of the service/API"

  - name: spec_type
    type: string
    required: false
    default: openapi
    description: "Type of API specification (openapi or asyncapi)"

execution:
  type: agent
  target: api.designer

status: active
tags: [api, design, enterprise]

Running the Validator

$ python skills/command.define/command_define.py commands/api-design.yaml
{
  "ok": true,
  "status": "registered",
  "errors": [],
  "path": "commands/api-design.yaml",
  "details": {
    "valid": true,
    "status": "registered",
    "registry_updated": true
  }
}

Invalid Command Example

If the target agent doesn't exist:

$ python skills/command.define/command_define.py commands/hello.yaml
{
  "ok": false,
  "status": "failed",
  "errors": [
    "Agent 'api.designer' not found in agent registry"
  ],
  "path": "commands/hello.yaml"
}

Integration

With Workflows

Commands can be validated as part of a workflow:

# workflows/register_command.yaml
steps:
  - skill: command.define
    args:
      - "commands/my-command.yaml"
    required: true

With Hooks

Validate commands automatically when they're edited:

# Create a hook that validates command manifests on save
python skills/hook.define/hook_define.py \
  --event on_file_save \
  --pattern "commands/**/*.yaml" \
  --command "python skills/command.define/command_define.py" \
  --blocking true

Common Errors

Error	Cause	Solution
"Missing required fields: name"	Command manifest missing `name` field	Add `name` field with value starting with `/`
"Invalid name: Command name must start with /"	Name doesn't start with `/`	Update name to start with `/` (e.g., `/api-design`)
"Skill 'X' not found in skill registry"	Referenced skill doesn't exist	Register the skill first using `skill.define` or fix the target name
"Agent 'X' not found in agent registry"	Referenced agent doesn't exist	Register the agent first using `agent.define` or fix the target name
"Workflow file not found"	Referenced workflow file doesn't exist	Create the workflow file at `/workflows/{target}.yaml`
"execution.type is required"	Missing execution type	Add `execution.type` field with value `skill`, `agent`, or `workflow`

Exit Codes

0: Success (manifest valid and registered)
1: Failure (validation errors or registry update failed)

Files Modified

Registry: /registry/commands.json – updated with new or modified command entry
Logs: Command validation and registration logged to Betty's logging system

Dependencies

Skill Registry (/registry/skills.json) – for validating skill targets
Agent Registry (/registry/agents.json) – for validating agent targets
Workflow Files (/workflows/*.yaml) – for validating workflow targets

Status

Active – This skill is production-ready and actively used in Betty's command infrastructure.

Version History

0.1.0 (Oct 2025) – Initial implementation with full validation and registry management

Command Define

Install Skill

SKILL.md