feat: add to_prompt() for XML skill prompt generation

openhands-sdk/openhands/sdk/context/skills/__init__.py

@@ -6,6 +6,7 @@
     load_public_skills,
     load_skills_from_dir,
     load_user_skills,
+    to_prompt,
 )
 from openhands.sdk.context.skills.trigger import (
     BaseTrigger,
@@ -33,4 +34,5 @@
     "SkillValidationError",
     "discover_skill_resources",
     "RESOURCE_DIRECTORIES",
+    "to_prompt",
 ]

openhands-sdk/openhands/sdk/context/skills/skill.py

@@ -2,6 +2,7 @@
 import re
 from pathlib import Path
 from typing import Annotated, ClassVar, Union
+from xml.sax.saxutils import escape as xml_escape
 
 import frontmatter
 from fastmcp.mcp_config import MCPConfig
@@ -776,3 +777,72 @@ def load_public_skills(
         f"Loaded {len(all_skills)} public skills: {[s.name for s in all_skills]}"
     )
     return all_skills
+
+
+def to_prompt(skills: list[Skill], max_description_length: int = 200) -> str:
+    """Generate XML prompt block for available skills.
+
+    Creates an `<available_skills>` XML block suitable for inclusion
+    in system prompts, following the AgentSkills format.
+
+    Args:
+        skills: List of skills to include in the prompt
+        max_description_length: Maximum length for descriptions (default 200)
+
+    Returns:
+        XML string in AgentSkills format
+
+    Example:
+        >>> skills = [Skill(name="pdf-tools", content="...", description="...")]
+        >>> print(to_prompt(skills))
+        <available_skills>
+          <skill name="pdf-tools">Extract text from PDF files.</skill>
+        </available_skills>
+    """  # noqa: E501
+    if not skills:
+        return "<available_skills>\n  no available skills\n</available_skills>"
+
+    lines = ["<available_skills>"]
+    for skill in skills:
+        # Use description if available, otherwise use first line of content
+        description = skill.description
+        content_truncated = 0
+        if not description:
+            # Extract first non-empty, non-header line from content as fallback
+            # Track position to calculate truncated content after the description
+            chars_before_desc = 0
+            for line in skill.content.split("\n"):
+                stripped = line.strip()
+                # Skip markdown headers and empty lines
+                if not stripped or stripped.startswith("#"):
+                    chars_before_desc += len(line) + 1  # +1 for newline
+                    continue
+                description = stripped
+                # Calculate remaining content after this line as truncated
+                desc_end_pos = chars_before_desc + len(line)
+                content_truncated = max(0, len(skill.content) - desc_end_pos)
+                break
+        description = description or ""
+
+        # Calculate total truncated characters
+        total_truncated = content_truncated
+
+        # Truncate description if needed and add truncation indicator
+        if len(description) > max_description_length:
+            total_truncated += len(description) - max_description_length
+            description = description[:max_description_length]
+
+        if total_truncated > 0:
+            truncation_msg = f"... [{total_truncated} characters truncated"
+            if skill.source:
+                truncation_msg += f". View {skill.source} for complete information"
+            truncation_msg += "]"
+            description = description + truncation_msg
+
+        # Escape XML special characters using standard library
+        xml_entities = {'"': "&quot;", "'": "&apos;"}
+        description = xml_escape(description, entities=xml_entities)
+        name = xml_escape(skill.name, entities=xml_entities)
+        lines.append(f'  <skill name="{name}">{description}</skill>')
+    lines.append("</available_skills>")
+    return "\n".join(lines)

tests/sdk/context/skill/test_validation_prompt.py

@@ -0,0 +1,90 @@
+"""Tests for prompt generation utilities (Issue #1478)."""
+
+from openhands.sdk.context.skills import (
+    Skill,
+    to_prompt,
+)
+
+
+def test_to_prompt_generates_xml() -> None:
+    """to_prompt() should generate valid XML for skills."""
+    # Empty list shows "no available skills"
+    assert (
+        to_prompt([])
+        == "<available_skills>\n  no available skills\n</available_skills>"
+    )
+
+    # Single skill with description
+    skill = Skill(name="pdf-tools", content="# PDF", description="Process PDFs.")
+    result = to_prompt([skill])
+    assert '<skill name="pdf-tools">' in result
+    assert "Process PDFs." in result
+    assert "<available_skills>" in result
+
+    # Multiple skills
+    skills = [
+        Skill(name="pdf-tools", content="# PDF", description="Process PDFs."),
+        Skill(name="code-review", content="# Code", description="Review code."),
+    ]
+    result = to_prompt(skills)
+    assert result.count("<skill") == 2
+
+
+def test_to_prompt_escapes_xml() -> None:
+    """to_prompt() should escape XML special characters."""
+    skill = Skill(
+        name="test", content="# Test", description='Handle <tags> & "quotes".'
+    )
+    result = to_prompt([skill])
+    assert "&lt;tags&gt;" in result
+    assert "&amp;" in result
+    assert "&quot;quotes&quot;" in result
+
+
+def test_to_prompt_uses_content_fallback() -> None:
+    """to_prompt() should use content when no description."""
+    skill = Skill(name="test", content="# Header\n\nActual content here.")
+    result = to_prompt([skill])
+    assert "Actual content here." in result
+    assert "# Header" not in result
+
+
+def test_to_prompt_content_fallback_counts_remaining_as_truncated() -> None:
+    """to_prompt() should count content after first line as truncated."""
+    # Content with header, description line, and additional content
+    content = "# Header\n\nFirst line used as description.\n\nMore content here."
+    skill = Skill(name="test", content=content, source="/skills/test.md")
+    result = to_prompt([skill])
+
+    # Should use first non-header line as description
+    assert "First line used as description." in result
+    # Should indicate truncation for remaining content
+    assert "characters truncated" in result
+    assert "View /skills/test.md for complete information" in result
+
+
+def test_to_prompt_truncates_long_descriptions() -> None:
+    """to_prompt() should truncate long descriptions with indicator."""
+    long_desc = "A" * 250  # 250 characters
+    skill = Skill(name="test", content="# Test", description=long_desc)
+    result = to_prompt([skill])
+
+    # Should contain truncation indicator
+    assert "... [50 characters truncated]" in result
+    # Should contain first 200 chars
+    assert "A" * 200 in result
+
+
+def test_to_prompt_truncation_includes_source() -> None:
+    """to_prompt() should include source path in truncation message."""
+    long_desc = "B" * 250
+    skill = Skill(
+        name="test",
+        content="# Test",
+        description=long_desc,
+        source="/path/to/skill.md",
+    )
+    result = to_prompt([skill])
+
+    assert "... [50 characters truncated" in result
+    assert "View /path/to/skill.md for complete information]" in result