gh-bandofai-puerto-plugins-claude-md-master/skills/marketplace-discovery/SKILL.md

Puerto Marketplace Discovery & Integration

Version: 1.0.0 Last Updated: 2025-11-01 Purpose: Comprehensive guide to discovering and integrating Puerto marketplace plugins

---

Purpose of This Skill

This skill provides knowledge for autonomously discovering installed Puerto plugins and generating appropriate CLAUDE.md integration sections. Use this when the marketplace-integrator agent needs to scan plugins and create routing rules.

Key Learning Objectives:

• Understand Puerto marketplace structure (140+ plugins, 27 squads)
• Learn how to discover installed plugins via filesystem
• Extract agent descriptions from plugin manifests
• Generate routing rules from agent descriptions
• Create comprehensive "Installed Puerto Plugins" sections

---

Puerto Marketplace Overview

Structure

• Total Plugins: 140+
• Organization: 27 specialized squads
• Installation Locations:
  • Global: ~/.claude/plugins/
  • Project-local: .claude/plugins/

Plugin Structure

Every Puerto plugin follows this consistent structure:

~/.claude/plugins/[plugin-name]/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── agents/
│   ├── agent1.md            # Agent markdown files
│   ├── agent2.md
│   └── agent3.md
├── skills/
│   └── skill-name/
│       └── SKILL.md         # Skill content
├── commands/                # Optional
│   └── command.md
└── README.md

---

Plugin Discovery Process

Step 1: Scan Installation Directories

Check both global and project-local plugin directories:

# Discover installed plugins
for plugin_dir in ~/.claude/plugins/* .claude/plugins/*; do
    if [ -d "$plugin_dir" ]; then
        plugin_json="$plugin_dir/.claude-plugin/plugin.json"
        if [ -f "$plugin_json" ]; then
            # Plugin found - extract info
            echo "Found plugin: $plugin_dir"
        fi
    fi
done

Step 2: Read Plugin Manifest

Extract key information from plugin.json:

# Read plugin.json
plugin_name=$(jq -r '.name' "$plugin_json")
plugin_description=$(jq -r '.description' "$plugin_json")
agent_files=$(jq -r '.agents[]' "$plugin_json")

Example plugin.json:

{
  "name": "engineering",
  "version": "1.0.0",
  "description": "Frontend development specialist for React/Vue/Svelte",
  "agents": [
    "./agents/frontend-engineer.md",
    "./agents/state-architect.md",
    "./agents/style-implementer.md"
  ],
  "skills": [
    "./skills/component-patterns.md"
  ],
  "author": {
    "name": "Puerto Plugin Collection"
  }
}

Step 3: Extract Agent Information

Read agent frontmatter from markdown files:

# For each agent file, extract frontmatter
for agent_file in $agent_files; do
    full_path="$plugin_dir/$agent_file"

    # Extract name from frontmatter
    agent_name=$(grep '^name:' "$full_path" | sed 's/name: //')

    # Extract description (contains trigger conditions)
    agent_description=$(grep '^description:' "$full_path" | sed 's/description: //')

    echo "Agent: $agent_name"
    echo "Description: $agent_description"
done

Example agent frontmatter:

---
name: frontend-engineer
description: PROACTIVELY use when implementing React/Vue/Svelte components. Skill-aware builder that produces production-ready components with TypeScript and tests.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---

Step 4: Generate Routing Rules from Descriptions

Parse agent descriptions to extract trigger conditions:

Pattern: Descriptions often contain "PROACTIVELY use when [trigger condition]"

Example:

• Description: "PROACTIVELY use when implementing React/Vue/Svelte components"
• Generated rule: WHEN implementing components → AUTOMATICALLY invoke: engineering/frontend-engineer

---

Puerto Plugin Categories (27 Squads)

1. Frontend Development Squad

• engineering: React/Vue/Svelte component development
• ux-researcher: User research and usability testing
• ux-writer: UX writing and microcopy
• accessibility-specialist: WCAG compliance and a11y

2. Backend Development Squad

• engineering: REST/GraphQL endpoint development
• engineering: API design, database schemas, system architecture

3. Database Squad

• engineering: Query optimization, migrations, schema design

4. DevOps Squad

• engineering/devops-engineer: CI/CD, deployment, infrastructure
• site-reliability-engineer: SRE practices, monitoring, incident response

5. Testing Squad

• test-runner: Test execution
• code-reviewer: Code quality review

6. Security Squad

• security-auditor: Security scanning and audits

7. Performance Squad

• web-performance-auditor: Lighthouse audits, performance optimization

8. Documentation Squad

• technical-writer: Documentation generation

9. Business Squad

• business-analyst: Business analysis and requirements
• sales-proposal-writer: Sales proposal creation

10. Data Squad

• data-analyst: Data analysis
• ml-engineer: Machine learning engineering

11-27. Additional Squads

(Add more as discovered during scanning)

---

Generating "Installed Puerto Plugins" Section

Format Template

## Installed Puerto Plugins

### [plugin-name]
- [agent-name]: [Brief description of what it does]
- [agent-name]: [Brief description]
- [agent-name]: [Brief description]

### [plugin-name]
- [agent-name]: [Brief description]

Example Generation

Input (discovered plugins):

• engineering (3 agents)
• engineering (3 agents)
• engineering (3 agents)

Output (CLAUDE.md section):

## Installed Puerto Plugins

### engineering
- frontend-engineer: Create React/Vue/Svelte components with TypeScript
- state-architect: Implement state management (Redux, Zustand, Context)
- style-implementer: Responsive design and styling with CSS/Tailwind

### engineering
- backend-engineer: Create REST/GraphQL endpoints with validation
- auth-implementer: Implement JWT, OAuth 2.0, API key authentication
- api-tester: Create comprehensive API integration tests

### engineering
- query-optimizer: Analyze and optimize slow database queries
- migration-manager: Create zero-downtime database migrations
- schema-designer: Design normalized database schemas and ER diagrams

---

Generating Routing Rules from Plugin Discovery

Process

1. Extract trigger conditions from agent descriptions
2. Map to WHEN/AUTOMATICALLY pattern
3. Group by category (Frontend, Backend, Database, etc.)
4. Add variations for common phrasings

Example: Frontend-Developer Plugin

Discovered Agents:

1. frontend-engineer: "PROACTIVELY use when creating React/Vue/Svelte components"
2. state-architect: "PROACTIVELY use when implementing state management"
3. style-implementer: "PROACTIVELY use for responsive design and styling"

Generated Routing Rules:

## Automatic Task Routing

### Frontend Development

WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer

WHEN user says "implement state management" OR "add [Redux/Zustand/Context]"
→ AUTOMATICALLY invoke: engineering:state-architect

WHEN user says "style [component]" OR "make [component] responsive"
→ AUTOMATICALLY invoke: engineering:style-implementer

Example: API-Developer Plugin

Discovered Agents:

1. backend-engineer: "PROACTIVELY use when implementing REST or GraphQL endpoints"
2. auth-implementer: "PROACTIVELY use when implementing API authentication"
3. api-tester: "PROACTIVELY use when creating API integration tests"

Generated Routing Rules:

### Backend Development

WHEN user says "create [endpoint name] endpoint" OR "add API route for [resource]"
→ AUTOMATICALLY invoke: engineering/backend-engineer

WHEN user says "implement authentication" OR "add login/signup"
→ AUTOMATICALLY invoke: engineering/backend-engineer

WHEN user says "write tests for [API]" OR "add API tests"
→ AUTOMATICALLY invoke: engineering:api-tester

---

Common Plugin Patterns

Pattern 1: Multi-Agent Specialist Plugins

Plugins with 3-5 agents covering different aspects of a domain:

Examples:

• engineering: frontend-engineer, state-architect, style-implementer, accessibility-validator
• engineering: backend-engineer, auth-implementer, api-tester, openapi-generator
• engineering/devops-engineer: cicd-builder, deployment-orchestrator, infrastructure-manager, monitoring-setup

Integration Strategy: Create subsections for each aspect:

### [Plugin] Tasks

#### Component Creation
WHEN... → AUTOMATICALLY invoke: [plugin]:[agent1]

#### State Management
WHEN... → AUTOMATICALLY invoke: [plugin]:[agent2]

#### Styling
WHEN... → AUTOMATICALLY invoke: [plugin]:[agent3]

Pattern 2: Single-Purpose Auditor Plugins

Plugins with 1-2 agents focused on specific analysis:

Examples:

• accessibility-specialist: accessibility-auditor, remediation-consultant
• security-auditor: security-scanner
• web-performance-auditor: lighthouse-auditor, performance-analyzer

Integration Strategy: Simple routing rules:

### Quality Assurance

WHEN user says "audit accessibility"
→ AUTOMATICALLY invoke: accessibility-specialist:accessibility-auditor

WHEN user says "check security"
→ AUTOMATICALLY invoke: security-auditor:security-scanner

Pattern 3: Workflow Plugins

Plugins with agents representing workflow stages:

Examples:

• engineering: api-designer (design) → engineering (schema) → system-architect (infrastructure)

Integration Strategy: Sequential routing:

### Architecture & Design

WHEN designing new feature
→ First invoke: engineering:system-architect (architecture)
→ Then invoke: engineering:engineering (schema)
→ Then invoke: engineering:api-designer (API spec)

---

Plugin Discovery Bash Script

Complete script for discovering and analyzing installed plugins:

#!/bin/bash

# PLUGIN DISCOVERY SCRIPT
# Scans ~/.claude/plugins/ and .claude/plugins/ for installed Puerto plugins

echo "=== Discovering Installed Puerto Plugins ==="
echo ""

# Array to store discovered plugins
declare -a discovered_plugins

# Scan global plugins
if [ -d ~/.claude/plugins ]; then
    echo "Scanning global plugins: ~/.claude/plugins/"
    for plugin_dir in ~/.claude/plugins/*; do
        if [ -d "$plugin_dir" ]; then
            plugin_json="$plugin_dir/.claude-plugin/plugin.json"
            if [ -f "$plugin_json" ]; then
                plugin_name=$(jq -r '.name' "$plugin_json")
                plugin_description=$(jq -r '.description' "$plugin_json")
                agent_count=$(jq '.agents | length' "$plugin_json")

                echo "  ✓ Found: $plugin_name ($agent_count agents)"
                discovered_plugins+=("$plugin_name|$plugin_dir|$agent_count")
            fi
        fi
    done
fi

# Scan project-local plugins
if [ -d .claude/plugins ]; then
    echo "Scanning project plugins: .claude/plugins/"
    for plugin_dir in .claude/plugins/*; do
        if [ -d "$plugin_dir" ]; then
            plugin_json="$plugin_dir/.claude-plugin/plugin.json"
            if [ -f "$plugin_json" ]; then
                plugin_name=$(jq -r '.name' "$plugin_json")
                plugin_description=$(jq -r '.description' "$plugin_json")
                agent_count=$(jq '.agents | length' "$plugin_json")

                echo "  ✓ Found: $plugin_name ($agent_count agents)"
                discovered_plugins+=("$plugin_name|$plugin_dir|$agent_count")
            fi
        fi
    done
fi

echo ""
echo "=== Total Plugins Found: ${#discovered_plugins[@]} ==="
echo ""

# Extract agent details for each plugin
for plugin_info in "${discovered_plugins[@]}"; do
    IFS='|' read -r plugin_name plugin_dir agent_count <<< "$plugin_info"

    echo "## $plugin_name ($agent_count agents)"

    plugin_json="$plugin_dir/.claude-plugin/plugin.json"
    agent_files=$(jq -r '.agents[]' "$plugin_json")

    for agent_file in $agent_files; do
        full_path="$plugin_dir/$agent_file"

        if [ -f "$full_path" ]; then
            # Extract agent name and description from frontmatter
            agent_name=$(grep '^name:' "$full_path" | head -1 | sed 's/name: //')
            agent_description=$(grep '^description:' "$full_path" | head -1 | sed 's/description: //')

            echo "  - $agent_name: $agent_description"
        fi
    done

    echo ""
done

---

Integration Workflow

Step-by-Step Process for marketplace-integrator Agent

1. Run Discovery Script

   • Execute bash script to scan plugin directories
   • Collect plugin names, descriptions, and agent details

2. Read Existing CLAUDE.md (if it exists)

   • Check if "Installed Puerto Plugins" section exists
   • Identify plugins already documented

3. Generate New Content

   • Create "Installed Puerto Plugins" section with discovered plugins
   • Generate routing rules based on agent descriptions
   • Group rules by logical categories

4. Merge with Existing Content

   • Preserve existing Project Type, Tech Stack, Patterns
   • Replace/update "Installed Puerto Plugins" section
   • Replace/update "Automatic Task Routing" section
   • Keep Domain Knowledge intact

5. Output Enhanced CLAUDE.md

   • Return complete updated file
   • Highlight what was added/changed

---

Example: Complete Integration Output

Before (user's existing CLAUDE.md):

# My React App

## Project Type
React SPA with Express backend

## Tech Stack
- Frontend: React 18, Tailwind
- Backend: Express, PostgreSQL

After (marketplace-integrator enhancement):

# My React App

## Project Type
React SPA with Express backend

## Tech Stack
- Frontend: React 18, Tailwind CSS
- Backend: Express, PostgreSQL

## Installed Puerto Plugins

### engineering
- frontend-engineer: Create React components with TypeScript
- state-architect: Implement state management
- style-implementer: Responsive design with Tailwind

### engineering
- backend-engineer: Create REST endpoints
- auth-implementer: Implement authentication
- api-tester: Create API tests

### engineering
- engineering: Design database schemas

## Automatic Task Routing

### Frontend Development

WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer

WHEN user says "implement state management"
→ AUTOMATICALLY invoke: engineering:state-architect

WHEN user says "style [component]"
→ AUTOMATICALLY invoke: engineering:style-implementer

### Backend Development

WHEN user says "create [endpoint] endpoint"
→ AUTOMATICALLY invoke: engineering/backend-engineer

WHEN user says "implement authentication"
→ AUTOMATICALLY invoke: engineering/backend-engineer

WHEN user says "write API tests"
→ AUTOMATICALLY invoke: engineering:api-tester

### Database Work

WHEN user says "design database schema"
→ AUTOMATICALLY invoke: engineering:engineering

---

Handling Edge Cases

Case 1: No Plugins Installed

Detection: Discovery script returns empty array

Action: Inform user and suggest installing plugins:

## Installed Puerto Plugins

No Puerto plugins detected. Install plugins with:
`/plugin install [plugin-name]`

Popular plugins for this project type:
- engineering (for React development)
- engineering (for Express APIs)
- engineering (for PostgreSQL schemas)

Case 2: Plugin Without Agents

Detection: plugin.json has empty agents array

Action: Skip plugin or note it in comments:

<!-- Plugin 'example-plugin' found but has no agents -->

Case 3: Malformed plugin.json

Detection: jq fails to parse

Action: Log error and skip plugin:

if ! jq empty "$plugin_json" 2>/dev/null; then
    echo "Warning: Malformed plugin.json in $plugin_dir (skipping)"
    continue
fi

Case 4: Agent File Missing Frontmatter

Detection: grep returns empty for name/description

Action: Use fallback values:

if [ -z "$agent_name" ]; then
    # Extract from filename: "./agents/frontend-engineer.md" → "frontend-engineer"
    agent_name=$(basename "$agent_file" .md)
fi

if [ -z "$agent_description" ]; then
    agent_description="No description available"
fi

---

Best Practices for Plugin Integration

1. Always scan both global and project-local directories

   • Users might have plugins in either location
   • Project-local plugins take precedence

2. Preserve existing CLAUDE.md content

   • Don't overwrite Project Patterns or Domain Knowledge
   • Only update "Installed Puerto Plugins" and "Automatic Task Routing"

3. Generate routing rules from agent descriptions

   • Parse "PROACTIVELY use when..." patterns
   • Add common trigger variations (create/add/implement)

4. Group routing rules logically

   • Frontend, Backend, Database, DevOps, Testing, etc.
   • Match categories to installed plugin types

5. Include agent descriptions in plugin listings

   • Helps users understand what each agent does
   • Creates self-documenting CLAUDE.md

6. Handle errors gracefully

   • Skip malformed plugins
   • Provide fallback descriptions
   • Log warnings for users

---

Summary: Plugin Discovery Checklist

When running marketplace-integrator agent:

• Scan ~/.claude/plugins/ for global plugins
• Scan .claude/plugins/ for project-local plugins
• Read plugin.json for each discovered plugin
• Extract plugin name, description, agent list
• Read agent frontmatter for each agent
• Extract agent names and descriptions
• Generate "Installed Puerto Plugins" section
• Generate routing rules from agent descriptions
• Group routing rules by category
• Preserve existing CLAUDE.md sections
• Output enhanced CLAUDE.md

---

End of Marketplace Discovery Skill

This skill should be used by the marketplace-integrator agent when scanning installed plugins and generating CLAUDE.md integration sections.