Skip to content

plugins.md

Latest commit

 

History

History
254 lines (193 loc) · 5.4 KB

plugins.md

File metadata and controls

254 lines (193 loc) · 5.4 KB
title Plugin Development Guide
category development
target_platform linux
audience ai_agent
keywords
plugins
skills
agents
hooks
mcp
development
version 1.0.33+

Plugin Development

Overview

Plugin Types:

  • Skills: Domain knowledge and workflows
  • Agents: Specialized subprocesses with tool restrictions
  • Hooks: Lifecycle event handlers
  • MCP Servers: External tool integrations
  • LSP Servers: Language protocol integrations

Architecture Comparison:

Component Location Namespace Scope
Standalone .claude/ Global /command Project-only
Plugin .claude-plugin/ /plugin:command Shareable/versioned

Quick Start

Minimum Viable Plugin

mkdir -p my-plugin/.claude-plugin
cd my-plugin

plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin description"
}

Directory structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── example/
│       └── SKILL.md
└── commands/
    └── hello.md

Testing

claude --plugin-dir ./my-plugin

# In session:
/my-plugin:hello
/help  # List all commands

Prerequisites

# Verify Claude Code installation
claude --version
# Required: >= 1.0.33

Plugin Manifest Schema

Required fields (.claude-plugin/plugin.json):

{
  "name": "plugin-identifier", // lowercase-hyphenated
  "version": "1.0.0", // semver
  "description": "Brief description" // one-line summary
}

Optional fields:

{
  "author": { "name": "Your Name", "url": "https://..." },
  "homepage": "https://..."
}

Strict mode warning: plugin.json uses Zod strict validation — unknown fields are rejected on install. Invalid fields (silently dropped by local tooling but rejected at install): keywords, repository, license, category. MCP and LSP servers use separate sidecar files (.mcp.json, .lsp.json) — not plugin.json.

Component Types

Commands

Location: commands/*.md Format: Markdown files with optional YAML frontmatter Invocation: /plugin-name:command-name

---
description: Command description
---

Command instructions using $ARGUMENTS placeholder for user input.

Skills

Location: skills/*/SKILL.md Format: Folder per skill with SKILL.md file Invocation: Auto-invoked by AI based on context

---
name: skill-name
description: When to use this skill
applyTo:
  - '**/*.py'
---
Skill implementation instructions.

See skills.md for complete reference.

Agents

Location: agents/*.md Purpose: Specialized subprocesses with tool restrictions Invocation: /agent-name

See sub-agents.md for complete reference.

Hooks

Location: hooks/hooks.json Purpose: Lifecycle event handlers Events: SessionStart, SessionEnd, PreToolUse, PostToolUse, etc.

See hooks.md for complete reference.

MCP Servers

Location: Configured in .mcp.json at plugin root Purpose: External tool integrations via Model Context Protocol

See mcp.md for complete reference.

LSP Servers

Location: Configured in .lsp.json at plugin root Purpose: Language Server Protocol for code intelligence

{
  "python": {
    "command": "pylsp",
    "args": [],
    "extensionToLanguage": {
      ".py": "python"
    }
  }
}

Directory Structure

plugin-name/
├── .claude-plugin/
│   └── plugin.json            # Required metadata
├── commands/                  # Optional command skills
│   └── command-name.md
├── skills/                    # Optional AI skills
│   └── skill-folder/
│       └── SKILL.md
├── agents/                    # Optional custom agents
│   └── agent-name.md
├── hooks/                     # Optional hooks
│   └── hooks.json
├── .lsp.json                  # Optional LSP config
└── README.md                  # Documentation — use docs/plugin-readme-template.md

Important: Only plugin.json goes inside .claude-plugin/. All other directories are at plugin root.

Every plugin README.md should follow docs/plugin-readme-template.md. Required sections: Summary, Principles, Requirements, Installation, How It Works (Mermaid), Usage, Planned Features, Known Issues, Links. Delete optional sections (Features, Configuration, Design Decisions, etc.) that don't apply to the specific plugin.

Development Workflow

1. Create Plugin

mkdir -p my-plugin/.claude-plugin
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Description"
}
EOF

2. Add Components

# Add a command
mkdir -p my-plugin/commands
cat > my-plugin/commands/hello.md << 'EOF'
---
description: Greet user
---
Greet the user named "$ARGUMENTS" warmly.
EOF

# Add a skill
mkdir -p my-plugin/skills/example
cat > my-plugin/skills/example/SKILL.md << 'EOF'
---
name: example
description: Example skill
---
Skill implementation.
EOF

3. Test Locally

claude --plugin-dir ./my-plugin

4, Update and Reload

# Make changes
# Restart Claude to reload
claude --plugin-dir ./my-plugin

Testing