Agent skill

multi-agent-config

Manage multi-agent AI code configurations across platforms (OpenAI Codex, Claude Code, Cursor, Gemini). Use when: (1) initializing new multi-agent projects, (2) syncing configurations (MCP servers, skills, rules, subagents) across platforms, (3) translating configurations between different agent platforms, (4) migrating from one agent platform to another, or (5) maintaining consistent agent configurations across development teams using different tools.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/marsolab/skills/tree/main/plugins/multi-agent-config/skills/multi-agent-config

SKILL.md

Multi-Agent Configuration Manager

Manage and sync AI code agent configurations across OpenAI Codex, Claude Code, Cursor, and Gemini.

Overview

This skill enables you to maintain consistent AI agent configurations across multiple platforms. It handles translation between different configuration formats (TOML ↔ JSON), directory structures, and platform-specific conventions.

Supported platforms:

  • OpenAI Codex (config.toml, AGENTS.md, skills)
  • Claude Code (config.json, .claude/, subagents, hooks)
  • Cursor (.cursorrules, partial support)
  • Gemini (placeholder for future support)

Quick Start

Initialize a New Multi-Agent Project

bash
python scripts/init_project.py /path/to/project

This creates:

  • .agent-config/ - Shared source of truth
  • .codex/ - Codex-specific structure
  • .claude/ - Claude Code-specific structure
  • .cursor/ - Cursor-specific structure
  • Platform-specific config files

Sync Existing Configuration

bash
# Sync all configurations to all platforms
python scripts/sync_config.py --to all

# Sync to specific platform
python scripts/sync_config.py --to claude-code

# Sync only MCP servers
python scripts/sync_config.py --mcp-only --to codex

Core Operations

1. Initialize Multi-Agent Project

When to use: Starting a new project that will be used with multiple AI code agents.

Process:

  1. Run the initialization script
  2. Edit shared configuration files
  3. Sync to target platforms

Example:

bash
# Initialize project
python scripts/init_project.py ./my-project

# Edit shared configuration
cd my-project
vim .agent-config/rules.md
vim .agent-config/mcp-servers.json

# Sync to all platforms
python scripts/sync_config.py --to all

2. Sync Configurations

When to use: After editing shared configs or when switching between agent platforms.

What gets synced:

  • MCP server configurations
  • Custom instructions/rules
  • Skills (Agent Skills standard)
  • Agents/subagents

Sync options:

bash
# All configurations to all platforms
python scripts/sync_config.py --to all

# Specific platform
python scripts/sync_config.py --to codex
python scripts/sync_config.py --to claude-code

# Specific config type
python scripts/sync_config.py --mcp-only
python scripts/sync_config.py --rules-only
python scripts/sync_config.py --skills-only
python scripts/sync_config.py --agents-only

3. Add MCP Servers

Process:

  1. Edit .agent-config/mcp-servers.json
  2. Add server configuration
  3. Sync to platforms

Example MCP server config:

json
{
  "servers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {},
      "enabled": true,
      "description": "Developer documentation MCP"
    }
  }
}

4. Add Skills

Process:

  1. Create skill in .agent-config/skills/
  2. Follow Agent Skills standard
  3. Sync to platforms

Example:

bash
# Create skill directory
mkdir -p .agent-config/skills/my-skill

# Create SKILL.md
cat > .agent-config/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Description of when to use this skill
---

# My Skill

Instructions for using this skill.
EOF

# Sync to platforms
python scripts/sync_config.py --skills-only

5. Translate Configurations

When to use: Migrating from one platform to another or understanding config differences.

Platform reference docs:

  • references/codex.md - Codex configuration format
  • references/claude-code.md - Claude Code configuration
  • references/cursor.md - Cursor format (partial)
  • references/translation-mappings.md - Cross-platform mappings
  • references/docker-mcp-gateway.md - Docker MCP Gateway

Manual translation example:

python
from scripts.translate_utils import ConfigTranslator, load_toml, save_json

# Load Codex config
codex_config = load_toml('~/.codex/config.toml')

# Translate MCP servers
translator = ConfigTranslator()
claude_mcp = translator.toml_mcp_to_json(codex_config)

# Save to Claude Code config
save_json(claude_mcp, '.claude/config.json')

6. Migrate to Docker MCP Gateway (Recommended)

When to use: Want centralized MCP management with better security and isolation.

Benefits:

  • ✅ Centralized configuration across all AI clients
  • ✅ Secure secrets management (no API keys in config files)
  • ✅ Container isolation for each MCP server
  • ✅ Built-in OAuth flows
  • ✅ No dependency management (npx, uvx, python)

Migration process:

bash
# 1. Migrate existing MCP servers to Docker MCP Gateway
python scripts/sync_config.py --migrate-to-docker-mcp

# 2. Follow generated instructions in DOCKER_MCP_SETUP.md
# This will show you exactly which docker commands to run

# 3. Example commands (generated by migration):
docker mcp catalog init
docker mcp server enable context7 github filesystem
docker mcp secret create context7-key "your-api-key"
docker mcp secret create github-token "ghp_token"

# 4. Configure servers
docker mcp config write 'servers:
  filesystem:
    config:
      allowed_paths: ["/home/user/projects"]
  context7:
    env:
      CONTEXT7_API_KEY: secret://context7-key'

# 5. Test the gateway
docker mcp tools ls

Result: All your AI clients now use a single gateway instead of individual MCP servers.

Before (traditional):

toml
# Codex config - managing individual servers
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { API_KEY = "exposed-in-config" }

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "exposed-in-config" }

After (Docker MCP Gateway):

toml
# Codex config - single gateway
[mcp_servers.docker-gateway]
command = "docker"
args = ["mcp", "gateway", "run"]

All MCP configuration now managed through Docker MCP CLI:

bash
docker mcp server ls              # List enabled servers
docker mcp secret ls              # List secrets (secure)
docker mcp config read            # View configuration

Workflow Examples

Team Standardization

bash
# Initialize shared project config
python scripts/init_project.py ~/team-project

# Edit shared rules
vim ~/team-project/.agent-config/rules.md

# Sync to all platforms
cd ~/team-project
python scripts/sync_config.py --to all

Platform Migration

bash
# Currently using Codex, want to try Claude Code
cd ~/my-codex-project

# Initialize Claude Code structure
python scripts/init_project.py . --platforms claude-code

# Copy Codex config to shared
cp AGENTS.md .agent-config/rules.md

# Sync to Claude Code
python scripts/sync_config.py --to claude-code

Docker MCP Gateway Migration (Recommended)

bash
# Step 1: Migrate existing MCP servers to Docker MCP Gateway
cd ~/my-project
python scripts/sync_config.py --migrate-to-docker-mcp

# This generates DOCKER_MCP_SETUP.md with specific commands for your setup
# Example output:

# Step 2: Initialize Docker MCP
docker mcp catalog init

# Step 3: Enable your MCP servers
docker mcp server enable context7 github filesystem

# Step 4: Store secrets securely
docker mcp secret create context7-key "sk-..."
docker mcp secret create github-token "ghp_..."

# Step 5: Configure servers
docker mcp config write 'servers:
  context7:
    env:
      CONTEXT7_API_KEY: secret://context7-key
  github:
    env:
      GITHUB_TOKEN: secret://github-token
  filesystem:
    config:
      allowed_paths:
        - /home/user/projects'

# Step 6: Test the gateway
docker mcp tools ls
docker mcp tools call read_file '{"path": "README.md"}'

# Step 7: Your client configs are already updated!
# All AI clients now use the Docker MCP Gateway

Benefits of Docker MCP Gateway:

  • All AI clients (Codex, Claude Code, Cursor) use the same MCP configuration
  • API keys stored securely in Docker Desktop, not in config files
  • Each MCP server runs in an isolated container
  • Easy to enable/disable servers without editing configs
  • OAuth flows handled automatically

Multi-Transport Docker MCP Gateway

bash
# Option 1: stdio (default) - one gateway per client
# Each client starts its own gateway process
# No additional setup needed

# Option 2: SSE - shared gateway for all clients
# Start gateway once
docker mcp gateway run --port 8080 --transport sse

# Update client configs to use shared gateway
cat > ~/.codex/config.toml << EOF
[mcp_servers.docker-gateway]
url = "http://localhost:8080"
EOF

cat > ~/.claude/config.json << EOF
{
  "mcpServers": {
    "docker-gateway": {
      "url": "http://localhost:8080",
      "transport": "sse"
    }
  }
}
EOF

# Option 3: streaming - high-performance shared gateway
docker mcp gateway run --port 8080 --transport streaming

Reference Documentation

For detailed platform formats and translations:

  • references/codex.md - OpenAI Codex configuration
  • references/claude-code.md - Claude Code configuration
  • references/cursor.md - Cursor configuration (partial)
  • references/gemini.md - Gemini configuration (placeholder)
  • references/docker-mcp-gateway.md - Docker MCP Gateway (recommended)
  • references/translation-mappings.md - Cross-platform mappings

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

marsolab/skills

landing-page-breakdown

Comprehensive landing page design analysis for extracting typography, color palette, spacing systems, visual elements, and conversion optimization insights. Use when a user provides a landing page URL for design analysis, wants to understand what makes a page effective, needs to extract design specifications, or wants to learn from high-converting landing pages.

0 0
Explore
marsolab/skills

copy

Professional copywriter for SaaS and startups. Expert in landing page copy, positioning, messaging, conversion optimization, and voice-of-customer research. Use when writing compelling copy for SaaS products, landing pages, marketing materials, or when you need help with product positioning and messaging strategy.

0 0
Explore
marsolab/skills

apple-dev

Comprehensive macOS and iOS development expertise covering Swift best practices, SwiftUI design patterns, Human Interface Guidelines, Apple frameworks, and performance optimization. Use when developing native Apple applications, implementing SwiftUI interfaces, working with Apple frameworks (Foundation, UIKit, AppKit, Core Data, CloudKit, etc.), optimizing app performance, following HIG principles, or writing production-quality Swift code for iOS, macOS, watchOS, or tvOS platforms.

0 0
Explore
marsolab/skills

sys-arch

Design production-grade software systems with expert knowledge of architecture patterns, distributed systems, cloud platforms, and operational excellence. Use this skill when architecting complex systems, evaluating technology choices, designing scalable infrastructure, or making critical architectural decisions requiring trade-off analysis.

0 0
Explore
marsolab/skills

front-dev

Build production-ready web applications using Bun, Astro, React, Tailwind CSS v4, and Shadcn UI. Use this skill when (1) creating new frontend projects or components, (2) building landing pages, dashboards, or web apps, (3) setting up Astro with islands architecture, (4) implementing React/Preact components with proper patterns, (5) styling with Tailwind v4 and Shadcn UI, (6) optimizing frontend performance and accessibility, (7) implementing state management, (8) setting up testing strategies, (9) configuring build tooling with Bun, (10) implementing security best practices, (11) setting up forms with validation, (12) building data tables and complex UI patterns. Covers architecture, performance, accessibility, testing, security, and developer experience.

0 0
Explore
marsolab/skills

go-dev

Write production-ready Go backends, CLIs, and APIs following modern best practices from top tier tech companies. Use this skill when creating or reviewing Go code for (1) backend services and APIs, (2) command-line tools, (3) code requiring proper error handling, concurrency, or testing patterns, (4) any Go development requiring adherence to established style guidelines. Includes comprehensive linting configuration and detailed style guide.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results