MCP and skills registries

Status: Superseded

Superseded by template-schema.md. Separate MCP and skills registries merge into one unified Registry domain. Credentials are inferred from registry metadata, not declared in templates.

MCP and skills registries

Decision

Skills and MCPs live inside arpi/registries/ — not as a separate domain, but as governed catalogs consumed by the harness assembly. Both are cross-platform (shared across Claude Code, Codex, Cursor).

MCP catalog

A single file arpi/registries/mcp.json contains all approved MCP server configurations. When arpi spawn runs, it cherry-picks the subset matching the definition’s mcps list and writes them to the platform-specific config (.claude/settings.json, .codex/mcp.json, etc.).

Per-server metadata files in arpi/registries/mcps/ document transport, auth, and version for each server. These are reference docs, not consumed by arpi spawn today.

No Worker API for now. The registry is files in git. A v0.1-compatible API on Cloudflare Workers is a future upgrade for GitHub Copilot org-level auto-discovery, but is not needed for internal use.

Skills registry

The skills registry is a separate git repo (sharpi/skills-registry) added as a submodule at arpi/registries/skills/.

skills-registry/
  manifest.yaml                 # source of truth: all approved skills
  skills/
    sequential-thinking/
      SKILL.md
      .upstream.yaml            # tracks source repo, pinned commit, sync status
    frontend-design/
      SKILL.md                  # contains Sharpi-specific additions
      .upstream.yaml            # flagged as customized
    sharpi-erp-sync/
      SKILL.md                  # fully custom, no upstream
  scripts/
    sync.py                     # checks upstream sources, creates PRs
  .github/workflows/
    skill-sync.yml              # weekly cron (Monday 9am)

Dependabot-style sync. A weekly GitHub Action checks upstream repos for each vendored skill. If changes are found:

• Non-customized skills: auto-create PR to update.
• Customized skills: create PR with warning, show upstream diff alongside local customizations.

Governance. Only skills listed in manifest.yaml can be installed by arpi. Adding a skill requires a PR with review. Each vendored skill has .upstream.yaml tracking its source and pinned commit.

How arpi uses them

1. arpi spawn <def> reads the definition’s mcps list.
2. Cherry-picks matching entries from registries/mcp.json.
3. Reads the definition’s skills list.
4. Copies matching skills from registries/skills/skills/ to the project’s .claude/skills/.
5. Skills not in manifest.yaml are never installed.

Why registries/ is not a separate domain

Registries are consumed only during harness assembly — they’re building blocks, not an independent system. They live inside arpi/registries/ because:

• MCP configs and skills are inputs to arpi spawn, not standalone services.
• The skills registry sync mechanism is a CI workflow, not a runtime service.
• Keeping them near harnesses/ reduces indirection while still allowing cross-platform consumption.

Current Status

Updated 2026-03-27

The MCP catalog has been implemented but lives in harnesses/mcp.json, not registries/mcp.json as originally specified. The registries/ top-level domain was absorbed into harnesses/ per the ontology ADR — MCPs and skills are consumed during harness assembly, so keeping them near the assembly building blocks reduces indirection.

Component	Status
MCP catalog (mcp.json)	IMPLEMENTED — lives at harnesses/mcp.json
Per-server metadata (mcps/)	NOT YET CREATED — reference docs for each MCP server
Skills submodule (registries/skills/)	DEFERRED to v2 — harnesses/skills/ directory does not yet exist
Skills manifest.yaml	DEFERRED to v2
Skills .upstream.yaml tracking	DEFERRED to v2
Skills sync script (scripts/sync.py)	DEFERRED to v2
Cloudflare Worker registry API	DEFERRED to v2 — not needed for internal use

The registries/ directory does not exist as a top-level folder. The current ontology places MCP and skills catalogs inside harnesses/ as cross-platform content consumed by assembly.

Verification

• mcp.json contains all approved MCP server configurations
• arpi spawn only installs MCPs and skills listed in the definition
• Skills not in manifest.yaml are never installed
• Vendored skills have .upstream.yaml with source and pinned commit
• Sync script detects upstream changes and creates PRs
• Customized skill sync PRs include warning and diff
• Adding a new MCP server = add to mcp.json + server metadata, merge PR
• Adding a new skill = add to manifest.yaml + skill directory, merge PR