my-plugin/
├── plugin.json           # At root
├── agents/
├── commands/
├── skills/
└── hooks/

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json  # In .claude-plugin/ directory
├── README.md
├── LICENSE
└── plugins/
    └── my-plugin/
        └── .claude-plugin/
            ├── plugin.json
            ├── agents/
            ├── commands/
            ├── skills/
            └── hooks/

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does",
  "author": {
    "name": "Author Name"
  },
  "license": "MIT",
  "repository": "https://github.com/owner/repo",
  "keywords": ["keyword1", "keyword2"]
}

{
  "name": "my-plugin",
  "author": "Author Name"  // ❌ Must be object: { "name": "..." }
}

{
  "$schema": "https://claude.ai/schemas/marketplace.json",
  "name": "my-marketplace",
  "owner": {
    "name": "Owner Name"
  },
  "metadata": {
    "description": "Marketplace description",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "Plugin description",
      "version": "1.0.0"
    }
  ]
}

// WRONG #1: marketplace.json at repo root (wrong location)
// ❌ my-marketplace/marketplace.json              (WRONG - at root)
// ✅ my-marketplace/.claude-plugin/marketplace.json  (CORRECT)

// WRONG #2: source pointing to root instead of plugin directory
{
  "plugins": [{
    "name": "my-plugin",
    "source": "./"  // ❌ WRONG - use "./plugins/my-plugin"
  }]
}

// WRONG #3: source including .claude-plugin path
{
  "plugins": [{
    "name": "my-plugin",
    "source": "./plugins/my-plugin/.claude-plugin"  // ❌ WRONG - don't include .claude-plugin
  }]
}

// WRONG #3: Using "author" instead of "owner"
{
  "name": "my-marketplace",
  "author": "Name",  // ❌ Use "owner": { "name": "Name" }
  "plugins": []
}

// WRONG #4: Using "path" instead of "source"
{
  "plugins": [{
    "path": ".",  // ❌ Use "source": "plugins/name/.claude-plugin"
    "config": {}  // ❌ "config" not allowed
  }]
}

// WRONG #5: Adding fields not in schema
{
  "displayName": "...",  // ❌ Not in schema
  "license": "MIT",      // ❌ Not in schema
  "repository": "...",   // ❌ Not in schema
  "keywords": [],        // ❌ Not in schema
  "categories": [],      // ❌ Not in schema
  "requirements": {},    // ❌ Not in schema
  "installation": {}     // ❌ Not in schema
}

---
name: my-agent
description: Use this agent when you need to analyze code quality
tools:
  - Read
  - Grep
  - Glob
model: haiku
color: blue
---

# My Agent

You are a specialized agent for...

## Your Responsibilities

1. Task one
2. Task two

## Important Rules

- Rule one
- Rule two

agents/my-agent/agent.md     ❌ Wrong: subdirectory
agents/my-agent/AGENT.md     ❌ Wrong: subdirectory
agents/my-agent.md           ✅ Correct

---
name: my-agent
allowed_tools:  # ❌ Use "tools" not "allowed_tools"
  - Read
---

---
name: my-command
description: What this command does
allowed-tools:
  - Read
  - Write
  - Bash
argument-hint: "<file-path>"
---

# /my-command

Instructions for implementing this command...

commands/my-command/command.md  ❌ Wrong: subdirectory
commands/my-command.md          ✅ Correct

---
name: my-command
allowed_tools:  # ❌ Use "allowed-tools" (kebab-case with hyphen)
  - Read
---

---
name: my-skill
triggers:
  - "use my skill"
  - "my skill please"
  - "activate skill"
---

# My Skill

Skill content goes here...

## Section One

Content...

## Section Two

Content...

skills/my-skill.md            ❌ Wrong: not in subdirectory
skills/my-skill/skill.md      ❌ Wrong: lowercase filename
skills/my-skill/index.md      ❌ Wrong: wrong filename
skills/my-skill/SKILL.md      ✅ Correct

---
name: my-skill
triggers: "single trigger"  # ❌ Must be array
---

{
  "$schema": "https://claude.ai/schemas/hooks.json",
  "description": "My plugin hooks",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validate.py",
            "timeout": 10
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "^/my-command",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/init.py",
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/stop.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

// WRONG #1: hooks as array (VERY COMMON MISTAKE!)
{
  "hooks": [  // ❌ WRONG: Must be object, not array
    {
      "event": "PreToolUse",
      "command": "..."
    }
  ]
}

// WRONG #2: Missing nested "hooks" array and "type"
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "command": "..."  // ❌ Must be inside hooks array with type: command
      }
    ]
  }
}

// WRONG #3: Hardcoded path
{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /home/user/hooks/script.py"  // ❌ Use ${CLAUDE_PLUGIN_ROOT}
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
"""Hook script for [purpose]."""
import json
import sys

def main():
    """Main hook handler."""
    try:
        input_data = json.load(sys.stdin)

        # Process input_data...
        # input_data contains event-specific fields

        # Exit codes:
        # 0 = allow (continue)
        # 2 = block (prevent action)
        sys.exit(0)

    except Exception as e:
        print(json.dumps({"error": str(e)}), file=sys.stderr)
        sys.exit(0)  # Allow on error (fail-open)

if __name__ == "__main__":
    main()

my-plugin/
├── plugin.json                      # REQUIRED at root
├── agents/
│   ├── agent-one.md                 # Direct .md file
│   └── agent-two.md
├── commands/
│   ├── command-one.md               # Direct .md file
│   └── command-two.md
├── skills/
│   ├── skill-one/
│   │   └── SKILL.md                 # MUST be SKILL.md
│   └── skill-two/
│       └── SKILL.md
└── hooks/
    ├── hooks.json                   # Hook configuration
    ├── hook-one.py
    └── hook-two.py

my-marketplace/                      # Repository root
├── .claude-plugin/
│   └── marketplace.json             # In .claude-plugin/ directory
├── README.md
├── LICENSE
└── plugins/
    └── my-plugin/
        └── .claude-plugin/          # Plugin content HERE
            ├── plugin.json          # Required
            ├── agents/
            │   └── my-agent.md
            ├── commands/
            │   └── my-cmd.md
            ├── skills/
            │   └── my-skill/
            │       └── SKILL.md
            └── hooks/
                ├── hooks.json
                └── my-hook.py

# WRONG: marketplace.json at repo root (should be in .claude-plugin/)
my-marketplace/
├── marketplace.json                 # ❌ Should be in .claude-plugin/
└── plugins/

# WRONG: Plugin content at repo root (not in plugins/ directory)
my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
├── plugin.json                      # ❌ Should be in plugins/<name>/.claude-plugin/
├── agents/                          # ❌ Should be in plugins/<name>/.claude-plugin/
└── skills/                          # ❌ Should be in plugins/<name>/.claude-plugin/

# WRONG: Missing .claude-plugin directory for plugin
my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── my-plugin/
        ├── plugin.json              # ❌ Missing .claude-plugin/ wrapper
        └── agents/

# Agent in subdirectory
agents/my-agent/agent.md             # ❌ Wrong
agents/my-agent.md                   # ✅ Correct

# Command in subdirectory
commands/my-cmd/command.md           # ❌ Wrong
commands/my-cmd.md                   # ✅ Correct

# Skill as direct file
skills/my-skill.md                   # ❌ Wrong
skills/my-skill/SKILL.md             # ✅ Correct

# Skill with wrong filename
skills/my-skill/skill.md             # ❌ Wrong (lowercase)
skills/my-skill/index.md             # ❌ Wrong (wrong name)
skills/my-skill/SKILL.md             # ✅ Correct