Component revision · implemented and reviewed

One management grammar for Plugins, Skills, and MCP

This document defines how an OpenProgram owner discovers, adds, configures, enables, diagnoses, and removes the three extension types in the Web UI. The audience is the Web and runtime maintainers. Programs, agent-specific allowlists, third-party marketplace governance, and new package formats are outside this task.

Revision base 74d971ffCandidate 5e754c2bReviews passedNo new dependency

Current implementation and verified gaps

Different task words

Plugins use Installed / Marketplace / Errors and “Install”; Skills use Browse / Discovery and “New skill”; MCP uses a server rail, “Browse catalog,” and “Add server.” The same user intent changes name and location.

Different failure behavior

Skills have a page error bar. Plugin initial load can reject without a page-level error. Several MCP mutations ignore non-2xx responses, leaving the visible state unchanged with no explanation.

Different status density

Plugins expose trust and load errors, Skills expose enabled state, and MCP exposes live readiness and tool count. The page chrome does not state which count means installed, enabled, ready, or failed.

Duplicated MCP discovery

MCP exposes Discover as both a secondary tab and a top-level action. The tab only opens a modal while Installed remains active, so navigation state and visible content disagree.

Shared task model

User task	Plugins	Skills	MCP servers
Installed	Installed packages	Local and bundled SKILL.md entries	Configured servers
Discover	Marketplace indexes	Configured skill catalogs	Curated and custom MCP catalogs
Add	Install package or local path	Install from catalog or create locally	Install catalog entry or configure manually
Availability	Enabled + loaded	Enabled	Enabled + ready
Diagnose	Validation and load error	Parse/load error	Connection error and tools
Remove	Uninstall	Delete owned skill	Delete configuration

Target Web surface

The visual system is defined by shared item components, not by an outer container. Installed entries use one row anatomy; Discover entries use one catalog-card anatomy. The page background remains open, matching the rest of OpenProgram.

Abilities

PluginsSkillsMCP

SearchRefresh

Installed 8DiscoverIssues 1

6 availableAdd plugin

Plugin list could not be refreshed: authentication required. Retry after opening OpenProgram from the App.

▦

browser availableverified

Control the embedded browser

Enabled

▦

example-plugin disabled

Local plugin · validation available from details

Disabled

State and failure flow

Public page action

Add, enable, refresh, test, update, or remove. The control enters a busy state and remains named after the action.

→

Typed JSON request

One client parses error and FastAPI detail, preserves status/code, and throws one error type.

→

Observable result

Success refreshes the affected collection and selection. Failure stays visible near the collection or dialog and explains the recovery action.

Adopted, modified, and rejected choices

Adopt

Reuse ManagePageHeader, ManageSubnav, ManageRow, existing dialogs, existing routes, and native fetch. Preserve each subsystem’s backend and security boundary.

Modify

Standardize task vocabulary, summary placement, loading/error feedback, and request error parsing. The top toolbar contains only search and refresh. Secondary tabs own the body and the single Add action. Plugins, Skills, and MCP share the same Installed row and Discover catalog card. MCP details use the standard detail dialog rather than a permanent split layout.

Reject

No decorative outer body frame, no MCP-only split-page grammar, no duplicated Discover action, no Discover modal, no universal extension backend, no merged persisted schema, and no new state library.

Reference comparison: Claude Code’s plugin manager supports installed/discover/error tasks but does not define OpenProgram Skills or MCP runtime readiness; opencode’s MCP and plugin surfaces do not provide one cross-type management model; Hermes groups skills but lacks the three-type availability summary. The target therefore adopts the shared task vocabulary while retaining OpenProgram-specific live MCP state and Skill hierarchy.

Task brief and acceptance

Approved sources	This document; skills-and-plugins; mcp-integration; current public routes under `/plugins`, `/skills`, and `/mcp`.
Production files	`apps/web/components/capabilities/`, the three management page component folders, `apps/web/components/ui/manage-page*`, and `apps/web/lib/net/fetch-client.ts`.
RED evidence	A focused executable Web check must fail when task vocabulary/status summaries diverge or when a non-2xx extension request has no visible error path.
Required behavior	Each type exposes Installed and Discover as body-owning navigation states; the top toolbar contains only search and refresh; the secondary navigation contains the only Add action; secondary tabs use a quieter visual treatment than the top capability tabs; there is no decorative outer body frame; Plugins, Skills, and MCP Installed use the same row anatomy; all three Discover views use the same catalog-card anatomy; MCP details open in the standard detail dialog rather than a permanent split layout; counts state installed/available/issue meaning; mutations expose progress, success refresh, and actionable error.
Compatibility	Existing URLs, API payloads, store data, secret masking, catalog provenance, Skill hierarchy, plugin trust confirmation, and MCP restart/selection behavior remain unchanged.
Security	No stored secret is retrieved or echoed. Remote catalog policy remains server-side. UI errors must not add credentials or raw secret values.
Exclusions	Programs, agent allowlists, backend schema consolidation, Windows work, keyrings, new marketplaces, and plugin runtime isolation.
Gate manifest	Focused extension-management check; Web unit tests; TypeScript/build check; owner-auth and secret non-retrieval checks; docs link check; diff check; visible desktop and narrow-width acceptance on the default App/18100 instance.

Implementation evidence

Prior visual revision	`f6bad3ac` → `f43c327a` moved Add into the secondary task bar and introduced quieter tabs, but the outer-frame treatment and MCP-specific internal components did not match the approved product language.
Component revision	`74d971ff` → `5e754c2b`. Decorative body frames and the MCP split rail are removed. Installed entries share `ManageRow`; all three Discover views share `ManageCatalogCard`; MCP details use the standard Dialog.
RED / GREEN	The focused check failed on missing shared item/card contracts, then passed with accessibility wiring, owner-auth, secret non-retrieval, TypeScript, 51 Web unit tests, production build, docs links, and diff checks.
Reviews	Specification PASS after complete tab/panel, Switch, and folder-button semantics in `ff3ec9a1`. Quality PASS after in-dialog MCP errors and real Plugins/Skills loading states in `5e754c2b`.
Remaining gate	Visible acceptance is intentionally left to user-provided screenshots or direct user inspection. The full Web gate still stops at the previously reproduced baseline `check:center-tabs` destination-cue assertion outside this subsystem.