Chapter 2: Marketplace Architecture and Plugin Structure

Welcome to Chapter 2: Marketplace Architecture and Plugin Structure. In this part of Wshobson Agents Tutorial: Pluginized Multi-Agent Workflows for Claude Code, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

This chapter explains the repository's composable plugin architecture.

Learning Goals

• understand how plugins isolate capabilities
• map relationships between agents, commands, and skills
• identify where marketplace metadata lives
• evaluate plugin design quality quickly

Structural Overview

Key paths:

• .claude-plugin/marketplace.json: plugin catalog metadata
• plugins/<plugin-name>/agents/: specialist agent prompts
• plugins/<plugin-name>/commands/: slash-command behavior
• plugins/<plugin-name>/skills/: progressive-disclosure skill packs
• docs/: operator and contributor documentation

Design Principles

The project emphasizes:

• single-responsibility plugins
• composability over monolithic bundles
• minimal token footprint by selective installs
• maintainable boundaries for updates and reviews

Architecture Review Checklist

• is plugin scope focused and clearly named?
• are command names predictable and discoverable?
• do skills have clear activation criteria?
• is there overlap that should be decomposed further?

Source References

• Architecture Guide
• Marketplace Directory
• Plugins Directory

Summary

You now understand the composable architecture that powers the ecosystem.

Next: Chapter 3: Installation and Plugin Selection Strategy

Source Code Walkthrough

Note: wshobson/agents is a collection of Claude Code plugin definitions (YAML/Markdown prompt files), not a traditional compiled library. The architecture is expressed through directory structure and file conventions rather than executable code.

docs/architecture.md

The architecture guide explains the composable plugin design: how plugins/<name>/agents/, plugins/<name>/commands/, and plugins/<name>/skills/ directories implement the single-responsibility principle described in this chapter.

.claude-plugin/marketplace.json

The marketplace manifest is the structural root of the plugin catalog — it maps plugin names to their directory paths, categories, and descriptions, making the composability model concrete.

How These Components Connect

flowchart TD
    A[marketplace.json] -->|catalog metadata| B[Plugin Discovery]
    B -->|points to| C[plugins/name/agents/]
    B -->|points to| D[plugins/name/commands/]
    B -->|points to| E[plugins/name/skills/]
    C --> F[specialist agent prompt files]
    D --> G[slash command definitions]
    E --> H[progressive-disclosure skill packs]