skill.define

Overview

skill.define is the compiler and registrar for Betty Framework skills. It ensures each skill.yaml conforms to schema and governance rules before registration.

Purpose

Acts as the quality gate for all skills in the Betty ecosystem:

•Schema Validation: Ensures all required fields are present
•Manifest Parsing: Validates YAML structure and syntax
•Registry Integration: Delegates to registry.update for registration
•Error Reporting: Provides detailed validation errors for troubleshooting

Usage

Basic Usage

bash

python skills/skill.define/skill_define.py <path_to_skill.yaml>

Arguments

Argument	Type	Required	Description
manifest_path	string	Yes	Path to the skill manifest file (skill.yaml)

Required Skill Manifest Fields

A valid skill manifest must include:

Field	Type	Description	Example
`name`	string	Unique skill identifier	`api.validate`
`version`	string	Semantic version	`0.1.0`
`description`	string	What the skill does	`Validates API specifications`
`inputs`	array	Input parameters	`["spec_path", "guideline_set"]`
`outputs`	array	Output artifacts	`["validation_report"]`
`dependencies`	array	Required skills/deps	`["context.schema"]`
`status`	string	Skill status	`active` or `draft`

Optional Fields

•entrypoints: CLI command definitions
•tags: Categorization tags
•permissions: Required filesystem/network permissions

Behavior

•Load Manifest: Reads and parses the YAML file
•Validate Structure: Checks for all required fields
•Validate Format: Ensures field types and values are correct
•Delegate Registration: Calls registry.update to add skill to registry
•Return Results: Provides JSON response with validation status

Outputs

Success Response

json

{
  "ok": true,
  "status": "registered",
  "errors": [],
  "path": "skills/workflow.validate/skill.yaml",
  "details": {
    "valid": true,
    "missing": [],
    "path": "skills/workflow.validate/skill.yaml",
    "manifest": {
      "name": "workflow.validate",
      "version": "0.1.0",
      "description": "Validates workflow YAML definitions",
      "inputs": ["workflow.yaml"],
      "outputs": ["validation_result.json"],
      "dependencies": ["context.schema"],
      "status": "active"
    },
    "status": "registered",
    "registry_updated": true
  }
}

Failure Response (Missing Fields)

json

{
  "ok": false,
  "status": "failed",
  "errors": [
    "Missing required fields: version, outputs"
  ],
  "path": "skills/my-skill/skill.yaml",
  "details": {
    "valid": false,
    "missing": ["version", "outputs"],
    "path": "skills/my-skill/skill.yaml"
  }
}

Failure Response (Invalid YAML)

json

{
  "ok": false,
  "status": "failed",
  "errors": [
    "Failed to parse YAML: mapping values are not allowed here"
  ],
  "path": "skills/broken/skill.yaml",
  "details": {
    "valid": false,
    "error": "Failed to parse YAML: mapping values are not allowed here",
    "path": "skills/broken/skill.yaml"
  }
}

Examples

Example 1: Validate a Complete Skill

Skill Manifest (skills/api.validate/skill.yaml):

yaml

name: api.validate
version: 0.1.0
description: "Validate OpenAPI and AsyncAPI specifications against enterprise guidelines"

inputs:
  - name: spec_path
    type: string
    required: true
    description: "Path to the API specification file"
  - name: guideline_set
    type: string
    required: false
    default: zalando
    description: "Which API guidelines to validate against"

outputs:
  - name: validation_report
    type: object
    description: "Detailed validation results"
  - name: valid
    type: boolean
    description: "Whether the spec is valid"

dependencies:
  - context.schema

status: active
tags: [api, validation, openapi]

Validation Command:

bash

$ python skills/skill.define/skill_define.py skills/api.validate/skill.yaml
{
  "ok": true,
  "status": "registered",
  "errors": [],
  "path": "skills/api.validate/skill.yaml",
  "details": {
    "valid": true,
    "status": "registered",
    "registry_updated": true
  }
}

Example 2: Detect Missing Fields

Incomplete Manifest (skills/incomplete/skill.yaml):

yaml

name: incomplete.skill
description: "This skill is missing required fields"
inputs: []

Validation Result:

bash

$ python skills/skill.define/skill_define.py skills/incomplete/skill.yaml
{
  "ok": false,
  "status": "failed",
  "errors": [
    "Missing required fields: version, outputs, dependencies, status"
  ],
  "path": "skills/incomplete/skill.yaml",
  "details": {
    "valid": false,
    "missing": ["version", "outputs", "dependencies", "status"],
    "path": "skills/incomplete/skill.yaml"
  }
}

Integration

With skill.create

The skill.create skill automatically generates a valid manifest and runs skill.define to validate it:

bash

python skills/skill.create/skill_create.py \
  my.skill \
  "Does something useful" \
  --inputs input1,input2 \
  --outputs output1
# Internally runs skill.define on the generated manifest

With Workflows

Skills can be validated as part of a workflow:

yaml

# workflows/create_and_register.yaml
steps:
  - skill: skill.create
    args: ["workflow.validate", "Validates workflow definitions"]

  - skill: skill.define
    args: ["skills/workflow.validate/skill.yaml"]
    required: true

  - skill: registry.update
    args: ["skills/workflow.validate/skill.yaml"]

With Hooks

Automatically validate skill manifests when they're edited:

bash

# Create a hook to validate on save
python skills/hook.define/hook_define.py \
  --event on_file_save \
  --pattern "skills/*/skill.yaml" \
  --command "python skills/skill.define/skill_define.py {file_path}" \
  --blocking true

Common Errors

Error	Cause	Solution
"Manifest file not found"	File path is incorrect	Check the path and ensure file exists
"Failed to parse YAML"	Invalid YAML syntax	Fix YAML syntax errors (indentation, quotes, etc.)
"Missing required fields: X"	Manifest missing required field(s)	Add the missing field(s) to the manifest
"registry.update skill not found"	Registry updater not available	Ensure `registry.update` skill exists in `skills/` directory

Relationship with registry.update

skill.define validates manifests but delegates registration to registry.update:

•skill.define: Validates the manifest structure
•registry.update: Updates /registry/skills.json with the validated skill

This separation of concerns follows Betty's single-responsibility principle.

Files Read

•Input: Skill manifest at specified path (e.g., skills/my.skill/skill.yaml)
•Registry: May read existing /registry/skills.json via delegation to registry.update

Files Modified

•None directly – Registry updates are delegated to registry.update skill
•Indirectly: /registry/skills.json updated via registry.update

Exit Codes

•0: Success (manifest valid, registration attempted)
•1: Failure (validation errors or file not found)

Logging

Logs validation steps using Betty's logging infrastructure:

code

INFO: Validating manifest: skills/api.validate/skill.yaml
INFO: ✅ Manifest validation passed
INFO: 🔁 Delegating registry update to registry.update skill...
INFO: Registry update succeeded

Best Practices

•Run Before Commit: Validate skill manifests before committing changes
•Use with skill.create: Let skill.create generate manifests to ensure correct structure
•Check Dependencies: Ensure any skills listed in dependencies exist in the registry
•Version Properly: Follow semantic versioning for skill versions
•Complete Descriptions: Write clear descriptions for inputs, outputs, and the skill itself
•Set Status Appropriately: Use draft for development, active for production-ready skills

Dependencies

•registry.update: For updating the skill registry (delegated call)
•betty.validation: Validation utility functions
•betty.config: Configuration constants

Status

Active – This skill is production-ready and core to Betty's skill infrastructure.

Version History

•0.1.0 (Oct 2025) – Initial implementation with manifest validation and registry delegation

Skill Define

skill.define

Overview

Purpose

Usage

Basic Usage

Arguments

Required Skill Manifest Fields

Optional Fields

Behavior

Outputs

Success Response

Failure Response (Missing Fields)

Failure Response (Invalid YAML)

Examples

Example 1: Validate a Complete Skill

Example 2: Detect Missing Fields

Integration

With skill.create

With Workflows

With Hooks

Common Errors

Relationship with registry.update

Files Read

Files Modified

Exit Codes

Logging

Best Practices

See Also

Dependencies

Status

Version History