# Building Your AI Agent Marketplace from Scratch

**Difficulty**: Intermediate | **Prerequisites**: Git, Bash, one AI coding tool

**TL;DR**: Fork the boilerplate. Customize 3 rule files. Build one real plugin (PR review agent shown step-by-step). Add pre-commit hooks and CI. Seed with 3-5 plugins and launch. Time to value: one afternoon.

* * *

## What You'll Build

By the end of this guide, your marketplace will have:

```plaintext
your-org/ai-agent-marketplace/
|
+-- plugins/
|   +-- example-plugin/         <-- Template (already included)
|   +-- pr-review-agent/        <-- You'll build this step by step
|
+-- rules/
|   +-- security.md             <-- Customized for your org
|   +-- coding-standards.md     <-- Customized for your stack
|   +-- compliance.md           <-- Customized for your regulations
|
+-- hooks/
|   +-- pre-commit/scan-secrets.sh   <-- Automated secret scanning
|   +-- on-install/setup-configs.sh  <-- Auto-generates platform configs
|
+-- .github/
|   +-- workflows/validate.yml  <-- CI pipeline for plugin validation
|   +-- CODEOWNERS              <-- Review ownership
|
+-- scripts/marketplace.sh      <-- CLI with 16 commands
```

* * *

## Prerequisites

*   A Git hosting platform (GitHub, GitHub Enterprise, Azure DevOps, GitLab)
    
*   Engineers who are already using at least one AI coding assistant
    
*   Bash (macOS/Linux), Git Bash/WSL (Windows), or PowerShell (Windows native, with a `.ps1` port included)
    
*   30 minutes to set up the foundation
    

> **Cross-platform note**: The marketplace CLI ships as both `marketplace.sh` (Bash for macOS, Linux, and Windows via Git Bash/WSL) and `marketplace.ps1` (PowerShell for native Windows). All commands work identically on both. The blog examples use Bash syntax, but PowerShell equivalents are in the onboarding guide.

## Step 1: Fork the Boilerplate

The companion repository to this blog series provides a complete, ready-to-customize marketplace boilerplate. Start by forking it into your organization's Git host.

```bash
# Clone the boilerplate
git clone https://github.com/pushp1997/ai-agent-marketplace ai-agent-marketplace
cd ai-agent-marketplace
```

## Step 2: Understand the Structure

Here's what you get out of the box:

```plaintext
ai-agent-marketplace/
|
+-- plugins/                     # Where plugins live
|   +-- example-plugin/          # A fully documented template plugin
|       +-- plugin.yaml          # Manifest: name, version, platforms, data access
|       +-- skills/              # Reusable single-purpose capabilities
|       +-- agents/              # Multi-step orchestrated workflows
|       +-- instructions/        # System prompts and context
|       +-- rules/               # Plugin-specific behavioral rules
|       +-- hooks/               # Lifecycle scripts
|       +-- README.md            # Plugin documentation
|
+-- rules/                       # Org-wide rules (apply everywhere)
|   +-- security.md              # Security policies
|   +-- coding-standards.md      # Coding conventions
|   +-- compliance.md            # Regulatory rules
|
+-- hooks/                       # Shared lifecycle hooks
+-- mcp-servers/                 # MCP server configurations
+-- scripts/                     # CLI tooling (browse, install, create)
+-- docs/                        # Onboarding, authoring, governance guides
+-- .claude/                     # Claude Code configuration
+-- .github/                     # GitHub Copilot + PR templates
```

Let's walk through each component and how to customize it.

## Step 3: Customize Org-Wide Rules

The `rules/` directory is the single most important part of your marketplace. These rules apply to **every plugin and every agent**. They're your organization's AI constitution.

### Security Rules (`rules/security.md`)

Open `rules/security.md` and customize it for your organization:

```markdown
# Org-Wide Rule: Security

## Mandatory Rules
1. No hardcoded secrets (enforced via pre-commit hooks)
2. No credential logging, even in debug mode
3. Input validation at all system boundaries
4. Least privilege: declare all data access in plugin.yaml
5. Secure defaults: HTTPS, encrypted connections, restrictive CORS
```

**Tip**: Start with the rules that matter most. You can always add more later. Three well-enforced rules beat twenty ignored ones.

### Coding Standards (`rules/coding-standards.md`)

Tailor this to your stack:

```markdown
# Org-Wide Rule: Coding Standards

## Our Stack
- Backend: Python (FastAPI). Use snake_case, type hints required
- Frontend: TypeScript (React). Use camelCase, strict mode enabled
- Infrastructure: Terraform. Modules in modules/, environments in envs/

## Non-Negotiables
- Functions under 50 lines
- No commented-out code
- Error cases handled explicitly
- Tests for all new functionality
```

### Compliance Rules (`rules/compliance.md`)

This varies dramatically by industry. A healthcare company needs HIPAA rules. A financial services firm needs SOX rules. A government contractor needs FedRAMP rules. Customize accordingly.

## Step 4: Build Your First Real Plugin

The `example-plugin` is a template. Let's build something your team will actually use. Here's a step-by-step example of a **PR Review Agent**.

### 4a: Scaffold the Plugin

```bash
./scripts/marketplace.sh create-plugin pr-review-agent
```

### 4b: Define the Manifest

Edit `plugins/pr-review-agent/plugin.yaml`:

```yaml
name: pr-review-agent
version: 1.0.0
description: >
  Automated PR review agent that checks code changes against
  org standards, security policies, and best practices.

author:
  name: Platform Team
  email: platform-team@your-org.com
  team: Platform Engineering

platforms:
  - claude-code
  - github-copilot
  - cursor

tags:
  - code-review
  - quality
  - security

data_access:
  - type: filesystem
    scope: project-local
    description: Reads changed files in the current project
  - type: api
    scope: internal
    description: Reads PR metadata from Git hosting platform
```

### 4c: Write the Skills

Create `plugins/pr-review-agent/skills/check-security.md`:

```markdown
# Skill: Security Check

Review the provided code changes for security issues.

## Check For
1. Hardcoded secrets (API keys, passwords, tokens)
2. SQL injection vectors (string concatenation in queries)
3. Command injection (unsanitized input in shell commands)
4. XSS opportunities (unescaped user input in HTML)
5. Insecure dependencies (known CVEs)
6. Disabled security features (SSL verification off, CSRF disabled)

## Output Format
For each finding:
- SEVERITY: CRITICAL / WARNING / INFO
- FILE: path and line number
- ISSUE: what's wrong
- FIX: how to fix it
```

Create `plugins/pr-review-agent/skills/check-standards.md`:

```markdown
# Skill: Standards Check

Review code changes against org coding standards.

## Check For
1. Naming conventions (per language rules in coding-standards.md)
2. Function length (flag functions over 50 lines)
3. Error handling (no empty catch blocks, no swallowed errors)
4. Test coverage (new code should have tests)
5. Documentation (public APIs need doc comments)
6. Dead code (no commented-out code, unused imports)

## Output
Categorize findings as:
- MUST FIX: Violations of non-negotiable standards
- SHOULD FIX: Best practice violations
- CONSIDER: Style suggestions
```

### 4d: Write the Agent

Create `plugins/pr-review-agent/agents/review.md`:

```markdown
# Agent: PR Review

You are a PR review agent. When asked to review a PR or code changes:

## Workflow
1. Read the PR description to understand intent
2. List all changed files
3. For each file:
   a. Run the Security Check skill
   b. Run the Standards Check skill
   c. Check for logical correctness
4. Produce a summary

## Summary Format

### Overview
[1-2 sentence summary of the PR]

### Verdict: APPROVE / REQUEST CHANGES / NEEDS DISCUSSION

### Findings
[List all findings from skills, grouped by severity]

### What's Good
[Highlight positive aspects: good tests, clean abstractions, etc.]

## Rules
- Be constructive, not adversarial
- Suggest fixes, don't just criticize
- Acknowledge good work
- If unsure about business logic, ask rather than assume
```

### 4e: Test and Document

```bash
cd plugins/pr-review-agent
../../scripts/marketplace.sh test
```

Update `plugins/pr-review-agent/README.md` with real usage examples.

## Step 5: Add Lifecycle Hooks

Hooks automate quality gates. Create shared hooks that run for all plugins:

### Pre-Commit Hook

Create `hooks/pre-commit/no-secrets.sh`:

```bash
#!/usr/bin/env bash
# Prevent committing secrets to the marketplace

set -euo pipefail

echo "Checking for secrets..."

PATTERNS='(AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9]{48}|ghp_[a-zA-Z0-9]{36}|xoxb-)'
if git diff --cached --diff-filter=ACMR | grep -qE "$PATTERNS"; then
  echo "ERROR: Potential secret detected in staged changes."
  echo "Use environment variables or a secret manager instead."
  exit 1
fi

echo "No secrets detected."
```

### On-Install Hook

Create `hooks/on-install/setup-config.sh`:

```bash
#!/usr/bin/env bash
# Runs after a plugin is installed into a project

PLUGIN_NAME="$1"
TARGET_DIR="$2"

echo "Setting up $PLUGIN_NAME..."

# Create Claude Code config if it doesn't exist
if [[ ! -f ".claude/CLAUDE.md" ]]; then
  mkdir -p .claude
  echo "# Project Instructions" > .claude/CLAUDE.md
  echo "" >> .claude/CLAUDE.md
  echo "Follow all rules in .ai-marketplace/rules/" >> .claude/CLAUDE.md
fi

echo "Plugin $PLUGIN_NAME configured."
```

## Step 6: Set Up Governance

### CODEOWNERS

Create `.github/CODEOWNERS`:

```plaintext
# Org-wide rules require governance team review
/rules/                  @your-org/governance-team

# CLI changes require platform team review
/scripts/                @your-org/platform-team

# Anyone can contribute plugins, but need one approval
/plugins/                @your-org/marketplace-reviewers
```

### CI Validation

Add a CI pipeline that runs on every PR:

```yaml
# .github/workflows/validate.yml
name: Validate Marketplace
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate changed plugins
        run: |
          for dir in plugins/*/; do
            if git diff --name-only origin/main | grep -q "^$dir"; then
              echo "Validating $(basename $dir)..."
              cd "$dir"
              ../../scripts/marketplace.sh test
              cd ../..
            fi
          done

      - name: Check for secrets
        run: |
          if grep -rE '(AKIA|sk-|ghp_|xoxb-)' plugins/; then
            echo "ERROR: Potential secrets detected"
            exit 1
          fi
```

## Step 7: Seed and Launch

Don't launch an empty marketplace. Seed it with **3-5 high-value plugins** that solve real problems your teams face today:

1.  **Code Review Agent**: the one we just built
    
2.  **Test Writer**: generates tests following your org's testing patterns
    
3.  **Incident Responder**: helps on-call engineers with TSG lookups and triage
    
4.  **Onboarding Assistant**: helps new hires navigate the codebase
    
5.  **Documentation Generator**: generates docs from code with org templates
    

## How to Add New Capabilities: A Reference

| What you want to add | Where it goes | Example |
| --- | --- | --- |
| A reusable single-purpose capability | `plugins/<name>/skills/` | Explain an error, summarize code |
| A multi-step workflow | `plugins/<name>/agents/` | PR review, bug fix workflow |
| System context for AI | `plugins/<name>/instructions/` | Domain knowledge, project context |
| Behavioral constraints | `plugins/<name>/rules/` or `rules/` | No secrets, naming conventions |
| Automated checks | `plugins/<name>/hooks/` or `hooks/` | Pre-commit validation |
| External tool access | `mcp-servers/` | ADO integration, Kusto queries |

## What's Next

In **Part 3**, we'll show how to make your marketplace work across every major AI platform (Claude Code, GitHub Copilot, Copilot Studio, Cursor, and Azure AI Foundry), with real-world scenarios for each.

* * *

* * *

**Subscribe** to get notified when the platform-specific guides drop (Claude Code, Copilot, Cursor, and more).

**What would YOUR first plugin be?** Code review? Test writer? Something unique to your domain? Drop it in the comments.

* * *

*This is Part 2 of the series.*