Clade Reference Architecture

---
name: clade-reference-architecture
description: "\"Build Claude Code plugins \\u2014 skills, agents, MCP servers, hooks,\\ \\ and slash commands.\\nUse when working with reference-architecture patterns.\\n\\ The complete guide to extending Claude Code with the Anthropic plugin system.\\n\\ Trigger with \\\"claude code plugin\\\", \\\"build a skill\\\", \\\"create mcp server\\\",\\n\\ \\\"anthropic plugin architecture\\\", \\\"claude code hooks\\\".\\n\""
allowed-tools: "Read, Write, Edit, Bash(npm:*)"
category: engineering-core
source_repo: jeremylongshore/claude-code-plugins-plus-skills
source_path: "skills/.curated/clade-reference-architecture/SKILL.md"
source_url: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/skills/.curated/clade-reference-architecture/SKILL.md
---

# 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.

---

**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `skills/.curated/clade-reference-architecture/SKILL.md`

**Also appears in:** `jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/claude-pack/skills/clade-reference-architecture/SKILL.md`