our-claude-skills/custom-skills/91-multi-agent-guide/skills/multi-agent-guide/SKILL.md

name, description, version, allowed-tools

name	description	version	allowed-tools
multi-agent-guide	Use when user asks to "set up multi-agent collaboration", "initialize multi-agent project", "create agent guardrails", "set up team AI collaboration", "configure agent ownership rules", "create agent handoff protocols", mentions "multi-agent guide", "multi-agent setup", "agent coordination", "AI agent collaboration", or wants to configure a project for multiple AI agents (Claude, Gemini, Codex) working together with proper ownership rules, task management, and CI/CD integration.	2.0.0	Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion

Multi-Agent Collaboration Guide Skill

This skill helps you set up a comprehensive multi-agent collaboration framework for complex software projects where multiple AI agents (Claude Code, Gemini, Codex, and Human) work together.

What's New in v2.0

Feature	Description
Consolidated Framework	Single MULTI_AGENT_FRAMEWORK.md (~250 lines vs ~2,400 in separate files)
Quick Setup Command	/multi-agent-setup for rapid deployment
Simplified Templates	One unified template instead of 5 separate files
Production-Tested	Based on dintel-data-agent and our-seo-agent implementations

Quick Start

For rapid setup, use:

/multi-agent-setup

This creates the essential files in under 2 minutes.

Overview

The multi-agent setup creates:

Component	Purpose
Agent Hierarchy	Defines lead agent and sub-agents with clear authority levels
Ownership Matrix	Specifies which agent owns which files/directories
Guardrails System	Prevents conflicts through locks and task claiming
Handoff Protocols	Standardizes communication between agents
CI/CD Integration	Automated ownership verification in pipelines
Pre-commit Hooks	Local verification before commits

When to Use This Skill

Activate when users:

1. Starting a complex project requiring multiple AI agents
2. Organizing existing project for multi-agent collaboration
3. Setting up guardrails to prevent agent conflicts
4. Implementing ownership rules for files and directories
5. Creating handoff protocols between AI agents
6. Configuring CI/CD for multi-agent workflows

Setup Workflow

Phase 1: Assessment

Before setup, gather the following information:

1. Project type (Python, Node.js, monorepo, etc.)
2. Agent hierarchy (which agents will participate)
3. Primary ownership domains for each agent
4. Shared file coordination needs
5. CI/CD platform (GitHub Actions, GitLab CI, etc.)

Phase 2: File Structure Creation

Create the following directory structure:

project-root/
├── .agent-state/           # Agent coordination state
│   ├── tasks.yaml          # Task registry
│   └── locks.yaml          # File lock registry
├── tools/                  # Ownership verification scripts
│   └── check-ownership.py  # Multi-agent ownership checker
├── AGENTS.md               # Shared collaboration rules
├── GUARDRAILS.md           # Ownership and enforcement rules
├── CLAUDE.md               # Lead agent (Claude) directive
├── GEMINI.md               # Sub-agent (Gemini) directive (optional)
├── CODEX.md                # Sub-agent (Codex) directive (optional)
└── .pre-commit-config.yaml # Pre-commit hooks (update existing)

Phase 3: Configuration

The setup configures:

1. Agent identity via SEO_AGENT_AUTHOR environment variable
2. Ownership matrix in check-ownership.py
3. Task and lock state in .agent-state/ YAML files
4. Commit message format enforcement: [Agent] type(scope): description
5. Pre-commit hooks for local verification
6. CI/CD workflows for PR verification (optional)

---

File Templates

AGENTS.md Template

The shared rules file should include:

# AGENTS.md - Common Ground Rules & Collaboration Protocols

## Agent Hierarchy

| Agent | Role | Authority | Context File |
|-------|------|-----------|--------------|
| **Claude Code** | Lead / Orchestrator | Architecture, core logic, final decisions | `CLAUDE.md` |
| **Gemini** | Sub-agent | Google APIs, documentation, research | `GEMINI.md` |
| **Codex** | Sub-agent | Tests, boilerplate, docstrings | `CODEX.md` |

## Handoff Protocols

### Claude → Gemini Handoff
- Google API implementation
- Documentation writing
- Research tasks

### Claude → Codex Handoff
- Unit test generation
- Boilerplate models
- Docstring generation

## Commit Convention

[Agent] type(scope): description

Types: feat, fix, docs, test, refactor, chore
Agent tags: [Claude], [Gemini], [Codex], [Human]

GUARDRAILS.md Template

The enforcement rules file should include:

# GUARDRAILS.md - Ownership & Enforcement Rules

## Ownership Matrix

### Claude Primary Ownership
- `src/*/cli.py`
- `src/*/core/`
- Architecture-related files

### Gemini Primary Ownership
- `src/*/integrations/google/`
- `docs/`
- Research documentation

### Codex Primary Ownership
- `tests/`
- `src/*/models.py`
- `src/*/utils/`

### Shared Files (Claude Approves)
- `pyproject.toml`
- `config/*.yaml`
- `.github/workflows/`

### Unrestricted Files
- `.agent-state/`
- `.gitignore`
- `README.md`

## Lock System

Lock types:
- **exclusive**: Only one agent can modify
- **shared**: Multiple agents can read, one can write
- **override**: Claude override for conflict resolution

Lock file format (.agent-state/locks.yaml):
```yaml
version: "1.0"
locks:
  - path: "src/module/"
    agent: "claude"
    lock_type: "exclusive"
    task_id: "TASK-001"
    expires_at: "2025-01-30T12:00:00Z"

Task Claiming Protocol

1. Check task status in .agent-state/tasks.yaml
2. Claim task by setting agent and status
3. Acquire necessary file locks
4. Complete work
5. Release locks and mark task complete

### check-ownership.py Template

The ownership verification script should:

1. Define `OWNERSHIP_MATRIX` with regex patterns
2. Define `SHARED_FILES` requiring Claude approval
3. Define `UNRESTRICTED_FILES` anyone can modify
4. Check file ownership before allowing modifications
5. Verify lock status in `.agent-state/locks.yaml`
6. Validate commit message format

Key functions:
- `get_file_owner(filepath)` → Returns (owner, ownership_type)
- `is_file_locked(filepath, root)` → Returns (is_locked, lock_info)
- `verify_ownership(files, agent, root)` → Returns (violations, warnings)
- `check_commit_message(msg_file)` → Returns bool

---

## Setup Commands

### Quick Setup (Recommended)

When user requests multi-agent setup, follow these steps:

1. **Ask configuration questions**:

• What is your project name and type?
• Which agents will participate? (Claude, Gemini, Codex, custom)
• What are the main directories/domains for each agent?
• Do you want CI/CD integration? (GitHub Actions, GitLab CI)

2. **Create directory structure**:
```bash
mkdir -p .agent-state
mkdir -p tools

3. Generate configuration files from templates:

   • AGENTS.md (customize based on project)
   • GUARDRAILS.md (customize ownership matrix)
   • Agent-specific .md files (CLAUDE.md, etc.)
   • .agent-state/tasks.yaml (initialize empty)
   • .agent-state/locks.yaml (initialize empty)
   • tools/check-ownership.py (customize OWNERSHIP_MATRIX)

4. Update pre-commit configuration:

   • Add check-ownership hook
   • Add commit-message hook

5. Optional: Create CI workflow:

   • GitHub Actions ownership-check.yml
   • Or equivalent for other CI systems

Environment Setup

Instruct users to set agent identity:

# Add to shell profile (.bashrc, .zshrc)
export SEO_AGENT_AUTHOR=claude  # or gemini, codex, human

# Or use direnv (.envrc)
export SEO_AGENT_AUTHOR=claude

---

Customization Guide

Adding New Agents

1. Create AGENTNAME.md at project root
2. Add to AGENTS.md hierarchy table
3. Update OWNERSHIP_MATRIX in check-ownership.py
4. Add to VALID_AGENTS set

Modifying Ownership Rules

1. Edit OWNERSHIP_MATRIX in check-ownership.py
2. Update GUARDRAILS.md documentation
3. Communicate changes to all agents

Adjusting Lock Timeouts

Default lock expiration: 4 hours

To change, modify the task/lock creation logic to use different expires_at values.

---

Integration with CI/CD

GitHub Actions

Create .github/workflows/ownership-check.yml:

name: Ownership Check

on:
  pull_request:
    branches: [main, develop]

jobs:
  check-ownership:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install pyyaml

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v44

      - name: Check ownership
        env:
          SEO_AGENT_AUTHOR: ci
        run: |
          python tools/check-ownership.py ${{ steps.changed-files.outputs.all_changed_files }}

Pre-commit Integration

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: check-ownership
        name: Check Agent Ownership
        entry: python tools/check-ownership.py
        language: python
        always_run: true
        pass_filenames: true
        additional_dependencies: [pyyaml]

      - id: check-commit-message
        name: Check Commit Message Format
        entry: python tools/check-ownership.py --check-commit-msg
        language: python
        stages: [commit-msg]
        additional_dependencies: [pyyaml]

---

Best Practices

Agent Coordination

Practice	Description
Claim before work	Always claim tasks in .agent-state/tasks.yaml
Lock during edits	Acquire locks for files you're modifying
Release promptly	Don't hold locks longer than necessary
Use handoff format	Follow standard handoff protocol for delegation
Attribution	Always include agent tag in commit messages

Conflict Resolution

1. Check locks first - Don't modify locked files
2. Escalate to Claude - Claude can override locks
3. Document conflicts - Update GUARDRAILS.md if patterns emerge
4. Communicate changes - Notify other agents of ownership changes

Code Style

Maintain consistent code style across agents:

Aspect	Standard
Formatter	Black (Python), Prettier (JS)
Line length	100 characters
Docstrings	Google-style
Type hints	Required

---

Reference Files

Supporting files in this skill:

File	Purpose
templates/multi-agent-framework.md	Consolidated framework (RECOMMENDED)
templates/agents-md.md	AGENTS.md template (legacy)
templates/guardrails-md.md	GUARDRAILS.md template (legacy)
templates/claude-md.md	CLAUDE.md template
templates/gemini-md.md	GEMINI.md template
templates/codex-md.md	CODEX.md template
templates/tasks-yaml.yaml	Tasks file template
templates/locks-yaml.yaml	Locks file template
scripts/check-ownership.py	Ownership verification script
references/ownership-matrix.md	Detailed ownership patterns
examples/minimal-setup/	Minimal 2-agent setup example
examples/full-setup/	Full 3-agent setup example

Template Selection Guide

Use Case	Template
New projects	multi-agent-framework.md (consolidated)
Existing projects with separate files	Keep existing AGENTS.md + GUARDRAILS.md
Quick setup	/multi-agent-setup command
Full customization	Individual templates (agents-md, guardrails-md, etc.)

---

Commands

Available actions when this skill is active:

Command	Description
"Set up multi-agent collaboration"	Initialize full framework
"Add new agent [name]"	Add a new agent to existing setup
"Update ownership matrix"	Modify file ownership rules
"Check agent setup"	Verify configuration is correct
"Create handoff for [agent]"	Generate handoff document
"Initialize task"	Create new task in tasks.yaml

---

Troubleshooting

Common Issues

"Ownership violation" error:

• Check SEO_AGENT_AUTHOR environment variable is set
• Verify file is in your agent's ownership domain
• Ask lead agent (Claude) for override if needed

"File locked" error:

• Check .agent-state/locks.yaml for active locks
• Wait for lock to expire or ask owner to release
• Claude can override locks if urgent

Pre-commit hook fails:

• Verify PyYAML is installed: pip install pyyaml
• Check .agent-state/ directory exists
• Ensure commit message follows format

CI workflow fails:

• Verify changed files list is correct
• Check that check-ownership.py is in tools/
• Ensure Python and dependencies are available

---

This skill is designed for complex projects requiring coordinated multi-agent collaboration with clear ownership, accountability, and conflict prevention.