Your First Plugin

This tutorial walks you through building a simple plugin from scratch. By the end, you'll have a working command that you can invoke with /hello-world.

Time Required

• Total: 15-20 minutes
• No coding experience required

---

What You'll Build

A minimal plugin with one command that:

1. Greets the user
2. Shows the current date
3. Lists files in the current directory

This teaches the fundamentals of plugin structure without complexity.

---

Prerequisites

• Claude Code or OpenCode installed (Quickstart)
• Access to the agents-infra repository (cloned locally)
• A text editor

Stuck?

Running into issues? Check the Troubleshooting Guide or ask in #artificial-intelligence-gpt Slack.

---

Step 1: Create the Directory Structure

Every plugin needs a specific folder structure. Create yours:

If you're stuck mid-tutorial

Jump to Troubleshooting or run /utils:help.

cd agents-infra

# Create the plugin directories
mkdir -p plugins/divisions/my-first-plugin/.claude-plugin
mkdir -p plugins/divisions/my-first-plugin/commands

Your structure should look like:

plugins/divisions/my-first-plugin/
├── .claude-plugin/
│   └── (plugin.json goes here)
└── commands/
    └── (your command goes here)

flowchart TB
    subgraph PLUGIN["📦 my-first-plugin"]
        subgraph META["📋 .claude-plugin/"]
            PJ["plugin.json<br/><i>manifest</i>"]
        end

        subgraph CMD["⚡ commands/"]
            HW["hello-world.md<br/><i>your command</i>"]
        end

        subgraph SKILL["🧠 skills/ (optional)"]
            SM["my-methods/<br/>SKILL.md"]
        end
    end

    style PLUGIN fill:#343456,color:#fff
    style META fill:#5050BC,color:#fff
    style CMD fill:#5050BC,color:#fff
    style SKILL fill:#5050BC,color:#fff

Directory	Purpose	Required?
.claude-plugin/	Plugin metadata and manifest	Yes
commands/	User-invokable commands	Yes (need at least one)
skills/	Auto-activated behavior patterns	Optional

---

Step 2: Create the Plugin Manifest

The manifest tells the system about your plugin. Create plugin.json:

touch plugins/divisions/my-first-plugin/.claude-plugin/plugin.json

Add this content:

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "A learning plugin to understand the basics",
  "dependencies": {
    "plugins": [
      {
        "name": "core-dependencies",
        "version": ">=1.0.0",
        "required": true
      }
    ]
  }
}

What This Means

Field	Purpose
name	Unique identifier for your plugin
version	Semantic version (major.minor.patch)
description	Human-readable explanation
dependencies	Other plugins this requires

Why core-dependencies?

All division plugins inherit from core-dependencies. This gives you shared writing standards, quality checks, and activation hooks automatically.

---

Step 3: Create Your First Command

Commands are markdown files that tell the AI what to do. Create hello-world.md:

touch plugins/divisions/my-first-plugin/commands/hello-world.md

Add this content:

---
name: hello-world
description: "A friendly greeting command to test plugin setup"
version: 1.0.0
---

# Hello World Command

When the user runs this command, perform the following steps:

## Step 1: Greet the User

Say hello and introduce yourself as a helpful assistant from the my-first-plugin.

## Step 2: Show Context

Tell the user:
- The current date and time
- The current working directory
- How many files are in the current directory

## Step 3: Offer Help

Ask the user what they'd like to do next. Suggest:
- Running another command
- Exploring the codebase
- Getting help with a task

Keep responses friendly and concise.

Anatomy of a Command

---
name: hello-world           # How users invoke it: /hello-world
description: "..."          # Shows in /utils:commands listing
version: 1.0.0              # Track changes over time
---

The body is natural language instructions for Claude. Write it like you're explaining to a helpful colleague.

---

Step 4: Register Your Plugin

Add your plugin to the marketplace registry. Open .claude-plugin/marketplace.json:

# View current registry
cat .claude-plugin/marketplace.json

Add your plugin to the plugins array:

{
  "plugins": [
    // ... existing plugins ...
    {
      "name": "my-first-plugin",
      "path": "plugins/divisions/my-first-plugin",
      "version": "1.0.0",
      "status": "development"
    }
  ]
}

---

Step 5: Test Your Command

Claude CodeOpenCode

Load your plugin for testing:

claude --plugin-dir ./plugins/divisions/my-first-plugin

Then run your command (namespaced):

/my-first-plugin:hello-world

Start OpenCode in the project directory:

opencode

Then run your command:

/hello-world

You should see Claude:

1. Greet you warmly
2. Show the current date/time and directory info
3. Offer to help with next steps

---

Step 6: Iterate and Improve

Try modifying your command. Edit hello-world.md and add:

## Step 4: Fun Fact

Share one interesting fact about AI agents or programming. Make it memorable!

Run /hello-world again to see the change.

---

What You Learned

Concept	What It Does
Plugin structure	.claude-plugin/plugin.json + commands/
Manifest	Declares name, version, dependencies
Command frontmatter	YAML header with name, description
Command body	Natural language instructions
Registration	Add to marketplace.json

---

Common Issues

"Command not found"

Cause: Plugin not registered in marketplace.json

Fix: Ensure your plugin is in the plugins array with the correct path.

"Dependencies not met"

Cause: Missing core-dependencies

Fix: Ensure core-dependencies is listed in your plugin.json dependencies.

"Command doesn't do what I expected"

Cause: Ambiguous instructions in the command body

Fix: Be more specific. Instead of "show files", say "use ls -la to show files with details".

Stuck?

Running into issues? Check the Troubleshooting Guide or ask in #artificial-intelligence-gpt Slack.

---

Next Steps

Now that you understand the basics:

Add a Skill

Skills define automatic behavior. Create plugins/divisions/my-first-plugin/skills/my-methods/SKILL.md:

---
name: my-methods
description: "Domain-specific patterns for my-first-plugin"
type: skill
auto-load: true
---

# My Methods

When working on tasks related to my-first-plugin:

- Always be friendly and encouraging
- Explain what you're doing as you go
- Offer alternatives when something doesn't work

Add More Commands

Create additional commands for different tasks:

• commands/summarize.md - Summarize a file or directory
• commands/explain.md - Explain code in plain English
• commands/checklist.md - Generate a todo list from a task

Add MCP Dependencies

If your commands need external data, declare MCP dependencies:

---
name: data-command
description: "Fetch and analyze data"
mcp: [bigquery, dataforseo]  # Optional MCP servers
version: 1.0.0
---

---

Related Tutorials

• Quickstart - Initial setup
• Your First Content Audit - Run a real workflow

Related How-To Guides

• Plugin Authoring - Advanced plugin patterns
• Workflows - Understanding command workflows

Reference

• Command Reference - All available commands
• Skill Reference - Available skills
• Configuration - Environment setup

---

Last updated: 2026-01-26