Plugin Development Expert

Expert guidance for creating production-ready Claude Code plugins.

Critical Structure Rules

Directory Hierarchy:

~/.claude/plugins/my-plugin/ ← Plugin root ├── .claude-plugin/ │ └── plugin.json ← Manifest (REQUIRED) ├── commands/ │ └── command-name.md ← Slash commands ├── skills/ │ └── skill-name/ ← MUST be subdirectory │ └── SKILL.md ← MUST be uppercase └── agents/ └── agent-name/ └── AGENT.md

Common Mistakes:

❌ WRONG

skills/SKILL.md # Missing subdirectory skills/my-skill.md # Wrong filename skills/My-Skill/SKILL.md # CamelCase not allowed

✅ CORRECT

skills/my-skill/SKILL.md # kebab-case subdirectory + SKILL.md

plugin.json Format

Minimum Required:

{ "name": "my-plugin", "description": "Clear description with activation keywords", "version": "1.0.0" }

Full Example:

{ "name": "my-awesome-plugin", "description": "Expert cost optimization for AWS, Azure, GCP. Activates for reduce costs, cloud costs, finops, save money, cost analysis.", "version": "1.0.0", "author": { "name": "Your Name", "email": "you@example.com" }, "homepage": "https://github.com/user/my-plugin", "repository": "https://github.com/user/my-plugin", "license": "MIT", "keywords": ["cost", "finops", "aws", "azure", "gcp"] }

Command Format (Slash Commands)

Header Format (CRITICAL):

/my-plugin:command-name

Rules:

• MUST start with # /

• Plugin name: kebab-case

• Command name: kebab-case

• NO YAML frontmatter (only skills use YAML)

Full Template:

/my-plugin:analyze-costs

Analyze cloud costs and provide optimization recommendations.

You are an expert FinOps engineer.

Your Task

1. Collect cost data
2. Analyze usage patterns
3. Identify optimization opportunities
4. Generate report

1. Data Collection

```bash aws ce get-cost-and-usage --time-period... ```

Example Usage

User: "Analyze our AWS costs"

Response:

• Pulls Cost Explorer data
• Identifies $5K/month in savings
• Provides implementation plan

When to Use

• Monthly cost reviews
• Budget overruns
• Pre-purchase planning

Skill Format (Auto-Activating)

YAML Frontmatter (REQUIRED):

name: cost-optimization description: Expert cloud cost optimization for AWS, Azure, GCP. Covers FinOps, reserved instances, spot instances, right-sizing, storage optimization. Activates for reduce costs, save money, cloud costs, aws costs, finops, cost optimization, budget overrun, expensive bill.

Activation Keywords:

✅ GOOD: Specific, varied keywords

description: Expert Python optimization. Activates for python performance, optimize python code, speed up python, profiling, cProfile, pypy, numba.

❌ BAD: Too generic

description: Python expert.

❌ BAD: No activation keywords

description: Expert Python optimization covering performance tuning.

Full Template:

name: my-skill description: Expert [domain] covering [topics]. Activates for keyword1, keyword2, phrase3, action4.

Skill Title

You are an expert [role] with deep knowledge of [domain].

Core Expertise

1. Topic Area

Content here...

2. Code Examples

```typescript // Working examples ```

Best Practices

• Practice 1
• Practice 2

You are ready to help with [domain]!

Agent Format (Sub-Agents)

File Location:

agents/agent-name/AGENT.md

Template:

name: specialist-agent description: Specialized agent for [specific task]

Agent Title

You are a specialized agent for [purpose].

Capabilities

1. Capability 1
2. Capability 2

Workflow

1. Analyze input
2. Execute specialized task
3. Return results

Invocation:

Task({ subagent_type: "plugin-name:folder-name:yaml-name", prompt: "Task description" });

// Example Task({ subagent_type: "my-plugin:specialist-agent:specialist-agent", prompt: "Analyze this code for security vulnerabilities" });

Testing Workflow

1. Install Plugin:

cp -r my-plugin ~/.claude/plugins/

OR

claude plugin add github:username/my-plugin

2. Restart Claude Code:

Required after:

• Adding new plugin
• Modifying plugin.json
• Adding/removing commands
• Changing YAML frontmatter

3. Test Commands:

Type "/" in Claude Code

Verify command appears: /my-plugin:command-name

Execute command

Verify behavior

4. Test Skills:

Ask trigger question: "How do I reduce costs?"

Verify skill activates

Check response uses skill knowledge

5. Check Logs:

tail -f ~/.claude/logs/claude.log | grep my-plugin

Expected:

✅ "Loaded plugin: my-plugin"

✅ "Registered command: /my-plugin:analyze"

✅ "Registered skill: cost-optimization"

Errors:

❌ "Failed to parse plugin.json"

❌ "YAML parsing error in SKILL.md"

❌ "Command header malformed"

Common Issues

Issue: Skill not activating

Checklist:

1. ✅ YAML frontmatter present? (---...---)
2. ✅ Activation keywords in description?
3. ✅ SKILL.md in subdirectory? (skills/name/SKILL.md)
4. ✅ File named SKILL.md (uppercase)?
5. ✅ Claude Code restarted?

Issue: Command not found

Checklist:

1. ✅ Header format: # /plugin-name:command-name
2. ✅ File in commands/ directory?
3. ✅ Plugin name matches plugin.json?
4. ✅ Claude Code restarted?

Issue: YAML parsing error

Common causes:

• Unclosed quotes: description: "Missing end
• Invalid characters: name: my_skill (use hyphens)
• Missing closing ---
• Incorrect indentation

Best Practices

Naming:

• Plugin: my-awesome-plugin (kebab-case)

• Commands: analyze-costs (kebab-case)

• Skills: cost-optimization (kebab-case)

• NO underscores, NO CamelCase

Activation Keywords:

• Include 5-10 trigger keywords

• Mix specific terms and common phrases

• Think about what users will ask

• Test with real questions

Documentation:

• Clear "Your Task" section

• Code examples with syntax highlighting

• "Example Usage" section

• "When to Use" section

Performance:

• Keep SKILL.md under 50KB

• Optimize command prompts

• Avoid expensive operations

Create production-ready Claude Code plugins!