Skill Define

What this skill does

# 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

1. **Load Manifest**: Reads and parses the YAML file
2. **Validate Structure**: Checks for all required fields
3. **Validate Format**: Ensures field types and values are correct
4. **Delegate Registration**: Calls `registry.update` to add skill to registry
5. **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`:

1. **skill.define**: Validates the manifest structure
2. **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:

```
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

1. **Run Before Commit**: Validate skill manifests before committing changes
2. **Use with skill.create**: Let `skill.create` generate manifests to ensure correct structure
3. **Check Dependencies**: Ensure any skills listed in `dependencies` exist in the registry
4. **Version Properly**: Follow semantic versioning fo