npx claudepluginhub joshuarweaver/cascade-code-general-misc-1 --plugin epieczko-bettyThis skill uses the workspace's default tool permissions.
**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.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
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.
Ensures synchronization between:
registry/skills.json) – Active skills with entrypointsregistry/commands.json) – Slash commandsplugin.yaml) – Claude Code plugin manifestThis skill helps maintain plugin.yaml accuracy by detecting:
skills.json and commands.jsonplugin.yamlplugin.preview.yaml with suggested updatesplugin_manifest_diff.md with detailed analysispython skills/docs.sync.plugin_manifest/plugin_manifest_sync.py
No arguments required - reads from standard locations.
/docs/sync/plugin-manifest
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)
Reads and parses:
registry/skills.json – All registered skillsregistry/commands.json – All registered commandsOnly processes entries with status: active.
Reads and parses:
plugin.yaml – Current plugin configurationExtracts all command definitions.
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": [...]
}
}
Performs four types of checks:
Commands in registry but not in plugin.yaml:
- skill/create (active in registry, missing from plugin)
- api/validate (active in registry, missing from plugin)
Commands in plugin.yaml but not in registry:
- old/deprecated (in plugin but not registered)
- test/removed (in plugin but removed from registry)
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"
Identifies registry entries missing recommended metadata:
- hook/define: Consider adding permissions metadata
- test/skill: Consider adding description
Creates plugin.preview.yaml by:
Creates plugin_manifest_diff.md with:
{
"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
}
}
============================================================
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
============================================================
{
"ok": false,
"status": "failed",
"error": "Failed to parse JSON from registry/skills.json"
}
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 ...
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
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
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
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
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"
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"
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
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
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
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: []
| 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 |
| 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 |
registry/skills.json – Skill registry (source of truth)registry/commands.json – Command registry (source of truth)plugin.yaml – Current plugin manifest (for comparison)plugin.preview.yaml – Updated plugin manifest previewplugin_manifest_diff.md – Detailed reconciliation reportNote: Discrepancies found are reported but don't cause failure (exit 0). Only parsing errors or system failures cause exit 1.
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
# 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"
# 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"
Problem: Reconciliation reports missing or orphaned commands
Solutions:
/plugin/sync to regenerate plugin.yaml from registriesplugin.preview.yaml manuallyactive in registryentrypoints definedProblem: Registry and plugin have different permissions/runtime/handlers
Solutions:
/skill/define to register changes/docs/sync/plugin-manifest to verify/plugin/syncProblem: Commands in plugin.yaml not found in registry
Solutions:
active in registryProblem: plugin.preview.yaml missing after running skill
Solutions:
Documentation & Infrastructure – Maintains consistency between registry and plugin configuration layers.
Active – Production-ready documentation and validation skill