creating intital scaffolding for claude code plugins

plugins/example-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "example-plugin",
+  "version": "1.0.0",
+  "description": "A comprehensive example plugin demonstrating all Claude Code extension options including commands, agents, skills, hooks, and MCP servers",
+  "author": {
+    "name": "Your Name",
+    "email": "your.email@example.com"
+  }
+}

plugins/example-plugin/.mcp.json

@@ -0,0 +1,6 @@
+{
+  "example-server": {
+    "type": "http",
+    "url": "https://mcp.example.com/api"
+  }
+}

plugins/example-plugin/README.md

@@ -0,0 +1,82 @@
+# Example Plugin
+
+A comprehensive example plugin demonstrating Claude Code extension options.
+
+## Structure
+
+```
+example-plugin/
+├── .claude-plugin/
+│   └── plugin.json        # Plugin metadata
+├── .mcp.json              # MCP server configuration
+├── commands/
+│   └── example-command.md # Slash command definition
+├── agents/
+│   └── example-agent.md   # Agent definition
+└── skills/
+    └── example-skill/
+        └── SKILL.md       # Skill definition
+```
+
+## Extension Options
+
+### Commands (`commands/`)
+
+Slash commands are user-invoked via `/command-name`. Define them as markdown files with frontmatter:
+
+```yaml
+---
+description: Short description for /help
+argument-hint: <arg1> [optional-arg]
+allowed-tools: [Read, Glob, Grep]
+---
+```
+
+### Agents (`agents/`)
+
+Agents are spawned by Claude via the Task tool. Define them as markdown files:
+
+```yaml
+---
+name: agent-name
+description: When to use this agent
+tools: Glob, Grep, Read, Write
+model: sonnet
+color: blue
+---
+```
+
+### Skills (`skills/`)
+
+Skills are model-invoked capabilities. Create a `SKILL.md` in a subdirectory:
+
+```yaml
+---
+name: skill-name
+description: Trigger conditions for this skill
+version: 1.0.0
+---
+```
+
+### MCP Servers (`.mcp.json`)
+
+Configure external tool integration via Model Context Protocol:
+
+```json
+{
+  "server-name": {
+    "type": "http",
+    "url": "https://mcp.example.com/api"
+  }
+}
+```
+
+## Installation
+
+Copy or symlink this plugin directory to your Claude Code plugins location.
+
+## Usage
+
+- `/example-command [args]` - Run the example slash command
+- The example agent is available for Claude to spawn when relevant
+- The example skill activates based on task context

plugins/example-plugin/agents/example-agent.md

@@ -0,0 +1,57 @@
+---
+name: example-agent
+description: An example agent that demonstrates agent definition structure and frontmatter options. Use this agent when the user asks to perform example tasks or needs a template reference.
+tools: Glob, Grep, Read, Write, Edit, Bash, WebFetch, WebSearch, TodoWrite
+model: sonnet
+color: blue
+---
+
+You are an example agent that demonstrates the agent definition format for Claude Code plugins.
+
+## Agent Purpose
+
+This agent serves as a template showing:
+- Required and optional frontmatter fields
+- Recommended prompt structure
+- How to define agent capabilities and behavior
+
+## Frontmatter Options Reference
+
+Agents support these frontmatter fields:
+
+- **name** (required): Agent identifier used in Task tool
+- **description** (required): When to use this agent - Claude reads this to decide which agent to spawn
+- **tools** (required): Comma-separated list of allowed tools
+- **model** (optional): "haiku", "sonnet", or "opus" (defaults to parent model)
+- **color** (optional): Terminal color for agent output (red, green, blue, yellow, magenta, cyan)
+
+## Available Tools
+
+Common tools to include:
+- **Glob**: Find files by pattern
+- **Grep**: Search file contents
+- **Read**: Read file contents
+- **Write**: Create new files
+- **Edit**: Modify existing files
+- **Bash**: Execute shell commands
+- **WebFetch**: Fetch web content
+- **WebSearch**: Search the web
+- **TodoWrite**: Track task progress
+- **NotebookRead**: Read Jupyter notebooks
+- **LSP**: Language server operations
+
+## Agent Behavior
+
+When spawned, this agent should:
+
+1. Understand the task from the prompt
+2. Use available tools systematically
+3. Report findings or complete the requested work
+4. Return a clear summary to the parent conversation
+
+## Best Practices
+
+- Write clear, actionable descriptions so Claude knows when to spawn this agent
+- Only include tools the agent actually needs
+- Use appropriate model based on task complexity
+- Structure prompts with clear sections and instructions

plugins/example-plugin/commands/example-command.md

@@ -0,0 +1,37 @@
+---
+description: An example slash command that demonstrates command frontmatter options
+argument-hint: <required-arg> [optional-arg]
+allowed-tools: [Read, Glob, Grep, Bash]
+---
+
+# Example Command
+
+This command demonstrates slash command structure and frontmatter options.
+
+## Arguments
+
+The user invoked this command with: $ARGUMENTS
+
+## Instructions
+
+When this command is invoked:
+
+1. Parse the arguments provided by the user
+2. Perform the requested action using allowed tools
+3. Report results back to the user
+
+## Frontmatter Options Reference
+
+Commands support these frontmatter fields:
+
+- **description**: Short description shown in /help
+- **argument-hint**: Hints for command arguments shown to user
+- **allowed-tools**: Pre-approved tools for this command (reduces permission prompts)
+- **model**: Override the model (e.g., "haiku", "sonnet", "opus")
+
+## Example Usage
+
+```
+/example-command my-argument
+/example-command arg1 arg2
+```

plugins/example-plugin/skills/example-skill/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: example-skill
+description: This skill should be used when the user asks to "demonstrate skills", "show skill format", "create a skill template", or discusses skill development patterns. Provides a reference template for creating Claude Code plugin skills.
+version: 1.0.0
+---
+
+# Example Skill
+
+This skill demonstrates the structure and format for Claude Code plugin skills.
+
+## Overview
+
+Skills are model-invoked capabilities that Claude autonomously uses based on task context. Unlike commands (user-invoked) or agents (spawned by Claude), skills provide contextual guidance that Claude incorporates into its responses.
+
+## When This Skill Applies
+
+This skill activates when the user's request involves:
+- Creating or understanding plugin skills
+- Skill template or reference needs
+- Skill development patterns
+
+## Skill Structure
+
+### Required Files
+
+```
+skills/
+└── skill-name/
+    └── SKILL.md          # Main skill definition (required)
+```
+
+### Optional Supporting Files
+
+```
+skills/
+└── skill-name/
+    ├── SKILL.md          # Main skill definition
+    ├── README.md         # Additional documentation
+    ├── references/       # Reference materials
+    │   └── patterns.md
+    ├── examples/         # Example files
+    │   └── sample.md
+    └── scripts/          # Helper scripts
+        └── helper.sh
+```
+
+## Frontmatter Options
+
+Skills support these frontmatter fields:
+
+- **name** (required): Skill identifier
+- **description** (required): Trigger conditions - describe when Claude should use this skill
+- **version** (optional): Semantic version number
+- **license** (optional): License information or reference
+
+## Writing Effective Descriptions
+
+The description field is crucial - it tells Claude when to invoke the skill.
+
+**Good description patterns:**
+```yaml
+description: This skill should be used when the user asks to "specific phrase", "another phrase", mentions "keyword", or discusses topic-area.
+```
+
+**Include:**
+- Specific trigger phrases users might say
+- Keywords that indicate relevance
+- Topic areas the skill covers
+
+## Skill Content Guidelines
+
+1. **Clear purpose**: State what the skill helps with
+2. **When to use**: Define activation conditions
+3. **Structured guidance**: Organize information logically
+4. **Actionable instructions**: Provide concrete steps
+5. **Examples**: Include practical examples when helpful
+
+## Best Practices
+
+- Keep skills focused on a single domain
+- Write descriptions that clearly indicate when to activate
+- Include reference materials in subdirectories for complex skills
+- Test that the skill activates for expected queries
+- Avoid overlap with other skills' trigger conditions