ADR-0010: Plugin-Aware Studio UI¶

Status: Accepted Date: 2026-05-20 Extends: ADR-0003 (marketplace), ADR-0007 (auto-discovery), ADR-0009 (SQLite state layer)

Context¶

Lion Studio currently presents skills, agents, and playbooks as flat lists scanned from ~/.lionagi/{skills,agents,playbooks}/. This ignores the plugin structure established in ADR-0003: four marketplace plugins at marketplace/ already group skills and agents by capability domain (devx, show, orchestrate, etc.).

The Skills page (62 skills) has no grouping — users see commit, fmt, ci next to flow-it, reprompt, write-playbook with no indication they belong to different plugins. Agent and playbook definitions are versioned through the definitions API (ADR-0016) but not associated with their parent plugin.

Claude Code's plugin format provides a standard packaging unit: plugin.json manifest + skills/, agents/, hooks/, .mcp.json, output-styles/, monitors/, themes/, bin/, settings.json. Studio should present this structure faithfully — it becomes the visual management layer for what CC loads.

Decision¶

1. Plugin discovery backend (services/plugins.py)¶

A new service scans two locations for plugins:

For each plugin directory, the service:

• Reads .claude-plugin/plugin.json for metadata (name, version, description)
• Falls back to directory name if no manifest exists
• Enumerates skills/*/SKILL.md, agents/*.md, hooks/hooks.json, .mcp.json
• Returns component counts and lists per plugin

The marketplace manifest (.claude-plugin/marketplace.json) provides the canonical list for repo plugins. Third-party plugins are discovered by directory scan.

2. API surface¶

GET  /api/plugins/              → list all plugins with component counts
GET  /api/plugins/{name}        → plugin detail: metadata + component lists
GET  /api/plugins/{name}/skills/{skill}  → skill content (read-only)
GET  /api/plugins/{name}/agents/{agent}  → agent content (read-only view; editing via Agents page)

The existing /api/skills/, /api/agents/, and /api/definitions/ endpoints remain — the plugins API is the grouping/browsing layer, not an editing surface.

3. Frontend: Plugins replaces Skills in nav¶

Navigation changes from Playbooks | Agents | Skills | Runs | Shows to Playbooks | Agents | Plugins | Shows | Runs.

Plugin list page: cards showing name, description, source badge (marketplace name or Lion Marketplace), component counts (N skills, M agents).

Plugin detail page: tabbed layout:

• Skills tab: two-pane list+detail, read-only SKILL.md viewer
• Agents tab: agent names/descriptions with Open in Agents → cross-links
• Hooks tab: hooks.json viewer (read-only)
• MCP tab: .mcp.json viewer (read-only)
• README tab: rendered markdown (proportional font for prose)

Editability matrix¶

Skills are not editable through the definitions API. They are Claude Code skill instructions, not lionagi definitions. The Plugins page is a read-only browser with cross-links to editable surfaces (Agents, Playbooks).

4. Third-party plugins are read-only¶

Plugins from ~/.claude/plugins/cache/ are displayed but not editable. The cache is managed by Claude Code's plugin add/remove commands. Studio surfaces them for visibility, not management.

5. Cross-links and source badges (added post-review)¶

Plugin components need explicit navigation to their editable counterparts and clear source/editability indicators:

Cross-links from plugin detail tabs:

• Agent tab: Open in Agents → link per agent (routes to /agents/{name})
• Skill tab: View source link, Copy path action
• All tabs: Open raw for filesystem path

Source badges on plugin list and detail:

Empty plugin stubs (0 skills, 0 agents) are de-emphasized — muted row treatment, grouped under "Scaffolded" section — but not hidden, since hiding them complicates plugin discovery debugging.

Skill search: Add a filter input inside the selected plugin's Skills tab, not just the plugin-level filter.

Markdown rendering: README and skill docs render prose in proportional font with code fences in monospace, not the current all-monospace treatment.

6. Deferred: CLI sync, monitors, themes, LSP¶

These are not part of this ADR:

• li plugin sync CLI (marketplace → CC plugin install) — separate feature
• Monitors, themes, LSP components — surface in Studio when usage warrants
• Model-agnostic abstraction — current format is CC-native; abstract later

Consequences¶

Positive

• Skills and agents gain context: users see which plugin provides each capability.
• Editing flows through existing definitions versioning — no new persistence layer.
• Third-party plugin visibility without management complexity.
• Direct alignment with CC's plugin model — what you see in Studio is what CC loads.

Negative

• Plugin discovery adds startup scan cost (~22ms for 4 plugins, negligible).
• Two navigation paths to the same skill (Plugins → devx → commit vs. direct URL).
• plugin.json may not exist for all marketplace plugins yet — fallback to dir name.

Alternatives Considered¶

Implementation¶

Two parallel agents:

1. Backend: services/plugins.py + routers/plugins.py — plugin scanner, API endpoints
2. Frontend: /plugins page (list + detail with tabs), Shell nav update, API client types

Both build on existing patterns: services/skills.py for scanning, app/agents/page.tsx for two-pane layout, lib/api.ts for type-safe fetch wrappers.