Agent Skills: Federated Registry Protocol

Federated Registry Protocol

Overview

The Federated Registry Protocol enables plugin resolution across multiple registries with configurable priority, security policies, conflict detection, and deterministic lockfiles. It transforms plugin management from a single-source package manager into an enterprise-grade multi-source orchestration system.

Architecture

                  +-----------------+
                  | RegistryClient  |  Fetches and caches registry indexes
                  +--------+--------+
                           |
                  +--------v--------+
                  | RegistryResolver|  Resolves plugins across registries
                  +--------+--------+
                           |
                  +--------v--------+
                  |  PolicyEngine   |  Evaluates allow/deny/require rules
                  +--------+--------+
                           |
                  +--------v--------+
                  | LockfileManager |  Deterministic version pinning
                  +-----------------+

Components

RegistryClient

Loads configuration from .claude/registries.json and fetches plugin indexes from multiple sources. Supports local filesystem directories and remote HTTP(S) URLs.

Key behaviors:

• Caches registry data with configurable TTL (default: 1 hour)
• Graceful degradation when registries are unavailable
• Token and OIDC authentication support
• Local directory scanning builds indexes from plugin manifests

RegistryResolver

Resolves plugin names across all configured registries in priority order (highest first).

Conflict detection:

• Same plugin name in multiple registries is detected via SHA-256 content hash comparison
• Resolution strategies: highest-priority (default), error, prompt
• All conflicts are recorded for audit trail

PolicyEngine

Evaluates security rules from .claude/policies/plugins.yaml using short-circuit matching (first match wins).

Rule types:

• allow — Permits the plugin
• deny — Blocks the plugin with a reason
• require — Warns when mandatory plugins are missing

Unless clause: Exempts matching plugins when ALL conditions are met (trust score threshold, signature verification).

LockfileManager

Produces plugin-lock.json for reproducible plugin environments.

Capabilities:

• Generate lockfile from current resolved state
• Detect drift between lockfile and installed plugins
• Produce human-readable diffs for PR reviews
• Install from lockfile for deterministic environments

Workflow

Setting Up Federation

1. Configure registries with priorities:

   /mp:registry add local ./plugins --priority 100
   /mp:registry add team https://plugins.team.dev/index.json --priority 75
   /mp:registry add public https://marketplace.claude.dev/registry.json --priority 0
   

2. Define security policy in .claude/policies/plugins.yaml

3. Sync registry caches:

   /mp:registry sync
   

Installing Plugins

1. Resolve plugin across registries (highest priority first)
2. Check policy engine for allow/deny decision
3. Install from the resolved source
4. Update the lockfile:

   /mp:lock generate
   

CI/CD Integration

1. Commit plugin-lock.json to version control
2. In CI: mp:lock check to verify no drift
3. In deployment: mp:lock install for reproducible environment
4. In PRs: mp:lock diff to review plugin changes

Policy Enforcement

1. Define rules in .claude/policies/plugins.yaml
2. Audit installed plugins: /mp:policy enforce
3. Check individual plugins: /mp:policy check <name>

Configuration Files

| File | Purpose | |------|---------| | .claude/registries.json | Registry sources and federation settings | | .claude/policies/plugins.yaml | Security policy rules | | plugin-lock.json | Deterministic version lock | | config/registries.default.json | Default registry configuration | | config/policies.default.yaml | Default security policy |

Commands

| Command | Description | |---------|-------------| | /mp:registry add | Add a registry source | | /mp:registry remove | Remove a registry | | /mp:registry list | Show configured registries | | /mp:registry sync | Refresh all caches | | /mp:policy check | Check a plugin against policy | | /mp:policy list | Show policy rules | | /mp:policy enforce | Audit installed plugins | | /mp:lock generate | Create lockfile from current state | | /mp:lock check | Verify plugins match lockfile | | /mp:lock diff | Show changes since last lock | | /mp:lock install | Install from lockfile |

Source Code

• Types: src/federation/types.ts
• Engine: src/federation/registry.ts
• Config: config/registries.default.json
• Policy: config/policies.default.yaml