# plugin-management > The plugin manager supports five operations: - Author: Tomas Kavka - Repository: bandofai/puerto - Version: 20251129200041 - Stars: 3 - Forks: 0 - Last Updated: 2026-02-08 - Source: https://github.com/bandofai/puerto - Web: https://mule.run/skillshub/@@bandofai/puerto~plugin-management:20251129200041 --- # Puerto Plugin Management Skill **Complete lifecycle management for Claude Code plugins in the Puerto marketplace** ## Core Principles 1. **Skills-First**: Agents MUST read skill documents before proceeding - patterns separate from workflow 2. **Validation-First**: All plugins must pass `scripts/validate-plugin.js` before publication 3. **Consistency**: Follow established Puerto conventions across all plugins 4. **Minimal Structure**: Only create directories that will contain files 5. **Pattern Learning**: Analyze similar plugins (5-10) to maintain consistency --- ## Operations Overview The plugin manager supports five operations: | Operation | Description | |-----------|-------------| | **Create** | Generate complete plugin structures with intelligent pattern learning | | **Modify** | Update existing plugins while preserving architectural consistency | | **Validate** | Check plugin compliance with Puerto standards | | **Tune** | Optimize plugin configurations (model selection, tool permissions) | | **Document** | Auto-generate comprehensive READMEs | --- ## Operation 1: Create New Plugin ### Step 1: Gather Requirements Ask these questions one at a time: 1. **Plugin Name** (Required) - Format: `/^[a-z0-9-]+$/` (lowercase-hyphens only) - Check if `plugins/[name]/` already exists 2. **Description** (Required) - Brief, 1-2 sentences 3. **Version** (Default: 1.0.0) - Semver format 4. **Author Name** (Required) 5. **Keywords** (Recommended) - Comma-separated for discovery 6. **Number of Agents** (Required, >= 0) 7. **For Each Agent**: - Name (lowercase-hyphens) - Description (starts with "PROACTIVELY use when..." or "Use when...") - Model (haiku/sonnet/opus) - Tools (comma-separated) 8. **Number of Skills** (Optional, >= 0) 9. **For Each Skill**: - Name (lowercase-hyphens) - Description 10. **Templates Needed?** (Optional) ### Step 2: Pattern Learning Find similar plugins via keywords: ```bash for dir in plugins/*/; do plugin_json="$dir/.claude-plugin/plugin.json" if [ -f "$plugin_json" ] && grep -qi "keyword1\|keyword2" "$plugin_json"; then echo "$dir" fi done | head -10 ``` Extract patterns from 5-10 similar plugins: - Agent count and structure - Model selection rationale - Tool permission patterns - Skill organization ### Step 3: In-Memory Validation Before creating files, validate: ```javascript // Name format if (!/^[a-z0-9-]+$/.test(pluginName)) { error("Plugin name must be lowercase alphanumeric with hyphens only"); } // Version format if (!/^\d+\.\d+\.\d+/.test(version)) { warn("Version should follow semver format"); } // Author format if (typeof author === 'string') { error("Author must be object with 'name' property, not string"); } // Duplicate check if (fs.existsSync(`plugins/${pluginName}`)) { error(`Plugin 'plugins/${pluginName}/' already exists`); } ``` ### Step 4: Present Plan for Approval Show user what will be created: ``` Plugin Creation Plan ==================== Plugin: my-plugin (v1.0.0) Description: Brief description here Author: John Doe Keywords: frontend, react, typescript Directory Structure: -------------------- plugins/my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── agents/ │ ├── agent-1.md │ └── agent-2.md ├── skills/ │ └── skill-1/ │ └── SKILL.md └── README.md Patterns applied from similar plugins: - Skills-first approach in all agents - Model selection: Haiku for CRUD, Sonnet for analysis Does this plan look good? (yes/no): ``` ### Step 5: Create Plugin Structure ```bash # Create directories mkdir -p "plugins/${plugin_name}/.claude-plugin" [ $agent_count -gt 0 ] && mkdir -p "plugins/${plugin_name}/agents" [ $skill_count -gt 0 ] && mkdir -p "plugins/${plugin_name}/skills" [ $template_count -gt 0 ] && mkdir -p "plugins/${plugin_name}/templates" ``` ### Step 6: Validate and Update Catalog ```bash node scripts/validate-plugin.js "plugins/${plugin_name}" node scripts/generate-catalog.js ``` ### Step 7: Report Completion ``` ✅ Plugin Created Successfully! Location: plugins/my-plugin/ Files Created: - plugins/my-plugin/.claude-plugin/plugin.json - plugins/my-plugin/README.md - plugins/my-plugin/agents/agent-1.md Validation: ✅ Passed (0 errors, 0 warnings) Catalog: ✅ Updated Next Steps: 1. Review generated files and customize 2. Add implementation details to agents 3. Expand skill documents with domain-specific patterns 4. Commit changes: git add plugins/my-plugin .claude-plugin/marketplace.json Installation Command: /plugin install my-plugin@puerto ``` --- ## Operation 2: Modify Existing Plugin ### Workflow 1. **List plugins**: `ls -d plugins/*/ | sed 's|plugins/||' | sed 's|/$||'` 2. **Select plugin** to modify 3. **Show components** (plugin.json, README, agents, skills, templates) 4. **Select component** to modify 5. **Perform modification** (preserve skills-first approach in agents) 6. **Re-validate**: `node scripts/validate-plugin.js "plugins/${plugin_name}"` 7. **Update catalog** if metadata changed 8. **Report completion** --- ## Operation 3: Validate Plugin ### Prerequisites Check ```bash # Check Node.js node_version=$(node --version 2>/dev/null) if [ -z "$node_version" ]; then echo "❌ Error: Node.js not found. Required: >= v18.0.0" exit 1 fi # Check validation script if [ ! -f scripts/validate-plugin.js ]; then echo "❌ Error: scripts/validate-plugin.js not found" exit 1 fi ``` ### Run Validation ```bash node scripts/validate-plugin.js "plugins/${plugin_name}" ``` ### Present Results with Fix Suggestions ``` Plugin Validation Report ======================== ❌ ERRORS (must fix): - Missing required field: name - author must be object with "name" property Suggested Fixes: ---------------- Error: "author must be an object..." Fix: Change in plugin.json: Before: "author": "John Doe" After: "author": { "name": "John Doe" } Would you like me to apply these fixes automatically? (yes/no): ``` --- ## Operation 4: Tune/Optimize Plugin ### Analysis Areas 1. **Model Selection** - Haiku for CRUD (cost-effective) - Sonnet for analysis (balanced) - Opus for architecture (deep reasoning) 2. **Tool Permissions** - Remove unused tools - Follow principle of least privilege 3. **Skills-First Approach** - Ensure all agents read skills first 4. **Documentation Quality** - Installation command format - Feature descriptions - Usage examples ### Optimization Report ``` Plugin Optimization Report ========================== Model Selection: ---------------- ✅ agent-1.md: haiku (appropriate for CRUD) ⚠️ agent-2.md: opus (may be overkill) Suggestion: Consider 'sonnet' (12x cost savings) Tool Permissions: ----------------- ⚠️ agent-2.md: Has WebSearch but never uses it Suggestion: Remove unused tools Skills-First: ------------- ❌ agent-1.md: Missing skills-first section Suggestion: Add mandatory skill reading step Overall Score: 7/10 ``` --- ## Operation 5: Generate Documentation ### README Structure ```markdown # Plugin Name [Description from plugin.json] ## Installation \`\`\`bash /plugin install plugin-name@puerto \`\`\` ## Features - **[Agent 1 Name]**: [Agent 1 description] - **[Agent 2 Name]**: [Agent 2 description] ## Usage ### [Agent Name] [Description and examples] ## License MIT ``` --- ## Plugin Structure Reference ### Required Files ``` plugins/[plugin-name]/ ├── .claude-plugin/ │ └── plugin.json # REQUIRED └── README.md # HIGHLY RECOMMENDED ``` ### Optional Directories (create only when needed) ``` plugins/[plugin-name]/ ├── agents/ # Agent definitions (.md) ├── skills/ # Skill documents (subdirs with SKILL.md) ├── templates/ # Data templates (.json) ├── commands/ # Slash commands (.md) └── hooks/ # Lifecycle hooks (rarely used) ``` --- ## plugin.json Format ### Complete Structure ```json { "name": "plugin-name", "version": "1.0.0", "description": "Brief, clear description", "author": { "name": "Author Name" }, "keywords": ["tag1", "tag2"], "agents": ["./agents/agent-name.md"], "skills": ["./skills/skill-name/SKILL.md"], "templates": ["./templates/template-name.json"] } ``` ### Validation Rules | Field | Required | Format | |-------|----------|--------| | name | ✅ | `/^[a-z0-9-]+$/` | | version | ✅ | Semver (e.g., `1.0.0`) | | description | ✅ | Non-empty string | | author | Recommended | Object with `name` property | | keywords | Recommended | Array of strings | ### Common Mistakes ```json // ❌ BAD: Author as string { "author": "John Doe" } // ✅ GOOD: Author as object { "author": { "name": "John Doe" } } // ❌ BAD: Uppercase name { "name": "MyPlugin" } // ✅ GOOD: Lowercase with hyphens { "name": "my-plugin" } ``` --- ## Agent Definition Format ### Complete Structure ```markdown --- name: agent-name description: PROACTIVELY use when [trigger]. [What it does]. tools: Read, Write, Edit, Bash, Grep, Glob model: haiku --- You are a [role] specializing in [domain]. ## CRITICAL: Skills-First Approach **MANDATORY FIRST STEP**: Read skill before proceeding. \`\`\`bash if [ -f ~/.claude/skills/skill-name/SKILL.md ]; then cat ~/.claude/skills/skill-name/SKILL.md elif [ -f .claude/skills/skill-name/SKILL.md ]; then cat .claude/skills/skill-name/SKILL.md elif [ -f plugins/[plugin-name]/skills/skill-name/SKILL.md ]; then cat plugins/[plugin-name]/skills/skill-name/SKILL.md fi \`\`\` This is NON-NEGOTIABLE. ## When Invoked 1. **Read skill** (mandatory, non-skippable) 2. [Step 2] 3. [Step 3] ``` ### Model Selection Guidelines | Model | Use For | Cost | |-------|---------|------| | **Haiku** | CRUD, fast processing, templates | ~$0.25/1M tokens | | **Sonnet** | Analysis, domain expertise, code review | ~$3/1M tokens | | **Opus** | Architecture, deep reasoning, planning | ~$15/1M tokens | ### Tool Permission Sets ```yaml # Read-only tools: Read, Grep, Glob, Bash # File creator tools: Read, Write, Bash, Grep, Glob # File editor tools: Read, Edit, Bash, Grep, Glob # Full file operations tools: Read, Write, Edit, Bash, Grep, Glob # With web research tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch ``` --- ## Skill Document Format ### Directory Structure ``` skills/ └── skill-name/ └── SKILL.md # One SKILL.md per subdirectory ``` ### Content Pattern ```markdown # Skill Name **Production patterns for [domain]** ## Core Principles 1. Principle 1 2. Principle 2 --- ## Pattern 1 ### Description [Explanation] ### Example \`\`\`[language] // ✅ GOOD [good example] // ❌ BAD [bad example] \`\`\` --- ## Best Practices Checklist - [ ] Item 1 - [ ] Item 2 --- **Version**: 1.0 **Last Updated**: [Date] ``` --- ## Naming Conventions | Type | Format | Examples | |------|--------|----------| | Plugin | `lowercase-hyphens` | `data-analyst`, `web-performance` | | Agent | `action-noun` | `component-builder`, `progress-analyzer` | | Skill | `noun-domain` | `component-development`, `api-implementation` | --- ## Validation Commands ```bash # Validate single plugin node scripts/validate-plugin.js plugins/my-plugin # Validate all plugins for dir in plugins/*/; do node scripts/validate-plugin.js "$dir" done # Update catalog after changes node scripts/generate-catalog.js ``` --- ## Edge Case Handling ### Duplicate Plugin Names ``` ❌ Error: Plugin 'plugins/my-plugin/' already exists Options: 1. Choose a different name 2. Overwrite existing plugin (WARNING: destructive!) 3. Cancel operation ``` ### Invalid Plugin Names ``` ❌ Error: Plugin name 'MyPlugin' is invalid Plugin names must be lowercase alphanumeric with hyphens only. ✅ my-plugin, data-analyst, engineering ❌ MyPlugin, my_plugin, my plugin ``` ### Validation Failures ``` ❌ Plugin validation failed Options: 1. Fix errors manually 2. Let me fix automatically (if possible) 3. Cancel operation ``` --- ## Best Practices Checklist ### Plugin Structure - [ ] plugin.json has all required fields - [ ] Plugin name follows lowercase-hyphens convention - [ ] Author is object with "name" property - [ ] Version follows semver format - [ ] README.md exists and is complete - [ ] Only needed directories created ### Agent Definition - [ ] YAML frontmatter complete (name, description, tools, model) - [ ] Description starts with "PROACTIVELY use when..." or "Use when..." - [ ] Skills-first approach implemented - [ ] Model selection appropriate for task - [ ] Tool permissions follow least privilege - [ ] Clear numbered workflow steps ### Skill Document - [ ] Located in `skills/[name]/SKILL.md` - [ ] Contains production-tested patterns - [ ] Includes ✅ GOOD / ❌ BAD examples - [ ] Has core principles section - [ ] Includes best practices checklist ### Documentation - [ ] README has `/plugin install name@puerto` - [ ] Features section lists clear benefits - [ ] Usage section has examples - [ ] License section included ### Validation - [ ] Passes validate-plugin.js with no errors - [ ] Warnings addressed - [ ] Catalog regenerated - [ ] Plugin appears in marketplace.json --- ## Quick Reference ### Create Plugin (Minimal) ```bash mkdir -p plugins/my-plugin/.claude-plugin cat > plugins/my-plugin/.claude-plugin/plugin.json < plugins/my-plugin/README.md <