claude-mpm 5.0.9__py3-none-any.whl → 5.6.23__py3-none-any.whl

claude_mpm/services/skills/selective_skill_deployer.py

@@ -0,0 +1,869 @@
+"""Selective skill deployment based on agent requirements.
+
+WHY: Agents now have a skills field in their frontmatter. We should only deploy
+skills that agents actually reference, reducing deployed skills from ~78 to ~20
+for a typical project.
+
+DESIGN DECISIONS:
+- Dual-source skill discovery:
+  1. Explicit frontmatter declarations (skills: field)
+  2. SkillToAgentMapper inference (pattern-based)
+- Support both legacy flat list and new required/optional dict formats
+- Parse YAML frontmatter from agent markdown files
+- Combine explicit + inferred skills for comprehensive coverage
+- Return set of unique skill names for filtering
+- Track deployed skills in .mpm-deployed-skills.json index
+- Remove orphaned skills (deployed by mpm but no longer referenced)
+
+FORMATS SUPPORTED:
+1. Legacy: skills: [skill-a, skill-b, ...]
+2. New: skills: {required: [...], optional: [...]}
+
+SKILL DISCOVERY FLOW:
+1. Scan deployed agents (.claude/agents/*.md)
+2. Extract frontmatter skills (explicit declarations)
+3. Query SkillToAgentMapper for pattern-based skills
+4. Combine both sources into unified set
+
+DEPLOYMENT TRACKING:
+1. Track which skills were deployed by claude-mpm in index file
+2. Update index after each deployment operation
+3. Clean up orphaned skills no longer referenced by agents
+
+References:
+- Feature: Progressive skills discovery (#117)
+- Service: SkillToAgentMapper (skill_to_agent_mapper.py)
+"""
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Set, Tuple
+
+import yaml
+
+from claude_mpm.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# Deployment tracking index file
+DEPLOYED_INDEX_FILE = ".mpm-deployed-skills.json"
+
+# Core PM skills that should always be deployed
+# These are referenced in PM_INSTRUCTIONS.md with [SKILL: name] markers
+# Without these skills, PM only sees placeholders, not actual content
+PM_CORE_SKILLS = {
+    "mpm-delegation-patterns",
+    "mpm-verification-protocols",
+    "mpm-tool-usage-guide",
+    "mpm-git-file-tracking",
+    "mpm-pr-workflow",
+    "mpm-ticketing-integration",
+    "mpm-teaching-mode",
+    "mpm-bug-reporting",
+    "mpm-circuit-breaker-enforcement",
+    "mpm-session-management",
+}
+
+# Core skills that are universally useful across all projects
+# These are deployed when skill mapping returns too many skills (>60)
+# Target: ~25-30 core skills for balanced functionality
+CORE_SKILLS = {
+    # Universal debugging and verification (4 skills)
+    "universal-debugging-systematic-debugging",
+    "universal-debugging-verification-before-completion",
+    "universal-verification-pre-merge",
+    "universal-verification-screenshot",
+    # Universal testing patterns (2 skills)
+    "universal-testing-test-driven-development",
+    "universal-testing-testing-anti-patterns",
+    # Universal architecture and design (1 skill)
+    "universal-architecture-software-patterns",
+    # Universal infrastructure (3 skills)
+    "universal-infrastructure-env-manager",
+    "universal-infrastructure-docker",
+    "universal-infrastructure-github-actions",
+    # Universal collaboration (1 skill)
+    "universal-collaboration-stacked-prs",
+    # Universal emergency/operations (1 skill)
+    "toolchains-universal-emergency-release",
+    "toolchains-universal-dependency-audit",
+    # Common language toolchains (6 skills)
+    "toolchains-typescript-core",
+    "toolchains-python-core",
+    "toolchains-javascript-tooling-biome",
+    "toolchains-python-tooling-mypy",
+    "toolchains-typescript-testing-vitest",
+    "toolchains-python-frameworks-flask",
+    # Common web frameworks (4 skills)
+    "toolchains-javascript-frameworks-nextjs",
+    "toolchains-nextjs-core",
+    "toolchains-typescript-frameworks-nodejs-backend",
+    "toolchains-javascript-frameworks-react-state-machine",
+    # Common testing tools (2 skills)
+    "toolchains-javascript-testing-playwright",
+    "toolchains-typescript-testing-jest",
+    # Common data/UI tools (3 skills)
+    "universal-data-xlsx",
+    "toolchains-ui-styling-tailwind",
+    "toolchains-ui-components-headlessui",
+}
+
+
+def parse_agent_frontmatter(agent_file: Path) -> Dict[str, Any]:
+    """Parse YAML frontmatter from agent markdown file.
+
+    Args:
+        agent_file: Path to agent markdown file
+
+    Returns:
+        Parsed frontmatter as dictionary, or empty dict if parsing fails
+
+    Example:
+        >>> frontmatter = parse_agent_frontmatter(Path("agent.md"))
+        >>> skills = frontmatter.get('skills', [])
+    """
+    try:
+        content = agent_file.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.warning(f"Failed to read {agent_file}: {e}")
+        return {}
+
+    # Match YAML frontmatter between --- delimiters
+    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        logger.debug(f"No frontmatter found in {agent_file}")
+        return {}
+
+    try:
+        frontmatter = yaml.safe_load(match.group(1))
+        return frontmatter or {}
+    except yaml.YAMLError as e:
+        logger.warning(f"Failed to parse frontmatter in {agent_file}: {e}")
+        return {}
+
+
+def get_skills_from_agent(frontmatter: Dict[str, Any]) -> Set[str]:
+    """Extract skill names from agent frontmatter (handles both formats).
+
+    Supports both legacy and new formats:
+    - Legacy: skills: [skill-a, skill-b, ...]
+    - New: skills: {required: [...], optional: [...]}
+
+    Args:
+        frontmatter: Parsed agent frontmatter
+
+    Returns:
+        Set of unique skill names
+
+    Example:
+        >>> # Legacy format
+        >>> frontmatter = {'skills': ['skill-a', 'skill-b']}
+        >>> get_skills_from_agent(frontmatter)
+        {'skill-a', 'skill-b'}
+
+        >>> # New format
+        >>> frontmatter = {'skills': {'required': ['skill-a'], 'optional': ['skill-b']}}
+        >>> get_skills_from_agent(frontmatter)
+        {'skill-a', 'skill-b'}
+    """
+    skills_field = frontmatter.get("skills")
+
+    # Handle None or missing skills field
+    if skills_field is None:
+        return set()
+
+    # New format: {required: [...], optional: [...]}
+    if isinstance(skills_field, dict):
+        required = skills_field.get("required") or []
+        optional = skills_field.get("optional") or []
+
+        # Ensure both are lists
+        if not isinstance(required, list):
+            required = []
+        if not isinstance(optional, list):
+            optional = []
+
+        return set(required + optional)
+
+    # Legacy format: [skill1, skill2, ...]
+    if isinstance(skills_field, list):
+        return set(skills_field)
+
+    # Unsupported format
+    logger.warning(f"Unexpected skills field type: {type(skills_field)}")
+    return set()
+
+
+def get_skills_from_mapping(agent_ids: List[str]) -> Set[str]:
+    """Get skills for agents using SkillToAgentMapper inference.
+
+    DEPRECATED: This function is deprecated as of Phase 3 refactor.
+    Skills are now declared exclusively in agent frontmatter.
+
+    The static skill_to_agent_mapping.yaml is no longer used for skill deployment.
+    Each agent must declare its skills in frontmatter or it gets zero skills.
+
+    This function remains for backward compatibility but is NO LONGER CALLED
+    by get_required_skills_from_agents().
+
+    Args:
+        agent_ids: List of DEPLOYED agent identifiers (e.g., ["python-engineer", "typescript-engineer"])
+                  These should be extracted from ~/.claude/agents/*.md files only.
+
+    Returns:
+        Set of unique skill names inferred from mapping configuration for DEPLOYED agents only
+        NOTE: This is now an empty set as the function is deprecated.
+
+    Example:
+        >>> # DEPRECATED - use frontmatter instead
+        >>> deployed_agent_ids = ["python-engineer", "typescript-engineer", "qa"]
+        >>> skills = get_skills_from_mapping(deployed_agent_ids)  # Returns empty set
+    """
+    # DEPRECATED: Return empty set
+    logger.warning(
+        "get_skills_from_mapping() is DEPRECATED and returns empty set. "
+        "Skills are now declared in agent frontmatter only. "
+        "Update your agents with 'skills:' field in frontmatter."
+    )
+    return set()
+
+
+def extract_skills_from_content(agent_file: Path) -> Set[str]:
+    """Extract skill names from [SKILL: skill-name] markers in agent file content.
+
+    This function complements frontmatter skill extraction by finding inline
+    skill references in the agent's markdown content body.
+
+    Supports multiple formats:
+    - Bold marker: **[SKILL: skill-name]**
+    - Plain marker: [SKILL: skill-name]
+    - Backtick list: - `skill-name` - Description
+    - With spaces: [SKILL:  skill-name  ]
+
+    Args:
+        agent_file: Path to agent markdown file
+
+    Returns:
+        Set of skill names found in content body
+
+    Example:
+        >>> skills = extract_skills_from_content(Path("pm.md"))
+        >>> # Finds skills from markers like **[SKILL: mpm-delegation-patterns]**
+        >>> # Also finds from lists like - `mpm-teaching-mode` - Description
+        >>> print(f"Found {len(skills)} skills in content")
+    """
+    try:
+        content = agent_file.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.warning(f"Failed to read {agent_file}: {e}")
+        return set()
+
+    skills = set()
+
+    # Pattern 1: [SKILL: skill-name] markers (with optional markdown bold)
+    # Handles: **[SKILL: skill-name]** or [SKILL: skill-name]
+    # Pattern breakdown:
+    # - \*{0,2}: Optional bold markdown (0-2 asterisks)
+    # - \[SKILL:\s*: Opening bracket with optional whitespace
+    # - ([a-zA-Z0-9_-]+): Skill name (capture group)
+    # - \s*\]: Closing bracket with optional whitespace
+    # - \*{0,2}: Optional closing bold markdown
+    pattern1 = r"\*{0,2}\[SKILL:\s*([a-zA-Z0-9_-]+)\s*\]\*{0,2}"
+    matches1 = re.findall(pattern1, content, re.IGNORECASE)
+    skills.update(matches1)
+
+    # Pattern 2: Backtick list items with mpm-* or toolchains-* skills
+    # Handles: - `mpm-skill-name` - Description
+    # Pattern breakdown:
+    # - ^-\s+: Start with dash and whitespace (list item)
+    # - `: Opening backtick
+    # - ((?:mpm-|toolchains-|universal-)[a-zA-Z0-9_-]+): Skill name starting with prefix
+    # - `: Closing backtick
+    # - \s+-: Followed by whitespace and dash (description separator)
+    pattern2 = r"^-\s+`((?:mpm-|toolchains-|universal-)[a-zA-Z0-9_-]+)`\s+-"
+    matches2 = re.findall(pattern2, content, re.MULTILINE | re.IGNORECASE)
+    skills.update(matches2)
+
+    if skills:
+        logger.debug(
+            f"Found {len(skills)} skills from content markers in {agent_file.name}"
+        )
+
+    return skills
+
+
+def get_required_skills_from_agents(agents_dir: Path) -> Set[str]:
+    """Extract all skills referenced by deployed agents.
+
+    MAJOR CHANGE (Phase 3): Now uses TWO sources for skill discovery:
+    1. Frontmatter-declared skills (skills: field)
+    2. Content body markers ([SKILL: skill-name])
+
+    The static skill_to_agent_mapping.yaml is DEPRECATED. Each agent must
+    declare its skills via frontmatter OR inline markers.
+
+    This change:
+    - Eliminates dual-source complexity (frontmatter + mapping)
+    - Makes skill requirements explicit per agent
+    - Enables per-agent customization via frontmatter or inline markers
+    - Removes dependency on static YAML mapping
+    - Fixes PM skills being removed as orphaned (they use inline markers)
+
+    Special handling for PM_INSTRUCTIONS.md:
+    - Also scans .claude-mpm/PM_INSTRUCTIONS.md for skill markers
+    - PM instructions are not in agents_dir but contain [SKILL: ...] references
+
+    Args:
+        agents_dir: Path to deployed agents directory (e.g., .claude/agents/)
+
+    Returns:
+        Set of unique skill names referenced across all agents
+
+    Example:
+        >>> agents_dir = Path(".claude/agents")
+        >>> required_skills = get_required_skills_from_agents(agents_dir)
+        >>> print(f"Found {len(required_skills)} unique skills")
+    """
+    if not agents_dir.exists():
+        logger.warning(f"Agents directory not found: {agents_dir}")
+        return set()
+
+    # Scan all agent markdown files
+    agent_files = list(agents_dir.glob("*.md"))
+
+    # Special case: Add PM_INSTRUCTIONS.md if it exists
+    # PM instructions live in .claude-mpm/ not .claude/agents/
+    pm_instructions = agents_dir.parent.parent / ".claude-mpm" / "PM_INSTRUCTIONS.md"
+    if pm_instructions.exists():
+        agent_files.append(pm_instructions)
+        logger.debug("Added PM_INSTRUCTIONS.md for skill scanning")
+
+    logger.debug(f"Scanning {len(agent_files)} agent files (including PM instructions)")
+
+    # Use TWO sources: frontmatter AND content markers
+    frontmatter_skills = set()
+    content_skills = set()
+
+    for agent_file in agent_files:
+        agent_id = agent_file.stem
+
+        # Source 1: Extract from frontmatter
+        frontmatter = parse_agent_frontmatter(agent_file)
+        agent_fm_skills = get_skills_from_agent(frontmatter)
+
+        if agent_fm_skills:
+            frontmatter_skills.update(agent_fm_skills)
+            logger.debug(
+                f"Agent {agent_id}: {len(agent_fm_skills)} skills from frontmatter"
+            )
+
+        # Source 2: Extract from content body [SKILL: ...] markers
+        agent_content_skills = extract_skills_from_content(agent_file)
+
+        if agent_content_skills:
+            content_skills.update(agent_content_skills)
+            logger.debug(
+                f"Agent {agent_id}: {len(agent_content_skills)} skills from content markers"
+            )
+
+        if not agent_fm_skills and not agent_content_skills:
+            logger.debug(
+                f"Agent {agent_id}: No skills declared (checked frontmatter + content)"
+            )
+
+    # Combine both sources
+    all_skills = frontmatter_skills | content_skills
+
+    logger.info(
+        f"Found {len(all_skills)} unique skills "
+        f"({len(frontmatter_skills)} from frontmatter, "
+        f"{len(content_skills)} from content markers)"
+    )
+
+    # Normalize skill paths: convert slashes to dashes for compatibility with deployment
+    # Some skills may use slash format, normalize to dashes
+    normalized_skills = {skill.replace("/", "-") for skill in all_skills}
+
+    if normalized_skills != all_skills:
+        logger.debug(
+            f"Normalized {len(all_skills)} skills to {len(normalized_skills)} "
+            "(converted slashes to dashes)"
+        )
+
+    # Always include PM core skills to ensure PM_INSTRUCTIONS.md markers are resolved
+    # These skills are referenced in PM_INSTRUCTIONS.md and must be deployed
+    # for PM to see actual content instead of [SKILL: name] placeholders
+    before_pm_skills = len(normalized_skills)
+    normalized_skills = normalized_skills | PM_CORE_SKILLS
+    pm_skills_added = len(normalized_skills) - before_pm_skills
+
+    if pm_skills_added > 0:
+        logger.info(
+            f"Added {pm_skills_added} PM core skills to ensure PM_INSTRUCTIONS.md markers resolve"
+        )
+
+    return normalized_skills
+
+
+# === Deployment Tracking Functions ===
+
+
+def load_deployment_index(claude_skills_dir: Path) -> Dict[str, Any]:
+    """Load deployment tracking index from ~/.claude/skills/.
+
+    Args:
+        claude_skills_dir: Path to Claude skills directory (~/.claude/skills/)
+
+    Returns:
+        Dict containing:
+        - deployed_skills: Dict mapping skill name to deployment metadata
+        - user_requested_skills: List of skill names manually requested by user
+        - last_sync: ISO timestamp of last sync operation
+
+    Example:
+        >>> index = load_deployment_index(Path.home() / ".claude" / "skills")
+        >>> print(f"Tracked skills: {len(index['deployed_skills'])}")
+    """
+    index_path = claude_skills_dir / DEPLOYED_INDEX_FILE
+
+    if not index_path.exists():
+        logger.debug(f"No deployment index found at {index_path}, creating new")
+        return {"deployed_skills": {}, "user_requested_skills": [], "last_sync": None}
+
+    try:
+        with open(index_path, encoding="utf-8") as f:
+            index = json.load(f)
+
+        # Ensure required keys exist
+        if "deployed_skills" not in index:
+            index["deployed_skills"] = {}
+        if "user_requested_skills" not in index:
+            index["user_requested_skills"] = []
+        if "last_sync" not in index:
+            index["last_sync"] = None
+
+        logger.debug(
+            f"Loaded deployment index: {len(index['deployed_skills'])} tracked skills, "
+            f"{len(index['user_requested_skills'])} user-requested"
+        )
+        return index
+
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning(f"Failed to load deployment index: {e}, creating new")
+        return {"deployed_skills": {}, "user_requested_skills": [], "last_sync": None}
+
+
+def save_deployment_index(claude_skills_dir: Path, index: Dict[str, Any]) -> None:
+    """Save deployment tracking index to ~/.claude/skills/.
+
+    Args:
+        claude_skills_dir: Path to Claude skills directory (~/.claude/skills/)
+        index: Index data to save
+
+    Example:
+        >>> index = {"deployed_skills": {...}, "last_sync": "2025-12-22T10:30:00Z"}
+        >>> save_deployment_index(Path.home() / ".claude" / "skills", index)
+    """
+    index_path = claude_skills_dir / DEPLOYED_INDEX_FILE
+
+    try:
+        # Ensure directory exists
+        claude_skills_dir.mkdir(parents=True, exist_ok=True)
+
+        with open(index_path, "w", encoding="utf-8") as f:
+            json.dump(index, f, indent=2, ensure_ascii=False)
+
+        logger.debug(f"Saved deployment index: {len(index['deployed_skills'])} skills")
+
+    except OSError as e:
+        logger.error(f"Failed to save deployment index: {e}")
+        raise
+
+
+def track_deployed_skill(
+    claude_skills_dir: Path, skill_name: str, collection: str
+) -> None:
+    """Track a newly deployed skill in the deployment index.
+
+    Args:
+        claude_skills_dir: Path to Claude skills directory (~/.claude/skills/)
+        skill_name: Name of deployed skill
+        collection: Collection name skill was deployed from
+
+    Example:
+        >>> track_deployed_skill(
+        ...     Path.home() / ".claude" / "skills",
+        ...     "systematic-debugging",
+        ...     "claude-mpm-skills"
+        ... )
+    """
+    index = load_deployment_index(claude_skills_dir)
+
+    # Add skill to deployed_skills
+    index["deployed_skills"][skill_name] = {
+        "collection": collection,
+        "deployed_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    }
+
+    # Update last_sync timestamp
+    index["last_sync"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+    save_deployment_index(claude_skills_dir, index)
+    logger.debug(f"Tracked deployment: {skill_name} from {collection}")
+
+
+def untrack_skill(claude_skills_dir: Path, skill_name: str) -> None:
+    """Remove skill from deployment tracking index.
+
+    Args:
+        claude_skills_dir: Path to Claude skills directory (~/.claude/skills/)
+        skill_name: Name of skill to untrack
+
+    Example:
+        >>> untrack_skill(
+        ...     Path.home() / ".claude" / "skills",
+        ...     "old-skill"
+        ... )
+    """
+    index = load_deployment_index(claude_skills_dir)
+
+    if skill_name in index["deployed_skills"]:
+        del index["deployed_skills"][skill_name]
+        index["last_sync"] = (
+            datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+        )
+        save_deployment_index(claude_skills_dir, index)
+        logger.debug(f"Untracked skill: {skill_name}")
+
+
+def cleanup_orphan_skills(
+    claude_skills_dir: Path, required_skills: Set[str]
+) -> Dict[str, Any]:
+    """Remove skills deployed by claude-mpm but no longer referenced by agents.
+
+    This function:
+    1. Loads deployment tracking index
+    2. Identifies orphaned skills (tracked but not in required_skills AND not user-requested)
+    3. Removes orphaned skill directories from ~/.claude/skills/
+    4. Updates deployment index
+
+    User-requested skills are NEVER cleaned up as orphans - they are treated as required.
+
+    Args:
+        claude_skills_dir: Path to Claude skills directory (~/.claude/skills/)
+        required_skills: Set of skill names currently required by agents
+
+    Returns:
+        Dict containing:
+        - removed_count: Number of skills removed
+        - removed_skills: List of removed skill names
+        - kept_count: Number of skills kept
+        - errors: List of error messages
+
+    Example:
+        >>> required = {"skill-a", "skill-b"}
+        >>> result = cleanup_orphan_skills(
+        ...     Path.home() / ".claude" / "skills",
+        ...     required
+        ... )
+        >>> print(f"Removed {result['removed_count']} orphaned skills")
+    """
+    import shutil
+
+    index = load_deployment_index(claude_skills_dir)
+    tracked_skills = set(index["deployed_skills"].keys())
+    user_requested = set(index.get("user_requested_skills", []))
+
+    # Find orphaned skills: tracked by mpm but not in required_skills AND not user-requested
+    # User-requested skills are treated as required and NEVER cleaned up
+    all_required = required_skills | user_requested
+    orphaned = tracked_skills - all_required
+
+    if not orphaned:
+        logger.info("No orphaned skills to remove")
+        return {
+            "removed_count": 0,
+            "removed_skills": [],
+            "kept_count": len(tracked_skills),
+            "errors": [],
+        }
+
+    logger.info(
+        f"Found {len(orphaned)} orphaned skills (tracked but not required by agents)"
+    )
+
+    removed = []
+    errors = []
+
+    for skill_name in orphaned:
+        skill_dir = claude_skills_dir / skill_name
+
+        # Remove skill directory if it exists
+        if skill_dir.exists():
+            try:
+                # Validate path is within claude_skills_dir (security)
+                skill_dir.resolve().relative_to(claude_skills_dir.resolve())
+
+                # Remove directory
+                if skill_dir.is_symlink():
+                    logger.debug(f"Removing symlink: {skill_dir}")
+                    skill_dir.unlink()
+                else:
+                    shutil.rmtree(skill_dir)
+
+                removed.append(skill_name)
+                logger.info(f"Removed orphaned skill: {skill_name}")
+
+            except ValueError:
+                error_msg = f"Path traversal attempt detected: {skill_dir}"
+                logger.error(error_msg)
+                errors.append(error_msg)
+                continue
+            except Exception as e:
+                error_msg = f"Failed to remove {skill_name}: {e}"
+                logger.error(error_msg)
+                errors.append(error_msg)
+                continue
+
+        # Remove from tracking index
+        untrack_skill(claude_skills_dir, skill_name)
+
+    kept_count = len(tracked_skills) - len(removed)
+
+    logger.info(
+        f"Cleanup complete: removed {len(removed)} skills, kept {kept_count} skills"
+    )
+
+    return {
+        "removed_count": len(removed),
+        "removed_skills": removed,
+        "kept_count": kept_count,
+        "errors": errors,
+    }
+
+
+# === Configuration Management Functions ===
+
+
+def save_agent_skills_to_config(skills: List[str], config_path: Path) -> None:
+    """Save agent-scanned skills to configuration.yaml under skills.agent_referenced.
+
+    Args:
+        skills: List of skill names scanned from deployed agents
+        config_path: Path to configuration.yaml file
+
+    Example:
+        >>> skills = ["systematic-debugging", "typescript-core"]
+        >>> save_agent_skills_to_config(skills, Path(".claude-mpm/configuration.yaml"))
+    """
+    import yaml
+
+    try:
+        # Load existing configuration (or create empty dict)
+        if config_path.exists():
+            with open(config_path, encoding="utf-8") as f:
+                config = yaml.safe_load(f) or {}
+        else:
+            config = {}
+
+        # Ensure skills section exists
+        if "skills" not in config:
+            config["skills"] = {}
+
+        # Update agent_referenced skills (sorted for consistency)
+        config["skills"]["agent_referenced"] = sorted(skills)
+
+        # Ensure user_defined exists (but don't overwrite if set)
+        if "user_defined" not in config["skills"]:
+            config["skills"]["user_defined"] = []
+
+        # Save configuration
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(config_path, "w", encoding="utf-8") as f:
+            yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+
+        logger.info(
+            f"Saved {len(skills)} agent-referenced skills to configuration.yaml"
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to save agent skills to config: {e}")
+        raise
+
+
+def get_skills_to_deploy(config_path: Path) -> Tuple[List[str], str]:
+    """Resolve which skills to deploy based on configuration priority.
+
+    Returns (skills_list, source) where source is 'user_defined' or 'agent_referenced'.
+
+    Logic:
+    - If config.skills.user_defined is non-empty → return (user_defined, 'user_defined')
+    - Otherwise → return (agent_referenced, 'agent_referenced')
+
+    Args:
+        config_path: Path to configuration.yaml file
+
+    Returns:
+        Tuple of (skills list, source string)
+
+    Example:
+        >>> skills, source = get_skills_to_deploy(Path(".claude-mpm/configuration.yaml"))
+        >>> print(f"Deploy {len(skills)} skills from {source}")
+    """
+    import yaml
+
+    try:
+        # Load configuration
+        if not config_path.exists():
+            logger.warning(f"Configuration file not found: {config_path}")
+            return ([], "agent_referenced")
+
+        with open(config_path, encoding="utf-8") as f:
+            config = yaml.safe_load(f) or {}
+
+        skills_config = config.get("skills", {})
+        user_defined = skills_config.get("user_defined", [])
+        agent_referenced = skills_config.get("agent_referenced", [])
+
+        # Priority: user_defined if non-empty, otherwise agent_referenced
+        if user_defined:
+            logger.info(
+                f"Using {len(user_defined)} user-defined skills from configuration"
+            )
+            return (user_defined, "user_defined")
+        logger.info(
+            f"Using {len(agent_referenced)} agent-referenced skills from configuration"
+        )
+        return (agent_referenced, "agent_referenced")
+
+    except Exception as e:
+        logger.error(f"Failed to load skills from config: {e}")
+        return ([], "agent_referenced")
+
+
+# === User-Requested Skills Management ===
+
+
+def get_user_requested_skills(claude_skills_dir: Path) -> List[str]:
+    """Get list of user-requested skills.
+
+    Args:
+        claude_skills_dir: Path to Claude skills directory (~/.claude/skills/)
+
+    Returns:
+        List of skill names manually requested by user
+
+    Example:
+        >>> skills = get_user_requested_skills(Path.home() / ".claude" / "skills")
+        >>> print(f"User requested {len(skills)} skills")
+    """
+    index = load_deployment_index(claude_skills_dir)
+    return index.get("user_requested_skills", [])
+
+
+def add_user_requested_skill(skill_name: str, claude_skills_dir: Path) -> bool:
+    """Add a skill to user_requested_skills list.
+
+    This function:
+    1. Loads deployment index
+    2. Adds skill name to user_requested_skills (if not already present)
+    3. Saves updated index
+    4. Returns success status
+
+    Note: This function does NOT deploy the skill, it only marks it as user-requested.
+    Use this in conjunction with skill deployment functions.
+
+    Args:
+        skill_name: Name of skill to mark as user-requested
+        claude_skills_dir: Path to Claude skills directory (~/.claude/skills/)
+
+    Returns:
+        True if skill was added, False if already present
+
+    Example:
+        >>> added = add_user_requested_skill(
+        ...     "django-framework",
+        ...     Path.home() / ".claude" / "skills"
+        ... )
+        >>> print(f"Skill added: {added}")
+    """
+    index = load_deployment_index(claude_skills_dir)
+    user_requested = index.get("user_requested_skills", [])
+
+    if skill_name in user_requested:
+        logger.debug(f"Skill {skill_name} already in user_requested_skills")
+        return False
+
+    user_requested.append(skill_name)
+    index["user_requested_skills"] = user_requested
+    index["last_sync"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+    save_deployment_index(claude_skills_dir, index)
+    logger.info(f"Added {skill_name} to user_requested_skills")
+    return True
+
+
+def remove_user_requested_skill(skill_name: str, claude_skills_dir: Path) -> bool:
+    """Remove a skill from user_requested_skills list.
+
+    This function:
+    1. Loads deployment index
+    2. Removes skill name from user_requested_skills
+    3. Saves updated index
+    4. Returns success status
+
+    Note: This function does NOT remove the deployed skill directory.
+    It only removes the skill from user_requested_skills, making it eligible
+    for cleanup during orphan removal.
+
+    Args:
+        skill_name: Name of skill to remove from user_requested_skills
+        claude_skills_dir: Path to Claude skills directory (~/.claude/skills/)
+
+    Returns:
+        True if skill was removed, False if not present
+
+    Example:
+        >>> removed = remove_user_requested_skill(
+        ...     "django-framework",
+        ...     Path.home() / ".claude" / "skills"
+        ... )
+        >>> print(f"Skill removed: {removed}")
+    """
+    index = load_deployment_index(claude_skills_dir)
+    user_requested = index.get("user_requested_skills", [])
+
+    if skill_name not in user_requested:
+        logger.debug(f"Skill {skill_name} not in user_requested_skills")
+        return False
+
+    user_requested.remove(skill_name)
+    index["user_requested_skills"] = user_requested
+    index["last_sync"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+    save_deployment_index(claude_skills_dir, index)
+    logger.info(f"Removed {skill_name} from user_requested_skills")
+    return True
+
+
+def is_user_requested_skill(skill_name: str, claude_skills_dir: Path) -> bool:
+    """Check if a skill is in the user_requested_skills list.
+
+    Args:
+        skill_name: Name of skill to check
+        claude_skills_dir: Path to Claude skills directory (~/.claude/skills/)
+
+    Returns:
+        True if skill is user-requested, False otherwise
+
+    Example:
+        >>> is_requested = is_user_requested_skill(
+        ...     "django-framework",
+        ...     Path.home() / ".claude" / "skills"
+        ... )
+        >>> print(f"User requested: {is_requested}")
+    """
+    user_requested = get_user_requested_skills(claude_skills_dir)
+    return skill_name in user_requested