Claude Code: Terminal-First AI Agents with Your Marketplace

Difficulty: Intermediate | Prerequisites: Claude Code installed, marketplace boilerplate forked

TL;DR: Use CLAUDE.md for rules, settings.json for hooks/MCP, and reference marketplace skill files directly. Claude Code's filesystem access makes it the most flexible platform for marketplace integration.

What is Claude Code?

Claude Code is Anthropic's CLI and IDE tool for AI-assisted software engineering. It runs in your terminal (or VS Code / JetBrains) and has direct access to your filesystem, shell, and development tools. This makes it uniquely powerful for agentic workflows: it can read code, edit files, run tests, and interact with your entire development environment.

Key differentiators for marketplace integration:

• CLAUDE.md files: project-level instructions that Claude follows automatically

• Hooks: shell commands that execute on lifecycle events (pre/post tool calls)

• MCP servers: Model Context Protocol for connecting to external tools

• Slash commands / Skills: reusable prompts invoked with /command

• Settings.json: project and user-level configuration

Scenario 1: Adding Marketplace Rules to a Brownfield Project

Situation: You have a 3 year old Python microservice. You want Claude Code to follow your org's standards when working in it.

Step 1: Install marketplace plugins

cd my-legacy-service
marketplace install pr-review-agent
marketplace install test-writer

This creates:

my-legacy-service/
+-- .ai-marketplace/
|   +-- pr-review-agent/
|   |   +-- skills/
|   |   +-- agents/
|   |   +-- rules/
|   +-- test-writer/
|   +-- rules/          # Org-wide rules synced here
|       +-- security.md
|       +-- coding-standards.md
|       +-- compliance.md

Step 2: Create CLAUDE.md

Create .claude/CLAUDE.md in your project root:

# Project: Legacy Auth Service

## Marketplace Rules
Follow ALL rules in .ai-marketplace/rules/. These are organization-wide policies.

## Available Skills
- .ai-marketplace/pr-review-agent/skills/: code review capabilities
- .ai-marketplace/test-writer/skills/: test generation

## Project-Specific Context
- Python 3.11, FastAPI framework
- PostgreSQL database with SQLAlchemy ORM
- Tests use pytest with fixtures in tests/conftest.py
- Deploy via GitHub Actions to Azure Container Apps

## Important
- This is a brownfield project. Preserve existing patterns
- Database migrations use Alembic. Never modify the DB schema directly
- Auth tokens are JWT, managed via Azure AD

Step 3: Use it

claude  # Start Claude Code in the project

> Review the changes I'm about to commit
# Claude reads the marketplace rules + your CLAUDE.md and reviews accordingly

> Write tests for the new /api/users endpoint
# Claude uses the test-writer plugin skills with your project's pytest patterns

Scenario 2: Setting Up Hooks for Automated Governance

Situation: You want every commit to be automatically checked for secrets, and every PR description to be auto-generated.

Configure hooks in .claude/settings.json:

{
  "hooks": {
    "PreToolCall": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .ai-marketplace/hooks/pre-commit-check.sh 2>/dev/null || true"
          }
        ]
      }
    ],
    "PostToolCall": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'grep -rE \"(password|secret|api_key)\\s*=\\s*[\\x27\\\"]\" \"$CLAUDE_FILE_PATH\" && echo WARNING: Potential secret detected || true'"
          }
        ]
      }
    ]
  }
}

Scenario 3: MCP Servers for Organizational Context

Situation: Your agents need to query Azure DevOps work items, search internal docs, and query Kusto telemetry.

Add MCP servers to .claude/settings.json:

{
  "mcpServers": {
    "ado": {
      "command": "agency",
      "args": ["mcp", "ado"]
    },
    "docs": {
      "command": "agency",
      "args": ["mcp", "docs"]
    },
    "kusto": {
      "command": "agency",
      "args": ["mcp", "kusto"]
    }
  }
}

Now your agents can:

> What work items are assigned to me this sprint?
> Search our internal docs for the token refresh architecture
> Query the last 24h of errors from the auth service

Scenario 4: Custom Slash Commands from Marketplace Skills

Turn marketplace skills into one-command invocations by referencing them in your CLAUDE.md or creating skill files:

# In CLAUDE.md

## Slash Commands
- When I say "/review", run the PR Review agent from .ai-marketplace/pr-review-agent/agents/review.md
- When I say "/test", run the Test Writer skill from .ai-marketplace/test-writer/skills/generate-tests.md
- When I say "/explain", run the Summarize Code skill from .ai-marketplace/example-plugin/skills/summarize-code.md

Usage:

claude
> /review    # Triggers full PR review workflow
> /test      # Generates tests for recent changes
> /explain src/auth/handler.py   # Summarizes the file

Scenario 5: Greenfield Project with Full Marketplace

Situation: Starting a brand-new TypeScript microservice with all org standards from day one.

# Create project
mkdir my-new-service && cd my-new-service
git init

# Install marketplace
marketplace install starter-kit
marketplace install pr-review-agent
marketplace install test-writer

# Claude Code setup is automatic; CLAUDE.md was created by on-install hook

# Start building
claude
> Scaffold a TypeScript Express API with health check, 
> error handling, and structured logging. Follow our org standards.

Claude reads the marketplace rules and builds the project with your org's patterns from the start.

Key Claude Code Concepts for the Marketplace

Tips for Marketplace Authors Targeting Claude Code

1. Write skills as markdown. Claude Code natively understands markdown instructions

2. Use CLAUDE.md references. Point to skill files rather than inlining everything

3. Leverage hooks for enforcement. Rules in markdown are suggestions; hooks are enforcement

4. Declare MCP dependencies. If your plugin needs a specific MCP server, document it in plugin.yaml

5. Test with claude --print. Preview how Claude interprets your instructions without executing

Quick Setup Checklist

Copy-paste this to get marketplace running with Claude Code in under 5 minutes:

# 1. Initialize marketplace in your project
cd /path/to/your/project
marketplace init

# 2. Install the plugins you need
marketplace install pr-review-agent
marketplace install test-writer
marketplace install incident-responder  # if on-call

# 3. Generate Claude Code config (auto-done by init, but just in case)
marketplace generate-claude-md

# 4. Add MCP servers to .claude/settings.json (copy from marketplace)
# Edit .claude/settings.json and add your org's MCP servers

# 5. Verify everything works
marketplace doctor

# 6. Commit and share with your team
git add .ai-marketplace/ .claude/
git commit -m "Add AI Agent Marketplace integration"

• .claude/CLAUDE.md exists and references marketplace rules

• .claude/settings.json has hooks configured (optional but recommended)

• MCP servers configured for your org's tools

• .ai-marketplace/rules/ contains org-wide rules

• At least one plugin installed and working