# 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

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

This creates:

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

```markdown
# 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

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

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

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

Now your agents can:

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

```markdown
# 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:

```bash
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.

```bash
# 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

| Concept | Purpose | Where it lives |
| --- | --- | --- |
| CLAUDE.md | Project instructions Claude always follows | `.claude/CLAUDE.md` |
| settings.json | Hooks, MCP servers, permissions | `.claude/settings.json` |
| Hooks | Automated checks on tool calls | `settings.json` > `hooks` |
| MCP Servers | External tool integrations | `settings.json` > `mcpServers` |
| Memory | Persistent cross-session knowledge | `.claude/memory/` |

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

```bash
# 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