# Anthropic Claude Plugin Structure: How File Layout Maps to Model Execution

> Explore the Anthropic Claude plugin structure and understand how its file layout directly maps to model execution. Discover how Claude accesses domain knowledge and tools without compiled code.

- Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
- Tags: architecture
- Published: 2026-05-25

---

**The knowledge-work-plugins repository uses a strict file-system layout that acts as a direct contract with Claude's runtime, allowing the model to discover domain knowledge, register slash-commands, and invoke external tools without compiled code.**

The `anthropics/knowledge-work-plugins` repository demonstrates how Anthropic extends Claude through self-contained plugin bundles. Each plugin follows a declarative architecture where JSON manifests and markdown skill files define how Claude processes user requests and interacts with external services.

## The File Layout Contract

The repository structure mirrors Claude's execution expectations exactly. When Claude loads a plugin, it interprets specific directories and files as functional components of its reasoning system.

### Plugin Manifest ([`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json))

The [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json) file serves as the registration entry point. Located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) within each plugin directory, this JSON file contains the plugin name, version, description, and author metadata. Claude reads this manifest during installation to register the bundle namespace, enabling the model to reference the plugin in prompts using slash notation (e.g., `/productivity:...`).

### MCP Connector Definitions ([`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json))

The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file defines MCP (Model-Context-Protocol) server endpoints. This connector specification lists authentication scopes, required environment variables, and server configurations that Claude uses at runtime to route tool calls. When a user requests actions like "search Slack" or "run a notebook," Claude consults this file to determine how to reach the external service.

### Domain Knowledge Base (`skills/`)

The `skills/` directory contains a hierarchy of markdown files ([`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md)) that encode best-practice workflows and domain expertise. Files like [`product-management/skills/write-spec/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/product-management/skills/write-spec/SKILL.md) contain structured "Trigger → Action" descriptions with templated prompts. Claude indexes these automatically, converting headings and bullet points into internal knowledge chunks that the model surfaces when conversation context matches the skill's triggers.

### Explicit Commands (`commands/`)

The `commands/` directory exposes UI-accessible slash-commands through JSON descriptors. Each file maps a command name (e.g., `sales:call-prep`) to a specific skill entry point. When users invoke these commands directly, Claude bypasses natural-language matching and jumps immediately to the associated skill logic.

## How Claude Processes Plugin Files

When Claude loads a plugin from the knowledge-work-plugins repository, it executes a four-phase initialization sequence:

1. **Parse [`plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/plugin.json)** – Registers the plugin name and version, establishing the namespace for subsequent references.
2. **Index [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) files** – Recursively processes every markdown file in `skills/`, extracting triggers and prompts into searchable knowledge chunks.
3. **Load MCP connections** – Reads [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) to create callable tool endpoints within Claude's tool-use sandbox.
4. **Register UI commands** – Exposes slash-commands from the `commands/` folder to the user interface surface.

This process requires no compilation or binary execution; Claude interprets the plain JSON and markdown files directly.

## Runtime Architecture

The architectural flow demonstrates how static files translate into dynamic model behavior:

Claude Runtime → Load plugin manifest ([`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json)) → Register plugin name/version  
↓  
Discover skills (`skills/**/*.SKILL.md`) → Index skill triggers and prompts  
↓  
Read MCP spec ([`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json)) → Create tool endpoints  
↓  
Expose UI commands (`commands/*`)  
↓  
User conversation → Claude matches request to skill or command → If tool call required, invoke MCP endpoint → Return data to Claude for continued reasoning

In [`productivity/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/productivity/.claude-plugin/plugin.json), the manifest declares the plugin identity (name: `productivity`, version: `1.2.0`). When a user asks "Help me plan my day," Claude queries its indexed knowledge chunks, finds the productivity skill describing daily planning workflows, and executes the encoded guidance. If the skill requires external data, Claude constructs a tool call like `tool_use("slack.search", {"query":"project X"})` using the connector definitions from [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json).

## Practical Usage Examples

### Installing Plugins via Claude Code

Register the marketplace and install specific plugins using the CLI:

```bash

# Register the marketplace first

claude plugin marketplace add anthropics/knowledge-work-plugins

# Install the "sales" plugin from the repo

claude plugin install sales@knowledge-work-plugins

```

The CLI reads [`sales/.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/.claude-plugin/plugin.json) to identify the plugin metadata, then loads all files from `sales/skills/` into Claude's knowledge store.

### Invoking Slash Commands

In a Claude Code chat session, explicit commands trigger specific skill workflows:

```

/sales:call-prep

```

Claude resolves this command to the `sales` plugin descriptor, then executes the underlying skill at [`sales/skills/call-prep/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/sales/skills/call-prep/SKILL.md). The skill gathers recent CRM notes via the MCP-defined Salesforce connector and drafts a meeting agenda using the skill's templated prompts.

### Automatic Skill Triggering

Natural language requests trigger skills based on context matching:

**User:** "I need a roadmap for the new feature."

Claude's reasoning engine scans indexed skills and matches the request to the **product-management/write-spec** skill. The model then runs the skill's step-by-step guidance, pulling data from connectors defined in [`product-management/.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/product-management/.mcp.json) (e.g., JIRA tickets, Figma mockups) without explicit command invocation.

### Direct MCP Tool Invocation

Advanced users can invoke MCP tools directly from prompts:

```python
tool_use("slack.search", {"query":"Q4 sales forecast"})

```

Claude looks up the `slack` entry in the plugin's [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json), creates a temporary tool call to the Slack MCP server, receives the message list, and incorporates it into the response context.

## Summary

- The **file-system layout is the execution contract** between the repository and Claude's runtime, requiring no compiled binaries.
- **[`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json)** registers plugin identity and version with Claude's namespace system.
- **[`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json)** defines external tool connectors that Claude invokes via the Model-Context-Protocol.
- **`skills/`** directories contain markdown-encoded domain knowledge that Claude indexes and matches conversationally.
- **`commands/`** expose explicit UI entry points that bypass natural-language matching.

## Frequently Asked Questions

### What is the purpose of the [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) file?

The [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) file acts as the plugin manifest that tells Claude the bundle's name, version, description, and author. Claude reads this file once during installation to register the plugin namespace, allowing the model to reference the plugin in system prompts and slash commands.

### How does Claude know when to use a specific skill from the `skills/` directory?

Claude automatically indexes every [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file into internal knowledge chunks containing trigger phrases and action descriptions. When user conversation context aligns with a skill's documented triggers—such as requesting "daily planning" matching the productivity skill—Claude surfaces that skill's guidance automatically without explicit command invocation.

### What role does the [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file play in plugin execution?

The [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json) file defines MCP (Model-Context-Protocol) server configurations that become callable tools in Claude's execution sandbox. When a skill requires external data or actions, Claude consults this file to construct tool calls to services like Slack, Salesforce, or custom REST APIs, handling authentication and endpoint routing automatically.

### Can plugins execute code, or are they limited to configuration files?

Plugins in the knowledge-work-plugins repository contain only declarative configuration—JSON manifests and markdown skill files. Claude interprets these files directly; no compiled code or binaries execute within the plugin bundle. External code execution occurs only through MCP server tool calls defined in [`.mcp.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.mcp.json), which run in isolated environments.