AI agent skill · by @bobmatnyc

Mpm Agents Skills

Agent and skill deployment mechanics for MPM system architecture

Archived 2026-10-23 · Source updated 2026-08-31. Check the original repository for the latest version.

SKILL.md instructions

# MPM Agents & Skills Deployment Mechanics

**Category:** Core Knowledge/PM Education
**Purpose:** Explain agent and skill deployment mechanics to PM
**Triggers:** When PM needs to understand system architecture

## Overview

This skill provides comprehensive understanding of how Claude MPM's agents and skills actually work under the hood. Essential for PM decision-making about delegation, configuration, and troubleshooting.

## Agent Deployment Mechanics

### Where Agents Live

**Agent Sources (Priority Order):**
1. **Project agents** - `.claude/agents/` (highest priority)
2. **User agents** - `~/.claude-mpm/agents/` (user-created)
3. **System agents** - Built-in MPM templates (cached)
4. **Git sources** - Remote repositories (configured)

**Directory Structure:**
```
.claude/
└── agents/
    ├── engineer.md        # Claude Code expects flat .md files
    ├── researcher.md
    └── qa.md

.claude-mpm/
└── cache/
    └── agents/            # Git sources cached here
        ├── engineer.md
        └── templates/
```

### Agent Discovery & Loading Process

**1. Cache Sync (Git Sources)**
- `GitSourceSyncService` downloads from configured repositories
- Cached in `.claude-mpm/cache/agents/`
- Default source: `github.com/bobmatnyc/claude-mpm-agents`

**2. Agent Deployment**
- `AgentDeploymentService.deploy_agents()` orchestrates deployment
- Copies from cache to `.claude/agents/` (Claude Code expects this location)
- Flattens nested Git structure to flat directory
- Version checking prevents unnecessary redeployment

**3. Multi-Source Resolution**
- When multiple sources have same agent, highest version wins
- User agents override system agents (by design)
- Project agents override everything (local customization)

### Agent Configuration Relationships

**`configuration.yaml` (User Preferences):**
```yaml
agents:
  auto_discover: true          # Find agents automatically
  enabled: ["engineer", "qa"]  # Specific agents to deploy
  excluded_agents: ["debug"]  # Agents to skip/remove
  precedence: ["project", "user", "system"]  # Resolution order
```

**`auto_config.yaml` (Deployment Metadata):**
```yaml
# Generated by auto-configure process
toolchain_detected: python
recommended_agents: ["engineer", "testing"]
last_scan: "2024-02-25T10:30:00Z"
deployment_version: "5.9.32"
```

**Key Distinction:**
- `configuration.yaml` = User choices and preferences
- `auto_config.yaml` = System-generated analysis and metadata

### Agent Lifecycle

**Creation:**
1. Template exists in source (Git repo or bundled)
2. `AgentTemplateBuilder` combines base_agent.md + template
3. Frontmatter added with version, source info
4. Written to `.claude/agents/` as markdown file

**Version Management:**
- Each agent has version in frontmatter
- `AgentVersionManager` compares template vs deployed versions
- Updates only when source version is newer
- Force rebuild bypasses version check

**Cleanup:**
- Excluded agents removed from `.claude/agents/`
- Orphaned agents (no longer in sources) cleaned up
- Legacy YAML format converted to Markdown

## Skill Deployment Mechanics

### Where Skills Live

**Skill Sources:**
1. **Deployed skills** - `~/.claude/skills/` (Claude Code scans here)
2. **Cached skills** - `.claude-mpm/cache/skills/system/`
3. **Bundled skills** - Built into MPM installation
4. **Git sources** - Remote skill repositories

**Structure Transformation:**
```
# Git Repository Structure (Nested):
collaboration/
  dispatching-parallel-agents/SKILL.md
  brainstorming/SKILL.md

# Deployed Structure (Flat):
~/.claude/skills/
├── collaboration-dispatching-parallel-agents/SKILL.md
├── collaboration-brainstorming/SKILL.md
```

### Skill Discovery & Deployment

**1. Git Source Sync**
- `GitSkillSourceManager` handles remote skill sources
- Skills cached with nested structure preserved
- Manifest files track skill metadata

**2. Skill Deployment**
- `GitSkillSourceManager.deploy_skills()` flattens to Claude Code structure
- Each nested path becomes hyphen-separated name
- SKILL.md files copied to `~/.claude/skills/skill-name/SKILL.md`

**3. Selective Deployment**
- Agent requirements drive which skills to deploy
- Unused skills removed during deployment (cleanup)
- `.mpm-deployed-skills.json` tracks deployment index

### Skill Configuration

**No Direct Configuration:**
- Skills don't have user configuration like agents
- Deployed based on agent requirements analysis
- Agent templates specify needed skills in metadata

**Deployment Tracking:**
```json
// ~/.claude/skills/.mpm-deployed-skills.json
{
  "deployed_skills": {
    "systematic-debugging": {
      "collection": "claude-mpm-skills",
      "deployed_at": "2024-02-25T10:30:00Z"
    }
  },
  "last_sync": "2024-02-25T10:30:00Z"
}
```

## Configuration File Relationships

### Primary Configuration Files

**1. `.claude-mpm/configuration.yaml`**
- **Purpose:** User preferences and settings
- **Contains:**
  - Agent enable/disable lists
  - Logging preferences
  - Hook settings
  - Orchestration mode
  - API provider config
- **When modified:** By user via `claude-mpm configure` or manual editing
- **Scope:** Per-project or global

**2. `.claude-mpm/auto_config.yaml`**
- **Purpose:** Deployment metadata and analysis results
- **Contains:**
  - Detected toolchain information
  - Recommended agents based on analysis
  - Last scan timestamps
  - Deployment version tracking
- **When modified:** By `claude-mpm auto-configure` process
- **Scope:** Generated, not user-editable

**3. `.claude-mpm/config/agent_sources.yaml`**
- **Purpose:** Define where to find agent templates
- **Contains:**
  - Git repository URLs and settings
  - Source priority and enabled status
  - System repo disable flag
- **When modified:** By user when adding custom agent sources
- **Scope:** Global configuration

### Configuration Hierarchy

**Loading Order:**
1. Built-in defaults
2. Global config (`~/.claude-mpm/configuration.yaml`)
3. Project config (`./claude-mpm/configuration.yaml`)
4. Environment variables
5. Command-line arguments (highest priority)

**Precedence Rules:**
- Project configs override global configs
- Explicit user settings override auto-detected settings
- Command-line flags override everything

## Startup Process Deep Dive

### 1. Configuration Loading
```python
# ConfigService loads in this order:
def load_configuration():
    config = DefaultConfig()
    config.merge(load_global_config())      # ~/.claude-mpm/
    config.merge(load_project_config())     # ./.claude-mpm/
    config.merge(environment_variables())   # CLAUDE_MPM_*
    return config
```

### 2. Agent Deployment
```python
def startup_agent_deployment():
    # 1. Sync git sources to cache
    git_sync_service.sync_agents()

    # 2. Deploy enabled agents to .claude/agents/
    deployment_service.deploy_agents(
        deployment_mode="update",  # Skip unchanged
        config=loaded_config
    )

    # 3. Remove excluded agents
    reconciler.remove_excluded_agents()
```

### 3. Skill Deployment
```python
def startup_skill_deployment():
    # 1. Analyze deployed agents for skill requirements
    required_skills = agent_analyzer.get_required_skills()

    # 2. Deploy only required skills (with cleanup)
    skill_manager.deploy_skills(
        skill_filter=required_skills,  # Selective deployment
        force=False
    )
```

### 4. Service Initialization
- MCP servers started based on configuration
- Hook delegation system initialized
- Network services (if enabled) started
- Logging and monitoring setup

## Commands vs Skills: When to Use What

### CLI Commands
**Use for:**
- Configuration management (`claude-mpm configure`)
- System operations (`claude-mpm init`, `claude-mpm status`)
- Deployment management (`claude-mpm agents deploy`)
- Troubleshooting (`claude-mpm doctor`)

**Characteristics:**
- Direct system access
- Stateful operations
- Administrative functions
- Can modify configuration files

### Skills (via `/skill-name`)
**Use for:**
- Workflow guidance and patterns
- Knowledge queries and education
- Complex multi-step procedures
- Context-aware assistance

**Characteristics:**
- Read-only operations (mostly)
- Stateless knowledge sharing
- User guidance and education
- Cannot modify system configuration

**Mapping Examples:**
- `claude-mpm configure` ↔ `/mpm-config` (skill explains configuration)
- `claude-mpm agents deploy` ↔ No skill equivalent (system operation)
- `claude-mpm status` ↔ `/mpm-status` (skill explains status interpretation)

## Common PM Misconceptions (Corrected)

### ❌ "Auto-configure creates agent files"
**✅ Truth:** Auto-configure only updates `auto_config.yaml` with recommendations. Actual deployment happens during `claude-mpm run` or explicit deploy commands.

### ❌ "Configuration.yaml controls agent deployment directly"
**✅ Truth:** It specifies preferences. The deployment service reads these preferences and deploys accordingly. The files are still copied from cache to `.claude/agents/`.

### ❌ "Skills are configured like agents"
**✅ Truth:** Skills have no user configuration. They're deployed based on agent requirements analysis, not user preferences.

### ❌ "All agents from Git sources are deployed"
**✅ Truth:** Only enabled agents (after filtering by excluded_agents list) are deployed. Multi-source resolution happens first.

### ❌ ".claude/ directory is just cache"
**✅ Truth:** `.claude/` is the active deployment directory that Claude Code scans. `.claude-mpm/cache/` is the actual cache.

## Decision Trees for PM

### Should I deploy this agent?
```
Is agent needed for current project? → Yes
  ├─ Is it in enabled list or auto_discover=true? → Yes
  │   ├─ Is it in excluded_agents list? → No
  │   │   └─ ✅ Deploy via configuration
  │   └─ Yes → ❌ Remove from excluded list first
  └─ No → ❌ Add to excluded_agents to clean up
```

### How to troubleshoot deployment issues?
```
Agent not appearing in .claude/agents/?
  ├─ Check cache: `.claude-mpm/cache/agents/` exists? → No
  │   └─ Run: claude-mpm agents sync
  ├─ Check config: In excluded_agents list? → Yes
  │   └─ Run: claude-mpm configure (remove exclusion)
  └─ Check logs: deployment_service.log for errors
```

### Should I use command or skill?
```
Need to change system state? → Yes
  └─ Use CLI command (claude-mpm ...)
Need guidance or information? → Yes
  └─ Use skill (/skill-name)
Need to understand how something works? → Yes
  └─ Use this skill (/mpm-agents-skills)
```

## Quick Reference

### Key Directories
- **`.claude/agents/`** - Active agent deployment (Claude Code scans)
- **`.claude/skills/`** - Active skill deployment (Claude Code scans)
- **`.claude-mpm/cache/`** - Git sources cache
- **`.claude-mpm/configuration.yaml`** - User preferences
- **`.claude-mpm/auto_config.yaml`** - System metadata

### Key Services
- **`GitSourceSyncService`** - Downloads and caches remote agents
- **`AgentDeploymentService`** - Deploys agents to .claude/agents/
- **`GitSkillSourceManager`** - Handles skill sync and deployment
- **`DeploymentReconciler`** - Ensures deployed state matches config

### Essential Commands
- **`claude-mpm agents sync`** - Update cache from Git sources
- **`claude-mpm agents deploy --force`** - Force redeploy all agents
- **`claude-mpm configure`** - Interactive configuration management
- **`claude-mpm doctor`** - Diagnose deployment issues

## Remember

- **Deployment ≠ Configuration**: Configuration expresses preferences, deployment implements them
- **Cache ≠ Active**: Cache stores templates, .claude/ directories are active deployments
- **Skills follow agents**: Skill deployment driven by agent requirements, not user config
- **Precedence matters**: Project > User > System for both agents and configuration
- **Version awareness**: System only updates when source versions are newer (unless forced)

This architecture ensures clean separation between user intent (configuration) and system state (deployment) while maintaining flexibility for different deployment scenarios.