component-patterns

flowchart LR
    User["User action"] --> Cmd["Command — user types /command"]
    Context["Task context"] --> Skill["Skill — description matches task"]
    Context --> Agent["Agent — capabilities match task"]
    Event["System event"] --> Hook["Hook — event matches registration"]
    ToolCall["Tool call"] --> MCP["MCP Server — capability matches call"]

flowchart TD
    Start(["What do you need<br>to add to your plugin?"]) --> Q1{"Does it need to<br>intercept or validate<br>tool calls or events?"}
    Q1 -->|"Yes — gate writes,<br>enforce policies,<br>inject context on events"| Hook["Use a Hook<br>Create with /plugin-creator:hook-creator"]
    Q1 -->|No| Q2{"Does it provide<br>external tool access<br>via API or process?"}
    Q2 -->|"Yes — database queries,<br>API calls, file processing<br>via external process"| MCP["Use an MCP Server<br>Create with /fastmcp-creator"]
    Q2 -->|No| Q3{"Does it need its own<br>identity, tools, model,<br>or permission scope?"}
    Q3 -->|"Yes — specialized worker<br>with restricted tools<br>or different model"| Agent["Use an Agent<br>Create with /plugin-creator:agent-creator"]
    Q3 -->|No| Q4{"Is it domain knowledge,<br>a workflow, or a<br>procedural guide?"}
    Q4 -->|"Yes — reference material,<br>multi-step process,<br>best practices"| Skill["Use a Skill<br>Create with /plugin-creator:skill-creator"]
    Q4 -->|"No — simple user-triggered<br>action with bash execution"| Command["Use a Command (legacy)<br>See /plugin-creator:command-development"]

    Hook --> HookNote["Events — PreToolUse, PostToolUse,<br>Stop, Notification, SubagentStop"]
    MCP --> MCPNote["Transports — stdio, SSE,<br>HTTP, WebSocket"]
    Agent --> AgentNote["Frontmatter — name, description,<br>tools, model, skills, hooks"]
    Skill --> SkillNote["Progressive disclosure —<br>SKILL.md + references/"]
    Command --> CmdNote["Legacy format —<br>prefer skills for new work"]

flowchart TD
    subgraph Components["Component Capabilities"]
        direction LR
        H["Hook"]
        M["MCP Server"]
        A["Agent"]
        S["Skill"]
        C["Command"]
    end

    subgraph Traits["Key Differentiators"]
        direction LR
        H --- HT["Intercepts events and tool calls<br>Can block or modify operations<br>Runs on system events"]
        M --- MT["Provides tools via external process<br>Persistent server with its own state<br>Accessed through tool calls"]
        A --- AT["Has its own identity and tool scope<br>Can use a different model<br>Selected by capability matching"]
        S --- ST["Provides knowledge and workflows<br>Activated by context matching<br>Progressive disclosure via references/"]
        C --- CT["User-triggered via /name<br>Can execute bash commands<br>Legacy — skills preferred for new work"]
    end

flowchart TD
    subgraph Commands["Command Patterns"]
        CF["Flat — up to 15 commands"]
        CC["Categorized — 15+ with functional groups"]
        CH["Hierarchical — 20+ with nested structure"]
    end

    subgraph Agents["Agent Patterns"]
        AR["Role-based — distinct non-overlapping roles"]
        AC["Capability-based — technology or domain expertise"]
        AW["Workflow-based — pipeline stage specialists"]
    end

    subgraph Skills["Skill Patterns"]
        ST["Topic-based — knowledge and reference content"]
        SL["Tool-based — specific tool or technology expertise"]
        SW["Workflow-based — multi-step process automation"]
        SR["Rich resources — SKILL.md + references/ + scripts/ + assets/"]
    end

    subgraph Hooks["Hook Patterns"]
        HM["Monolithic — single hooks.json, up to 10 hooks"]
        HE["Event-based — separate config per event type"]
        HP["Purpose-based — grouped by security, quality, workflow"]
    end

plugin/
├── commands/
│   └── test.md        # references lib/test-utils.sh
├── agents/
│   └── tester.md      # references lib/test-utils.sh
├── hooks/
│   └── scripts/
│       └── pre-test.sh # sources lib/test-utils.sh
└── lib/
    ├── test-utils.sh
    └── deploy-utils.sh

plugin/
├── commands/          # User interface layer
├── agents/            # Orchestration layer
├── skills/            # Knowledge layer
└── lib/
    ├── core/          # Core business logic
    ├── integrations/  # External service adapters
    └── utils/         # Shared helper functions

plugin/
├── .claude-plugin/
│   └── plugin.json
├── core/
│   ├── commands/
│   └── agents/
└── extensions/
    ├── extension-a/
    │   ├── commands/
    │   └── agents/
    └── extension-b/
        ├── commands/
        └── agents/