clade-reference-architecture

# 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](https://docs.anthropic.com/en/docs/claude-code/plugins)
- [SKILL.md Spec](https://docs.anthropic.com/en/docs/claude-code/skills)
- [MCP Protocol](https://modelcontextprotocol.io)

## Next Steps
See `clade-multi-env-setup` for managing plugins across environments.