Plugin Management

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 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:

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:

// 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

# 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

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

# 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

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

# 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

{
  "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

Common Mistakes

// ❌ 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

---
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

Tool Permission Sets

# 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

# 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

Validation Commands

# 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)

mkdir -p plugins/my-plugin/.claude-plugin

cat > plugins/my-plugin/.claude-plugin/plugin.json <<EOF
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description",
  "author": { "name": "Your Name" },
  "keywords": ["keyword1"]
}
EOF

cat > plugins/my-plugin/README.md <<EOF
# My Plugin

Description

## Installation

\`\`\`bash
/plugin install my-plugin@puerto
\`\`\`

## License

MIT
EOF

node scripts/validate-plugin.js plugins/my-plugin
node scripts/generate-catalog.js

Important Reminders

• NO GIT AUTOMATION: Creates/modifies files only. User handles git.
• INTERACTIVE ONLY: Gather requirements via Q&A before implementing.
• SKILLS-FIRST: Read this skill at the start of EVERY invocation.
• VALIDATE ALWAYS: Run validation before presenting results.
• PATTERN LEARNING: Analyze 5-10 similar plugins for consistency.

Version: 2.0 Last Updated: January 2025 Use Cases: Puerto plugin creation, modification, validation, tuning, documentation