claude-mpm 5.4.22__py3-none-any.whl → 5.6.34__py3-none-any.whl

claude_mpm/skills/registry.py

@@ -14,35 +14,144 @@ logger = get_logger(__name__)
 
 @dataclass
 class Skill:
-    """Represents a skill that can be used by agents."""
-
+    """Represents a skill that can be used by agents.
+
+    Supports agentskills.io specification with backward compatibility for legacy claude-mpm format.
+
+    Spec fields (agentskills.io):
+    - name: Required, 1-64 chars, lowercase alphanumeric + hyphens
+    - description: Required, 1-1024 chars
+    - license: Optional, license name or reference
+    - compatibility: Optional, max 500 chars, environment requirements
+    - metadata: Optional, key-value mapping for arbitrary data
+    - allowed_tools: Optional, list of pre-approved tools
+
+    Internal fields:
+    - path: Path to skill file
+    - content: Skill content (markdown)
+    - source: Origin of skill ('bundled', 'user', 'project', 'pm')
+    - version: Skill version (from metadata.version or top-level)
+    - skill_id: Internal ID (defaults to name)
+    - agent_types: Which agent types can use this skill
+    - updated_at: Last update timestamp (from metadata.updated)
+    - tags: Tags for discovery (from metadata.tags or top-level)
+
+    Claude-mpm extensions (preserved for backward compat):
+    - category: Skill category for organization
+    - toolchain: Associated toolchain (python, javascript, etc.)
+    - progressive_disclosure: Progressive disclosure configuration
+    - user_invocable: Whether skill can be manually invoked
+    """
+
+    # Core spec fields (agentskills.io)
     name: str
-    path: Path
-    content: str
-    source: str  # 'bundled', 'user', or 'project'
-
-    # Version tracking fields
-    version: str = "0.1.0"
-    skill_id: str = ""  # defaults to name if not provided
-
-    # Existing fields
-    description: str = ""
+    description: str
+    license: Optional[str] = None
+    compatibility: Optional[str] = None
+    metadata: Dict[str, Any] = None
+    allowed_tools: List[str] = None
+
+    # Internal fields (not in frontmatter spec)
+    path: Path = None
+    content: str = ""
+    source: str = "bundled"  # 'bundled', 'user', 'project', 'pm'
+
+    # Derived fields (from metadata or fallback)
+    version: str = "0.1.0"  # From metadata.version or top-level
+    skill_id: str = ""  # Internal ID (defaults to name)
     agent_types: List[str] = None  # Which agent types can use this skill
+    updated_at: Optional[str] = None  # From metadata.updated
+    tags: List[str] = None  # From metadata.tags or top-level
 
-    # Optional metadata
-    updated_at: Optional[str] = None
-    tags: List[str] = None
+    # Claude-mpm extensions (preserved for backward compat)
+    category: Optional[str] = None
+    toolchain: Optional[str] = None
+    progressive_disclosure: Optional[Dict[str, Any]] = None
+    user_invocable: bool = False
 
     def __post_init__(self):
         """Initialize default values if not provided."""
+        if self.metadata is None:
+            self.metadata = {}
         if self.agent_types is None:
             self.agent_types = []
         if self.tags is None:
             self.tags = []
+        if self.allowed_tools is None:
+            self.allowed_tools = []
         if not self.skill_id:
             self.skill_id = self.name
 
 
+def validate_agentskills_spec(skill: Skill) -> tuple[bool, List[str]]:
+    """Validate skill against agentskills.io specification.
+
+    Args:
+        skill: Skill object to validate
+
+    Returns:
+        Tuple of (is_valid, list_of_warnings)
+        - is_valid: True if skill meets spec requirements
+        - warnings: List of warning messages for spec violations
+    """
+    warnings = []
+
+    # Validate name (required field)
+    if not skill.name:
+        warnings.append("Missing required field: name")
+        return False, warnings
+
+    # Validate name format: lowercase alphanumeric + hyphens, no leading/trailing hyphens
+    if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", skill.name):
+        warnings.append(
+            f"Invalid name format: '{skill.name}' (must be lowercase alphanumeric with hyphens, "
+            "no leading/trailing hyphens, no consecutive hyphens)"
+        )
+
+    # Validate name length (max 64 chars)
+    if len(skill.name) > 64:
+        warnings.append(
+            f"Name too long: {len(skill.name)} chars (max 64 per agentskills.io spec)"
+        )
+
+    # Validate description (required field)
+    if not skill.description:
+        warnings.append("Missing required field: description")
+        return False, warnings
+
+    # Validate description length (1-1024 chars)
+    desc_len = len(skill.description)
+    if desc_len < 1 or desc_len > 1024:
+        warnings.append(
+            f"Description length {desc_len} chars is outside spec range (1-1024 chars)"
+        )
+
+    # Validate compatibility length (max 500 chars)
+    if skill.compatibility and len(skill.compatibility) > 500:
+        warnings.append(
+            f"Compatibility field too long: {len(skill.compatibility)} chars (max 500)"
+        )
+
+    # Validate metadata is dict
+    if skill.metadata is not None and not isinstance(skill.metadata, dict):
+        warnings.append("Metadata must be a key-value mapping (dict)")
+
+    # Check for spec-compliant metadata structure
+    spec_metadata_fields = ["version", "author", "updated", "tags"]
+    for field in spec_metadata_fields:
+        if hasattr(skill, field):
+            field_value = getattr(skill, field)
+            if field_value and field not in skill.metadata:
+                warnings.append(
+                    f"Field '{field}' should be in metadata block per agentskills.io spec "
+                    f"(found as top-level field)"
+                )
+
+    # Valid if no errors (only warnings allowed)
+    is_valid = len(warnings) == 0 or all("should be in metadata" in w for w in warnings)
+    return is_valid, warnings
+
+
 class SkillsRegistry:
     """Registry for managing skills across all tiers."""
 
@@ -54,7 +163,10 @@ class SkillsRegistry:
         self._load_project_skills()
 
     def _parse_skill_frontmatter(self, content: str) -> Dict[str, Any]:
-        """Parse YAML frontmatter from skill markdown file.
+        """Parse YAML frontmatter from skill markdown file with spec validation.
+
+        Supports both agentskills.io spec format and legacy claude-mpm format
+        with automatic migration.
 
         Returns:
             Dict with frontmatter fields or empty dict if no frontmatter
@@ -70,11 +182,150 @@ class SkillsRegistry:
 
         try:
             frontmatter = yaml.safe_load(match.group(1))
-            return frontmatter or {}
+            if not frontmatter:
+                return {}
+
+            # Apply backward compatibility migration
+            return self._apply_backward_compatibility(frontmatter)
         except yaml.YAMLError as e:
             logger.warning(f"Failed to parse skill frontmatter: {e}")
             return {}
 
+    def _apply_backward_compatibility(
+        self, frontmatter: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Apply backward compatibility transformations to legacy frontmatter.
+
+        Auto-migrates legacy claude-mpm fields to agentskills.io spec format:
+        - version → metadata.version
+        - author → metadata.author
+        - updated → metadata.updated
+        - tags → metadata.tags (if not already present)
+
+        Args:
+            frontmatter: Parsed frontmatter dict
+
+        Returns:
+            Transformed frontmatter with spec-compliant structure
+        """
+        # Initialize metadata if not present
+        if "metadata" not in frontmatter:
+            frontmatter["metadata"] = {}
+
+        metadata = frontmatter["metadata"]
+
+        # Auto-migrate version (top-level → metadata.version)
+        if "version" in frontmatter and "version" not in metadata:
+            metadata["version"] = frontmatter["version"]
+            logger.debug(
+                f"Auto-migrated 'version' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Auto-migrate author (top-level → metadata.author)
+        if "author" in frontmatter and "author" not in metadata:
+            metadata["author"] = frontmatter["author"]
+            logger.debug(
+                f"Auto-migrated 'author' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Auto-migrate updated (top-level → metadata.updated)
+        if "updated" in frontmatter and "updated" not in metadata:
+            metadata["updated"] = frontmatter["updated"]
+            logger.debug(
+                f"Auto-migrated 'updated' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Auto-migrate tags (top-level → metadata.tags)
+        if "tags" in frontmatter and "tags" not in metadata:
+            metadata["tags"] = frontmatter["tags"]
+            logger.debug(
+                f"Auto-migrated 'tags' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Parse allowed-tools from space-delimited string to list
+        if "allowed-tools" in frontmatter:
+            allowed_tools = frontmatter["allowed-tools"]
+            if isinstance(allowed_tools, str):
+                frontmatter["allowed-tools"] = allowed_tools.split()
+
+        # Set default compatibility for claude-code if not present
+        if "compatibility" not in frontmatter:
+            frontmatter["compatibility"] = "claude-code"
+
+        return frontmatter
+
+    def _create_skill_from_frontmatter(
+        self, frontmatter: Dict[str, Any], path: Path, content: str, source: str
+    ) -> Optional[Skill]:
+        """Create Skill object from frontmatter with spec compliance.
+
+        Args:
+            frontmatter: Parsed and migrated frontmatter dict
+            path: Path to skill file
+            content: Full skill content
+            source: Source type ('bundled', 'user', 'project', 'pm')
+
+        Returns:
+            Skill object or None if required fields missing
+        """
+        # Extract spec fields (required)
+        name = frontmatter.get("name")
+        description = frontmatter.get("description", "")
+
+        # If name not in frontmatter, use filename stem
+        if not name:
+            name = path.stem
+
+        # If description not in frontmatter, extract from content
+        if not description:
+            description = self._extract_description(content)
+
+        # Validate required fields
+        if not name or not description:
+            logger.warning(
+                f"Skipping skill at {path}: missing required field (name or description)"
+            )
+            return None
+
+        # Extract spec fields (optional)
+        license_field = frontmatter.get("license")
+        compatibility = frontmatter.get("compatibility", "claude-code")
+        metadata = frontmatter.get("metadata", {})
+        allowed_tools = frontmatter.get("allowed-tools", [])
+
+        # Extract derived fields from metadata or top-level
+        version = frontmatter.get("version") or metadata.get("version", "0.1.0")
+        skill_id = frontmatter.get("skill_id", name)
+        updated_at = frontmatter.get("updated_at") or metadata.get("updated")
+        tags = frontmatter.get("tags", []) or metadata.get("tags", [])
+
+        # Extract claude-mpm extensions
+        category = frontmatter.get("category")
+        toolchain = frontmatter.get("toolchain")
+        progressive_disclosure = frontmatter.get("progressive_disclosure")
+        user_invocable = frontmatter.get("user-invocable", False)
+
+        # Create skill object
+        return Skill(
+            name=name,
+            description=description,
+            license=license_field,
+            compatibility=compatibility,
+            metadata=metadata,
+            allowed_tools=allowed_tools,
+            path=path,
+            content=content,
+            source=source,
+            version=version,
+            skill_id=skill_id,
+            updated_at=updated_at,
+            tags=tags,
+            category=category,
+            toolchain=toolchain,
+            progressive_disclosure=progressive_disclosure,
+            user_invocable=user_invocable,
+        )
+
     def _load_bundled_skills(self):
         """Load skills bundled with MPM."""
         bundled_dir = Path(__file__).parent / "bundled"
@@ -88,32 +339,16 @@ class SkillsRegistry:
                 skill_name = skill_file.stem
                 content = skill_file.read_text(encoding="utf-8")
 
-                # Parse frontmatter
+                # Parse frontmatter with backward compatibility
                 frontmatter = self._parse_skill_frontmatter(content)
 
-                # Extract version fields from frontmatter
-                version = frontmatter.get("skill_version", "0.1.0")
-                skill_id = frontmatter.get("skill_id", skill_name)
-                updated_at = frontmatter.get("updated_at")
-                tags = frontmatter.get("tags", [])
-
-                # Extract description (from frontmatter or fallback to content parsing)
-                description = frontmatter.get("description", "")
-                if not description:
-                    description = self._extract_description(content)
-
-                self.skills[skill_name] = Skill(
-                    name=skill_name,
-                    path=skill_file,
-                    content=content,
-                    source="bundled",
-                    version=version,
-                    skill_id=skill_id,
-                    description=description,
-                    updated_at=updated_at,
-                    tags=tags,
+                # Create skill from frontmatter
+                skill = self._create_skill_from_frontmatter(
+                    frontmatter, skill_file, content, "bundled"
                 )
-                skill_count += 1
+                if skill:
+                    self.skills[skill_name] = skill
+                    skill_count += 1
             except Exception as e:
                 logger.error(f"Error loading bundled skill {skill_file}: {e}")
 
@@ -130,36 +365,20 @@ class SkillsRegistry:
         for skill_file in user_skills_dir.glob("*.md"):
             try:
                 skill_name = skill_file.stem
-                # User skills override bundled skills
                 content = skill_file.read_text(encoding="utf-8")
 
-                # Parse frontmatter
+                # Parse frontmatter with backward compatibility
                 frontmatter = self._parse_skill_frontmatter(content)
 
-                # Extract version fields from frontmatter
-                version = frontmatter.get("skill_version", "0.1.0")
-                skill_id = frontmatter.get("skill_id", skill_name)
-                updated_at = frontmatter.get("updated_at")
-                tags = frontmatter.get("tags", [])
-
-                # Extract description (from frontmatter or fallback to content parsing)
-                description = frontmatter.get("description", "")
-                if not description:
-                    description = self._extract_description(content)
-
-                self.skills[skill_name] = Skill(
-                    name=skill_name,
-                    path=skill_file,
-                    content=content,
-                    source="user",
-                    version=version,
-                    skill_id=skill_id,
-                    description=description,
-                    updated_at=updated_at,
-                    tags=tags,
+                # Create skill from frontmatter
+                skill = self._create_skill_from_frontmatter(
+                    frontmatter, skill_file, content, "user"
                 )
-                skill_count += 1
-                logger.debug(f"User skill '{skill_name}' overrides bundled version")
+                if skill:
+                    # User skills override bundled skills
+                    self.skills[skill_name] = skill
+                    skill_count += 1
+                    logger.debug(f"User skill '{skill_name}' overrides bundled version")
             except Exception as e:
                 logger.error(f"Error loading user skill {skill_file}: {e}")
 
@@ -177,36 +396,22 @@ class SkillsRegistry:
         for skill_file in project_skills_dir.glob("*.md"):
             try:
                 skill_name = skill_file.stem
-                # Project skills override both user and bundled skills
                 content = skill_file.read_text(encoding="utf-8")
 
-                # Parse frontmatter
+                # Parse frontmatter with backward compatibility
                 frontmatter = self._parse_skill_frontmatter(content)
 
-                # Extract version fields from frontmatter
-                version = frontmatter.get("skill_version", "0.1.0")
-                skill_id = frontmatter.get("skill_id", skill_name)
-                updated_at = frontmatter.get("updated_at")
-                tags = frontmatter.get("tags", [])
-
-                # Extract description (from frontmatter or fallback to content parsing)
-                description = frontmatter.get("description", "")
-                if not description:
-                    description = self._extract_description(content)
-
-                self.skills[skill_name] = Skill(
-                    name=skill_name,
-                    path=skill_file,
-                    content=content,
-                    source="project",
-                    version=version,
-                    skill_id=skill_id,
-                    description=description,
-                    updated_at=updated_at,
-                    tags=tags,
+                # Create skill from frontmatter
+                skill = self._create_skill_from_frontmatter(
+                    frontmatter, skill_file, content, "project"
                 )
-                skill_count += 1
-                logger.debug(f"Project skill '{skill_name}' overrides other versions")
+                if skill:
+                    # Project skills override both user and bundled skills
+                    self.skills[skill_name] = skill
+                    skill_count += 1
+                    logger.debug(
+                        f"Project skill '{skill_name}' overrides other versions"
+                    )
             except Exception as e:
                 logger.error(f"Error loading project skill {skill_file}: {e}")
 

claude_mpm/skills/skill_manager.py

@@ -2,7 +2,9 @@
 
 import json
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Any, Dict, List, Optional
+
+import yaml
 
 from claude_mpm.core.logging_utils import get_logger
 
@@ -56,12 +58,81 @@ class SkillManager:
         if mapping_count > 0:
             logger.info(f"Loaded skill mappings for {mapping_count} agents")
 
+    def _get_pm_skills(
+        self, project_dir: Optional[Path] = None
+    ) -> List[Dict[str, Any]]:
+        """Load PM skills from project's .claude/skills/ directory.
+
+        PM skills are special framework management skills (mpm-*) deployed
+        per-project to .claude/skills/, NOT fetched from the skills repository.
+
+        Args:
+            project_dir: Project directory. Defaults to current working directory.
+
+        Returns:
+            List of PM skill dictionaries with metadata
+        """
+        if project_dir is None:
+            project_dir = Path.cwd()
+
+        pm_skills_dir = project_dir / ".claude" / "skills"
+
+        if not pm_skills_dir.exists():
+            logger.debug("PM skills directory not found")
+            return []
+
+        skills = []
+        for skill_dir in pm_skills_dir.iterdir():
+            if skill_dir.is_dir():
+                skill_file = skill_dir / "SKILL.md"
+                if skill_file.exists():
+                    skill = self._load_pm_skill(skill_file)
+                    if skill:
+                        skills.append(skill)
+
+        if skills:
+            logger.debug(f"Loaded {len(skills)} PM skills from {pm_skills_dir}")
+
+        return skills
+
+    def _load_pm_skill(self, skill_file: Path) -> Optional[Dict[str, Any]]:
+        """Load a single PM skill from SKILL.md file.
+
+        Args:
+            skill_file: Path to SKILL.md file
+
+        Returns:
+            Dictionary with skill metadata and content, or None if failed
+        """
+        try:
+            content = skill_file.read_text(encoding="utf-8")
+
+            # Parse YAML frontmatter
+            if content.startswith("---"):
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    metadata = yaml.safe_load(parts[1])
+                    body = parts[2].strip()
+
+                    return {
+                        "name": metadata.get("name", skill_file.parent.name),
+                        "version": metadata.get("version", "1.0.0"),
+                        "description": metadata.get("description", ""),
+                        "when_to_use": metadata.get("when_to_use", ""),
+                        "content": body,
+                        "is_pm_skill": True,
+                    }
+        except Exception as e:
+            logger.warning(f"Failed to load PM skill {skill_file}: {e}")
+
+        return None
+
     def get_agent_skills(self, agent_type: str) -> List[Skill]:
         """
-        Get all skills for an agent (bundled + discovered).
+        Get all skills for an agent (bundled + discovered + PM skills if PM agent).
 
         Args:
-            agent_type: Agent type/ID (e.g., 'engineer', 'python_engineer')
+            agent_type: Agent type/ID (e.g., 'engineer', 'python_engineer', 'pm')
 
         Returns:
             List of Skill objects for this agent
@@ -86,6 +157,30 @@ class SkillManager:
             if skill not in skills:
                 skills.append(skill)
 
+        # Add PM skills for PM agent only
+        if agent_type.lower() in ("pm", "project-manager", "project_manager"):
+            pm_skill_dicts = self._get_pm_skills()
+            for pm_skill_dict in pm_skill_dicts:
+                # Convert PM skill dict to Skill object
+                pm_skill = Skill(
+                    name=pm_skill_dict["name"],
+                    path=Path.cwd()
+                    / ".claude-mpm"
+                    / "skills"
+                    / "pm"
+                    / pm_skill_dict["name"],
+                    content=pm_skill_dict["content"],
+                    source="pm",  # Special source type for PM skills
+                    version=pm_skill_dict["version"],
+                    skill_id=pm_skill_dict["name"],
+                    description=pm_skill_dict["description"],
+                    agent_types=["pm", "project-manager", "project_manager"],
+                )
+                skills.append(pm_skill)
+
+            if pm_skill_dicts:
+                logger.debug(f"Added {len(pm_skill_dicts)} PM skills for PM agent")
+
         return skills
 
     def enhance_agent_prompt(

claude_mpm/templates/.pre-commit-config.yaml

@@ -0,0 +1,112 @@
+# Pre-commit hooks configuration for claude-mpm
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+
+repos:
+  # Standard pre-commit hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^(.*\.md|.*\.txt)$
+      - id: end-of-file-fixer
+        exclude: ^(.*\.md|.*\.txt)$
+      - id: check-yaml
+        args: ['--unsafe']  # Allow custom YAML tags
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-shebang-scripts-are-executable
+      - id: mixed-line-ending
+        args: ['--fix=lf']
+
+  # Ruff - replaces black, isort, flake8, pyupgrade (10-200x faster)
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4  # Use latest version
+    hooks:
+      # Run the linter
+      - id: ruff
+        args: [--fix]
+      # Run the formatter
+      - id: ruff-format
+
+  # Type checking with mypy
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-PyYAML, types-requests]
+        args: ['--config-file=mypy.ini']
+        exclude: ^(venv/|\.venv/|env/|\.env/|build/|dist/|\.git/|tests/.*\.py|scripts/.*\.py)
+
+  # Security scanning with bandit
+  - repo: https://github.com/pycqa/bandit
+    rev: 1.7.5
+    hooks:
+      - id: bandit
+        args: ['-r', '-f', 'json']
+        exclude: ^(venv/|\.venv/|env/|\.env/|build/|dist/|\.git/|tests/.*\.py)
+
+  # Secret detection with detect-secrets
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+        exclude: |
+          (?x)^(
+            venv/.*|
+            \.venv/.*|
+            node_modules/.*|
+            \.git/.*|
+            __pycache__/.*|
+            .*\.lock|
+            .*package-lock\.json|
+            .*\.pyc
+          )$
+
+  # Documentation linting
+  - repo: https://github.com/pycqa/doc8
+    rev: v1.1.1
+    hooks:
+      - id: doc8
+        args: ['--max-line-length=88']
+        files: \.rst$
+
+  # Commitizen for conventional commits
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v3.13.0
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
+# Configuration for specific file types
+exclude: |
+  (?x)^(
+    venv/.*|
+    \.venv/.*|
+    env/.*|
+    \.env/.*|
+    build/.*|
+    dist/.*|
+    \.git/.*|
+    __pycache__/.*|
+    .*\.pyc|
+    .*\.pyo|
+    .*\.egg-info/.*|
+    \.coverage|
+    \.pytest_cache/.*|
+    \.mypy_cache/.*|
+    node_modules/.*|
+    \.DS_Store|
+    \.vscode/.*|
+    \.idea/.*
+  )$
+
+# Global settings
+default_stages: [pre-commit]
+fail_fast: false