feat: Add component metadata to plugin.json for improved discoverability

[richlira]

Summary

This is a proposal to improve plugin discoverability in Claude Code by extending the plugin.json schema with component metadata.

Problem

When users browse plugins, they only see name + description. There's no way to know:

• What components a plugin includes (agents, commands, skills, hooks, MCPs)
• The "weight" or complexity of a plugin
• How much context/tokens a plugin consumes
• Whether it fits their use case

Solution

Extend plugin.json with optional fields:

{
  "components": {
    "agents": ["code-reviewer", "code-architect"],
    "commands": ["feature-dev"],
    "skills": [],
    "hooks": [],
    "mcpServers": []
  },
  "metadata": {
    "tags": ["development", "workflow"],
    "estimatedTokens": 8500
  }
}

Changes

• 12 modified: Updated all existing plugin.json files with component metadata
• 1 new file: Added missing plugin.json for plugin-dev plugin
• 1 RFC: proposals/001-plugin-component-badges.md - Full proposal for UI changes

---

Proposed UI Changes (requires Claude Code implementation)

1. Component Badges in Plugin List

Display component counts and token impact as compact badges:

pr-review-toolkit v1.0.0
├─ 🤖 6 agents  ⚡ 1 command  📝 0 skills  🪝 0 hooks
├─ 🏷️ code-review, pull-request, testing, quality
└─ 📊 ~12,000 tokens

hookify v0.1.0
├─ 🤖 1 agent  ⚡ 4 commands  📝 1 skill  🪝 4 hooks
├─ 🏷️ hooks, automation, rules, behavior
└─ 📊 ~5,200 tokens

security-guidance v1.0.0
├─ 🪝 1 hook
├─ 🏷️ security, owasp, xss, injection, safety
└─ 📊 ~800 tokens (lightweight)

2. Expanded View on Selection

When a user clicks/selects a plugin, show detailed composition:

┌─────────────────────────────────────────────────────────────┐
│  pr-review-toolkit v1.0.0                                   │
│  Comprehensive PR review agents specializing in comments,   │
│  tests, error handling, type design, and code quality       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Agents (6):                    Commands (1):               │
│  • code-reviewer                • /review-pr                │
│  • code-simplifier                                          │
│  • comment-analyzer             Skills (0)                  │
│  • pr-test-analyzer                                         │
│  • silent-failure-hunter        Hooks (0)                   │
│  • type-design-analyzer                                     │
│                                 MCP Servers (0)             │
│                                                             │
│  Tags: code-review, pull-request, testing, quality          │
│                                                             │
│  ┌─ Context Impact ───────────────────────────────────────┐ │
│  │  📊 Estimated: ~12,000 tokens                          │ │
│  │  ⚠️  This plugin adds significant context overhead.    │ │
│  │     Consider for dedicated code review sessions.       │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
│  [Install]  [View Source]                                   │
└─────────────────────────────────────────────────────────────┘

3. Filter Options in Discover/Marketplace

Allow users to filter plugins by component type, tags, and context impact:

┌─ Filter Plugins ─────────────────────────────┐
│                                              │
│  Component Type:                             │
│  [x] Has agents                              │
│  [ ] Has skills                              │
│  [ ] Has hooks                               │
│  [ ] Has MCP servers                         │
│                                              │
│  Context Impact:                             │
│  ○ Any                                       │
│  ○ Lightweight (<2k tokens)                  │
│  ● Medium (2k-10k tokens)                    │
│  ○ Heavy (>10k tokens)                       │
│                                              │
│  Tags:                                       │
│  [ workflow ] [ security ] [ git ]           │
│  [ code-review ] [ development ] [ ui ]      │
│                                              │
└──────────────────────────────────────────────┘

4. Quick Comparison View

Enable side-by-side comparison of similar plugins:

┌────────────────────────┬────────────────────────┐
│  code-review           │  pr-review-toolkit     │
├────────────────────────┼────────────────────────┤
│  🤖 0 agents           │  🤖 6 agents           │
│  ⚡ 1 command          │  ⚡ 1 command          │
│  📝 0 skills           │  📝 0 skills           │
│  🪝 0 hooks            │  🪝 0 hooks            │
│  📊 ~3k tokens         │  📊 ~12k tokens        │
├────────────────────────┼────────────────────────┤
│  Simpler, lightweight  │  Comprehensive with    │
│  single command        │  specialized agents    │
│                        │  Higher context cost   │
└────────────────────────┴────────────────────────┘

5. Context Budget Awareness

Show users their available context and plugin impact:

┌─ Your Context Budget ────────────────────────────────────┐
│                                                          │
│  Total available: 200,000 tokens                         │
│  Currently used by plugins: 18,500 tokens (9.25%)        │
│                                                          │
│  Installed plugins:                                      │
│  • pr-review-toolkit     📊 12,000 tokens                │
│  • commit-commands       📊  1,500 tokens                │
│  • hookify               📊  5,000 tokens                │
│                                                          │
│  💡 Tip: Disable unused plugins to free up context       │
│                                                          │
└──────────────────────────────────────────────────────────┘

---

Token Estimation Methodology

The estimatedTokens field could be calculated by:

1. Static analysis: Sum of all prompt/instruction text in agents, skills, commands
2. Runtime sampling: Measure actual token usage during typical sessions
3. Manual estimation: Author provides approximate value based on content size

Suggested categories:

Category	Token Range	Examples
Lightweight	<2,000	security-guidance, commit-commands
Medium	2,000-10,000	hookify, feature-dev
Heavy	>10,000	pr-review-toolkit, plugin-dev

---

Backwards Compatibility

• New fields are optional - existing plugins without them continue to work
• JSON parsers typically ignore unknown fields
• UI should gracefully degrade when fields are missing:

// Graceful handling of missing components
const agents = plugin.components?.agents ?? [];
const tokens = plugin.metadata?.estimatedTokens;

if (agents.length > 0) showBadge('agents', agents.length);
if (tokens) showTokenBadge(tokens);

Test plan

• Verify existing Claude Code version doesn't break with new fields
• Review RFC proposal in proposals/001-plugin-component-badges.md

---

🤖 Generated with Claude Code