Claude Bridge Skill Guide

Overview

Spawns a second Claude CLI instance (claude -p) targeting a different project directory. The current session (Agent A) sends a prompt, receives structured JSON output from Agent B, and integrates the findings. Supports multi-turn cross-project conversations via session resumption.

Project Registry

Config file: ~/.claude/skills/claude-bridge/projects.json

Read this file at the start of every bridge invocation. It contains:

• defaults — fallback model and mode
• projects — alias-to-path mapping with optional per-project overrides

{
  "defaults": {
    "model": "sonnet",
    "mode": "read-only"
  },
  "projects": {
    "backend": {
      "path": "/absolute/path/to/backend",
      "description": "NestJS backend API",
      "model": "sonnet"
    }
  }
}

To add a new project, edit this JSON file. Each key is an alias usable in natural language.

How to Invoke

The skill supports 3 ways to specify the target project, from most convenient to most explicit:

1. By Alias (recommended for repeated use)

User says something like:

• "ask backend about the users endpoint"
• "bridge to frontend — what component renders the dashboard?"
• "check backend for breaking changes"

Flow:

1. Read projects.json
2. Match the alias (e.g., "backend") to its registered path
3. Use the project's configured model (or defaults.model)
4. Execute immediately — no questions needed

2. By Explicit Path

User says something like:

• "ask the project at /Users/enesgur/work/payment-service about..."
• "bridge to /tmp/some-repo — analyze the auth flow"

Flow:

1. Extract the path from the user's message
2. Use defaults.model from config
3. Execute immediately — no questions needed

3. No Path Given

User says something like:

• "ask the other project about the API"
• "I need info from the backend"

Flow:

1. Read projects.json and list registered projects via AskUserQuestion
2. Let the user pick a registered project OR type a custom path
3. Then execute

Model Selection

The model is resolved in this priority order:

1. User explicitly says it → use that model
   • "ask backend with opus about the architecture"
   • "bridge to frontend using haiku — quick question"
2. Project-level config → projects.<alias>.model from projects.json
3. Global default → defaults.model from projects.json
4. Hardcoded fallback → sonnet

If the user says "use opus" or "with haiku", extract that and override everything else.

Running a Query

Step 1: Build the Prompt

Construct a clear, self-contained prompt for Agent B. Always include:

• What information is needed
• Relevant context from the current project (error messages, types, expected contracts)
• The desired response format

Prompt template:

You are analyzing this project to help a developer working in a separate [frontend/backend/service] project.

Context from the caller project:
---
[Insert relevant context: error message, type definition, API call code, etc.]
---

Task: [Clear, specific question or request]

Respond concisely. Focus only on what was asked.

Step 2: Execute

# Read-only analysis (default)
echo "<prompt>" | claude -p \
  --model <MODEL> \
  --output-format json \
  --permission-mode plan \
  --add-dir <TARGET_PROJECT_PATH> \
  2>/dev/null

# With edit capability (requires user confirmation first)
echo "<prompt>" | claude -p \
  --model <MODEL> \
  --output-format json \
  --permission-mode acceptEdits \
  --add-dir <TARGET_PROJECT_PATH> \
  2>/dev/null

IMPORTANT:

• Always append 2>/dev/null to suppress stderr noise.
• Always use --output-format json for reliable parsing.
• Use --add-dir to grant the spawned agent access to the target project directory.
• For read-only queries, use --permission-mode plan.
• For edit tasks, use --permission-mode acceptEdits and confirm with the user first.

Step 3: Parse the Response

The JSON output contains:

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Agent B's text response",
  "session_id": "uuid-for-resumption",
  "total_cost_usd": 0.05,
  "duration_ms": 3000
}

Extract and present:

• result — the actual answer from Agent B
• session_id — save for potential follow-up
• is_error — check for failures

Step 4: Present Results

Summarize Agent B's response. Include:

• The answer/analysis from the target project
• Session ID reference for follow-up: "You can continue this conversation by saying 'bridge resume' or asking a follow-up about [project alias]."

Resuming a Session

To continue a previous cross-project conversation:

echo "<follow-up prompt>" | claude -p \
  --resume <SESSION_ID> \
  --output-format json \
  2>/dev/null

When resuming:

• Do NOT re-specify --model, --permission-mode, or --add-dir (inherited from original).
• Only pass --resume, --output-format json, and the new prompt.

User triggers resume by saying:

• "bridge resume — also check the middleware"
• "follow up with backend — what about pagination?"
• "ask backend again — show me the error handler too"

Managing Projects

Adding a project

When the user says "bridge add project" or "register project":

1. Ask for alias, path, description, and optional model override via AskUserQuestion
2. Read projects.json, add the new entry, write it back
3. Confirm to the user

Listing projects

When the user says "bridge list" or "show bridge projects":

1. Read projects.json
2. Display a table of alias, path, description, model

Removing a project

When the user says "bridge remove [alias]":

1. Read projects.json, remove the entry, write it back
2. Confirm to the user

Quick Reference

Common Scenarios

1. Frontend asks Backend about an endpoint

User says: "ask backend about the GET /api/users/:id endpoint — I'm getting a 422"

Prompt to Agent B:

You are analyzing this backend project to help a frontend developer.

Context from frontend:
---
I'm calling GET /api/users/:id but getting a 422 error.
My request code: fetch(`/api/users/${id}`, { headers: { Authorization: `Bearer ${token}` } })
---

Task: Find the route handler for GET /api/users/:id. What parameters does it expect? What validation does it apply? What does a successful response look like?

2. Debug a contract mismatch

User says: "bridge to backend — response shape doesn't match what we expect for user data"

Prompt to Agent B:

You are analyzing this backend project to help a frontend developer.

Context from frontend:
---
The frontend expects: { user: { id: string, name: string, email: string, avatar: string } }
But we receive: { data: { userId: number, fullName: string, emailAddress: string } }
---

Task: Find the serializer/response transformer for the user endpoint. Show the actual response structure and field names.

3. Check for breaking changes

User says: "ask backend with opus — did anything break for our user endpoints recently?"

4. Get TypeScript types from backend

User says: "ask backend with haiku — give me TypeScript interfaces for /api/auth/* endpoints"

Error Handling

• If claude -p exits non-zero, report the error and ask whether to retry with different settings.
• If is_error is true in the JSON,