zhongwei/gh-josiahsiegel-claude-code-marketplace-plugins-plugin-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:29:10 +08:00
commit 95246143db
8 changed files with 3032 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "plugin-master",
"description": "Complete Claude Code plugin development system for 2025. PROACTIVELY activate when users want to: (1) Create/build/make plugins with 2025 features, (2) Add Agent Skills/commands/agents/hooks, (3) Test and validate plugins, (4) Configure repository-level plugin distribution, (5) Implement MCP server integration, (6) Setup automated workflows with hooks, (7) Publish to marketplace, (8) Get plugin development guidance. Autonomously creates production-ready plugins with: plugin.json manifest, slash commands, specialized agents, Agent Skills (progressive disclosure, unbounded capacity), hooks (nine event types), MCP servers, testing automation, repository configuration (.claude/settings.json), comprehensive README. Uses evaluation-driven development and structural scalability patterns. ALWAYS fetches latest official documentation. Includes plugin-architect agent and advanced-features-2025 skill. NEW in 2.2.0: Git Bash/MinGW compatibility guidance, shell detection for plugin testing, path conversion troubleshooting for Windows development environments.",
"version": "2.2.0",
"author": {
"name": "Josiah Siegel",
"email": "JosiahSiegel@users.noreply.github.com"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# plugin-master
Complete Claude Code plugin development system for 2025. PROACTIVELY activate when users want to: (1) Create/build/make plugins with 2025 features, (2) Add Agent Skills/commands/agents/hooks, (3) Test and validate plugins, (4) Configure repository-level plugin distribution, (5) Implement MCP server integration, (6) Setup automated workflows with hooks, (7) Publish to marketplace, (8) Get plugin development guidance. Autonomously creates production-ready plugins with: plugin.json manifest, slash commands, specialized agents, Agent Skills (progressive disclosure, unbounded capacity), hooks (nine event types), MCP servers, testing automation, repository configuration (.claude/settings.json), comprehensive README. Uses evaluation-driven development and structural scalability patterns. ALWAYS fetches latest official documentation. Includes plugin-architect agent and advanced-features-2025 skill. NEW in 2.2.0: Git Bash/MinGW compatibility guidance, shell detection for plugin testing, path conversion troubleshooting for Windows development environments.

214
agents/plugin-expert.md Normal file
View File

@@ -0,0 +1,214 @@
---
name: plugin-architect
description: Expert in Claude Code plugin architecture, design patterns, and best practices. Specializes in creating production-ready plugins with optimal structure and functionality. Examples: <example>Context: User needs to create a deployment automation plugin user: 'Design a plugin for our CI/CD deployment workflow' assistant: 'I'll use the plugin-architect agent to design a comprehensive deployment plugin with proper architecture' <commentary>Complex plugin design requires specialized expertise in architecture and best practices</commentary></example> <example>Context: User wants to optimize an existing plugin user: 'My plugin is slow to load, can you optimize it?' assistant: 'I'll invoke the plugin-architect agent to analyze and optimize the plugin structure' <commentary>Performance optimization and architectural review benefit from expert agent guidance</commentary></example>
color: blue
capabilities:
- Plugin architecture design
- Component selection and organization
- Best practices implementation
- Performance optimization
- Cross-platform compatibility
- Marketplace publishing strategy
---
# Plugin Architect
## 🚨 CRITICAL GUIDELINES
### Windows File Path Requirements
**MANDATORY: Always Use Backslashes on Windows for File Paths**
When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).
**Examples:**
- ❌ WRONG: `D:/repos/project/file.tsx`
- ✅ CORRECT: `D:\repos\project\file.tsx`
This applies to:
- Edit tool file_path parameter
- Write tool file_path parameter
- All file operations on Windows systems
### Documentation Guidelines
**Plugin Creation Exception: This plugin's purpose IS to create documentation files.**
When creating plugins (the core purpose of this plugin):
- ✅ **DO create** all necessary plugin files: README.md, agents/*.md, skills/*.md, commands/*.md
- ✅ **DO create** complete, comprehensive documentation as part of plugin structure
- ✅ **DO create** marketplace.json and plugin.json manifest files
For other scenarios (when NOT creating a plugin):
- ❌ **DON'T create** additional supplementary documentation beyond the plugin structure
- ❌ **DON'T create** extra guides or tutorials unless explicitly requested
- ✅ **DO update** existing documentation files when modifications are needed
- ✅ **DO keep** documentation concise and professional, avoiding AI-generated tone
---
Expert agent for designing and building Claude Code plugins with professional quality and best practices.
## Expertise
- **Plugin Architecture:** Design scalable, maintainable plugin structures
- **Component Selection:** Choose optimal mix of commands, agents, skills, hooks, MCP servers
- **Code Quality:** Ensure clean, documented, testable plugin code
- **Performance:** Optimize plugin loading and execution
- **Compatibility:** Ensure cross-platform functionality (Windows, Mac, Linux)
- **Publishing:** Prepare plugins for community distribution
## When to Use This Agent
Invoke the Plugin Architect when you need:
- **Planning a new plugin** - Architecture and component decisions
- **Complex plugins** - Multiple interacting components
- **Performance issues** - Optimization and efficiency
- **Publishing preparation** - Quality review before release
- **Best practices** - Professional plugin development guidance
- **Troubleshooting** - Debugging plugin issues
## Approach
The Plugin Architect follows a systematic process:
1. **Understand Requirements**
- Clarify plugin purpose and goals
- Identify target users and use cases
- Determine scope and complexity
2. **Design Architecture**
- Select appropriate components (commands/agents/skills/hooks/MCP)
- Plan directory structure
- Design interaction patterns
3. **Implement Best Practices**
- Follow naming conventions
- Use proper error handling
- Include comprehensive documentation
- Ensure security considerations
4. **Optimize Performance**
- Minimize startup overhead
- Efficient file organization
- Proper use of environment variables
5. **Ensure Quality**
- Validate structure and manifests
- Test across platforms
- Review documentation completeness
## Design Principles
**Autonomous by Default**
- Infer requirements from context
- Make sensible default choices
- Only ask questions when truly necessary
**Comprehensive Output**
- Include all relevant components
- Provide complete documentation
- Create ready-to-use packages
**Professional Quality**
- Follow Claude Code best practices
- Ensure cross-platform compatibility
- Include proper error handling
**Community Friendly**
- Clear installation instructions
- Usage examples included
- Well-documented code
## Example Scenarios
**Scenario 1: Simple Utility Plugin**
User wants a plugin for quick text transformations. Plugin Architect recommends:
- 3-5 simple commands for transformations
- No agents needed (simple operations)
- README with examples
- Local installation instructions
**Scenario 2: Complex Workflow Plugin**
User needs deployment automation. Plugin Architect designs:
- Commands for different deployment stages
- Agents for environment-specific logic
- Hooks for post-deployment validation
- MCP server for external tool integration
- Comprehensive documentation
**Scenario 3: Team Distribution**
Company wants internal tools. Plugin Architect provides:
- Marketplace structure for multiple plugins
- Private repository setup guide
- Team installation instructions
- Version management strategy
## Integration with Plugin-Master Skill
The Plugin Architect agent automatically uses the plugin-master skill to:
- Access latest plugin documentation
- Follow current best practices
- Use proven templates and patterns
- Generate production-ready code
- Create proper package structures
## Best Practices Enforced
✅ **Structure**
- Correct directory layout
- Proper file locations
- Valid manifest files
✅ **Naming**
- kebab-case for plugin names
- Descriptive command names
- Clear agent descriptions
✅ **Documentation**
- Comprehensive README
- Usage examples
- Installation instructions
- Platform-specific notes (Windows/Git Bash/Mac/Linux)
✅ **Quality**
- Valid JSON syntax
- Proper frontmatter
- Error handling
- Security considerations
✅ **Cross-Platform Compatibility**
- GitHub-first installation for Windows/Git Bash
- Shell detection for testing environments ($MSYSTEM for Git Bash/MinGW)
- Path conversion awareness for Git Bash path issues
- Portable paths using ${CLAUDE_PLUGIN_ROOT}
- Testing guidance for all development environments
✅ **Distribution**
- GitHub-ready structure
- Marketplace compatibility
- Version management
- Publishing checklist
## Communication Style
The Plugin Architect is:
- **Clear and concise** - Explains decisions simply
- **Proactive** - Suggests improvements without being asked
- **Educational** - Teaches best practices while building
- **Practical** - Focuses on working solutions
- **Supportive** - Encourages learning and experimentation
## Success Criteria
A plugin designed by the Plugin Architect will:
- ✅ Work correctly on all supported platforms
- ✅ Follow all Claude Code plugin standards
- ✅ Include complete documentation
- ✅ Be ready for immediate use or publishing
- ✅ Demonstrate best practices
- ✅ Be maintainable and extensible
Invoke this agent when you want professional-quality plugin development with expert guidance and best practices built in.

121
commands/create-plugin.md Normal file
View File

@@ -0,0 +1,121 @@
---
description: Create a comprehensive Claude Code plugin with all necessary components and marketplace structure
---
## 🚨 CRITICAL GUIDELINES
### Windows File Path Requirements
**MANDATORY: Always Use Backslashes on Windows for File Paths**
When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).
**Examples:**
- ❌ WRONG: `D:/repos/project/file.tsx`
- ✅ CORRECT: `D:\repos\project\file.tsx`
This applies to:
- Edit tool file_path parameter
- Write tool file_path parameter
- All file operations on Windows systems
### Documentation Guidelines
**NEVER create new documentation files unless explicitly requested by the user.**
- **Priority**: Update existing README.md files rather than creating new documentation
- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise
- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone
- **User preference**: Only create additional .md files when user specifically asks for documentation
---
# Create Plugin
Autonomously create production-ready Claude Code plugins with complete structure, documentation, and marketplace packaging.
## Purpose
Guides Claude through the complete plugin creation workflow: fetching latest docs, generating all files (plugin.json, commands, agents, skills, README), creating marketplace structure, and providing installation instructions.
## Instructions
1. **Fetch latest documentation** from docs.claude.com (plugins-reference, plugin-marketplaces)
2. **Detect repository context** - Check git config for author info and marketplace.json existence
3. **Infer requirements** from user request - Only ask questions if genuinely ambiguous
4. **Create comprehensive structure**:
- Plugin manifest with all appropriate metadata fields
- Commands, agents, and Agent Skills as needed (2025: Skills are auto-discovered from skills/ directory)
- Hooks for automated workflows (PreToolUse, PostToolUse, SessionStart, etc.)
- MCP servers for external integrations (inline in plugin.json or .mcp.json)
- Complete README with examples and installation instructions
- Marketplace structure if not in existing marketplace repo
5. **Apply 2025 best practices**:
- Use Agent Skills for dynamic knowledge loading
- Configure hooks for automated validation and testing
- Support repository-level plugin configuration via .claude/settings.json
- Use ${CLAUDE_PLUGIN_ROOT} environment variable for portable paths
6. **Validate plugin.json schema** - **CRITICAL RULES**:
- ✅ `repository` must be a **string URL**, NOT an object
- ✅ `agents` field is **NOT needed** - auto-discovered from `agents/` directory
- ✅ `skills` field is **NOT needed** - auto-discovered from `skills/` directory
- ✅ `commands` field is **optional** - auto-discovered from `commands/` directory by default
- ✅ Only include: name, version, description, author (object), homepage, repository (string), license, keywords (array)
- ❌ NEVER include `agents: {...}` or `skills: {...}` in plugin.json - these cause validation errors
7. **CRITICAL: Update BOTH marketplace files**:
- Update `.claude-plugin/marketplace.json` (if exists) - Add plugin entry to plugins array
- Update `README.md` - Add plugin to appropriate category
- Synchronize descriptions and keywords between both files
8. **Provide clear instructions** for GitHub-first installation and repository-level configuration
## Best Practices
### Plugin Design Philosophy (2025)
**Agent-First, Minimal Commands:**
- **Primary interface:** Expert agent that users interact with conversationally
- **Minimal commands:** Only 0-2 slash commands per plugin for specific, high-value workflows
- **Why:** Users want to invoke domain expertise, not navigate command menus
- **Commands only for:** Automated workflows, batch operations, or specialized utilities
- **Agent handles:** Questions, guidance, code generation, troubleshooting, best practices
**Agent Naming Standard:**
- **CRITICAL:** Every plugin must have exactly ONE primary agent named `{domain}-expert`
- **Pattern:** `docker-master` → agent named `docker-expert`
- **Pattern:** `terraform-master` → agent named `terraform-expert`
- **Why:** Predictable names allow Claude to reliably invoke the correct agent
- **Never:** Use multiple specialized agents or non-standard names
**Examples:**
- ✅ `dotnet-microservices-master`: 0 commands, 1 agent (`dotnet-microservices-expert`)
- ✅ `docker-master`: 0 commands, 1 agent (`docker-expert`)
- ❌ OLD: 10+ commands + multiple agents - overwhelming and unpredictable!
**Default to action, not questions** - infer intent from context
- Include agent and Agent Skills by default
- Commands only when genuinely needed for automation
- Use detected git config values for author fields (never use placeholders)
- Create in plugins/ subdirectory if marketplace.json exists at repo root
- **ALWAYS update `.claude-plugin/marketplace.json` when adding plugins to a marketplace repository**
- Synchronize descriptions and keywords between plugin.json, marketplace.json, and README.md
- Add hooks for common automation needs (testing, linting, validation)
- Use ${CLAUDE_PLUGIN_ROOT} for all internal paths (scripts, configs, MCP servers)
- Include .claude/settings.json template for team distribution
- Leverage Agent Skills for dynamic, context-efficient knowledge delivery
- Configure MCP servers inline in plugin.json for simpler distribution
- Emphasize GitHub marketplace installation for cross-platform reliability (especially Windows/Git Bash)
- Document shell detection for plugin testing ($MSYSTEM for Git Bash/MinGW)
- Include path conversion guidance for Git Bash users developing plugins
- Support repository-level automatic installation for team standardization
## Example Usage
```
/create-plugin for Git workflow automation
/create-plugin with deployment commands and rollback features
/create-plugin that helps with code reviews and security scanning
```
The plugin-master skill activates automatically to provide complete templates and current best practices.

102
commands/validate-plugin.md Normal file
View File

@@ -0,0 +1,102 @@
---
description: Comprehensive validation of plugin structure, manifests, and configuration against 2025 standards
---
## 🚨 CRITICAL GUIDELINES
### Windows File Path Requirements
**MANDATORY: Always Use Backslashes on Windows for File Paths**
When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).
**Examples:**
- ❌ WRONG: `D:/repos/project/file.tsx`
- ✅ CORRECT: `D:\repos\project\file.tsx`
This applies to:
- Edit tool file_path parameter
- Write tool file_path parameter
- All file operations on Windows systems
### Documentation Guidelines
**NEVER create new documentation files unless explicitly requested by the user.**
- **Priority**: Update existing README.md files rather than creating new documentation
- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise
- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone
- **User preference**: Only create additional .md files when user specifically asks for documentation
---
# Validate Plugin
Systematically validate plugin files against current Claude Code requirements and best practices.
## Purpose
Pre-publishing validation that checks plugin.json schema, directory structure, component files, and marketplace compatibility. Identifies errors, warnings, and optimization opportunities.
## Instructions
1. **Locate plugin** - Use current directory or specified path
2. **Validate plugin.json** (2025 standards):
- Required field: `name`
- Schema validation: `author` as object, `version` as string, `keywords` as array
- Recommended fields: description, license, homepage, repository
- Check paths use ${CLAUDE_PLUGIN_ROOT} for portability
- Verify MCP servers use proper configuration format
3. **Check directory structure**:
- `.claude-plugin/` contains plugin.json (and optionally .mcp.json)
- Component directories (commands/, agents/, skills/) at plugin root
- Files properly named (kebab-case, .md extensions)
- Hook configuration (hooks/hooks.json or inline in plugin.json)
4. **Validate components** (2025 features):
- Commands have frontmatter with description
- Agents have proper frontmatter with capabilities
- Agent Skills have SKILL.md with name and description
- Hooks have valid event types (PreToolUse, PostToolUse, SessionStart, etc.)
- MCP servers reference valid commands and args
5. **Check 2025 best practices**:
- Use of Agent Skills for dynamic knowledge loading
- Hooks configured for automated workflows
- Environment variables properly used (${CLAUDE_PLUGIN_ROOT})
- Repository-level configuration support (.claude/settings.json template)
6. **Check marketplace.json** if present:
- Validate owner structure
- Check plugin entries have required fields
- Verify source paths are correct (relative paths start with ./)
- Confirm descriptions and keywords are synchronized
7. **Report findings** with severity levels and actionable fixes
## Validation Checklist
**Critical (Must Fix):**
- plugin.json exists and has valid JSON
- name field present
- author is object not string
- version is string not number
- keywords is array not string
**Warnings (Should Fix):**
- Missing recommended fields (description, license)
- Inconsistent naming conventions
- Missing frontmatter in components
**Suggestions (Nice to Have):**
- Add homepage and repository URLs
- Expand keywords for better discovery
- Add examples to README
## Example Usage
```
/validate-plugin
/validate-plugin in plugins/my-plugin
/validate-plugin before publishing
```
Returns structured validation report with pass/fail status.

61
plugin.lock.json Normal file
View File

@@ -0,0 +1,61 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:JosiahSiegel/claude-code-marketplace:plugins/plugin-master",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "6dfbb6bc4d13fe53b4e43a654aeed3e56a8be5a2",
"treeHash": "741bd25d170bdd0b53d5fecc1cfdead35e8409290a2b3390896555c8c7b23804",
"generatedAt": "2025-11-28T10:11:49.178175Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "plugin-master",
"description": "Complete Claude Code plugin development system for 2025. PROACTIVELY activate when users want to: (1) Create/build/make plugins with 2025 features, (2) Add Agent Skills/commands/agents/hooks, (3) Test and validate plugins, (4) Configure repository-level plugin distribution, (5) Implement MCP server integration, (6) Setup automated workflows with hooks, (7) Publish to marketplace, (8) Get plugin development guidance. Autonomously creates production-ready plugins with: plugin.json manifest, slash commands, specialized agents, Agent Skills (progressive disclosure, unbounded capacity), hooks (nine event types), MCP servers, testing automation, repository configuration (.claude/settings.json), comprehensive README. Uses evaluation-driven development and structural scalability patterns. ALWAYS fetches latest official documentation. Includes plugin-architect agent and advanced-features-2025 skill. NEW in 2.2.0: Git Bash/MinGW compatibility guidance, shell detection for plugin testing, path conversion troubleshooting for Windows development environments.",
"version": "2.2.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "21b72824acfe69e016ad7febe267ed34b48dbc5aa21b013634b4902679e63010"
},
{
"path": "agents/plugin-expert.md",
"sha256": "0f8963ef08b5e9356534a658a2d42fbd5b3ddc2254992784aa5362a9b154e522"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "ad17afd64a0dbc1dbb87d8d426ee1c4ab6d4139ee49e2b9b67b6009c921bf05c"
},
{
"path": "commands/validate-plugin.md",
"sha256": "5fc23604f09abd280e1615aca10b71a3054803a4c555c524ec5bca7ba5e24d4a"
},
{
"path": "commands/create-plugin.md",
"sha256": "e4a13b92551a339a7fcae4432ead7dc39eb34c4ad9ca3abd70044a8121d44cb9"
},
{
"path": "skills/advanced-features-2025/SKILL.md",
"sha256": "32574f6b453756b67509764f14c41806a5f2307072fc2f94a4789a09ab660752"
},
{
"path": "skills/plugin-master/SKILL.md",
"sha256": "9f843d49c7892dffca0b7adc71f6f7d636972fdc10bb22c5bede532878120241"
}
],
"dirSha256": "741bd25d170bdd0b53d5fecc1cfdead35e8409290a2b3390896555c8c7b23804"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

766
skills/advanced-features-2025/SKILL.md Normal file
View File

@@ -0,0 +1,766 @@
---
name: advanced-features-2025
description: "Complete guide to 2025 Claude Code plugin features: Agent Skills, Hooks, MCP integration, and repository-level configuration. PROACTIVELY activate for: (1) Agent Skills implementation, (2) Hook automation setup, (3) MCP server integration, (4) Team plugin distribution, (5) Advanced plugin architecture. Provides: Agent Skills patterns, hook event types, MCP configuration, repository setup, context optimization strategies. Ensures production-ready 2025 plugin capabilities."
license: MIT
---
## 🚨 CRITICAL GUIDELINES
### Windows File Path Requirements
**MANDATORY: Always Use Backslashes on Windows for File Paths**
When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).
**Examples:**
- ❌ WRONG: `D:/repos/project/file.tsx`
- ✅ CORRECT: `D:\repos\project\file.tsx`
This applies to:
- Edit tool file_path parameter
- Write tool file_path parameter
- All file operations on Windows systems
### Documentation Guidelines
**NEVER create new documentation files unless explicitly requested by the user.**
- **Priority**: Update existing README.md files rather than creating new documentation
- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise
- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone
- **User preference**: Only create additional .md files when user specifically asks for documentation
---
# Advanced Plugin Features (2025)
Comprehensive guide to cutting-edge Claude Code plugin capabilities introduced in 2025.
## Agent Skills
**What are Agent Skills?**
Skills that Claude autonomously invokes based on task context, enabling dynamic knowledge loading and context-efficient workflows through progressive disclosure architecture.
### Key Characteristics (2025)
- **Automatic Discovery**: Skills are discovered from `skills/` directory upon plugin installation
- **Context-Driven**: Claude loads Skills only when relevant to the current task
- **Progressive Disclosure**: Three-tier information structure (frontmatter → SKILL.md body → linked files)
- **Dynamic Loading**: Reduces context usage by loading only necessary components
- **Unbounded Capacity**: With filesystem access, agents can bundle effectively unlimited content
### Creating Agent Skills
**Directory Structure:**
```
plugin-root/
└── skills/
├── skill-name-1/
│ └── SKILL.md
└── skill-name-2/
├── SKILL.md
├── examples/
└── resources/
```
**SKILL.md Format:**
```markdown
---
name: skill-name
description: "Complete [domain] system. PROACTIVELY activate for: (1) [use cases]. Provides: [capabilities]."
license: MIT
---
# Skill Title
## Overview
High-level summary always loaded
## Core Concepts
Key information organized for quick scanning
## Examples
Concrete usage patterns
## Best Practices
Proven approaches and patterns
```
### Agent Skills Best Practices (2025)
**Evaluation-Driven Development:**
- Start by identifying capability gaps through representative tasks
- Observe where agents struggle, then build skills addressing specific shortcomings
- Avoid anticipating needs upfront - respond to actual failures
**Structural Scalability:**
- When SKILL.md becomes unwieldy, split content into separate files and reference them
- Keep mutually exclusive contexts in distinct paths to reduce token consumption
- Code should serve dual purposes: executable tools AND documentation
- Split large skills into focused components as needed
**Iterative Refinement:**
- Collaborate with Claude during development
- Ask Claude to capture successful approaches into reusable context
- Request self-reflection on failure modes to reveal actual information needs
**DO:**
- Use descriptive, action-oriented names
- Write comprehensive activation descriptions with numbered use cases
- Include concrete examples and code snippets
- Organize content with clear headers for scanning
- Keep individual skills focused on single domains
**DON'T:**
- Create overly broad skills that cover too many topics
- Duplicate content across multiple skills
- Skip the frontmatter metadata
- Use generic descriptions that don't specify activation scenarios
### Context Efficiency Strategy (2025)
Agent Skills achieve unbounded capacity through:
1. **Progressive Disclosure**: Three-tier structure (frontmatter loaded at startup → SKILL.md body when determining relevance → additional files only when needed)
2. **Lazy Loading**: Only loaded when task matches activation criteria
3. **Filesystem Retrieval**: With code execution capabilities, agents retrieve only necessary components instead of loading entire skills
4. **Focused Scope**: Each skill covers specific domain/capability
5. **Structured Content**: Headers enable Claude to scan efficiently
6. **Optimized Metadata**: Name and description fields directly influence triggering accuracy
**Example Activation Pattern:**
```
User task: "Deploy to production"
→ Claude scans skill metadata (frontmatter only)
→ Identifies deployment-workflows skill as relevant
→ Loads SKILL.md body to confirm match
→ Retrieves only needed sections/files
→ Unloads when task complete
```
**Result**: Effectively unlimited bundled content without context window constraints.
## Hooks
**What are Hooks?**
Automatic triggers that execute actions at specific events during Claude Code's workflow.
### Hook Event Types (2025)
**Tool Lifecycle:**
- `PreToolUse`: Before any tool execution (validation, preparation)
- `PostToolUse`: After tool execution (testing, cleanup, notifications)
**Session Lifecycle:**
- `SessionStart`: When Claude Code session begins
- `SessionEnd`: When session terminates
- `PreCompact`: Before context compaction (cleanup, state save)
**User Interaction:**
- `UserPromptSubmit`: After user submits prompt (logging, preprocessing)
- `Notification`: When notifications are displayed
- `Stop`: When user stops execution
- `SubagentStop`: When subagent terminates
### Hook Configuration
**Inline in plugin.json:**
```json
{
"name": "my-plugin",
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh"
}
]
}
]
}
}
```
**Separate hooks.json:**
```json
{
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "./scripts/format.sh",
"env": {
"FILE_PATH": "${TOOL_INPUT_FILE_PATH}"
}
}
]
}
],
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Session started at $(date)' >> session.log"
}
]
}
]
}
```
### Hook Matchers
**Tool Matchers:**
Match specific tools using regex patterns:
- `Write` - File write operations
- `Edit` - File edit operations
- `Write|Edit` - Either write or edit
- `Bash` - Shell command execution
- `.*` - Any tool (use sparingly)
**Matcher Best Practices:**
- Be specific to avoid unnecessary executions
- Use `|` for multiple tools
- Test matchers thoroughly
- Document why each matcher is used
### Common Hook Patterns
**Automated Testing:**
```json
{
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh",
"description": "Run tests after code changes"
}
]
}
]
}
```
**Code Formatting:**
```json
{
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "prettier --write ${TOOL_INPUT_FILE_PATH}"
}
]
}
]
}
```
**Session Logging:**
```json
{
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/log-session.sh"
}
]
}
]
}
```
**Validation:**
```json
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bash.sh"
}
]
}
]
}
```
## MCP Server Integration
**What is MCP?**
Model Context Protocol enables Claude to interact with external tools, APIs, and services through standardized server interfaces.
### MCP Configuration (2025)
**Inline in plugin.json (Recommended for Distribution):**
```json
{
"name": "my-plugin",
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "@company/mcp-server"],
"env": {
"API_KEY": "${API_KEY}",
"SERVER_URL": "https://api.example.com"
}
},
"local-server": {
"command": "${CLAUDE_PLUGIN_ROOT}/bin/server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
}
}
}
```
**Separate .mcp.json:**
```json
{
"mcpServers": {
"database-server": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/mcp/db-server.js"],
"env": {
"DB_CONNECTION": "${DATABASE_URL}"
}
}
}
}
```
### MCP Best Practices
**DO:**
- Use `${CLAUDE_PLUGIN_ROOT}` for plugin-relative paths
- Document required environment variables in README
- Provide sensible defaults for optional configuration
- Test MCP servers in isolation before integration
- Include error handling in server implementations
**DON'T:**
- Hardcode absolute paths (breaks portability)
- Expose secrets in plugin.json (use environment variables)
- Assume environment variables are always set
- Skip validation of MCP server responses
### MCP Use Cases
**API Integration:**
```json
{
"mcpServers": {
"stripe-api": {
"command": "npx",
"args": ["-y", "@stripe/mcp-server"],
"env": {
"STRIPE_API_KEY": "${STRIPE_API_KEY}"
}
}
}
}
```
**Database Access:**
```json
{
"mcpServers": {
"postgres": {
"command": "${CLAUDE_PLUGIN_ROOT}/bin/pg-server",
"args": ["--connection", "${DATABASE_URL}"]
}
}
}
```
**Custom Tooling:**
```json
{
"mcpServers": {
"internal-tools": {
"command": "python",
"args": ["${CLAUDE_PLUGIN_ROOT}/mcp/tools_server.py"],
"env": {
"TOOLS_CONFIG": "${CLAUDE_PLUGIN_ROOT}/config/tools.json"
}
}
}
}
```
## Repository-Level Plugin Configuration
**What is it?**
Automatic marketplace and plugin installation for team members when they trust a repository folder.
### Configuration File Location
Create `.claude/settings.json` at repository root:
```
repo-root/
├── .claude/
│ └── settings.json
├── src/
└── README.md
```
### Settings Format
```json
{
"extraKnownMarketplaces": [
"company-org/internal-plugins",
"JosiahSiegel/claude-code-marketplace"
],
"plugins": {
"enabled": [
"deployment-helper@company-org",
"test-master@JosiahSiegel",
"code-review-helper"
]
}
}
```
### Team Distribution Workflow
1. **Repository Maintainer:**
- Create `.claude/settings.json`
- Configure required marketplaces and plugins
- Commit to version control
- Document in README that team should trust folder
2. **Team Member:**
- Clone repository
- Open in Claude Code
- Trust folder when prompted
- Automatic installation occurs
3. **Updates:**
- Maintainer updates settings.json
- Team members pull changes
- Claude Code applies updated configuration
### Best Practices
**Start Minimal:**
```json
{
"extraKnownMarketplaces": ["company/tools"],
"plugins": {
"enabled": ["essential-plugin@company"]
}
}
```
**Document Requirements:**
Add to README:
```markdown
## Claude Code Setup
This repository uses Claude Code plugins for standardized workflows.
### First Time Setup
1. Install Claude Code
2. Clone this repository
3. Open in Claude Code
4. Trust this repository folder when prompted
Plugins will be installed automatically.
```
**Security Considerations:**
- Only trust repositories from known sources
- Review settings.json before trusting
- Use organizational repositories for internal plugins
- Document why each plugin is required
## Environment Variables
### Standard Variables (2025)
**${CLAUDE_PLUGIN_ROOT}:**
Resolves to plugin's absolute installation path.
**Usage:**
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
}
]
}
]
},
"mcpServers": {
"local-server": {
"command": "${CLAUDE_PLUGIN_ROOT}/bin/server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
}
}
}
```
**Why Use It:**
- Ensures portability across different installation locations
- Works on all platforms (Windows, Mac, Linux)
- Simplifies plugin distribution
- Enables relative path resolution
### Custom Environment Variables
**In Hooks:**
```json
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/deploy.sh",
"env": {
"ENVIRONMENT": "${DEPLOY_ENV}",
"API_KEY": "${API_KEY}",
"CUSTOM_VAR": "value"
}
}
]
}
```
**In MCP Servers:**
```json
{
"mcpServers": {
"api-server": {
"command": "npx",
"args": ["-y", "@company/mcp-server"],
"env": {
"API_URL": "${COMPANY_API_URL}",
"AUTH_TOKEN": "${COMPANY_AUTH_TOKEN}"
}
}
}
}
```
**Best Practices:**
- Document all required environment variables in README
- Provide .env.example template
- Use sensible defaults when possible
- Validate environment variables in scripts
- Never hardcode secrets
## Complete Plugin Example (2025 Best Practices)
```
deployment-automation/
├── .claude-plugin/
│ └── plugin.json
├── commands/
│ ├── deploy-staging.md
│ └── deploy-production.md
├── agents/
│ └── deployment-expert.md
├── skills/
│ ├── deployment-workflows/
│ │ └── SKILL.md
│ └── kubernetes-patterns/
│ └── SKILL.md
├── hooks/
│ └── hooks.json
├── scripts/
│ ├── validate-deployment.sh
│ └── run-tests.sh
├── .claude/
│ └── settings.json
└── README.md
```
**plugin.json:**
```json
{
"name": "deployment-automation",
"version": "2.0.0",
"description": "Complete deployment automation system. PROACTIVELY activate for: (1) ANY deployment task, (2) Production releases, (3) Rollback operations, (4) Deployment validation, (5) Kubernetes workflows. Provides: automated deployment, rollback safety, validation hooks, multi-environment support. Ensures safe, reliable deployments.",
"author": {
"name": "Your Company",
"email": "[email protected]"
},
"keywords": ["deployment", "kubernetes", "production", "automation", "cicd"],
"license": "MIT",
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-deployment.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh"
}
]
}
]
},
"mcpServers": {
"kubernetes": {
"command": "kubectl",
"args": ["proxy"],
"env": {
"KUBECONFIG": "${KUBECONFIG}"
}
}
}
}
```
**hooks/hooks.json:**
```json
{
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Deployment session started' >> deployment.log"
}
]
}
]
}
```
**.claude/settings.json:**
```json
{
"extraKnownMarketplaces": ["company/internal-tools"],
"plugins": {
"enabled": ["deployment-automation@company"]
}
}
```
## Migration from Legacy Plugins
### Key Changes in 2025
**1. Component Discovery:**
- **Old**: Manual registration in plugin.json
- **New**: Automatic discovery from standard directories
**2. Skills → Agent Skills:**
- **Old**: Static skills loaded in context
- **New**: Dynamic Agent Skills loaded on-demand
**3. Hooks:**
- **Old**: Limited hook support
- **New**: Comprehensive event system (PreToolUse, PostToolUse, SessionStart, etc.)
**4. MCP Integration:**
- **Old**: External configuration required
- **New**: Inline in plugin.json or .mcp.json
**5. Repository Configuration:**
- **Old**: Manual plugin installation per developer
- **New**: Automatic installation via .claude/settings.json
### Migration Checklist
- [ ] Update plugin.json to version 2.x.x
- [ ] Convert static skills to Agent Skills with proper frontmatter
- [ ] Add hooks for automated workflows
- [ ] Configure MCP servers inline if applicable
- [ ] Create .claude/settings.json for team distribution
- [ ] Update README with 2025 installation instructions
- [ ] Test on all platforms (Windows, Mac, Linux)
- [ ] Use ${CLAUDE_PLUGIN_ROOT} for all internal paths
- [ ] Validate with latest Claude Code version
## Debugging Advanced Features
### Debug Mode
```bash
claude --debug
```
**Shows:**
- Plugin loading status
- Agent Skills discovery and activation
- Hook registration and execution
- MCP server initialization
- Environment variable resolution
### Common Issues
**Agent Skills not loading:**
- Verify SKILL.md exists in skills/skill-name/ directory
- Check frontmatter has name and description fields
- Ensure description includes activation criteria
**Hooks not executing:**
- Verify event type is valid (PreToolUse, PostToolUse, etc.)
- Check matcher pattern matches tool name
- Confirm script has execute permissions
- Validate ${CLAUDE_PLUGIN_ROOT} resolves correctly
**MCP server not starting:**
- Check command and args are correct
- Verify required environment variables are set
- Test MCP server independently
- Review server logs for errors
**Repository settings not applying:**
- Confirm .claude/settings.json is at repository root
- Verify repository folder is trusted
- Check marketplace names are correct
- Ensure plugins exist in specified marketplaces
## Additional Resources
- Official Plugin Reference: https://docs.claude.com/en/docs/claude-code/plugins-reference
- Marketplace Guide: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces
- Agent Skills Engineering: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- MCP Documentation: https://docs.claude.com/en/docs/claude-code/mcp
- Community Plugins: https://claudecodemarketplace.com/
## Conclusion
2025 plugin features enable:
- **Context Efficiency**: Agent Skills load knowledge dynamically
- **Automation**: Hooks trigger workflows automatically
- **Integration**: MCP connects external tools seamlessly
- **Team Standardization**: Repository-level configuration ensures consistency
Apply these patterns to create production-ready, scalable plugins that leverage the full power of Claude Code's 2025 capabilities.

1747
skills/plugin-master/SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff