# Core Concepts of the Plugin Architecture: Skills, Commands, and MCP > Explore the core concepts of the Plugin Architecture: skills, commands, and MCP. Discover how declarative JSON manifests, Markdown skills, and MCP connectors empower Claude as a domain specialist effortlessly. - Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins) - Tags: deep-dive - Published: 2026-05-30 --- **The Knowledge Work Plugins architecture employs a declarative, file-based system where JSON manifests declare capabilities, Markdown skills encode domain logic with automatic triggers, and MCP connectors abstract external APIs into logical categories, enabling Claude to act as a domain specialist without any compiled code.** The `anthropics/knowledge-work-plugins` repository implements a unique approach to extending Claude's capabilities through static configuration rather than traditional software extensions. This architecture transforms Claude into a role-specific specialist—such as a sales assistant or research analyst—using only Markdown documentation, JSON configuration files, and the Model Context Protocol (MCP). Every plugin is a self-contained directory that Claude discovers and loads at runtime, requiring no build pipeline or code compilation. ## The Four Pillars of Plugin Architecture ### Plugin Manifest ([`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json)) Every plugin begins with a manifest file located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) that declares the plugin's identity and metadata. This JSON file serves as the entry point for Claude's plugin discovery system, specifying the plugin name, version, and description without requiring any code execution. ```json { "name": "sales", "version": "1.0.0", "description": "Sales specialist plugin for CRM workflows" } ``` Claude scans for these manifest files at startup to build the list of available capabilities. The manifest in the sales plugin at [`sales/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.claude-plugin/plugin.json) demonstrates this lightweight declaration pattern. ### MCP Connectors ([`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json)) The **Model Context Protocol (MCP)** connector configuration abstracts external SaaS integrations through logical category names. The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file maps placeholders like `~~crm` or `~~slack` to concrete MCP server endpoints, making skills **tool-agnostic**. ```json { "connectors": { "crm": "http://localhost:3001/mcp", "slack": "http://localhost:3002/mcp" } } ``` When a skill references `~~crm`, Claude resolves this placeholder using the plugin's [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) configuration and routes the request through the MCP server, which handles authentication and proxies the call to the actual API—whether Salesforce, HubSpot, or a custom internal system. ### Skills (`skills/**/*.md`) **Skills** are the primary automation engine, implemented as Markdown files with YAML frontmatter that defines triggers, workflow phases, and MCP dependencies. Located in the `skills/` directory, each skill encodes domain knowledge and step-by-step procedures that Claude executes when specific conditions are met. ```yaml --- name: create-an-asset description: Generate tailored sales assets from deal context. --- # Create an Asset ## Triggers - User says `/create-an-asset` or `/create-an-asset AcmeCorp` - User asks "make a landing page" or "build a deck" ## Workflow 1. Search prospect details: `search: "[Company]" site:linkedin.com` 2. Query CRM: ~~crm ``` The frontmatter defines when Claude should activate the skill, while the Markdown body describes how to execute the task. Skills automatically bind to slash commands matching their filename, though explicit command definitions can override this behavior. ### Optional Commands (`commands/`) While skills can be invoked through natural language triggers or implicit slash commands, the optional `commands/` directory provides explicit **UI entry points** for deterministic invocation. These are thin wrappers that map specific slash commands—such as `/sales:call-prep`—to their corresponding skills. ```markdown --- name: call-prep description: Prepare a sales call by gathering prospect context. --- /sales:call-prep ``` In practice, most plugins omit this directory because the filename of the skill in `skills/` automatically generates the slash command, but explicit command files allow for custom naming conventions or additional metadata for toolbar integrations. ## How Skills, Commands, and MCP Interact The architecture follows a clear execution pipeline that transforms user intent into external tool actions: 1. **Intent Detection**: Claude parses user input against **Triggers** defined in skill frontmatter, matching either explicit slash commands (e.g., `/create-an-asset`) or natural language patterns (e.g., "make a landing page"). 2. **Skill Selection**: Upon trigger match, Claude loads the corresponding Markdown skill file from `skills/` and initializes the execution context. 3. **MCP Resolution**: When the skill workflow encounters a connector placeholder like `~~crm`, Claude consults the plugin's [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) to resolve the logical name to a concrete MCP server URL. 4. **External Execution**: Claude issues an HTTP request to the MCP server endpoint, which authenticates with the third-party API (Salesforce, Slack, Notion, etc.) and returns structured data. 5. **Context Integration**: The skill processes the returned data through its defined workflow phases, filling templates and applying domain logic encoded in the Markdown. 6. **Result Delivery**: Claude synthesizes the final output—whether text, HTML, or file attachments—and returns it to the user, completing the specialized task. This flow is entirely **declarative**; the plugin contains no executable code, only configuration and documentation that Claude interprets at runtime. ## Key Architectural Principles **File-Based Discovery**: Claude identifies plugins by scanning directory trees for [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) files. This static approach enables version control, forking, and customization without dependency management or compilation steps. **Category-Agnostic Connectors**: By referencing logical categories (`crm`, `slack`, `notion`) rather than specific vendors, skills remain portable across different enterprise environments. The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file handles the environmental binding, allowing the same skill to work with HubSpot in one organization and Salesforce in another. **Skill-Driven Automation**: Skills encapsulate both the *when* (triggers) and *how* (workflow phases) of domain tasks. They serve as the "brain" of the plugin, encoding institutional knowledge that would traditionally reside in custom application code. **Zero-Build Deployment**: Because all components are JSON or Markdown files, plugins deploy via standard file copying or Git clone operations. There are no binaries to compile, containers to build, or package managers to configure. ## Practical Code Examples ### Defining a Skill with Triggers The [`sales/skills/create-an-asset/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/skills/create-an-asset/SKILL.md) file demonstrates the frontmatter pattern that enables automatic invocation: ```yaml --- name: create-an-asset description: Generate tailored sales assets from deal context. --- ## Triggers - /create-an-asset - "build a deck for [Company]" ``` ### Referencing MCP Connectors Skills interact with external systems through placeholder syntax that [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) resolves at runtime: ```yaml Actions: 1. Fetch deal data: ~~crm/opportunities/{deal_id} 2. Post to channel: ~~slack/channels/sales ``` ### Explicit Command Definition When implicit naming is insufficient, define precise slash commands in [`commands/call-prep.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/commands/call-prep.md): ```markdown --- name: call-prep --- /sales:call-prep ``` ## Summary - **Plugin Manifest**: The [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) file declares plugin metadata and enables discovery without code execution. - **MCP Connectors**: The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file abstracts external APIs into logical categories like `~~crm`, making plugins tool-agnostic and environment-portable. - **Skills**: Markdown files in `skills/` define automation logic, triggers, and workflows, serving as the primary interface for domain expertise. - **Commands**: Optional `commands/` files provide explicit slash-command mappings for UI integration, though skills often auto-generate these from filenames. - **Declarative Architecture**: The entire system uses static JSON and Markdown files, eliminating build pipelines and enabling version-controlled customization. ## Frequently Asked Questions ### What is the difference between a skill and a command? A **skill** is a comprehensive Markdown document containing domain logic, workflow steps, trigger patterns, and MCP references that defines *how* to accomplish a task. A **command** is an optional, thin wrapper—often just a few lines of frontmatter—that provides a deterministic slash-command entry point (e.g., `/sales:call-prep`) for UI toolbars or explicit user invocation. In most implementations, the command filename simply references the skill, and many plugins omit explicit command files entirely since skills automatically expose slash commands based on their filenames. ### How does MCP make plugins tool-agnostic? The **Model Context Protocol (MCP)** introduces an abstraction layer through the [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) configuration file, which maps logical connector names like `~~crm` or `~~slack` to concrete MCP server endpoints. Skills reference only these logical categories rather than specific vendor APIs. This means a skill requesting `~~crm` works equally with Salesforce, HubSpot, or a custom internal CRM, provided the deployment environment's [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) points the logical name to the appropriate MCP server. This architectural decision decouples the domain logic from external service implementations. ### Do plugins require compilation or build steps? No. The Knowledge Work Plugins architecture is **fully declarative** and contains no compiled code. All components—manifests, skills, commands, and connector configurations—are static JSON or Markdown files. Deployment requires only copying or cloning the plugin directory to a location Claude can access. This file-based approach eliminates dependency management, build pipelines, and runtime compilation, making plugins immediately inspectable, version-controllable, and customizable using standard text editors. ### How does Claude discover available plugins? Claude performs **file-system scanning** at startup to locate plugins, specifically searching for [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) files within the configured plugin directories. Upon finding a manifest, Claude loads the plugin's metadata and scans the `skills/` directory to build an index of available triggers and commands. This discovery mechanism requires no registration API or centralized marketplace; simply placing a properly structured directory in the plugins folder makes the capabilities available immediately.