multi-agent-ai-projects - Claude MCP Skill

# Multi-Agent AI Projects

Guidelines for working with multi-agent AI learning projects and experimental codebases.

## CRITICAL: First Actions When Starting or Resuming Work

**Read STATUS.md FIRST** (usually `.spec/STATUS.md` or project root) - Shows current phase, completed lessons, blockers, and resume instructions. This prevents working on wrong lessons or repeating completed work.

Then:
1. Check git status
2. Verify dependencies installed
3. Check lesson-specific .env files

**Auto-activate when:** Project has `.spec/` directory, `lessons/` subdirectory, `STATUS.md`, or lesson-numbered directories.

## Project Structure Recognition

### Common Patterns
- `.spec/` directory - Learning specifications and experimental code
- `lessons/` or similar learning directories
- `STATUS.md` - Progress tracking for learning journey
- Per-lesson or per-module structure
- Self-contained lesson directories

### Typical Lesson Structure
```
lesson-XXX/
├── <name>_agent/          # Agent (agent.py, tools.py, prompts.py, cli.py)
├── .env                   # API keys (gitignored)
├── PLAN.md / README.md    # Lesson docs
├── COMPLETE.md            # Learnings
└── test_*.py              # Tests
```

## Workflow Patterns

### Execution
- Use `uv run python` from lesson directory
- Check lesson README for setup

### API Keys
- Per-lesson `.env` files (never commit)
- Check `.env.example` or `.env.template`

### Dependencies
- `uv sync --group lesson-XXX` for lesson-specific deps
- Check `pyproject.toml` for dependency groups

## Progress Tracking

### STATUS.md Pattern
- **Read before starting work** (most important!)
- Update after completing lessons
- Note blockers and next steps
- Document learnings and insights
- Track which lessons are complete

### Session Management
- **Always check STATUS.md at session start** (FIRST action)
- Update STATUS.md before ending sessions
- Note any experimental findings
- Document what worked and what didn't

## Common Project Types

### Learning Spike Projects
- Focus on exploration and experimentation
- Code may not be production-quality
- Documentation of learnings is important
- Test different approaches
- Iterate quickly

### Multi-Agent Frameworks
- Agent coordination patterns
- Tool usage and integration
- Message passing between agents
- State management across agents
- Router/coordinator patterns

## Quick Reference

**Execution:**
- `uv run python` from lesson directory
- Check per-lesson dependencies

**Documentation:**
- Update STATUS.md with progress
- Document findings in COMPLETE.md
- Note blockers and next steps

---

**Note:** These projects are learning-focused - prioritize understanding and documentation over production perfection. STATUS.md is your single source of truth for project state.