fix: implement _format_error for structured skill error responses (#680)

tools/skill_manager_tool.py

@@ -73,6 +73,40 @@ def _security_scan_skill(skill_dir: Path) -> Optional[str]:
         logger.warning("Security scan failed for %s: %s", skill_dir, e, exc_info=True)
     return None
 
+
+def _format_error(
+    message: str,
+    skill_name: str = None,
+    file_path: str = None,
+    suggestion: str = None,
+    context: dict = None,
+) -> Dict[str, Any]:
+    """Build a structured error response with optional metadata.
+
+    Returns a dict with success=False and enriched error string that includes
+    skill name, file path, suggestion, and context details when provided.
+    """
+    parts = [message]
+    if skill_name:
+        parts.append(f"Skill: {skill_name}")
+    if file_path:
+        parts.append(f"File: {file_path}")
+    if suggestion:
+        parts.append(f"Suggestion: {suggestion}")
+    if context:
+        for key, value in context.items():
+            parts.append(f"{key}: {value}")
+
+    return {
+        "success": False,
+        "error": "\n".join(parts),
+        "skill_name": skill_name,
+        "file_path": file_path,
+        "suggestion": suggestion,
+        "context": context,
+    }
+
+
 import yaml
 
 
@@ -358,7 +392,11 @@ def _edit_skill(name: str, content: str) -> Dict[str, Any]:
 
     existing = _find_skill(name)
     if not existing:
-        return {"success": False, "error": f"Skill '{name}' not found. Use skills_list() to see available skills."}
+        return _format_error(
+            f"Skill '{name}' not found.",
+            skill_name=name,
+            suggestion="Use skills_list() to see available skills.",
+        )
 
     skill_md = existing["path"] / "SKILL.md"
     # Back up original content for rollback
@@ -392,13 +430,25 @@ def _patch_skill(
     Requires a unique match unless replace_all is True.
     """
     if not old_string:
-        return {"success": False, "error": "old_string is required for 'patch'."}
+        return _format_error(
+            "old_string is required for 'patch'.",
+            skill_name=name,
+            suggestion="Provide the exact text to find in the skill file.",
+        )
     if new_string is None:
-        return {"success": False, "error": "new_string is required for 'patch'. Use an empty string to delete matched text."}
+        return _format_error(
+            "new_string is required for 'patch'. Use an empty string to delete matched text.",
+            skill_name=name,
+            suggestion="Provide the replacement text, or '' to delete.",
+        )
 
     existing = _find_skill(name)
     if not existing:
-        return {"success": False, "error": f"Skill '{name}' not found."}
+        return _format_error(
+            f"Skill '{name}' not found.",
+            skill_name=name,
+            suggestion="Use skills_list() to see available skills.",
+        )
 
     skill_dir = existing["path"]