Initial commit
This commit is contained in:
Zhongwei Li
18
.claude-plugin/plugin.json
Normal file
18
.claude-plugin/plugin.json
Normal 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
3
README.md
Normal 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
214
agents/plugin-expert.md
Normal 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
121
commands/create-plugin.md
Normal 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
102
commands/validate-plugin.md
Normal 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
61
plugin.lock.json
Normal 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
766
skills/advanced-features-2025/SKILL.md
Normal 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
1747
skills/plugin-master/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user