name	Plugin Manifest Sync
description	Reconcile plugin.yaml with Betty Framework registries

docs.sync.plugin_manifest

Overview

docs.sync.plugin_manifest is a validation and reconciliation tool that compares plugin.yaml against Betty Framework's registry files to ensure consistency and completeness. It identifies missing commands, orphaned entries, metadata mismatches, and suggests corrections.

Purpose

Ensures synchronization between:

Skill Registry (registry/skills.json) – Active skills with entrypoints
Command Registry (registry/commands.json) – Slash commands
Plugin Configuration (plugin.yaml) – Claude Code plugin manifest

This skill helps maintain plugin.yaml accuracy by detecting:

Active skills missing from plugin.yaml
Orphaned commands in plugin.yaml not found in registries
Metadata inconsistencies (permissions, runtime, handlers)
Missing metadata that should be added

What It Does

Loads Registries: Reads skills.json and commands.json
Loads Plugin: Reads current plugin.yaml
Builds Indexes: Creates lookup tables for both registries and plugin
Compares Entries: Identifies missing, orphaned, and mismatched commands
Analyzes Metadata: Checks permissions, runtime, handlers, descriptions
Generates Preview: Creates plugin.preview.yaml with suggested updates
Creates Report: Outputs plugin_manifest_diff.md with detailed analysis
Provides Summary: Displays key findings and recommendations

Usage

Basic Usage

python skills/docs.sync.plugin_manifest/plugin_manifest_sync.py

No arguments required - reads from standard locations.

Via Betty CLI

/docs/sync/plugin-manifest

Expected File Structure

betty/
├── registry/
│   ├── skills.json      # Source of truth for skills
│   └── commands.json    # Source of truth for commands
├── plugin.yaml          # Current plugin manifest
├── plugin.preview.yaml  # Generated preview (output)
└── plugin_manifest_diff.md  # Generated report (output)

Behavior

1. Registry Loading

Reads and parses:

registry/skills.json – All registered skills
registry/commands.json – All registered commands

Only processes entries with status: active.

2. Plugin Loading

Reads and parses:

plugin.yaml – Current plugin configuration

Extracts all command definitions.

3. Index Building

Registry Index: Maps command names to their registry sources

{
  "skill/define": {
    "type": "skill",
    "source": "skill.define",
    "skill": {...},
    "entrypoint": {...}
  },
  "api/validate": {
    "type": "skill",
    "source": "api.validate",
    "skill": {...},
    "entrypoint": {...}
  }
}

Plugin Index: Maps command names to plugin entries

{
  "skill/define": {
    "name": "skill/define",
    "handler": {...},
    "permissions": [...]
  }
}

4. Comparison Analysis

Performs four types of checks:

Missing Commands

Commands in registry but not in plugin.yaml:

- skill/create (active in registry, missing from plugin)
- api/validate (active in registry, missing from plugin)

Orphaned Commands

Commands in plugin.yaml but not in registry:

- old/deprecated (in plugin but not registered)
- test/removed (in plugin but removed from registry)

Metadata Mismatches

Commands present in both but with different metadata:

Runtime Mismatch:

- skill/define:
  - Registry: python
  - Plugin: node

Permission Mismatch:

- api/validate:
  - Missing: filesystem:read
  - Extra: network:write

Handler Mismatch:

- skill/create:
  - Registry: skills/skill.create/skill_create.py
  - Plugin: skills/skill.create/old_handler.py

Description Mismatch:

- agent/run:
  - Registry: "Execute a Betty agent..."
  - Plugin: "Run agent"

Missing Metadata Suggestions

Identifies registry entries missing recommended metadata:

- hook/define: Consider adding permissions metadata
- test/skill: Consider adding description

5. Preview Generation

Creates plugin.preview.yaml by:

Taking all active commands from registries
Converting to plugin.yaml format
Including all metadata from registries
Adding generation timestamp
Preserving existing plugin metadata (author, license, etc.)

6. Report Generation

Creates plugin_manifest_diff.md with:

Executive summary
Lists of missing commands
Lists of orphaned commands
Detailed metadata issues
Metadata suggestions

Outputs

Success Response

{
  "ok": true,
  "status": "success",
  "preview_path": "/home/user/betty/plugin.preview.yaml",
  "report_path": "/home/user/betty/plugin_manifest_diff.md",
  "reconciliation": {
    "missing_commands": [...],
    "orphaned_commands": [...],
    "metadata_issues": [...],
    "metadata_suggestions": [...],
    "total_registry_commands": 19,
    "total_plugin_commands": 18
  }
}

Console Output

============================================================
PLUGIN MANIFEST RECONCILIATION COMPLETE
============================================================

📊 Summary:
  - Commands in registry: 19
  - Commands in plugin.yaml: 18
  - Missing from plugin.yaml: 2
  - Orphaned in plugin.yaml: 1
  - Metadata issues: 3
  - Metadata suggestions: 2

📄 Output files:
  - Preview: /home/user/betty/plugin.preview.yaml
  - Diff report: /home/user/betty/plugin_manifest_diff.md

⚠️  2 command(s) missing from plugin.yaml:
    - registry/query (registry.query)
    - hook/simulate (hook.simulate)

⚠️  1 orphaned command(s) in plugin.yaml:
    - old/deprecated

✅ Review plugin_manifest_diff.md for full details
============================================================

Failure Response

{
  "ok": false,
  "status": "failed",
  "error": "Failed to parse JSON from registry/skills.json"
}

Generated Files

plugin.preview.yaml

Updated plugin manifest with all active registry commands:

# Betty Framework - Claude Code Plugin (Preview)
# Generated by docs.sync.plugin_manifest skill
# Review changes before applying to plugin.yaml

name: betty-framework
version: 1.0.0
description: Betty Framework - Structured AI-assisted engineering
author:
  name: RiskExec
  email: platform@riskexec.com
  url: https://github.com/epieczko/betty
license: MIT

metadata:
  generated_at: "2025-10-23T20:00:00.000000+00:00"
  generated_by: docs.sync.plugin_manifest skill
  command_count: 19

commands:
  - name: skill/define
    description: Validate a Claude Code skill manifest
    handler:
      runtime: python
      script: skills/skill.define/skill_define.py
    parameters:
      - name: manifest_path
        type: string
        required: true
        description: Path to skill.yaml file
    permissions:
      - filesystem:read
      - filesystem:write

  # ... more commands ...

plugin_manifest_diff.md

Detailed reconciliation report:

# Plugin Manifest Reconciliation Report
Generated: 2025-10-23T20:00:00.000000+00:00

## Summary
- Total commands in registry: 19
- Total commands in plugin.yaml: 18
- Missing from plugin.yaml: 2
- Orphaned in plugin.yaml: 1
- Metadata issues: 3
- Metadata suggestions: 2

## Missing Commands (in registry but not in plugin.yaml)
- **registry/query** (skill: registry.query)
- **hook/simulate** (skill: hook.simulate)

## Orphaned Commands (in plugin.yaml but not in registry)
- **old/deprecated**

## Metadata Issues
- **skill/create**: Permissions Mismatch
  - Missing: process:execute
  - Extra: network:http
- **api/validate**: Handler Mismatch
  - Registry: `skills/api.validate/api_validate.py`
  - Plugin: `skills/api.validate/validator.py`
- **agent/run**: Runtime Mismatch
  - Registry: `python`
  - Plugin: `node`

## Metadata Suggestions
- **hook/define** (permissions): Consider adding permissions metadata
- **test/skill** (description): Consider adding description

Examples

Example 1: Routine Sync Check

Scenario: Regular validation after making registry changes

# Make some registry updates
/skill/define skills/new.skill/skill.yaml

# Check for discrepancies
/docs/sync/plugin-manifest

# Review the report
cat plugin_manifest_diff.md

# If changes look good, apply them
cp plugin.preview.yaml plugin.yaml

Output:

============================================================
PLUGIN MANIFEST RECONCILIATION COMPLETE
============================================================

📊 Summary:
  - Commands in registry: 20
  - Commands in plugin.yaml: 19
  - Missing from plugin.yaml: 1
  - Orphaned in plugin.yaml: 0
  - Metadata issues: 0
  - Metadata suggestions: 0

⚠️  1 command(s) missing from plugin.yaml:
    - new/skill (new.skill)

✅ Review plugin_manifest_diff.md for full details

Example 2: Detecting Orphaned Commands

Scenario: A skill was removed from registry but command remains in plugin.yaml

# Remove skill from registry
rm -rf skills/deprecated.skill/

# Run reconciliation
/docs/sync/plugin-manifest

# Check report
cat plugin_manifest_diff.md

Output:

============================================================
PLUGIN MANIFEST RECONCILIATION COMPLETE
============================================================

📊 Summary:
  - Commands in registry: 18
  - Commands in plugin.yaml: 19
  - Missing from plugin.yaml: 0
  - Orphaned in plugin.yaml: 1
  - Metadata issues: 0
  - Metadata suggestions: 0

⚠️  1 orphaned command(s) in plugin.yaml:
    - deprecated/skill

✅ Review plugin_manifest_diff.md for full details

Example 3: Finding Metadata Mismatches

Scenario: Registry was updated but plugin.yaml wasn't synced

# Update skill permissions in registry
/skill/define skills/api.validate/skill.yaml

# Check for differences
/docs/sync/plugin-manifest

# Review specific mismatches
grep -A 5 "Metadata Issues" plugin_manifest_diff.md

Report Output:

## Metadata Issues
- **api/validate**: Permissions Mismatch
  - Missing: network:http
  - Extra: filesystem:write

Example 4: Pre-Commit Validation

Scenario: Validate plugin.yaml before committing changes

# Before committing
/docs/sync/plugin-manifest

# If discrepancies found, fix them
if [ $? -eq 0 ]; then
  # Review and apply changes
  diff plugin.yaml plugin.preview.yaml
  cp plugin.preview.yaml plugin.yaml
fi

# Commit changes
git add plugin.yaml
git commit -m "Sync plugin.yaml with registries"

Example 5: CI/CD Integration

Scenario: Automated validation in CI pipeline

# .github/workflows/validate-plugin.yml
name: Validate Plugin Manifest

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Reconcile Plugin Manifest
        run: |
          python skills/docs.sync.plugin_manifest/plugin_manifest_sync.py

          # Check if there are discrepancies
          if grep -q "Missing from plugin.yaml: [1-9]" plugin_manifest_diff.md; then
            echo "❌ Plugin manifest has missing commands"
            cat plugin_manifest_diff.md
            exit 1
          fi

          if grep -q "Orphaned in plugin.yaml: [1-9]" plugin_manifest_diff.md; then
            echo "❌ Plugin manifest has orphaned commands"
            cat plugin_manifest_diff.md
            exit 1
          fi

          echo "✅ Plugin manifest is in sync"

Integration

With plugin.sync

Use reconciliation to verify before syncing:

# Check current state
/docs/sync/plugin-manifest

# Review differences
cat plugin_manifest_diff.md

# If satisfied, run full sync
/plugin/sync

With skill.define

Validate after defining skills:

# Define new skill
/skill/define skills/my.skill/skill.yaml

# Check plugin consistency
/docs/sync/plugin-manifest

# Apply changes if needed
cp plugin.preview.yaml plugin.yaml

With Hooks

Auto-check on registry changes:

# .claude/hooks.yaml
- event: on_file_save
  pattern: "registry/*.json"
  command: python skills/docs.sync.plugin_manifest/plugin_manifest_sync.py
  blocking: false
  description: Check plugin manifest sync when registries change

With Workflows

Include in skill lifecycle workflow:

# workflows/update_plugin.yaml
steps:
  - skill: skill.define
    args: ["skills/new.skill/skill.yaml"]

  - skill: docs.sync.plugin_manifest
    args: []

  - skill: plugin.sync
    args: []

What Gets Reported

✅ Detected Issues

Active skills missing from plugin.yaml
Orphaned commands in plugin.yaml
Runtime mismatches (python vs node)
Permission mismatches (missing or extra)
Handler path mismatches
Description mismatches
Missing metadata (permissions, descriptions)

❌ Not Detected

Draft/inactive skills (intentionally excluded)
Malformed YAML syntax (causes failure)
Handler file existence (use plugin.sync for that)
Parameter schema validation

Common Use Cases

Use Case	When to Use
Pre-commit check	Before committing plugin.yaml changes
Post-registry update	After adding/updating skills in registry
CI/CD validation	Automated pipeline checks
Manual audit	Periodic manual review of plugin state
Debugging	When commands aren't appearing as expected
Migration	After major registry restructuring

Common Errors

Error	Cause	Solution
"Failed to parse JSON"	Invalid JSON in registry	Fix JSON syntax in registry files
"Failed to parse YAML"	Invalid YAML in plugin.yaml	Fix YAML syntax in plugin.yaml
"Registry file not found"	Missing registry files	Ensure registries exist in registry/
"Permission denied"	Cannot write output files	Check write permissions on directory
All commands missing	Empty or invalid registries	Verify registry files are populated

Files Read

registry/skills.json – Skill registry (source of truth)
registry/commands.json – Command registry (source of truth)
plugin.yaml – Current plugin manifest (for comparison)

Files Generated

plugin.preview.yaml – Updated plugin manifest preview
plugin_manifest_diff.md – Detailed reconciliation report

Exit Codes

0: Success (reconciliation completed successfully)
1: Failure (error during reconciliation)

Note: Discrepancies found are reported but don't cause failure (exit 0). Only parsing errors or system failures cause exit 1.

Logging

Logs reconciliation progress:

INFO: Starting plugin manifest reconciliation...
INFO: Loading registry files...
INFO: Loading plugin.yaml...
INFO: Building registry index...
INFO: Building plugin index...
INFO: Comparing registries with plugin.yaml...
INFO: Reconciling registries with plugin.yaml...
INFO: Generating updated plugin.yaml...
INFO: ✅ Written file to /home/user/betty/plugin.preview.yaml
INFO: Generating diff report...
INFO: ✅ Written diff report to /home/user/betty/plugin_manifest_diff.md

Best Practices

Run Before Committing: Always check sync status before committing plugin.yaml
Review Diff Report: Read the full report to understand all changes
Validate Preview: Review plugin.preview.yaml before applying
Include in CI: Add validation to your CI/CD pipeline
Regular Audits: Run periodic checks even without changes
Address Orphans: Remove orphaned commands promptly
Fix Mismatches: Resolve metadata mismatches to maintain consistency
Keep Registries Clean: Mark inactive skills as draft instead of deleting

Workflow Integration

Recommended Workflow

# 1. Define or update skills
/skill/define skills/my.skill/skill.yaml

# 2. Check for discrepancies
/docs/sync/plugin-manifest

# 3. Review the report
cat plugin_manifest_diff.md

# 4. Review the preview
diff plugin.yaml plugin.preview.yaml

# 5. Apply changes if satisfied
cp plugin.preview.yaml plugin.yaml

# 6. Commit changes
git add plugin.yaml registry/
git commit -m "Update plugin manifest"

Alternative: Auto-Sync Workflow

# 1. Define or update skills
/skill/define skills/my.skill/skill.yaml

# 2. Run full sync (overwrites plugin.yaml)
/plugin/sync

# 3. Validate the result
/docs/sync/plugin-manifest

# 4. If clean, commit
git add plugin.yaml registry/
git commit -m "Update plugin manifest"

Troubleshooting

Plugin.yaml Shows as Out of Sync

Problem: Reconciliation reports missing or orphaned commands

Solutions:

Run /plugin/sync to regenerate plugin.yaml from registries
Review and apply plugin.preview.yaml manually
Check if skills are marked as active in registry
Verify skills have entrypoints defined

Metadata Mismatches Reported

Problem: Registry and plugin have different permissions/runtime/handlers

Solutions:

Update skill.yaml with correct metadata
Run /skill/define to register changes
Run /docs/sync/plugin-manifest to verify
Apply plugin.preview.yaml or run /plugin/sync

Orphaned Commands Found

Problem: Commands in plugin.yaml not found in registry

Solutions:

Check if skill was removed from registry
Verify skill status is active in registry
Re-register the skill if it should exist
Remove from plugin.yaml if intentionally deprecated

Preview File Not Generated

Problem: plugin.preview.yaml missing after running skill

Solutions:

Check write permissions on betty/ directory
Verify registries are readable
Check logs for errors
Ensure plugin.yaml exists and is valid

Architecture

Skill Category

Documentation & Infrastructure – Maintains consistency between registry and plugin configuration layers.

Design Principles

Non-Destructive: Never modifies plugin.yaml directly
Comprehensive: Reports all types of discrepancies
Actionable: Provides preview file ready to apply
Transparent: Detailed report explains all findings
Idempotent: Can be run multiple times safely

Dependencies

plugin.sync: Plugin generation infrastructure
registry.update: Registry management
betty.config: Configuration constants and paths
betty.logging_utils: Logging infrastructure

Status

Active – Production-ready documentation and validation skill

Version History

0.1.0 (Oct 2025) – Initial implementation with full reconciliation, preview generation, and diff reporting

Install Skill

SKILL.md

docs.sync.plugin_manifest

Overview

Purpose

What It Does

Usage

Basic Usage

Via Betty CLI

Expected File Structure

Behavior

1. Registry Loading

2. Plugin Loading

3. Index Building

4. Comparison Analysis

Missing Commands

Orphaned Commands

Metadata Mismatches

Missing Metadata Suggestions

5. Preview Generation

6. Report Generation

Outputs

Success Response

Console Output

Failure Response

Generated Files

plugin.preview.yaml

plugin_manifest_diff.md

Examples

Example 1: Routine Sync Check

Example 2: Detecting Orphaned Commands

Example 3: Finding Metadata Mismatches

Example 4: Pre-Commit Validation

Example 5: CI/CD Integration

Integration

With plugin.sync

With skill.define

With Hooks

With Workflows

What Gets Reported

✅ Detected Issues

❌ Not Detected

Common Use Cases

Common Errors

Files Read

Files Generated

Exit Codes

Logging

Best Practices

Workflow Integration

Recommended Workflow

Alternative: Auto-Sync Workflow

Troubleshooting

Plugin.yaml Shows as Out of Sync

Metadata Mismatches Reported

Orphaned Commands Found

Preview File Not Generated

Architecture

Skill Category

Design Principles

See Also

Dependencies

Status

Version History