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

Plugin on Yarang's Tech Lair