Claude Code Plugin Architecture

Overview

Claude Code has a plugin system with 4 extension points: skills (auto-activating knowledge), commands (slash commands), agents (specialized sub-agents), and MCP servers (tool providers). This skill covers building all four.

Prerequisites

• A supported Claude Code environment and an isolated plugin workspace
• A declared ownership boundary for filesystem, network, and credential access
• Validation tooling for manifests, skill metadata, commands, agents, and MCP
• A rollback plan that can disable a plugin without deleting user state

Instructions

Start with the smallest extension point that meets the requirement, declare only the tools and permissions it needs, and validate it locally before adding it to a marketplace or shared environment. Test discovery, activation, failure, and rollback paths; do not expose secrets through examples, environment files, logs, or MCP response payloads.

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: name, version, description, author
├── skills/
│   └── my-skill/
│       └── SKILL.md          # Auto-activating skill
├── commands/
│   └── my-command.md         # Slash command (/my-command)
├── agents/
│   └── my-agent.md           # Custom agent
└── README.md

Building a Skill (SKILL.md)

---
name: my-skill
description: |
  When to activate this skill. Include trigger phrases so Claude
  knows when to use it. Be specific about the problem it solves.
allowed-tools: Read, Write, Edit, Bash(npm:*)
version: 1.0.0
author: Your Name <you@example.com>
license: MIT
compatible-with: claude-code
tags: [category, topic]
---

# Skill Title

## Overview
What this skill does and when to use it.

## Prerequisites
- Claude Code installed
- Understanding of Markdown and YAML frontmatter
- For MCP servers: Node.js 18+ and `@modelcontextprotocol/sdk`

## Instructions
Step-by-step instructions Claude follows when this skill activates.

### Step 1: Do the thing
Explain what to do with code examples.

## Output
What the user should expect when this skill runs.

## Error Handling
| Error | Cause | Solution |
|-------|-------|----------|
| ... | ... | ... |

Building a Slash Command

---
name: my-command
description: "Run my custom workflow"
user-invocable: true
argument-hint: "<file-path>"
allowed-tools: Read, Write, Edit, Bash(npm:*)
version: 1.0.0
---

# /my-command

When the user runs `/my-command <file-path>`, do the following:

1. Read the file at $ARGUMENTS
2. Analyze it for issues
3. Report findings

Building an Agent

---
name: my-agent
description: "Specialized agent for code review"
capabilities: ["code-review", "security-audit"]
model: sonnet
maxTurns: 10
---

# Code Review Agent

You are a code review specialist. When invoked:
1. Read the files provided
2. Check for security issues, code quality, and performance
3. Report findings with specific line references

Building an MCP Server

// src/index.ts
#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({ name: 'my-tools', version: '1.0.0' }, {
  capabilities: { tools: {} },
});

server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'search_docs',
    description: 'Search documentation for a query',
    inputSchema: {
      type: 'object',
      properties: { query: { type: 'string' } },
      required: ['query'],
    },
  }],
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'search_docs') {
    const results = await searchDocs(request.params.arguments.query);
    return { content: [{ type: 'text', text: JSON.stringify(results) }] };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Hooks

// .claude/settings.json
{
  "hooks": {
    "pre-tool-call": [{
      "matcher": "Edit",
      "command": "echo 'About to edit a file'"
    }],
    "post-tool-call": [{
      "matcher": "Bash",
      "command": "echo 'Bash command completed'"
    }]
  }
}

Path Variables

Variable	Context	Resolves To
${CLAUDE_SKILL_DIR}	Skills (bash/DCI)	Skill's directory
${CLAUDE_PLUGIN_ROOT}	Hooks	Plugin root directory
${CLAUDE_PLUGIN_DATA}	Persistent state	Survives updates
$ARGUMENTS	Commands	User-provided args

Error Handling

Condition	Response
Manifest or metadata validation fails	Stop installation, correct the declared contract, and rerun validation.
Plugin requests unapproved capability	Remove or narrowly justify the capability before release.
MCP server fails or returns malformed data	Fail closed, redact diagnostic output, and preserve a correlation ID.
Upgrade changes plugin behavior	Disable or pin the new version and restore the last tested release.

Output

Produce a plugin architecture record identifying the chosen extension point, manifest version, declared tools/permissions, test evidence, release owner, and rollback procedure. Treat a rendered example as illustrative only; the validated manifest and runtime behavior are the operative contract.

Examples

See Building a Skill (SKILL.md), Building a Slash Command, Building an Agent, Building an MCP Server, and Hooks configuration examples above.

Resources

• Plugin Docs
• SKILL.md Spec
• MCP Protocol

Next Steps

See clade-multi-env-setup for managing plugins across environments.