openhands-sdk 1.7.4__py3-none-any.whl → 1.8.0__py3-none-any.whl

openhands/sdk/context/skills/skill.py

@@ -1,20 +1,31 @@
 import io
 import re
-import shutil
-import subprocess
 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
 from pydantic import BaseModel, Field, field_validator, model_validator
 
-from openhands.sdk.context.skills.exceptions import SkillValidationError
+from openhands.sdk.context.skills.exceptions import SkillError, SkillValidationError
 from openhands.sdk.context.skills.trigger import (
     KeywordTrigger,
     TaskTrigger,
 )
 from openhands.sdk.context.skills.types import InputMetadata
+from openhands.sdk.context.skills.utils import (
+    discover_skill_resources,
+    find_mcp_config,
+    find_regular_md_files,
+    find_skill_md_directories,
+    find_third_party_files,
+    get_skills_cache_dir,
+    load_and_categorize,
+    load_mcp_config,
+    update_skills_repository,
+    validate_skill_name,
+)
 from openhands.sdk.logger import get_logger
 from openhands.sdk.utils import maybe_truncate
 
@@ -25,12 +36,48 @@ logger = get_logger(__name__)
 # These files are always active, so we want to keep them reasonably sized
 THIRD_PARTY_SKILL_MAX_CHARS = 10_000
 
-# Regex pattern for valid AgentSkills names
-# - 1-64 characters
-# - Lowercase alphanumeric + hyphens only (a-z, 0-9, -)
-# - Must not start or end with hyphen
-# - Must not contain consecutive hyphens (--)
-SKILL_NAME_PATTERN = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+class SkillResources(BaseModel):
+    """Resource directories for a skill (AgentSkills standard).
+
+    Per the AgentSkills specification, skills can include:
+    - scripts/: Executable scripts the agent can run
+    - references/: Reference documentation and examples
+    - assets/: Static assets (images, data files, etc.)
+    """
+
+    skill_root: str = Field(description="Root directory of the skill (absolute path)")
+    scripts: list[str] = Field(
+        default_factory=list,
+        description="List of script files in scripts/ directory (relative paths)",
+    )
+    references: list[str] = Field(
+        default_factory=list,
+        description="List of reference files in references/ directory (relative paths)",
+    )
+    assets: list[str] = Field(
+        default_factory=list,
+        description="List of asset files in assets/ directory (relative paths)",
+    )
+
+    def has_resources(self) -> bool:
+        """Check if any resources are available."""
+        return bool(self.scripts or self.references or self.assets)
+
+    def get_scripts_dir(self) -> Path | None:
+        """Get the scripts directory path if it exists."""
+        scripts_dir = Path(self.skill_root) / "scripts"
+        return scripts_dir if scripts_dir.is_dir() else None
+
+    def get_references_dir(self) -> Path | None:
+        """Get the references directory path if it exists."""
+        refs_dir = Path(self.skill_root) / "references"
+        return refs_dir if refs_dir.is_dir() else None
+
+    def get_assets_dir(self) -> Path | None:
+        """Get the assets directory path if it exists."""
+        assets_dir = Path(self.skill_root) / "assets"
+        return assets_dir if assets_dir.is_dir() else None
 
 
 # Union type for all trigger types
@@ -43,10 +90,16 @@ TriggerType = Annotated[
 class Skill(BaseModel):
     """A skill provides specialized knowledge or functionality.
 
-    Skills use triggers to determine when they should be activated:
-    - None: Always active, for repository-specific guidelines
-    - KeywordTrigger: Activated when keywords appear in user messages
-    - TaskTrigger: Activated for specific tasks, may require user input
+    Skill behavior depends on format (is_agentskills_format) and trigger:
+
+    AgentSkills format (SKILL.md files):
+    - Always listed in <available_skills> with name, description, location
+    - Agent reads full content on demand (progressive disclosure)
+    - If has triggers: content is ALSO auto-injected when triggered
+
+    Legacy OpenHands format:
+    - With triggers: Listed in <available_skills>, content injected on trigger
+    - Without triggers (None): Full content in <REPO_CONTEXT>, always active
 
     This model supports both OpenHands-specific fields and AgentSkills standard
     fields (https://agentskills.io/specification) for cross-platform compatibility.
@@ -57,11 +110,11 @@ class Skill(BaseModel):
     trigger: TriggerType | None = Field(
         default=None,
         description=(
-            "Skills use triggers to determine when they should be activated. "
-            "None implies skill is always active. "
-            "Other implementations include KeywordTrigger (activated by a "
-            "keyword in a Message) and TaskTrigger (activated by specific tasks "
-            "and may require user input)"
+            "Trigger determines when skill content is auto-injected. "
+            "None = no auto-injection (for AgentSkills: agent reads on demand; "
+            "for legacy: full content always in system prompt). "
+            "KeywordTrigger = auto-inject when keywords appear in user messages. "
+            "TaskTrigger = auto-inject for specific tasks, may require user input."
         ),
     )
     source: str | None = Field(
@@ -83,6 +136,16 @@ class Skill(BaseModel):
         default_factory=list,
         description="Input metadata for the skill (task skills only)",
     )
+    is_agentskills_format: bool = Field(
+        default=False,
+        description=(
+            "Whether this skill was loaded from a SKILL.md file following the "
+            "AgentSkills standard. AgentSkills-format skills use progressive "
+            "disclosure: always listed in <available_skills> with name, "
+            "description, and location. If the skill also has triggers, content "
+            "is auto-injected when triggered AND agent can read file anytime."
+        ),
+    )
 
     # AgentSkills standard fields (https://agentskills.io/specification)
     description: str | None = Field(
@@ -120,6 +183,23 @@ class Skill(BaseModel):
             "AgentSkills standard field (parsed from space-delimited string)."
         ),
     )
+    resources: SkillResources | None = Field(
+        default=None,
+        description=(
+            "Resource directories for the skill (scripts/, references/, assets/). "
+            "AgentSkills standard field. Only populated for SKILL.md directory format."
+        ),
+    )
+
+    @field_validator("description")
+    @classmethod
+    def _validate_description_length(cls, v: str | None) -> str | None:
+        """Validate description length per AgentSkills spec (max 1024 chars)."""
+        if v is not None and len(v) > 1024:
+            raise SkillValidationError(
+                f"Description exceeds 1024 characters ({len(v)} chars)"
+            )
+        return v
 
     @field_validator("allowed_tools", mode="before")
     @classmethod
@@ -169,6 +249,7 @@ class Skill(BaseModel):
         cls,
         path: str | Path,
         skill_base_dir: Path | None = None,
+        strict: bool = True,
     ) -> "Skill":
         """Load a skill from a markdown file with frontmatter.
 
@@ -181,6 +262,8 @@ class Skill(BaseModel):
         Args:
             path: Path to the skill file.
             skill_base_dir: Base directory for skills (used to derive relative names).
+            strict: If True, enforce strict AgentSkills name validation.
+                If False, allow relaxed naming (e.g., for plugin compatibility).
         """
         path = Path(path) if isinstance(path, str) else path
 
@@ -188,20 +271,24 @@ class Skill(BaseModel):
             file_content = f.read()
 
         if path.name.lower() == "skill.md":
-            return cls._load_agentskills_skill(path, file_content)
+            return cls._load_agentskills_skill(path, file_content, strict=strict)
         else:
             return cls._load_legacy_openhands_skill(path, file_content, skill_base_dir)
 
     @classmethod
-    def _load_agentskills_skill(cls, path: Path, file_content: str) -> "Skill":
+    def _load_agentskills_skill(
+        cls, path: Path, file_content: str, strict: bool = True
+    ) -> "Skill":
         """Load a skill from an AgentSkills-format SKILL.md file.
 
         Args:
             path: Path to the SKILL.md file.
             file_content: Content of the file.
+            strict: If True, enforce strict AgentSkills name validation.
         """
         # For SKILL.md files, use parent directory name as the skill name
         directory_name = path.parent.name
+        skill_root = path.parent
 
         file_io = io.StringIO(file_content)
         loaded = frontmatter.load(file_io)
@@ -211,14 +298,35 @@ class Skill(BaseModel):
         # Use name from frontmatter if provided, otherwise use directory name
         agent_name = str(metadata_dict.get("name", directory_name))
 
-        # Validate skill name
-        name_errors = _validate_skill_name(agent_name, directory_name)
-        if name_errors:
-            raise SkillValidationError(
-                f"Invalid skill name '{agent_name}': {'; '.join(name_errors)}"
-            )
+        # Validate skill name (only in strict mode)
+        if strict:
+            name_errors = validate_skill_name(agent_name, directory_name)
+            if name_errors:
+                raise SkillValidationError(
+                    f"Invalid skill name '{agent_name}': {'; '.join(name_errors)}"
+                )
 
-        return cls._create_skill_from_metadata(agent_name, content, path, metadata_dict)
+        # Load MCP configuration from .mcp.json (agent_skills ONLY use .mcp.json)
+        mcp_tools: dict | None = None
+        mcp_json_path = find_mcp_config(skill_root)
+        if mcp_json_path:
+            mcp_tools = load_mcp_config(mcp_json_path, skill_root)
+
+        # Discover resource directories
+        resources: SkillResources | None = None
+        discovered_resources = discover_skill_resources(skill_root)
+        if discovered_resources.has_resources():
+            resources = discovered_resources
+
+        return cls._create_skill_from_metadata(
+            agent_name,
+            content,
+            path,
+            metadata_dict,
+            mcp_tools,
+            resources=resources,
+            is_agentskills_format=True,
+        )
 
     @classmethod
     def _load_legacy_openhands_skill(
@@ -252,11 +360,25 @@ class Skill(BaseModel):
         # Use name from frontmatter if provided, otherwise use derived name
         agent_name = str(metadata_dict.get("name", skill_name))
 
-        return cls._create_skill_from_metadata(agent_name, content, path, metadata_dict)
+        # Legacy skills ONLY use mcp_tools from frontmatter (not .mcp.json)
+        mcp_tools = metadata_dict.get("mcp_tools")
+        if mcp_tools is not None and not isinstance(mcp_tools, dict):
+            raise SkillValidationError("mcp_tools must be a dictionary or None")
+
+        return cls._create_skill_from_metadata(
+            agent_name, content, path, metadata_dict, mcp_tools
+        )
 
     @classmethod
     def _create_skill_from_metadata(
-        cls, agent_name: str, content: str, path: Path, metadata_dict: dict
+        cls,
+        agent_name: str,
+        content: str,
+        path: Path,
+        metadata_dict: dict,
+        mcp_tools: dict | None = None,
+        resources: SkillResources | None = None,
+        is_agentskills_format: bool = False,
     ) -> "Skill":
         """Create a Skill object from parsed metadata.
 
@@ -265,6 +387,9 @@ class Skill(BaseModel):
             content: The markdown content (without frontmatter).
             path: Path to the skill file.
             metadata_dict: Parsed frontmatter metadata.
+            mcp_tools: MCP tools configuration (from .mcp.json or frontmatter).
+            resources: Discovered resource directories.
+            is_agentskills_format: Whether this skill follows the AgentSkills standard.
         """
         # Extract AgentSkills standard fields (Pydantic validators handle
         # transformation). Handle "allowed-tools" to "allowed_tools" key mapping.
@@ -309,6 +434,9 @@ class Skill(BaseModel):
                 source=str(path),
                 trigger=TaskTrigger(triggers=keywords),
                 inputs=inputs,
+                mcp_tools=mcp_tools,
+                resources=resources,
+                is_agentskills_format=is_agentskills_format,
                 **agentskills_fields,
             )
 
@@ -318,19 +446,21 @@ class Skill(BaseModel):
                 content=content,
                 source=str(path),
                 trigger=KeywordTrigger(keywords=keywords),
+                mcp_tools=mcp_tools,
+                resources=resources,
+                is_agentskills_format=is_agentskills_format,
                 **agentskills_fields,
             )
         else:
             # No triggers, default to None (always active)
-            mcp_tools = metadata_dict.get("mcp_tools")
-            if mcp_tools is not None and not isinstance(mcp_tools, dict):
-                raise SkillValidationError("mcp_tools must be a dictionary or None")
             return Skill(
                 name=agent_name,
                 content=content,
                 source=str(path),
                 trigger=None,
                 mcp_tools=mcp_tools,
+                resources=resources,
+                is_agentskills_format=is_agentskills_format,
                 **agentskills_fields,
             )
 
@@ -431,162 +561,6 @@ class Skill(BaseModel):
         return len(variables) > 0
 
 
-def _find_skill_md(skill_dir: Path) -> Path | None:
-    """Find SKILL.md file in a directory (case-insensitive).
-
-    Args:
-        skill_dir: Path to the skill directory to search.
-
-    Returns:
-        Path to SKILL.md if found, None otherwise.
-    """
-    if not skill_dir.is_dir():
-        return None
-    for item in skill_dir.iterdir():
-        if item.is_file() and item.name.lower() == "skill.md":
-            return item
-    return None
-
-
-def _validate_skill_name(name: str, directory_name: str | None = None) -> list[str]:
-    """Validate skill name according to AgentSkills spec.
-
-    Args:
-        name: The skill name to validate.
-        directory_name: Optional directory name to check for match.
-
-    Returns:
-        List of validation error messages (empty if valid).
-    """
-    errors = []
-
-    if not name:
-        errors.append("Name cannot be empty")
-        return errors
-
-    if len(name) > 64:
-        errors.append(f"Name exceeds 64 characters: {len(name)}")
-
-    if not SKILL_NAME_PATTERN.match(name):
-        errors.append(
-            "Name must be lowercase alphanumeric with single hyphens "
-            "(e.g., 'my-skill', 'pdf-tools')"
-        )
-
-    if directory_name and name != directory_name:
-        errors.append(f"Name '{name}' does not match directory '{directory_name}'")
-
-    return errors
-
-
-def _find_third_party_files(repo_root: Path) -> list[Path]:
-    """Find third-party skill files in the repository root.
-
-    Searches for files like .cursorrules, AGENTS.md, CLAUDE.md, etc.
-    with case-insensitive matching.
-
-    Args:
-        repo_root: Path to the repository root directory.
-
-    Returns:
-        List of paths to third-party skill files found.
-    """
-    if not repo_root.exists():
-        return []
-
-    # Build a set of target filenames (lowercase) for case-insensitive matching
-    target_names = {name.lower() for name in Skill.PATH_TO_THIRD_PARTY_SKILL_NAME}
-
-    files: list[Path] = []
-    seen_names: set[str] = set()
-    for item in repo_root.iterdir():
-        if item.is_file() and item.name.lower() in target_names:
-            # Avoid duplicates (e.g., AGENTS.md and agents.md in same dir)
-            name_lower = item.name.lower()
-            if name_lower in seen_names:
-                logger.warning(
-                    f"Duplicate third-party skill file ignored: {item} "
-                    f"(already found a file with name '{name_lower}')"
-                )
-            else:
-                files.append(item)
-                seen_names.add(name_lower)
-    return files
-
-
-def _find_skill_md_directories(skill_dir: Path) -> list[Path]:
-    """Find AgentSkills-style directories containing SKILL.md files.
-
-    Args:
-        skill_dir: Path to the skills directory.
-
-    Returns:
-        List of paths to SKILL.md files.
-    """
-    results: list[Path] = []
-    if not skill_dir.exists():
-        return results
-    for subdir in skill_dir.iterdir():
-        if subdir.is_dir():
-            skill_md = _find_skill_md(subdir)
-            if skill_md:
-                results.append(skill_md)
-    return results
-
-
-def _find_regular_md_files(skill_dir: Path, exclude_dirs: set[Path]) -> list[Path]:
-    """Find regular .md skill files, excluding SKILL.md and files in excluded dirs.
-
-    Args:
-        skill_dir: Path to the skills directory.
-        exclude_dirs: Set of directories to exclude (e.g., SKILL.md directories).
-
-    Returns:
-        List of paths to regular .md skill files.
-    """
-    files: list[Path] = []
-    if not skill_dir.exists():
-        return files
-    for f in skill_dir.rglob("*.md"):
-        is_readme = f.name == "README.md"
-        is_skill_md = f.name.lower() == "skill.md"
-        is_in_excluded_dir = any(f.is_relative_to(d) for d in exclude_dirs)
-        if not is_readme and not is_skill_md and not is_in_excluded_dir:
-            files.append(f)
-    return files
-
-
-def _load_and_categorize(
-    path: Path,
-    skill_base_dir: Path,
-    repo_skills: dict[str, Skill],
-    knowledge_skills: dict[str, Skill],
-    agent_skills: dict[str, Skill],
-) -> None:
-    """Load a skill and categorize it.
-
-    Categorizes into repo_skills, knowledge_skills, or agent_skills.
-
-    Args:
-        path: Path to the skill file.
-        skill_base_dir: Base directory for skills (used to derive relative names).
-        repo_skills: Dictionary for skills with trigger=None (permanent context).
-        knowledge_skills: Dictionary for skills with triggers (progressive).
-        agent_skills: Dictionary for AgentSkills standard SKILL.md files.
-    """
-    skill = Skill.load(path, skill_base_dir)
-
-    # AgentSkills (SKILL.md directories) are a separate category from OpenHands skills.
-    # They follow the AgentSkills standard and should be handled differently.
-    is_skill_md = path.name.lower() == "skill.md"
-    if is_skill_md:
-        agent_skills[skill.name] = skill
-    elif skill.trigger is None:
-        repo_skills[skill.name] = skill
-    else:
-        knowledge_skills[skill.name] = skill
-
-
 def load_skills_from_dir(
     skill_dir: str | Path,
 ) -> tuple[dict[str, Skill], dict[str, Skill], dict[str, Skill]]:
@@ -615,28 +589,23 @@ def load_skills_from_dir(
     agent_skills: dict[str, Skill] = {}
     logger.debug(f"Loading agents from {skill_dir}")
 
-    # Discover all skill files
-    repo_root = skill_dir.parent.parent
-    third_party_files = _find_third_party_files(repo_root)
-    skill_md_files = _find_skill_md_directories(skill_dir)
+    # Discover skill files in the skills directory
+    # Note: Third-party files (AGENTS.md, etc.) are loaded separately by
+    # load_project_skills() to ensure they're loaded even when this directory
+    # doesn't exist.
+    skill_md_files = find_skill_md_directories(skill_dir)
     skill_md_dirs = {skill_md.parent for skill_md in skill_md_files}
-    regular_md_files = _find_regular_md_files(skill_dir, skill_md_dirs)
-
-    # Load third-party files
-    for path in third_party_files:
-        _load_and_categorize(
-            path, skill_dir, repo_skills, knowledge_skills, agent_skills
-        )
+    regular_md_files = find_regular_md_files(skill_dir, skill_md_dirs)
 
     # Load SKILL.md files (auto-detected and validated in Skill.load)
     for skill_md_path in skill_md_files:
-        _load_and_categorize(
+        load_and_categorize(
             skill_md_path, skill_dir, repo_skills, knowledge_skills, agent_skills
         )
 
     # Load regular .md files
     for path in regular_md_files:
-        _load_and_categorize(
+        load_and_categorize(
             path, skill_dir, repo_skills, knowledge_skills, agent_skills
         )
 
@@ -710,6 +679,9 @@ def load_project_skills(work_dir: str | Path) -> list[Skill]:
     directories are merged, with skills/ taking precedence for
     duplicate names.
 
+    Also loads third-party skill files (AGENTS.md, .cursorrules, etc.)
+    directly from the work directory.
+
     Args:
         work_dir: Path to the project/working directory.
 
@@ -721,7 +693,22 @@ def load_project_skills(work_dir: str | Path) -> list[Skill]:
         work_dir = Path(work_dir)
 
     all_skills = []
-    seen_names = set()
+    seen_names: set[str] = set()
+
+    # First, load third-party skill files directly from work directory
+    # This ensures they are loaded even if .openhands/skills doesn't exist
+    third_party_files = find_third_party_files(
+        work_dir, Skill.PATH_TO_THIRD_PARTY_SKILL_NAME
+    )
+    for path in third_party_files:
+        try:
+            skill = Skill.load(path)
+            if skill.name not in seen_names:
+                all_skills.append(skill)
+                seen_names.add(skill.name)
+                logger.debug(f"Loaded third-party skill: {skill.name} from {path}")
+        except (SkillError, OSError) as e:
+            logger.warning(f"Failed to load third-party skill from {path}: {e}")
 
     # Load project-specific skills from .openhands/skills and legacy microagents
     project_skills_dirs = [
@@ -742,7 +729,7 @@ def load_project_skills(work_dir: str | Path) -> list[Skill]:
                 project_skills_dir
             )
 
-            # Merge all skill categories
+            # Merge all skill categories (skip duplicates including third-party)
             for skills_dict in [repo_skills, knowledge_skills, agent_skills]:
                 for name, skill in skills_dict.items():
                     if name not in seen_names:
@@ -770,97 +757,6 @@ PUBLIC_SKILLS_REPO = "https://github.com/OpenHands/skills"
 PUBLIC_SKILLS_BRANCH = "main"
 
 
-def _get_skills_cache_dir() -> Path:
-    """Get the local cache directory for public skills repository.
-
-    Returns:
-        Path to the skills cache directory (~/.openhands/cache/skills).
-    """
-    cache_dir = Path.home() / ".openhands" / "cache" / "skills"
-    cache_dir.mkdir(parents=True, exist_ok=True)
-    return cache_dir
-
-
-def _update_skills_repository(
-    repo_url: str,
-    branch: str,
-    cache_dir: Path,
-) -> Path | None:
-    """Clone or update the local skills repository.
-
-    Args:
-        repo_url: URL of the skills repository.
-        branch: Branch name to use.
-        cache_dir: Directory where the repository should be cached.
-
-    Returns:
-        Path to the local repository if successful, None otherwise.
-    """
-    repo_path = cache_dir / "public-skills"
-
-    try:
-        if repo_path.exists() and (repo_path / ".git").exists():
-            logger.debug(f"Updating skills repository at {repo_path}")
-            try:
-                subprocess.run(
-                    ["git", "fetch", "origin"],
-                    cwd=repo_path,
-                    check=True,
-                    capture_output=True,
-                    timeout=30,
-                )
-                subprocess.run(
-                    ["git", "reset", "--hard", f"origin/{branch}"],
-                    cwd=repo_path,
-                    check=True,
-                    capture_output=True,
-                    timeout=10,
-                )
-                logger.debug("Skills repository updated successfully")
-            except subprocess.TimeoutExpired:
-                logger.warning("Git pull timed out, using existing cached repository")
-            except subprocess.CalledProcessError as e:
-                logger.warning(
-                    f"Failed to update repository: {e.stderr.decode()}, "
-                    f"using existing cached version"
-                )
-        else:
-            logger.info(f"Cloning public skills repository from {repo_url}")
-            if repo_path.exists():
-                shutil.rmtree(repo_path)
-
-            subprocess.run(
-                [
-                    "git",
-                    "clone",
-                    "--depth",
-                    "1",
-                    "--branch",
-                    branch,
-                    repo_url,
-                    str(repo_path),
-                ],
-                check=True,
-                capture_output=True,
-                timeout=60,
-            )
-            logger.debug(f"Skills repository cloned to {repo_path}")
-
-        return repo_path
-
-    except subprocess.TimeoutExpired:
-        logger.warning(f"Git operation timed out for {repo_url}")
-        return None
-    except subprocess.CalledProcessError as e:
-        logger.warning(
-            f"Failed to clone/update repository {repo_url}: {e.stderr.decode()}"
-        )
-        return None
-    except Exception as e:
-        logger.warning(f"Error managing skills repository: {str(e)}")
-        return None
-
-
 def load_public_skills(
     repo_url: str = PUBLIC_SKILLS_REPO,
     branch: str = PUBLIC_SKILLS_BRANCH,
@@ -896,8 +792,8 @@ def load_public_skills(
 
     try:
         # Get or update the local repository
-        cache_dir = _get_skills_cache_dir()
-        repo_path = _update_skills_repository(repo_url, branch, cache_dir)
+        cache_dir = get_skills_cache_dir()
+        repo_path = update_skills_repository(repo_url, branch, cache_dir)
 
         if repo_path is None:
             logger.warning("Failed to access public skills repository")
@@ -936,3 +832,86 @@ 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 from skills-ref.
+
+    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 with name, description, and location
+
+    Example:
+        >>> skills = [Skill(name="pdf-tools", content="...",
+        ...                 description="Extract text from PDF files.",
+        ...                 source="/path/to/skill")]
+        >>> print(to_prompt(skills))
+        <available_skills>
+          <skill>
+            <name>pdf-tools</name>
+            <description>Extract text from PDF files.</description>
+            <location>/path/to/skill</location>
+          </skill>
+        </available_skills>
+    """
+    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
+        description = xml_escape(description.strip())
+        name = xml_escape(skill.name.strip())
+
+        # Build skill element following AgentSkills format from skills-ref
+        lines.append("  <skill>")
+        lines.append(f"    <name>{name}</name>")
+        lines.append(f"    <description>{description}</description>")
+        if skill.source:
+            source = xml_escape(skill.source.strip())
+            lines.append(f"    <location>{source}</location>")
+        lines.append("  </skill>")
+
+    lines.append("</available_skills>")
+    return "\n".join(lines)