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.

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)

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

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

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

typescript
// 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

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

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.