MPM Agents & Skills Deployment Mechanics

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

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

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

// ~/.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

# 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

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

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.