gh-epieczko-betty/skills/registry.diff/SKILL.md

registry.diff

Compare current and previous versions of skills/agents and report differences.

Overview

The registry.diff skill analyzes changes between a current manifest file (skill.yaml or agent.yaml) and its existing registry entry. It detects various types of changes, determines the required action, and provides suggestions for proper version management and breaking change prevention.

Purpose

• Version Control: Ensure proper semantic versioning when updating skills/agents
• Breaking Change Detection: Identify changes that break backward compatibility
• Permission Auditing: Track permission changes and flag unauthorized modifications
• Workflow Integration: Enable automated validation in CI/CD pipelines

Usage

# Compare a skill manifest against the registry
./skills/registry.diff/registry_diff.py path/to/skill.yaml

# Compare an agent manifest
./skills/registry.diff/registry_diff.py path/to/agent.yaml

# Using with betty command (if configured)
betty registry.diff <manifest_path>

Input

Parameter	Type	Required	Description
manifest_path	string	Yes	Path to skill.yaml or agent.yaml file to analyze

Output

The skill returns a JSON response with the following structure:

{
  "ok": true,
  "status": "success",
  "errors": [],
  "path": "path/to/manifest.yaml",
  "details": {
    "manifest_path": "path/to/manifest.yaml",
    "manifest_type": "skill",
    "diff_type": "version_bump",
    "required_action": "register",
    "suggestions": [
      "Version upgraded: 0.1.0 -> 0.2.0",
      "Clean version bump with no breaking changes"
    ],
    "details": {
      "name": "example.skill",
      "current_version": "0.2.0",
      "previous_version": "0.1.0",
      "version_comparison": "upgrade",
      "permission_changed": false,
      "added_permissions": [],
      "removed_permissions": [],
      "removed_fields": [],
      "status_changed": false,
      "current_status": "active",
      "previous_status": "active"
    },
    "timestamp": "2025-10-23T12:00:00+00:00"
  }
}

Diff Types

Type	Description
new	Entry does not exist in registry (first-time registration)
version_bump	Version was properly incremented
version_downgrade	Version was decreased (breaking change)
permission_change	Permissions were added or removed
breaking_change	Breaking changes detected (removed fields, etc.)
status_change	Status field changed (active, deprecated, etc.)
needs_version_bump	Changes detected without version increment
no_change	No significant changes detected

Required Actions

Action	Description	Exit Code
register	Changes are acceptable, proceed with registration	0
review	Manual review recommended before registration	0
reject	Breaking/unauthorized changes, registration blocked	1
skip	No changes detected, no action needed	0

Examples

Example 1: New Skill Registration

$ ./skills/registry.diff/registry_diff.py skills/new.skill/skill.yaml

Output:

{
  "ok": true,
  "status": "success",
  "details": {
    "diff_type": "new",
    "required_action": "register",
    "suggestions": [
      "New skill 'new.skill' ready for registration"
    ]
  }
}

Example 2: Clean Version Bump

$ ./skills/registry.diff/registry_diff.py skills/example.skill/skill.yaml

Output:

{
  "ok": true,
  "status": "success",
  "details": {
    "diff_type": "version_bump",
    "required_action": "register",
    "suggestions": [
      "Version upgraded: 0.1.0 -> 0.2.0",
      "Clean version bump with no breaking changes"
    ]
  }
}

Example 3: Breaking Change Detected

$ ./skills/registry.diff/registry_diff.py skills/example.skill/skill.yaml

Output:

{
  "ok": false,
  "status": "failed",
  "errors": [
    "Fields removed without version bump: dependencies",
    "Removing fields requires a version bump",
    "Suggested version: 0.2.0"
  ],
  "details": {
    "diff_type": "breaking_change",
    "required_action": "reject",
    "details": {
      "removed_fields": ["dependencies"],
      "current_version": "0.1.0",
      "previous_version": "0.1.0"
    }
  }
}

Exit code: 1

Example 4: Permission Change

$ ./skills/registry.diff/registry_diff.py skills/example.skill/skill.yaml

Output:

{
  "ok": true,
  "status": "success",
  "details": {
    "diff_type": "permission_change",
    "required_action": "review",
    "suggestions": [
      "New permissions added: network",
      "Review: Ensure new permissions are necessary and documented"
    ],
    "details": {
      "added_permissions": ["network"],
      "removed_permissions": []
    }
  }
}

Example 5: Version Downgrade (Rejected)

$ ./skills/registry.diff/registry_diff.py skills/example.skill/skill.yaml

Output:

{
  "ok": false,
  "status": "failed",
  "errors": [
    "Version downgrade detected: 0.2.0 -> 0.1.0",
    "Version downgrades are not permitted",
    "Suggested action: Restore version to at least 0.2.0"
  ],
  "details": {
    "diff_type": "version_downgrade",
    "required_action": "reject"
  }
}

Exit code: 1

Exit Codes

• 0: Success - Changes are acceptable or no changes detected
• 1: Failure - Breaking or unauthorized changes detected

Workflow Integration

Pre-Commit Hook

# .git/hooks/pre-commit
#!/bin/bash
changed_files=$(git diff --cached --name-only | grep -E "skill\.yaml|agent\.yaml")

for file in $changed_files; do
  echo "Checking $file..."
  ./skills/registry.diff/registry_diff.py "$file"
  if [ $? -ne 0 ]; then
    echo "❌ Registry diff failed for $file"
    exit 1
  fi
done

CI/CD Pipeline

# .github/workflows/validate-changes.yml
name: Validate Skill Changes

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Check skill changes
        run: |
          for file in $(git diff --name-only origin/main | grep -E "skill\.yaml|agent\.yaml"); do
            python3 skills/registry.diff/registry_diff.py "$file"
          done

Change Detection Rules

Breaking Changes (Exit 1)

1. Version Downgrade: Current version < Previous version
2. Removed Fields: Fields removed without version bump
3. Removed Permissions: Permissions removed without version bump

Requires Review (Exit 0, but flagged)

1. Permission Addition: New permissions added
2. Status Change: Status changed to deprecated/archived
3. Needs Version Bump: Changes without version increment

Acceptable Changes (Exit 0)

1. New Entry: First-time registration
2. Clean Version Bump: Version incremented properly
3. No Changes: No significant changes detected

Semantic Versioning Guidelines

The skill follows semantic versioning principles:

• Major (X.0.0): Breaking changes, removed functionality
• Minor (0.X.0): New features, deprecated functionality, significant changes
• Patch (0.0.X): Bug fixes, documentation updates, minor tweaks

Suggested Version Bumps

Change Type	Suggested Bump
Remove fields	Minor
Remove permissions	Minor
Add permissions	Patch or Minor
Status to deprecated	Minor
Bug fixes	Patch
New features	Minor
Breaking changes	Major

Dependencies

• Python 3.6+
• packaging library (for version comparison)
• Betty Framework core utilities
• PyYAML

Related Skills

• registry.update: Update registry entries
• skill.define: Define and validate skill manifests
• audit.log: Audit trail for registry changes

Notes

• Automatically detects whether input is a skill or agent manifest
• Compares against appropriate registry (skills.json or agents.json)
• Provides human-readable output to stderr for CLI usage
• Returns structured JSON for programmatic integration
• Thread-safe registry reading using Betty Framework utilities

Troubleshooting

"Manifest file not found"

Ensure the path to the manifest file is correct and the file exists.

"Empty manifest file"

The YAML file exists but contains no data. Check for valid YAML content.

"Registry file not found"

The registry hasn't been initialized yet. This is normal for new Betty Framework installations.

"Invalid YAML in manifest"

The manifest file contains syntax errors. Validate with a YAML parser.

Future Enhancements

• Support for dependency tree validation
• Integration with semantic version recommendation engine
• Diff visualization in HTML format
• Support for comparing arbitrary versions (not just latest)
• Batch mode for comparing multiple manifests