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

openhands/sdk/context/skills/skill.py

@@ -2,7 +2,6 @@ import io
 import re
 import shutil
 import subprocess
-from itertools import chain
 from pathlib import Path
 from typing import Annotated, ClassVar, Union
 
@@ -26,6 +25,14 @@ 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]+)*$")
+
+
 # Union type for all trigger types
 TriggerType = Annotated[
     KeywordTrigger | TaskTrigger,
@@ -136,6 +143,19 @@ class Skill(BaseModel):
             return {str(k): str(val) for k, val in v.items()}
         raise SkillValidationError("metadata must be a dictionary")
 
+    @field_validator("mcp_tools")
+    @classmethod
+    def _validate_mcp_tools(cls, v: dict | None, _info):
+        """Validate mcp_tools conforms to MCPConfig schema."""
+        if v is None:
+            return v
+        if isinstance(v, dict):
+            try:
+                MCPConfig.model_validate(v)
+            except Exception as e:
+                raise SkillValidationError(f"Invalid MCPConfig dictionary: {e}") from e
+        return v
+
     PATH_TO_THIRD_PARTY_SKILL_NAME: ClassVar[dict[str, str]] = {
         ".cursorrules": "cursorrules",
         "agents.md": "agents",
@@ -144,89 +164,108 @@ class Skill(BaseModel):
         "gemini.md": "gemini",
     }
 
-    @classmethod
-    def _handle_third_party(cls, path: Path, file_content: str) -> Union["Skill", None]:
-        # Determine the agent name based on file type
-        skill_name = cls.PATH_TO_THIRD_PARTY_SKILL_NAME.get(path.name.lower())
-
-        # Create Skill with None trigger (always active) if we recognized the file type
-        if skill_name is not None:
-            # Truncate content if it exceeds the limit
-            # Third-party files are always active, so we want to keep them
-            # reasonably sized
-            truncated_content = maybe_truncate(
-                file_content,
-                truncate_after=THIRD_PARTY_SKILL_MAX_CHARS,
-                truncate_notice=(
-                    f"\n\n<TRUNCATED><NOTE>The file {path} exceeded the "
-                    f"maximum length ({THIRD_PARTY_SKILL_MAX_CHARS} "
-                    f"characters) and has been truncated. Only the "
-                    f"beginning and end are shown. You can read the full "
-                    f"file if needed.</NOTE>\n\n"
-                ),
-            )
-
-            if len(file_content) > THIRD_PARTY_SKILL_MAX_CHARS:
-                logger.warning(
-                    f"Third-party skill file {path} ({len(file_content)} chars) "
-                    f"exceeded limit ({THIRD_PARTY_SKILL_MAX_CHARS} chars), truncating"
-                )
-
-            return Skill(
-                name=skill_name,
-                content=truncated_content,
-                source=str(path),
-                trigger=None,
-            )
-
-        return None
-
     @classmethod
     def load(
         cls,
         path: str | Path,
-        skill_dir: Path | None = None,
-        file_content: str | None = None,
+        skill_base_dir: Path | None = None,
     ) -> "Skill":
         """Load a skill from a markdown file with frontmatter.
 
-        The agent's name is derived from its path relative to the skill_dir.
+        The agent's name is derived from its path relative to skill_base_dir,
+        or from the directory name for AgentSkills-style SKILL.md files.
 
         Supports both OpenHands-specific frontmatter fields and AgentSkills
         standard fields (https://agentskills.io/specification).
+
+        Args:
+            path: Path to the skill file.
+            skill_base_dir: Base directory for skills (used to derive relative names).
         """
         path = Path(path) if isinstance(path, str) else path
 
-        # Calculate derived name from relative path if skill_dir is provided
-        skill_name = None
-        if skill_dir is not None:
-            # Special handling for files which are not in skill_dir
-            skill_name = cls.PATH_TO_THIRD_PARTY_SKILL_NAME.get(
-                path.name.lower()
-            ) or str(path.relative_to(skill_dir).with_suffix(""))
+        with open(path) as f:
+            file_content = f.read()
+
+        if path.name.lower() == "skill.md":
+            return cls._load_agentskills_skill(path, file_content)
         else:
-            skill_name = path.stem
+            return cls._load_legacy_openhands_skill(path, file_content, skill_base_dir)
+
+    @classmethod
+    def _load_agentskills_skill(cls, path: Path, file_content: str) -> "Skill":
+        """Load a skill from an AgentSkills-format SKILL.md file.
 
-        # Only load directly from path if file_content is not provided
-        if file_content is None:
-            with open(path) as f:
-                file_content = f.read()
+        Args:
+            path: Path to the SKILL.md file.
+            file_content: Content of the file.
+        """
+        # For SKILL.md files, use parent directory name as the skill name
+        directory_name = path.parent.name
 
+        file_io = io.StringIO(file_content)
+        loaded = frontmatter.load(file_io)
+        content = loaded.content
+        metadata_dict = loaded.metadata or {}
+
+        # 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)}"
+            )
+
+        return cls._create_skill_from_metadata(agent_name, content, path, metadata_dict)
+
+    @classmethod
+    def _load_legacy_openhands_skill(
+        cls, path: Path, file_content: str, skill_base_dir: Path | None
+    ) -> "Skill":
+        """Load a skill from a legacy OpenHands-format file.
+
+        Args:
+            path: Path to the skill file.
+            file_content: Content of the file.
+            skill_base_dir: Base directory for skills (used to derive relative names).
+        """
         # Handle third-party agent instruction files
         third_party_agent = cls._handle_third_party(path, file_content)
         if third_party_agent is not None:
             return third_party_agent
 
+        # Calculate derived name from path
+        if skill_base_dir is not None:
+            skill_name = cls.PATH_TO_THIRD_PARTY_SKILL_NAME.get(
+                path.name.lower()
+            ) or str(path.relative_to(skill_base_dir).with_suffix(""))
+        else:
+            skill_name = path.stem
+
         file_io = io.StringIO(file_content)
         loaded = frontmatter.load(file_io)
         content = loaded.content
-
-        # Handle case where there's no frontmatter or empty frontmatter
         metadata_dict = loaded.metadata or {}
 
         # 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)
+
+    @classmethod
+    def _create_skill_from_metadata(
+        cls, agent_name: str, content: str, path: Path, metadata_dict: dict
+    ) -> "Skill":
+        """Create a Skill object from parsed metadata.
+
+        Args:
+            agent_name: The name of the skill.
+            content: The markdown content (without frontmatter).
+            path: Path to the skill file.
+            metadata_dict: Parsed frontmatter metadata.
+        """
         # Extract AgentSkills standard fields (Pydantic validators handle
         # transformation). Handle "allowed-tools" to "allowed_tools" key mapping.
         allowed_tools_value = metadata_dict.get(
@@ -284,7 +323,7 @@ class Skill(BaseModel):
         else:
             # No triggers, default to None (always active)
             mcp_tools = metadata_dict.get("mcp_tools")
-            if not isinstance(mcp_tools, dict | None):
+            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,
@@ -295,18 +334,42 @@ class Skill(BaseModel):
                 **agentskills_fields,
             )
 
-    # Field-level validation for mcp_tools
-    @field_validator("mcp_tools")
     @classmethod
-    def _validate_mcp_tools(cls, v: dict | None, _info):
-        if v is None:
-            return v
-        if isinstance(v, dict):
-            try:
-                MCPConfig.model_validate(v)
-            except Exception as e:
-                raise SkillValidationError(f"Invalid MCPConfig dictionary: {e}") from e
-        return v
+    def _handle_third_party(cls, path: Path, file_content: str) -> Union["Skill", None]:
+        """Handle third-party skill files (e.g., .cursorrules, AGENTS.md).
+
+        Creates a Skill with None trigger (always active) if the file type
+        is recognized. Truncates content if it exceeds the limit.
+        """
+        skill_name = cls.PATH_TO_THIRD_PARTY_SKILL_NAME.get(path.name.lower())
+
+        if skill_name is not None:
+            truncated_content = maybe_truncate(
+                file_content,
+                truncate_after=THIRD_PARTY_SKILL_MAX_CHARS,
+                truncate_notice=(
+                    f"\n\n<TRUNCATED><NOTE>The file {path} exceeded the "
+                    f"maximum length ({THIRD_PARTY_SKILL_MAX_CHARS} "
+                    f"characters) and has been truncated. Only the "
+                    f"beginning and end are shown. You can read the full "
+                    f"file if needed.</NOTE>\n\n"
+                ),
+            )
+
+            if len(file_content) > THIRD_PARTY_SKILL_MAX_CHARS:
+                logger.warning(
+                    f"Third-party skill file {path} ({len(file_content)} chars) "
+                    f"exceeded limit ({THIRD_PARTY_SKILL_MAX_CHARS} chars), truncating"
+                )
+
+            return Skill(
+                name=skill_name,
+                content=truncated_content,
+                source=str(path),
+                trigger=None,
+            )
+
+        return None
 
     @model_validator(mode="after")
     def _append_missing_variables_prompt(self):
@@ -368,72 +431,223 @@ 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]]:
+) -> tuple[dict[str, Skill], dict[str, Skill], dict[str, Skill]]:
     """Load all skills from the given directory.
 
+    Supports both formats:
+    - OpenHands format: skills/*.md files
+    - AgentSkills format: skills/skill-name/SKILL.md directories
+
     Note, legacy repo instructions will not be loaded here.
 
     Args:
         skill_dir: Path to the skills directory (e.g. .openhands/skills)
 
     Returns:
-        Tuple of (repo_skills, knowledge_skills) dictionaries.
-        repo_skills have trigger=None, knowledge_skills have KeywordTrigger
-        or TaskTrigger.
+        Tuple of (repo_skills, knowledge_skills, agent_skills) dictionaries.
+        - repo_skills: Skills with trigger=None (permanent context)
+        - knowledge_skills: Skills with KeywordTrigger or TaskTrigger (progressive)
+        - agent_skills: AgentSkills standard SKILL.md files (separate category)
     """
     if isinstance(skill_dir, str):
         skill_dir = Path(skill_dir)
 
-    repo_skills = {}
-    knowledge_skills = {}
-
-    # Load all agents from skills directory
+    repo_skills: dict[str, Skill] = {}
+    knowledge_skills: dict[str, Skill] = {}
+    agent_skills: dict[str, Skill] = {}
     logger.debug(f"Loading agents from {skill_dir}")
 
-    # Always check for .cursorrules and AGENTS.md files in repo root
-    special_files = []
+    # 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)
+    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
+        )
 
-    # Check for third party rules: .cursorrules, AGENTS.md, etc
-    for filename in Skill.PATH_TO_THIRD_PARTY_SKILL_NAME.keys():
-        for variant in [filename, filename.lower(), filename.upper()]:
-            if (repo_root / variant).exists():
-                special_files.append(repo_root / variant)
-                break  # Only add the first one found to avoid duplicates
-
-    # Collect .md files from skills directory if it exists
-    md_files = []
-    if skill_dir.exists():
-        md_files = [f for f in skill_dir.rglob("*.md") if f.name != "README.md"]
+    # Load SKILL.md files (auto-detected and validated in Skill.load)
+    for skill_md_path in skill_md_files:
+        _load_and_categorize(
+            skill_md_path, skill_dir, repo_skills, knowledge_skills, agent_skills
+        )
 
-    # Process all files in one loop
-    for file in chain(special_files, md_files):
-        try:
-            skill = Skill.load(
-                file,
-                skill_dir,
-            )
-            if skill.trigger is None:
-                repo_skills[skill.name] = skill
-            else:
-                # KeywordTrigger and TaskTrigger skills
-                knowledge_skills[skill.name] = skill
-        except SkillValidationError as e:
-            # For validation errors, include the original exception
-            error_msg = f"Error loading skill from {file}: {str(e)}"
-            raise SkillValidationError(error_msg) from e
-        except Exception as e:
-            # For other errors, wrap in a ValueError with detailed message
-            error_msg = f"Error loading skill from {file}: {str(e)}"
-            raise ValueError(error_msg) from e
+    # Load regular .md files
+    for path in regular_md_files:
+        _load_and_categorize(
+            path, skill_dir, repo_skills, knowledge_skills, agent_skills
+        )
 
+    total = len(repo_skills) + len(knowledge_skills) + len(agent_skills)
     logger.debug(
-        f"Loaded {len(repo_skills) + len(knowledge_skills)} skills: "
-        f"{[*repo_skills.keys(), *knowledge_skills.keys()]}"
+        f"Loaded {total} skills: "
+        f"repo={list(repo_skills.keys())}, "
+        f"knowledge={list(knowledge_skills.keys())}, "
+        f"agent={list(agent_skills.keys())}"
     )
-    return repo_skills, knowledge_skills
+    return repo_skills, knowledge_skills, agent_skills
 
 
 # Default user skills directories (in order of priority)
@@ -464,10 +678,12 @@ def load_user_skills() -> list[Skill]:
 
         try:
             logger.debug(f"Loading user skills from {skills_dir}")
-            repo_skills, knowledge_skills = load_skills_from_dir(skills_dir)
+            repo_skills, knowledge_skills, agent_skills = load_skills_from_dir(
+                skills_dir
+            )
 
-            # Merge repo and knowledge skills
-            for skills_dict in [repo_skills, knowledge_skills]:
+            # Merge all skill categories
+            for skills_dict in [repo_skills, knowledge_skills, agent_skills]:
                 for name, skill in skills_dict.items():
                     if name not in seen_names:
                         all_skills.append(skill)
@@ -522,10 +738,12 @@ def load_project_skills(work_dir: str | Path) -> list[Skill]:
 
         try:
             logger.debug(f"Loading project skills from {project_skills_dir}")
-            repo_skills, knowledge_skills = load_skills_from_dir(project_skills_dir)
+            repo_skills, knowledge_skills, agent_skills = load_skills_from_dir(
+                project_skills_dir
+            )
 
-            # Merge repo and knowledge skills
-            for skills_dict in [repo_skills, knowledge_skills]:
+            # Merge all skill categories
+            for skills_dict in [repo_skills, knowledge_skills, agent_skills]:
                 for name, skill in skills_dict.items():
                     if name not in seen_names:
                         all_skills.append(skill)
@@ -701,7 +919,7 @@ def load_public_skills(
             try:
                 skill = Skill.load(
                     path=skill_file,
-                    skill_dir=repo_path,
+                    skill_base_dir=repo_path,
                 )
                 if skill is None:
                     continue

openhands/sdk/context/view.py

@@ -489,9 +489,11 @@ class View(BaseModel):
         # Check for an unhandled condensation request -- these are events closer to the
         # end of the list than any condensation action.
         unhandled_condensation_request = False
+
         for event in reversed(events):
             if isinstance(event, Condensation):
                 break
+
             if isinstance(event, CondensationRequest):
                 unhandled_condensation_request = True
                 break