claude-mpm 5.4.65__py3-none-any.whl → 5.6.10__py3-none-any.whl

claude_mpm/services/skills/git_skill_source_manager.py

@@ -16,6 +16,7 @@ Trade-offs:
 - Flexibility: Easy to extend with skills-specific features
 """
 
+import os
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime, timezone
 from pathlib import Path
@@ -32,6 +33,46 @@ from claude_mpm.services.skills.skill_discovery_service import SkillDiscoverySer
 logger = get_logger(__name__)
 
 
+def _get_github_token(source: Optional[SkillSource] = None) -> Optional[str]:
+    """Get GitHub token with source-specific override support.
+
+    Priority: source.token > GITHUB_TOKEN > GH_TOKEN
+
+    Args:
+        source: Optional SkillSource to check for per-source token
+
+    Returns:
+        GitHub token if found, None otherwise
+
+    Token Resolution:
+        1. If source has token starting with "$", resolve as env var
+        2. If source has direct token, use it (not recommended for security)
+        3. Fall back to GITHUB_TOKEN env var
+        4. Fall back to GH_TOKEN env var
+        5. Return None if no token found
+
+    Security Note:
+        Token is never logged or printed to avoid exposure.
+        Direct tokens in config are discouraged - use env var refs ($VAR_NAME).
+
+    Example:
+        >>> source = SkillSource(..., token="$PRIVATE_TOKEN")
+        >>> token = _get_github_token(source)  # Resolves $PRIVATE_TOKEN from env
+        >>> token = _get_github_token()  # Falls back to GITHUB_TOKEN
+    """
+    # Priority 1: Per-source token (env var reference or direct)
+    if source and source.token:
+        if source.token.startswith("$"):
+            # Env var reference: $VAR_NAME -> os.environ.get("VAR_NAME")
+            env_var_name = source.token[1:]
+            return os.environ.get(env_var_name)
+        # Direct token (not recommended but supported)
+        return source.token
+
+    # Priority 2-3: Global environment variables
+    return os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+
+
 class GitSkillSourceManager:
     """Manages multiple Git-based skill sources with priority resolution.
 
@@ -217,9 +258,21 @@ class GitSkillSourceManager:
             )
 
             # Discover skills in cache
+            self.logger.debug(f"Scanning cache path for skills: {cache_path}")
             discovery_service = SkillDiscoveryService(cache_path)
             discovered_skills = discovery_service.discover_skills()
 
+            # Log discovery results
+            if len(discovered_skills) == 0:
+                self.logger.info(
+                    f"No SKILL.md files found in {cache_path}. "
+                    "Ensure your skill source has SKILL.md files with valid frontmatter."
+                )
+            else:
+                self.logger.debug(
+                    f"Successfully parsed {len(discovered_skills)} skills from {cache_path}"
+                )
+
             # Build result
             result = {
                 "synced": True,
@@ -469,7 +522,7 @@ class GitSkillSourceManager:
         # Step 1: Discover all files via GitHub Tree API (single request)
         # This discovers the COMPLETE repository structure (272 files for skills)
         all_files = self._discover_repository_files_via_tree_api(
-            owner_repo, source.branch
+            owner_repo, source.branch, source
         )
 
         if not all_files:
@@ -504,7 +557,7 @@ class GitSkillSourceManager:
                 raw_url = f"https://raw.githubusercontent.com/{owner_repo}/{source.branch}/{file_path}"
                 cache_file = cache_path / file_path
                 future = executor.submit(
-                    self._download_file_with_etag, raw_url, cache_file, force
+                    self._download_file_with_etag, raw_url, cache_file, force, source
                 )
                 future_to_file[future] = file_path
 
@@ -533,7 +586,7 @@ class GitSkillSourceManager:
         return files_updated, files_cached
 
     def _discover_repository_files_via_tree_api(
-        self, owner_repo: str, branch: str
+        self, owner_repo: str, branch: str, source: Optional[SkillSource] = None
     ) -> List[str]:
         """Discover all files in repository using GitHub Git Tree API.
 
@@ -596,9 +649,17 @@ class GitSkillSourceManager:
             )
             self.logger.debug(f"Fetching commit SHA from {refs_url}")
 
-            refs_response = requests.get(
-                refs_url, headers={"Accept": "application/vnd.github+json"}, timeout=30
-            )
+            # Build headers with authentication if token available
+            headers = {"Accept": "application/vnd.github+json"}
+            token = _get_github_token(source)
+            if token:
+                headers["Authorization"] = f"token {token}"
+                if source and source.token:
+                    self.logger.debug(f"Using source-specific token for {source.id}")
+                else:
+                    self.logger.debug("Using GitHub token for authentication")
+
+            refs_response = requests.get(refs_url, headers=headers, timeout=30)
 
             # Check for rate limiting
             if refs_response.status_code == 403:
@@ -621,7 +682,7 @@ class GitSkillSourceManager:
             self.logger.debug(f"Fetching recursive tree from {tree_url}")
             tree_response = requests.get(
                 tree_url,
-                headers={"Accept": "application/vnd.github+json"},
+                headers=headers,  # Reuse headers with auth from Step 1
                 params=params,
                 timeout=30,
             )
@@ -652,7 +713,11 @@ class GitSkillSourceManager:
         return all_files
 
     def _download_file_with_etag(
-        self, url: str, local_path: Path, force: bool = False
+        self,
+        url: str,
+        local_path: Path,
+        force: bool = False,
+        source: Optional[SkillSource] = None,
     ) -> bool:
         """Download file from URL with ETag caching (thread-safe).
 
@@ -660,6 +725,7 @@ class GitSkillSourceManager:
             url: Raw GitHub URL
             local_path: Local file path to save to
             force: Force download even if cached
+            source: Optional SkillSource for token resolution
 
         Returns:
             True if file was updated, False if cached
@@ -682,7 +748,7 @@ class GitSkillSourceManager:
                 try:
                     with open(etag_cache_file, encoding="utf-8") as f:
                         etag_cache = json.load(f)
-                except Exception:
+                except Exception:  # nosec B110 - intentional: proceed without cache on read failure
                     pass
 
             cached_etag = etag_cache.get(str(local_path))
@@ -692,6 +758,11 @@ class GitSkillSourceManager:
         if cached_etag and not force:
             headers["If-None-Match"] = cached_etag
 
+        # Add GitHub authentication if token available
+        token = _get_github_token(source)
+        if token:
+            headers["Authorization"] = f"token {token}"
+
         try:
             response = requests.get(url, headers=headers, timeout=30)
 
@@ -1095,7 +1166,11 @@ class GitSkillSourceManager:
             if removed_skills:
                 self.logger.info(
                     f"Removed {len(removed_skills)} orphaned skills not referenced by agents: {removed_skills[:10]}"
-                    + (f" (and {len(removed_skills) - 10} more)" if len(removed_skills) > 10 else "")
+                    + (
+                        f" (and {len(removed_skills) - 10} more)"
+                        if len(removed_skills) > 10
+                        else ""
+                    )
                 )
 
         self.logger.info(
@@ -1159,6 +1234,10 @@ class GitSkillSourceManager:
     ) -> List[str]:
         """Remove skills from target directory that aren't in the filtered skill list.
 
+        CRITICAL: Only removes MPM-managed skills (those in our cache). Custom user skills
+        are preserved. This prevents accidental deletion of user-created skills that were
+        never part of MPM's skill repository.
+
         Uses fuzzy matching to handle both exact deployment names and short skill names.
         For example:
         - "toolchains-python-frameworks-flask" (deployed dir) matches "flask" (filter)
@@ -1209,6 +1288,40 @@ class GitSkillSourceManager:
 
             return False
 
+        def is_mpm_managed_skill(skill_dir_name: str) -> bool:
+            """Check if skill is managed by MPM (exists in our cache).
+
+            Custom user skills (not in cache) are NEVER deleted, even if not in filter.
+            Only MPM-managed skills (in cache but not in filter) are candidates for removal.
+
+            Args:
+                skill_dir_name: Name of deployed skill directory
+
+            Returns:
+                True if skill exists in MPM cache (MPM-managed), False if custom user skill
+            """
+            # Check all configured skill sources for this skill
+            for source in self.config.get_enabled_sources():
+                cache_path = self._get_source_cache_path(source)
+                if not cache_path.exists():
+                    continue
+
+                # Check if this skill directory exists anywhere in the cache
+                # Use glob to find matching directories recursively
+                matches = list(cache_path.rglob(f"*{skill_dir_name}*"))
+                if matches:
+                    # Found in cache - this is MPM-managed
+                    self.logger.debug(
+                        f"Skill '{skill_dir_name}' found in cache at {matches[0]} - MPM-managed"
+                    )
+                    return True
+
+            # Not found in any cache - this is a custom user skill
+            self.logger.debug(
+                f"Skill '{skill_dir_name}' not found in cache - custom user skill, preserving"
+            )
+            return False
+
         # Check each directory in target_dir
         if not target_dir.exists():
             return removed_skills
@@ -1225,6 +1338,15 @@ class GitSkillSourceManager:
 
                 # Check if this skill directory should be kept (fuzzy matching)
                 if not should_keep_skill(item.name):
+                    # CRITICAL: Check if this is an MPM-managed skill before deletion
+                    if not is_mpm_managed_skill(item.name):
+                        # This is a custom user skill - NEVER delete
+                        self.logger.debug(
+                            f"Preserving custom user skill (not in MPM cache): {item.name}"
+                        )
+                        continue
+
+                    # It's MPM-managed but not in filter - safe to remove
                     try:
                         # Security: Validate path is within target_dir
                         if not self._validate_safe_path(target_dir, item):
@@ -1240,7 +1362,9 @@ class GitSkillSourceManager:
                             shutil.rmtree(item)
 
                         removed_skills.append(item.name)
-                        self.logger.info(f"Removed orphaned skill: {item.name}")
+                        self.logger.info(
+                            f"Removed orphaned MPM-managed skill: {item.name}"
+                        )
 
                     except Exception as e:
                         self.logger.warning(

claude_mpm/services/skills/selective_skill_deployer.py

@@ -44,13 +44,28 @@ from typing import Any, Dict, List, Set, Tuple
 import yaml
 
 from claude_mpm.core.logging_config import get_logger
-from claude_mpm.services.skills.skill_to_agent_mapper import SkillToAgentMapper
 
 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
@@ -60,26 +75,20 @@ CORE_SKILLS = {
     "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",
@@ -87,17 +96,14 @@ CORE_SKILLS = {
     "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",
@@ -224,18 +230,90 @@ def get_skills_from_mapping(agent_ids: List[str]) -> Set[str]:
     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 ONLY uses frontmatter-declared skills.
+    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 in frontmatter or it gets zero skills deployed.
+    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
+    - 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/)
@@ -254,40 +332,78 @@ def get_required_skills_from_agents(agents_dir: Path) -> Set[str]:
 
     # Scan all agent markdown files
     agent_files = list(agents_dir.glob("*.md"))
-    logger.debug(f"Scanning {len(agent_files)} agent files in {agents_dir}")
 
-    # ONLY use frontmatter skills - no more mapping inference
+    # 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_skills = get_skills_from_agent(frontmatter)
+        agent_fm_skills = get_skills_from_agent(frontmatter)
 
-        if agent_skills:
-            frontmatter_skills.update(agent_skills)
+        if agent_fm_skills:
+            frontmatter_skills.update(agent_fm_skills)
             logger.debug(
-                f"Agent {agent_id}: {len(agent_skills)} skills from frontmatter"
+                f"Agent {agent_id}: {len(agent_fm_skills)} skills from frontmatter"
             )
-        else:
-            logger.debug(f"Agent {agent_id}: No skills declared in 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(frontmatter_skills)} unique skills from agent frontmatter "
-        f"(static mapping no longer used)"
+        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 frontmatter_skills}
+    normalized_skills = {skill.replace("/", "-") for skill in all_skills}
 
-    if normalized_skills != frontmatter_skills:
+    if normalized_skills != all_skills:
         logger.debug(
-            f"Normalized {len(frontmatter_skills)} skills to {len(normalized_skills)} "
+            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
 
 

claude_mpm/services/skills/skill_discovery_service.py

@@ -163,10 +163,22 @@ class SkillDiscoveryService:
         skill_md_files = list(self.skills_dir.rglob("SKILL.md"))
 
         # Also find legacy *.md files in top-level directory for backward compatibility
+        # Exclude common non-skill documentation files
+        excluded_filenames = {
+            "skill.md",  # Case variations of SKILL.md
+            "readme.md",
+            "claude.md",
+            "contributing.md",
+            "changelog.md",
+            "license.md",
+            "authors.md",
+            "code_of_conduct.md",
+        }
+
         legacy_md_files = [
             f
             for f in self.skills_dir.glob("*.md")
-            if f.name != "SKILL.md" and f.name.lower() != "readme.md"
+            if f.name.lower() not in excluded_filenames
         ]
 
         all_skill_files = skill_md_files + legacy_md_files
@@ -176,6 +188,15 @@ class SkillDiscoveryService:
             f"and {len(legacy_md_files)} legacy .md files in {self.skills_dir}"
         )
 
+        # Log first few file paths for debugging
+        if all_skill_files:
+            sample_files = [
+                str(f.relative_to(self.skills_dir)) for f in all_skill_files[:5]
+            ]
+            self.logger.debug(f"Sample skill files: {sample_files}")
+        else:
+            self.logger.debug(f"No SKILL.md or .md files found in {self.skills_dir}")
+
         # Track deployment names to detect collisions
         deployment_names = {}
 
@@ -214,7 +235,14 @@ class SkillDiscoveryService:
             except Exception as e:
                 self.logger.warning(f"Failed to parse skill {skill_file}: {e}")
 
-        self.logger.info(f"Discovered {len(skills)} skills from {self.skills_dir.name}")
+        # Summary logging
+        parsed_count = len(skills)
+        failed_count = len(all_skill_files) - parsed_count
+        self.logger.info(
+            f"Discovered {parsed_count} skills from {self.skills_dir.name} "
+            f"({len(all_skill_files)} files found, {failed_count} failed to parse)"
+        )
+
         return skills
 
     def _parse_skill_file(self, skill_file: Path) -> Optional[Dict[str, Any]]:
@@ -255,7 +283,35 @@ class SkillDiscoveryService:
         try:
             frontmatter, body = self._extract_frontmatter(content)
         except Exception as e:
-            self.logger.warning(f"No valid frontmatter in {skill_file.name}: {e}")
+            # Only log as debug for documentation files to reduce noise
+            # Common documentation files (CLAUDE.md, README.md) are expected to lack skill frontmatter
+            relative_path = (
+                skill_file.relative_to(self.skills_dir)
+                if skill_file.is_relative_to(self.skills_dir)
+                else skill_file
+            )
+
+            # Check if this looks like a documentation file
+            is_documentation = any(
+                doc_pattern in skill_file.name.lower()
+                for doc_pattern in [
+                    "readme",
+                    "claude",
+                    "contributing",
+                    "changelog",
+                    "license",
+                ]
+            )
+
+            if is_documentation:
+                self.logger.debug(
+                    f"Skipping documentation file {relative_path} (no skill frontmatter): {e}"
+                )
+            else:
+                # For actual skill files with invalid YAML, use warning level
+                self.logger.warning(
+                    f"Failed to parse skill frontmatter in {relative_path}: {e}"
+                )
             return None
 
         # Validate required fields
@@ -354,10 +410,24 @@ class SkillDiscoveryService:
         frontmatter_text = match.group(1)
         body = match.group(2)
 
-        # Parse YAML
+        # Parse YAML with improved error handling
         try:
             frontmatter = yaml.safe_load(frontmatter_text)
         except yaml.YAMLError as e:
+            # Provide more specific error message with context
+            error_line = getattr(e, "problem_mark", None)
+            if error_line:
+                line_num = error_line.line + 1
+                col_num = error_line.column + 1
+                # Extract problematic line for context
+                lines = frontmatter_text.split("\n")
+                problem_line = (
+                    lines[error_line.line] if error_line.line < len(lines) else ""
+                )
+                raise ValueError(
+                    f"Invalid YAML in frontmatter at line {line_num}, column {col_num}: {e.problem}\n"
+                    f"  Problematic line: {problem_line.strip()}"
+                ) from e
             raise ValueError(f"Invalid YAML in frontmatter: {e}") from e
 
         if not isinstance(frontmatter, dict):