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

---
name: multi-agent-guide
description: 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.
version: 1.0.0
allowed-tools: 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.

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

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

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

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

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

```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/agents-md.md` | AGENTS.md template |
| `templates/guardrails-md.md` | GUARDRAILS.md template |
| `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 |

---

## 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.*