Claude Code on Yarang's Tech Lair

Claude Code Plugin Development Complete Guide — From plugin.json to Deployment

Mon, 23 Mar 2026 10:53:23 +0900

# Claude Code Plugin Development Complete Guide — From plugin.json to Deployment

Claude Code CLI officially supports the **plugin system** starting from `v2.1.0`. By combining four components—skills, agents, commands, and hooks—you can package Claude's behavior like a tool and deploy it across your team. Based on the actual operational `yarang-plugins` marketplace repo, this article explains step-by-step so that developers creating a plugin for the first time can make it all the way to deployment.

---

## What is a Plugin? — The 4 Components of Claude Code Extensions

Claude Code plugins are not just simple script bundles. By combining the following four elements, you declaratively define Claude's roles and behaviors.

| Component | Directory | Role |
|---|---|---|
| **skills** | `skills/<name>/SKILL.md` | Inject specific domain knowledge and behavioral rules into Claude |
| **agents** | `agents/<role>.md` | Define sub-agent personas (assign expert roles) |
| **commands** | `commands/<verb>-<noun>.md` | Register /slash-command shortcuts |
| **hooks** | `hooks/hooks.json` | Automatic execution triggers before/after tool calls |

```mermaid
graph TD
 A[User Request] --> B[Command /create-post]
 B --> C[Load Skill blog-writer]
 C --> D[Execute Claude Writing]
 D --> E{Call Write Tool}
 E --> F[Execute Hook PostToolUse]
 F --> G[Automatic SEO Review]
 G --> H[Final Output]

Step 1: Create Directory Structure

Plugin names must be written in kebab-case in the format <domain>-<function>. Examples: blog-writer, domain-checker.

plugins/blog-writer/
├── .claude-plugin/
│ └── plugin.json ← Plugin metadata (required)
├── skills/
│ └── blog-writer/
│ └── SKILL.md ← Skill file name is fixed as SKILL.md
├── agents/
│ └── editor.md ← <role>.md format
├── commands/
│ └── create-post.md ← <verb>-<noun>.md format
├── hooks/
│ └── hooks.json ← hooks are only declared here
└── README.md

If you violate the file naming conventions, Claude Code will not recognize the file.

Step 2: Write plugin.json — Core of Metadata

plugin.json is the plugin’s ID card. If you specify only the directory paths in the skills, commands, and agents fields, it automatically explores the internal files.

{
 "name": "blog-writer",
 "description": "A skill plugin that structurally writes SEO-optimized blog posts",
 "author": {
 "name": "yarang",
 "url": "https://github.com/yarang"
 },
 "license": "MIT",
 "keywords": ["blog", "seo", "writing", "content"],
 "skills": "./skills/",
 "commands": "./commands/"
}

3 Important Notes:

Do not include the version field in plugin.json — Internal plugins only declare versions in marketplace.json.
Do not specify the hooks field here — v2.1+ automatically detects hooks/hooks.json.
Referencing paths outside the plugin directory using ../ is prohibited.

Step 3: Write SKILL.md — Inject Claude’s Expertise

A skill is a markdown document that injects behavioral rules and knowledge of a specific domain into Claude. Let’s look at the SKILL.md of the blog-writer plugin as an example.

# Blog Writer Skill

Writes an SEO-optimized blog post on a given topic.

## Structure

1. **Title (H1)**: Includes keywords, encourages clicks
2. **Introduction**: Raise reader's problem, introduce content covered
3. **Body**: Structured with H2/H3 subheadings, naturally includes core keywords
4. **Conclusion**: Core summary, Call to Action (CTA)

## Guidelines

- Sentences should be clear
- Write sufficient explanations in paragraphs
- Include keywords readers search for in the title and first paragraph
- Focus on practical information
- Also include diagrams

SKILL.md is injected like a system prompt when Claude is called with that skill. The more specific the behavioral guidelines, the higher the output quality.

Step 4: agents/ — Define Expert Sub-Agents

Agent files assign personas to Claude Code’s sub-agents. The name and description in the YAML frontmatter are key.

---
name: blog-editor
description: |
 Expert agent for blog editing.
 Reviews writing style, structure, and SEO optimization, and suggests improvements.
 When to use: When requesting review, editing, or proofreading of text.
---

# Technical Blog Editor Agent

You are a professional technical blog editor. Review articles based on the following criteria:

- Visualize operation methods with Mermaid diagrams
- Check SEO keyword density
- Verify inclusion of references

If you specify “When to use” in the description, Claude automatically selects that agent at the appropriate time.

Step 5: commands/ — Register Slash Commands

Command files register slash commands like /blog-writer:create-post. You can restrict allowed tools and descriptions via frontmatter.

---
description: Generate an SEO-optimized blog post
allowed-tools: Read, Write, WebFetch
---

# /blog-writer:create-post

Receives a topic from $ARGUMENTS and writes an SEO-optimized blog post.

If there is no topic, ask the user for one.

Use the blog-writer skill to write the post, and after completion, confirm whether to save it as a file.

$ARGUMENTS: Automatically binds arguments following the command. Use like /create-post AI agent design.
allowed-tools: Explicitly limits the tools the command can use for security.

Step 6: hooks/hooks.json — Set Automatic Triggers

Hooks define prompts or commands that Claude automatically executes before or after specific tool calls.

{
 "hooks": {
 "PostToolUse": [
 {
 "matcher": "Write",
 "hooks": [
 {
 "type": "prompt",
 "prompt": "Check the written file and review the title and first paragraph from an SEO perspective."
 }
 ]
 }
 ]
 }
}

This is an example of automatically triggering an SEO review immediately after the Write tool is executed. Hook events support PreToolUse, PostToolUse, Notification, Stop, etc.

sequenceDiagram
 participant U as User
 participant C as Claude
 participant H as Hook Engine

 U->>C: Execute /create-post
 C->>C: Call Write Tool
 C->>H: PostToolUse Event Fired
 H->>C: Inject SEO Review Prompt
 C->>U: Return SEO Review Result

Do not declare the hooks field in plugin.json. It is automatically recognized if only the hooks/hooks.json file exists (v2.1.0+).

Step 7: Register Plugin in marketplace.json

Internal plugins are registered in the marketplace root’s .claude-plugin/marketplace.json. The version is declared only here.

{
 "name": "yarang-plugins",
 "plugins": [
 {
 "name": "blog-writer",
 "description": "A skill plugin that structurally writes SEO-optimized blog posts",
 "version": "1.1.0",
 "keywords": ["blog", "seo", "writing", "content"],
 "source": {
 "source": "relative",
 "path": "./plugins/blog-writer"
 }
 },
 {
 "name": "domain-checker",
 "description": "Check domain availability",
 "keywords": ["domain", "rdap", "whois"],
 "source": {
 "source": "github",
 "repo": "yarang/skill-domain-checker",
 "ref": "v1.2.0"
 }
 }
 ]
}

For external repo plugins, set source.source to "github" and specify repo and ref (tag/branch).

Local Test → Deployment Workflow

flowchart LR
 A[Write Plugin] --> B[Local Test]
 B --> C{Check Behavior}
 C -- Failure --> A
 C -- Success --> D[Register in marketplace.json]
 D --> E[GitHub push]
 E --> F[Team Member Install]

# 1. Local Test (check immediately without installation)
claude --plugin-dir ./plugins/blog-writer

# 2. Refresh marketplace catalog
claude plugin marketplace update

# 3. Personal Install (user scope, default)
claude plugin install blog-writer@yarang-plugins

# 4. Team Shared Install (project scope — recorded in .claude/settings.json)
claude plugin install blog-writer@yarang-plugins --scope project

Common Mistakes Checklist

Item	Correct Method
Skill file name	`SKILL.md` (fixed uppercase)
Command file name	`<verb>-<noun>.md` (e.g., `create-post.md`)
Agent file name	`<role>.md` (e.g., `editor.md`)
version location	Internal plugin → only `marketplace.json` / External plugin → only `plugin.json`
hooks location	`hooks/hooks.json` (not in plugin.json)
Path Escaping	Using `../` is prohibited

Conclusion

Claude Code plugins are a powerful system that packages Claude’s behavior using declarative markdown. Define metadata with plugin.json, inject expertise with SKILL.md, create shortcuts with commands/, and set automation triggers with hooks/hooks.json — so the entire team can share the same workflow.

To get started right now:

Create a plugins/<name>/ directory
Write plugin.json and SKILL.md
Run a local test with claude --plugin-dir ./plugins/<name>.

A single plugin automates dozens of repetitive team tasks.

References

Claude Code Plugin System Docs
yarang/yarang-plugins — CLAUDE.md, docs/PLUGIN_SPEC.md
Claude Code v2.1 Release Notes

[Claude Code] Team Agent Communication Architecture

Sat, 28 Feb 2026 14:07:38 +0900

Claude Code Team Agent Communication Architecture Design

Overview

When multiple AI agents collaborate in Claude Code, an efficient communication method is needed. This article shares the communication architecture designed while building a Discord-integrated server monitoring team.

Problem Definition

Claude Code has two types of agents:

Python Processes (Daemon)
- Discord Gateway, user_comm_daemon, etc.
- Always running, filesystem access available
LLM Agents (Created as Tasks)
- gcp-monitor, oci-monitor, alert-manager, etc.
- Use SendMessage tool, Claude Code native communication

Communication between these two types was needed.

Considered Approaches

1. File-based Message Queue (Existing)

Pros: Simple implementation, no dependencies
Cons: Latency (~1s), file management required

2. WebSocket

Pros: Real-time bidirectional communication
Cons: Server/client implementation required

3. gRPC

Pros: Strong type checking, streaming
Cons: proto file management, high complexity

4. SQLite Message Hub (Adopted)

Pros: Fast (~10ms), transactions, no additional dependencies
Cons: Works only on a single machine

Final Architecture

┌─────────────────────────────────────────────────────────────────┐
│ SQLite Message Hub (messages.db) │
│ ~/.claude/teams/{team}/messages.db │
└───────────────────────────┬─────────────────────────────────────┘
 │
 ┌───────────────────┼───────────────────┐
 ↓ ↓ ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Discord │ │ Python │ │ LLM │
│ Gateway │ │ Daemon │ │ Agent │
│ (Direct Access)│ │ (Direct Access)│ │ (MCP Tool) │
└──────────────┘ └──────────────┘ └──────────────┘

SQLite Message Hub Structure

Messages Table

CREATE TABLE messages (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 message_id TEXT UNIQUE NOT NULL,
 sender TEXT NOT NULL,
 recipient TEXT, -- NULL = broadcast
 message_type TEXT DEFAULT 'message',
 content TEXT NOT NULL,
 priority TEXT DEFAULT 'normal',
 metadata TEXT DEFAULT '{}',
 status TEXT DEFAULT 'pending',
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 processed_at TIMESTAMP,
 expires_at TIMESTAMP
);

Agent Status Table

CREATE TABLE agent_status (
 agent_name TEXT PRIMARY KEY,
 status TEXT DEFAULT 'offline',
 last_heartbeat TIMESTAMP,
 metadata TEXT DEFAULT '{}'
);

Communication Methods

LLM Agent ↔ LLM Agent

Use SendMessage (Claude Code native)
Auto-managed, idle notification provided

Python ↔ LLM Agent

SQLite Hub + MCP Tool
Python accesses SQLite directly
LLM Agent accesses via MCP Tool

MCP Server Implementation

MCP tools for LLM Agents:

@server.list_tools()
async def list_tools():
 return [
 Tool(name="team_send_message", ...),
 Tool(name="team_read_messages", ...),
 Tool(name="team_broadcast", ...),
 Tool(name="team_get_status", ...),
 Tool(name="team_update_status", ...),
 ]

Message Flow Example

1. Discord user: "Hello"
 ↓
2. Discord Gateway → SQLite: INSERT message
 ↓
3. user_comm Daemon → SQLite: SELECT pending
 ↓
4. user_comm → SQLite: INSERT response
 ↓
5. Discord Gateway → SQLite: SELECT response
 ↓
6. Discord channel: "Hi there! 👋"

Performance Comparison

Method	Latency	Stability	Complexity
File-based	~1000ms	Medium	Low
WebSocket	~5ms	High	Medium
SQLite	~10ms	High	Low

Conclusion

The SQLite Message Hub + MCP Server combination was most suitable for Claude Code team agent communication:

Low Latency: 100x faster than file-based
Stability: Data integrity guaranteed through transactions
Simplicity: Uses Python’s built-in sqlite3 without additional dependencies
Flexibility: Both Python and LLM Agents use the same data source

Code

Core components:

message_hub.py: SQLite Message Hub
team_comm_mcp_server.py: MCP Server
discord_gateway.py: Discord integration gateway
user_comm_daemon.py: Message processing daemon

Korean Version: 한국어 버전