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

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)

The plugin.json file serves as the registration entry point. Located at .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)

The .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) that encode best-practice workflows and domain expertise. Files like 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 – Registers the plugin name and version, establishing the namespace for subsequent references.
2. Index 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 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) → Register plugin name/version
↓
Discover skills (skills/**/*.SKILL.md) → Index skill triggers and prompts
↓
Read MCP spec (.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, 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.

Practical Usage Examples

Installing Plugins via Claude Code

Register the marketplace and install specific plugins using the CLI:

# 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 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. 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 (e.g., JIRA tickets, Figma mockups) without explicit command invocation.

Direct MCP Tool Invocation

Advanced users can invoke MCP tools directly from prompts:

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

Claude looks up the slack entry in the plugin's .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 registers plugin identity and version with Claude's namespace system.
• .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 file?

The .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 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 file play in plugin execution?

The .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, which run in isolated environments.

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