Core Concepts of the Plugin Architecture: Skills, Commands, and MCP

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)

Every plugin begins with a manifest file located at .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.

{
  "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 demonstrates this lightweight declaration pattern.

MCP Connectors (.mcp.json)

The Model Context Protocol (MCP) connector configuration abstracts external SaaS integrations through logical category names. The .mcp.json file maps placeholders like ~~crm or ~~slack to concrete MCP server endpoints, making skills tool-agnostic.

{
  "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 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.

---
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.

---
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 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 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 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 file demonstrates the frontmatter pattern that enables automatic invocation:

---
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 resolves at runtime:

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:

---
name: call-prep
---

/sales:call-prep

Summary

• Plugin Manifest: The .claude-plugin/plugin.json file declares plugin metadata and enables discovery without code execution.
• MCP Connectors: The .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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}