aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/skills/models.py

@@ -0,0 +1,769 @@
+"""Skill object model.
+
+Skill objects validate local skill roots, preserve SKILL.md frontmatter metadata,
+and provide stable local/backend roots for staging and runtime loading.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import os
+import posixpath
+import shlex
+from dataclasses import dataclass
+from enum import StrEnum
+from importlib import util as importlib_util
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field
+
+try:
+    # Pydantic v2 preferred config
+    from pydantic import ConfigDict  # type: ignore
+except ImportError:  # pragma: no cover
+    ConfigDict = None  # type: ignore
+
+from aip_agents.common.callable_introspection import callable_accepts_keyword
+from aip_agents.skills.errors import SkillExecutionError
+from aip_agents.skills.installer import SkillInstaller
+from aip_agents.skills.validation import validate_skill_root
+
+_SKILL_MD_FILENAME = "SKILL.md"
+_MISSING_POLICY = object()
+_MALFORMED_FRONTMATTER_POLICY = object()
+_DENY_POLICY_MARKERS = {"none", "null", "false", "deny", "deny-all"}
+_SKILL_MD_FILENAME = "SKILL.md"
+
+
+class Skill(BaseModel):
+    """Represents an installed skill.
+
+    Attributes:
+        name (str): Skill name (derived from folder name).
+        description (str | None): Optional metadata. Defaults to None.
+        version (str | None): Optional metadata. Defaults to None.
+        tags (tuple[str, ...]): Optional metadata. Defaults to ().
+        triggers (tuple[str, ...]): Optional metadata. Defaults to ().
+        source (str | None): The install source, when applicable. Defaults to None.
+        local_root_path (Path): Local filesystem path to the skill root.
+        backend_root (str): Deterministic backend root path (`/skills/<name>`).
+    """
+
+    name: str
+    local_root_path: Path
+    source: str | None = None
+    description: str | None = None
+    version: str | None = None
+    author: str | None = None
+    license: str | None = None
+    tags: tuple[str, ...] = ()
+    triggers: tuple[str, ...] = ()
+    required_credential_files: tuple[str, ...] = ()
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    source_type: str = "generated_fixture"
+    trust_label: str = "generated_fixture"
+    content_hash: str | None = None
+
+    if ConfigDict is not None:
+        # Pydantic v2 style config
+        model_config = ConfigDict(frozen=True)  # type: ignore[assignment]
+    else:  # pragma: no cover
+
+        class Config:  # type: ignore[no-redef]
+            """Pydantic v1 fallback config for Skill."""
+
+            allow_mutation = False
+
+    @property
+    def local_root(self) -> str:
+        """Local filesystem root as a string path.
+
+        Returns:
+            str: Local skill root path.
+        """
+        return str(self.local_root_path)
+
+    @property
+    def provenance(self) -> dict[str, Any]:
+        """Return source and trust context for diagnostics and harness payloads."""
+        return {
+            "source": self.source or str(self.local_root_path),
+            "source_type": self.source_type,
+            "trust_label": self.trust_label,
+            "local_root": str(self.local_root_path),
+            "content_hash": self.content_hash,
+        }
+
+    @property
+    def backend_root(self) -> str:
+        """Backend root path used for staging (`/skills/<skill-name>`).
+
+        Returns:
+            str: Backend root path.
+        """
+        return f"/skills/{self.name}"
+
+    @property
+    def skill_md_path(self) -> Path:
+        """Return the path to the required SKILL.md file.
+
+        Returns:
+            Path: SKILL.md file path.
+        """
+        return self.local_root_path / _SKILL_MD_FILENAME
+
+    def allowed_scripts_policy(self) -> dict[str, Any]:
+        """Return the normalized `allowed-scripts` policy from SKILL.md."""
+        frontmatter = self._read_frontmatter()
+        raw_policy = self._frontmatter_value(frontmatter, "allowed-scripts", "allowed_scripts", default=_MISSING_POLICY)
+        return self.normalize_allowed_scripts_policy(raw_policy, skill_name=self.name)
+
+    def setup_readiness(self, *, backend: Any | None = None) -> dict[str, Any]:
+        """Report skill setup readiness without reading credential file contents."""
+        frontmatter = self._read_frontmatter()
+        policy = self.allowed_scripts_policy()
+        credential_files = self._normalize_string_sequence(
+            self._frontmatter_value(
+                frontmatter,
+                "required_credential_files",
+                "required-credential-files",
+                default=[],
+            ),
+            field_name="required_credential_files",
+        )
+        optional_dependencies = self._normalize_string_sequence(
+            self._frontmatter_value(
+                frontmatter,
+                "optional_dependencies",
+                "optional-dependencies",
+                default=[],
+            ),
+            field_name="optional_dependencies",
+        )
+        scripts = self._script_paths_for_readiness(policy)
+
+        credential_checks = [self._credential_file_check(path) for path in credential_files]
+        dependency_checks = [self._optional_dependency_check(name) for name in optional_dependencies]
+        script_checks = [self._script_file_check(path) for path in scripts]
+        backend_check = self._backend_execution_check(backend, needs_execution=bool(scripts))
+
+        blocking_checks = [*credential_checks, *dependency_checks, *script_checks]
+        ready = policy["valid"] and all(check["status"] != "missing" for check in blocking_checks)
+        ready = ready and backend_check["status"] not in ("unsupported", "not_checked")
+
+        return {
+            "skill_name": self.name,
+            "ready": ready,
+            "policy": policy,
+            "credential_files": credential_checks,
+            "scripts": script_checks,
+            "optional_dependencies": dependency_checks,
+            "backend_execution": backend_check,
+        }
+
+    @classmethod
+    def from_path(cls, path: str | os.PathLike[str]) -> Skill:
+        """Create a Skill object from an already-installed local directory.
+
+        Args:
+            path (str | os.PathLike[str]): Path to a skill directory.
+
+        Returns:
+            Skill: The validated skill object.
+
+        Raises:
+            SkillValidationError: If the path is not a valid skill.
+        """
+        skill_root = Path(path).expanduser()
+        validate_skill_root(skill_root)
+        frontmatter = _read_skill_frontmatter(skill_root / _SKILL_MD_FILENAME)
+        return cls(
+            name=skill_root.name,
+            local_root_path=skill_root,
+            description=_optional_text(frontmatter.get("description")),
+            version=_optional_text(frontmatter.get("version")),
+            author=_optional_text(frontmatter.get("author")),
+            license=_optional_text(frontmatter.get("license")),
+            tags=_string_tuple(frontmatter.get("tags")),
+            triggers=_string_tuple(frontmatter.get("triggers")),
+            required_credential_files=_string_tuple(
+                frontmatter.get("required_credential_files") or frontmatter.get("required-credential-files")
+            ),
+            metadata=frontmatter,
+            source_type="local_path",
+            trust_label="explicit_local_path",
+            content_hash=_skill_md_hash(skill_root / _SKILL_MD_FILENAME),
+        )
+
+    @classmethod
+    async def from_github(
+        cls,
+        *,
+        source: str,
+        destination_root: str | os.PathLike[str],
+        token: str | None = None,
+    ) -> Skill:
+        """Install a skill from GitHub and return a Skill object.
+
+        Args:
+            source (str): GitHub tree URL pointing at a skill directory.
+            destination_root (str | os.PathLike[str]): Installation destination root
+                (e.g. `.agents/skills`).
+            token (str | None, optional): GitHub token used for private repos. Defaults to None.
+
+        Returns:
+            Skill: The installed and validated skill.
+
+        Raises:
+            SkillInstallError: If installation fails.
+            SkillValidationError: If the installed result is invalid.
+        """
+        installer = SkillInstaller(token=token)
+        installed_root = await installer.install_github_tree(source=source, destination_root=destination_root)
+
+        installed_skill = cls.from_path(installed_root)
+        return cls(
+            name=installed_skill.name,
+            local_root_path=installed_skill.local_root_path,
+            source=source,
+            description=installed_skill.description,
+            version=installed_skill.version,
+            author=installed_skill.author,
+            license=installed_skill.license,
+            tags=installed_skill.tags,
+            triggers=installed_skill.triggers,
+            required_credential_files=installed_skill.required_credential_files,
+            metadata=copy.deepcopy(installed_skill.metadata),
+            source_type="github_url",
+            trust_label="installed_cache",
+            content_hash=installed_skill.content_hash,
+        )
+
+    def execute_skill_script(
+        self,
+        *,
+        backend: Any,
+        script_relative_path: str,
+        args: list[str] | tuple[str, ...] | None = None,
+        timeout_seconds: int | None = None,
+        default_timeout_seconds: int = 30,
+        max_timeout_seconds: int = 300,
+    ) -> dict[str, Any]:
+        """Execute a staged skill script through backend execute support.
+
+        Args:
+            backend: Backend instance exposing execute().
+            script_relative_path: Relative script path within the skill root.
+            args: Optional command-line arguments.
+            timeout_seconds: Optional timeout override.
+            default_timeout_seconds: Default timeout when override is omitted.
+            max_timeout_seconds: Maximum accepted timeout.
+
+        Returns:
+            dict[str, Any]: Deterministic, serializable execution payload.
+
+        Raises:
+            SkillExecutionError: If execution is unavailable or input is invalid.
+        """
+        normalized_relative_path = self._normalize_script_relative_path(script_relative_path)
+        script_path = self._resolve_backend_script_path(normalized_relative_path)
+        self._enforce_allowed_script(normalized_relative_path, script_path)
+        self._ensure_local_script_exists(normalized_relative_path, script_path)
+
+        execute_fn = getattr(backend, "execute", None)
+        if not callable(execute_fn):
+            denial = self._execution_denial(
+                script_relative_path=normalized_relative_path,
+                script_path=script_path,
+                policy_reason="unsupported_backend",
+            )
+            raise SkillExecutionError(
+                "Execution not available: backend does not expose execute().",
+                denial=denial,
+            )
+
+        allow_execute = getattr(backend, "allow_execute", None)
+        if allow_execute is False:
+            denial = self._execution_denial(
+                script_relative_path=normalized_relative_path,
+                script_path=script_path,
+                policy_reason="backend_execute_disabled",
+            )
+            raise SkillExecutionError("Execution not available: backend execute() is disabled.", denial=denial)
+
+        normalized_args = tuple(str(arg) for arg in (args or []))
+        command = self._build_command(script_path, normalized_args)
+        resolved_timeout = self._resolve_timeout(timeout_seconds, default_timeout_seconds, max_timeout_seconds)
+
+        if callable_accepts_keyword(execute_fn, "timeout"):
+            result = execute_fn(command, timeout=resolved_timeout)
+        else:
+            result = execute_fn(command)
+
+        return {
+            "skill_name": self.name,
+            "script_relative_path": normalized_relative_path,
+            "script_path": script_path,
+            "command": command,
+            "timeout_seconds": resolved_timeout,
+            "stdout": str(getattr(result, "stdout", "")),
+            "stderr": str(getattr(result, "stderr", "")),
+            "exit_code": int(getattr(result, "exit_code", -1)),
+            "truncated": bool(getattr(result, "truncated", False)),
+        }
+
+    def _resolve_backend_script_path(self, script_relative_path: str) -> str:
+        """Resolve and validate a script path under `/skills/<skill-name>/`.
+
+        Args:
+            script_relative_path: Relative script path.
+
+        Returns:
+            str: Canonical backend script path.
+
+        Raises:
+            SkillExecutionError: If path escapes skill root or is invalid.
+        """
+        normalized_relative_path = self._normalize_script_relative_path(script_relative_path)
+
+        skill_root = PurePosixPath(self.backend_root)
+        candidate_path = PurePosixPath(posixpath.normpath(posixpath.join(str(skill_root), normalized_relative_path)))
+        candidate_path_str = str(candidate_path)
+        skill_root_str = str(skill_root)
+        if not (candidate_path_str == skill_root_str or candidate_path_str.startswith(f"{skill_root_str}/")):
+            raise SkillExecutionError("Resolved script path escapes the skill root.")
+
+        return candidate_path_str
+
+    @staticmethod
+    def _canonicalize_skill_path(path: str, skill_name: str) -> str:
+        """Canonicalize a skill path to skill-relative form.
+
+        Strips current-skill path prefixes (.agents/skills/<name>/,
+        skills/<name>/, /skills/<name>/) to produce a clean skill-relative
+        path for comparison or resolution across both authoring and runtime
+        conventions.
+
+        Args:
+            path: Raw path string in any supported form.
+            skill_name: The expected skill name for validation.
+
+        Returns:
+            str: Canonical skill-relative path.
+
+        Raises:
+            SkillExecutionError: If the path is empty, uses an absolute or
+                .agents path for a different skill, or is an absolute path in
+                an unsupported form.
+        """
+        stripped = str(path).strip()
+        if not stripped:
+            raise SkillExecutionError("Path is required.")
+        normalized = posixpath.normpath(stripped.replace("\\", "/"))
+
+        # Strip runtime absolute prefix: /skills/<skill_name>/
+        runtime_prefix = f"/skills/{skill_name}"
+        if normalized.startswith("/"):
+            if normalized == runtime_prefix:
+                normalized = ""  # pragma: no cover
+            elif normalized.startswith(f"{runtime_prefix}/"):
+                normalized = normalized[len(runtime_prefix) + 1 :]
+            elif normalized.startswith("/skills/"):
+                remainder = normalized[len("/skills/") :]
+                referenced_name = remainder.split("/", 1)[0]
+                raise SkillExecutionError(
+                    f"script_relative_path references skill '{referenced_name}', "
+                    f"not the current skill '{skill_name}'."
+                )
+            else:
+                raise SkillExecutionError("Path must be relative, not absolute.")
+
+        # Strip authoring-time prefix: .agents/skills/<skill_name>/
+        agents_prefix = f".agents/skills/{skill_name}"
+        if normalized == agents_prefix:
+            normalized = ""  # pragma: no cover
+        elif normalized.startswith(f"{agents_prefix}/"):
+            normalized = normalized[len(agents_prefix) + 1 :]
+
+        # Strip runtime-relative prefix: skills/<skill_name>/
+        skill_prefix = f"skills/{skill_name}"
+        if normalized == skill_prefix:
+            normalized = ""
+        elif normalized.startswith(f"{skill_prefix}/"):
+            normalized = normalized[len(skill_prefix) + 1 :]
+
+        # Reject .agents/skills/<other>/ authoring paths.
+        _reject_wrong_skill_path(normalized, skill_name)
+
+        return normalized
+
+    def _normalize_script_relative_path(self, script_relative_path: str) -> str:
+        normalized = self._canonicalize_skill_path(script_relative_path, self.name)
+        if normalized in {"", "."}:
+            raise SkillExecutionError("script_relative_path must point to a concrete file.")
+        if normalized == ".." or normalized.startswith("../"):
+            raise SkillExecutionError("script_relative_path cannot traverse outside the skill directory.")
+        return normalized
+
+    def _enforce_allowed_script(self, script_relative_path: str, script_path: str) -> None:
+        policy = self.allowed_scripts_policy()
+        allowed = policy["mode"] == "allow_all" or script_relative_path in policy["allowed_scripts"]
+        if policy["mode"] == "deny_all":
+            allowed = False
+        if allowed:
+            return
+
+        denial = self._execution_denial(
+            script_relative_path=script_relative_path,
+            script_path=script_path,
+            policy_reason=str(policy["reason"]),
+            policy=policy,
+        )
+        raise SkillExecutionError(f"Skill script execution denied by policy: {policy['reason']}.", denial=denial)
+
+    def _ensure_local_script_exists(self, script_relative_path: str, script_path: str) -> None:
+        if (self.local_root_path / script_relative_path).is_file():
+            return
+        denial = self._execution_denial(
+            script_relative_path=script_relative_path,
+            script_path=script_path,
+            policy_reason="missing_script",
+        )
+        raise SkillExecutionError(
+            f"Skill script execution denied: script not found at {script_relative_path}.",
+            denial=denial,
+        )
+
+    def _execution_denial(
+        self,
+        *,
+        script_relative_path: str,
+        script_path: str,
+        policy_reason: str,
+        policy: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        resolved_policy = policy or self.allowed_scripts_policy()
+        return {
+            "skill_name": self.name,
+            "requested_script": script_relative_path,
+            "requested_resource": script_path,
+            "policy_mode": resolved_policy["mode"],
+            "allowed_scripts": resolved_policy["allowed_scripts"],
+            "policy_reason": policy_reason,
+        }
+
+    def _read_frontmatter(self) -> dict[str, Any]:
+        try:
+            content = self.skill_md_path.read_text(encoding="utf-8")
+        except OSError:
+            return {}
+        if not content.startswith("---"):
+            return {}
+        start = content.find("\n")
+        end = content.find("\n---", start + 1)
+        if start == -1 or end == -1:
+            return {"allowed-scripts": _MALFORMED_FRONTMATTER_POLICY}
+        try:
+            loaded = yaml.safe_load(content[start + 1 : end])
+        except yaml.YAMLError:
+            return {"allowed-scripts": _MALFORMED_FRONTMATTER_POLICY}
+        return loaded if isinstance(loaded, dict) else {"allowed-scripts": _MALFORMED_FRONTMATTER_POLICY}
+
+    @staticmethod
+    def _frontmatter_value(frontmatter: dict[str, Any], *keys: str, default: Any) -> Any:
+        for key in keys:
+            if key in frontmatter:
+                return frontmatter[key]
+        return default
+
+    @staticmethod
+    def _parse_allowed_scripts_str(raw_value: str) -> list[str] | None:
+        raw_value = raw_value.strip()
+        if raw_value == "*":
+            return ["*"]
+        if raw_value.lower() in _DENY_POLICY_MARKERS or not raw_value:
+            return []
+        return [item for part in raw_value.split(",") for item in part.split()]
+
+    @staticmethod
+    def _parse_allowed_scripts_list(raw_policy: list[Any]) -> list[str] | None:
+        if not raw_policy:
+            return []
+        if not all(isinstance(item, str) for item in raw_policy):
+            return None
+        return raw_policy
+
+    @staticmethod
+    def _normalize_script_items(raw_items: list[str], *, skill_name: str) -> dict[str, Any] | None:
+        normalized = []
+        for item in raw_items:
+            try:
+                normalized_item = Skill._canonicalize_skill_path(item, skill_name)
+            except SkillExecutionError:
+                return None
+            if normalized_item in {"", ".", ".."} or normalized_item.startswith("../"):
+                return None  # pragma: no cover
+            normalized.append(normalized_item)
+        if "*" in normalized:
+            return Skill._allow_all_policy(skill_name, reason="allowed_scripts_allow_all")
+        return {
+            "skill_name": skill_name,
+            "mode": "allow_list",
+            "allowed_scripts": sorted(set(normalized)),
+            "valid": True,
+            "reason": "allowed_scripts_allow_list",
+        }
+
+    @staticmethod
+    def _allow_all_policy(skill_name: str, *, reason: str) -> dict[str, Any]:
+        return {
+            "skill_name": skill_name,
+            "mode": "allow_all",
+            "allowed_scripts": ["*"],
+            "valid": True,
+            "reason": reason,
+        }
+
+    @staticmethod
+    def normalize_allowed_scripts_policy(raw_policy: Any, *, skill_name: str) -> dict[str, Any]:
+        """Normalize frontmatter `allowed-scripts` into an enforcement contract."""
+        if raw_policy is _MISSING_POLICY:
+            return Skill._allow_all_policy(skill_name, reason="missing_allowed_scripts_defaults_to_allow_all")
+        if raw_policy is _MALFORMED_FRONTMATTER_POLICY:
+            return Skill._deny_all_policy(skill_name, reason="malformed_frontmatter", valid=False)
+        if raw_policy is None:
+            return Skill._deny_all_policy(skill_name, reason="allowed_scripts_denies_all")
+
+        if isinstance(raw_policy, str):
+            raw_items = Skill._parse_allowed_scripts_str(raw_policy)
+        elif isinstance(raw_policy, list):
+            raw_items = Skill._parse_allowed_scripts_list(raw_policy)
+        else:
+            raw_items = None
+
+        if raw_items is None:
+            return Skill._deny_all_policy(skill_name, reason="malformed_allowed_scripts", valid=False)
+        if not raw_items:
+            return Skill._deny_all_policy(skill_name, reason="allowed_scripts_denies_all")
+
+        result = Skill._normalize_script_items(raw_items, skill_name=skill_name)
+        if result is not None:
+            return result
+        return Skill._deny_all_policy(skill_name, reason="malformed_allowed_scripts", valid=False)
+
+    @staticmethod
+    def missing_allowed_scripts_policy_marker() -> object:
+        """Return the internal sentinel used for absent `allowed-scripts` metadata."""
+        return _MISSING_POLICY
+
+    @staticmethod
+    def _deny_all_policy(skill_name: str, *, reason: str, valid: bool = True) -> dict[str, Any]:
+        return {
+            "skill_name": skill_name,
+            "mode": "deny_all",
+            "allowed_scripts": [],
+            "valid": valid,
+            "reason": reason,
+        }
+
+    @staticmethod
+    def _normalize_string_sequence(raw_value: Any, *, field_name: str) -> list[str]:
+        if raw_value in (None, ""):
+            return []
+        if isinstance(raw_value, str):
+            trimmed = raw_value.strip()
+            return [trimmed] if trimmed else []
+        if isinstance(raw_value, list) and all(isinstance(item, str) for item in raw_value):
+            return [item.strip() for item in raw_value if item.strip()]
+        return []
+
+    def _script_paths_for_readiness(self, policy: dict[str, Any]) -> list[str]:
+        if policy["mode"] == "allow_list":
+            return list(policy["allowed_scripts"])
+        scripts_root = self.local_root_path / "scripts"
+        if not scripts_root.exists():
+            return []
+        return sorted(
+            path.relative_to(self.local_root_path).as_posix() for path in scripts_root.rglob("*") if path.is_file()
+        )
+
+    def _credential_file_check(self, path: str) -> dict[str, Any]:
+        expanded_path = Path(path).expanduser()
+        if not expanded_path.is_absolute():
+            expanded_path = self.local_root_path / expanded_path
+        return {"path": path, "status": "present" if expanded_path.is_file() else "missing"}
+
+    def _script_file_check(self, path: str) -> dict[str, Any]:
+        try:
+            normalized_path = self._normalize_script_relative_path(path)
+        except SkillExecutionError as exc:
+            return {"path": path, "status": "missing", "reason": str(exc)}
+        return {
+            "path": normalized_path,
+            "status": "present" if (self.local_root_path / normalized_path).is_file() else "missing",
+        }
+
+    @staticmethod
+    def _optional_dependency_check(name: str) -> dict[str, Any]:
+        import_name = name
+        for separator in ("[", "<", ">", "=", "!", "~"):
+            import_name = import_name.split(separator, 1)[0]
+        import_name = import_name.strip().replace("-", "_")
+        try:
+            found = bool(import_name) and importlib_util.find_spec(import_name) is not None
+        except (ModuleNotFoundError, ValueError):
+            found = False
+        return {"name": name, "status": "present" if found else "missing"}
+
+    @staticmethod
+    def _backend_execution_check(backend: Any | None, *, needs_execution: bool) -> dict[str, Any]:
+        if not needs_execution:
+            return {"status": "not_required"}
+        if backend is None:
+            return {"status": "not_checked"}
+        execute_fn = getattr(backend, "execute", None)
+        if not callable(execute_fn) or getattr(backend, "allow_execute", None) is False:
+            return {"status": "unsupported"}
+        return {"status": "supported"}
+
+    @staticmethod
+    def _resolve_timeout(timeout_seconds: int | None, default_timeout_seconds: int, max_timeout_seconds: int) -> int:
+        """Resolve timeout bounded by configured min/max values."""
+        default_timeout = max(1, int(default_timeout_seconds))
+        max_timeout = max(1, int(max_timeout_seconds))
+        if timeout_seconds is None:
+            return min(default_timeout, max_timeout)
+        return max(1, min(int(timeout_seconds), max_timeout))
+
+    @staticmethod
+    def _execute_accepts_timeout(execute_fn: Any) -> bool:
+        """Return whether execute callable accepts a timeout keyword."""
+        return callable_accepts_keyword(execute_fn, "timeout")
+
+    @staticmethod
+    def _build_command(script_path: str, args: tuple[str, ...]) -> str:
+        """Build a deterministic Python command for script execution."""
+        parts = ["python", script_path, *args]
+        return " ".join(shlex.quote(part) for part in parts)
+
+
+def _reject_wrong_skill_path(path: str, current_skill_name: str) -> None:
+    """Reject .agents/skills/<other>/ paths that reference a different skill.
+
+    Args:
+        path (str): Normalized path to inspect. Relative skills/<x>/ paths are
+            treated as local subdirectories after current-skill prefix stripping.
+        current_skill_name (str): The expected skill name.
+
+    Raises:
+        SkillExecutionError: If the path references a different skill.
+    """
+    # Check .agents/skills/<other-skill>/... without the current skill prefix
+    agents_other = ".agents/skills/"
+    if path.startswith(agents_other):
+        remainder = path[len(agents_other) :]
+        next_slash = remainder.find("/")
+        if next_slash > 0:
+            referenced_name = remainder[:next_slash]
+            if referenced_name != current_skill_name:
+                raise SkillExecutionError(
+                    f"script_relative_path references skill '{referenced_name}', "
+                    f"not the current skill '{current_skill_name}'."
+                )
+
+
+class ResourceType(StrEnum):
+    """Type of resource contained in a staged skill manifest."""
+
+    INSTRUCTION = "instruction"
+    REFERENCE = "reference"
+    EXAMPLE = "example"
+    SCRIPT = "script"
+    ASSET = "asset"
+
+
+@dataclass
+class ResourceEntry:
+    """Metadata for one staged skill resource."""
+
+    backend_path: str
+    relative_path: str
+    resource_type: ResourceType
+    size_bytes: int
+    is_binary: bool
+    summary: str | None = None
+
+
+@dataclass
+class ResourceManifest:
+    """Deterministic manifest of resources staged for one skill."""
+
+    skill_name: str
+    resources: list[ResourceEntry]
+
+
+def _read_skill_frontmatter(skill_md_path: Path) -> dict[str, Any]:
+    try:
+        content = skill_md_path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    frontmatter = _extract_frontmatter(content)
+    if frontmatter is None:
+        return {}
+    try:
+        parsed = yaml.safe_load(frontmatter)
+    except yaml.YAMLError:
+        return {}
+    if not isinstance(parsed, dict):
+        return {}
+    return dict(parsed)
+
+
+def _extract_frontmatter(content: str) -> str | None:
+    lines = content.splitlines(keepends=True)
+    if not lines or not _is_frontmatter_delimiter(lines[0]):
+        return None
+
+    body: list[str] = []
+    for line in lines[1:]:
+        if _is_frontmatter_delimiter(line):
+            return "".join(body)
+        body.append(line)
+
+    return None
+
+
+def _is_frontmatter_delimiter(line: str) -> bool:
+    stripped = line.rstrip("\r\n")
+    return stripped.strip() == "---" and stripped == stripped.lstrip()
+
+
+def _skill_md_hash(skill_md_path: Path) -> str | None:
+    try:
+        data = skill_md_path.read_bytes()
+    except OSError:
+        return None
+    return f"sha256:{hashlib.sha256(data).hexdigest()}"
+
+
+def _optional_text(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _string_tuple(value: Any) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return (value.strip(),) if value.strip() else ()
+    if isinstance(value, list | tuple):
+        return tuple(str(item).strip() for item in value if str(item).strip())
+    return (str(value).strip(),) if str(value).strip() else ()