docs(skills): clarify LocalDirLazySkillSource host paths

Author: MukundaKatta

docs/sandbox/guide.md

@@ -205,6 +205,7 @@ By default, `SandboxAgent.capabilities` uses `Capabilities.default()`, which inc
 For skills, choose the source based on how you want them materialized:
 
 - `Skills(lazy_from=LocalDirLazySkillSource(...))` is a good default for larger local skill directories because the model can discover the index first and load only what it needs.
+- `LocalDirLazySkillSource(source=LocalDir(...))` reads from the host filesystem, not from a path that already exists inside the sandbox image or workspace. If you mount skills into the sandbox at `/skills`, still pass the original host directory to `LocalDir(...)`.
 - `Skills(from_=LocalDir(src=...))` is better for a small local bundle you want staged up front.
 - `Skills(from_=GitRepo(repo=..., ref=...))` is the right fit when the skills themselves should come from a repository.
 

docs/sandbox_agents.md

@@ -65,6 +65,8 @@ def build_agent(model: str) -> SandboxAgent[None]:
         capabilities=Capabilities.default() + [
             Skills(
                 lazy_from=LocalDirLazySkillSource(
+                    # This is a host path. The lazy loader copies skills into `.agents/`
+                    # on demand, so do not point this at an in-sandbox path such as `/skills`.
                     source=LocalDir(src=HOST_SKILLS_DIR),
                 )
             ),

src/agents/sandbox/capabilities/skills.py

@@ -173,8 +173,17 @@ async def load_skill(
         src_root = self._src_root()
         if src_root is None:
             raise SkillsConfigError(
-                message="lazy skill source directory is unavailable",
-                context={"skill_name": skill_name},
+                message=(
+                    "lazy skill source directory is unavailable; "
+                    "LocalDirLazySkillSource expects a host filesystem path, not a path "
+                    "inside the sandbox"
+                ),
+                context={
+                    "skill_name": skill_name,
+                    "configured_source_path": None
+                    if self.source.src is None
+                    else str(self.source.src),
+                },
             )
 
         matches = [

tests/sandbox/capabilities/test_skills_capability.py

@@ -556,9 +556,19 @@ async def test_load_skill_rejects_missing_lazy_source_directory(self, tmp_path:
         )
         capability.bind(_SkillsSession(Manifest(root=str(workspace_root))))
 
-        with pytest.raises(SkillsConfigError):
+        with pytest.raises(SkillsConfigError) as exc_info:
             await capability.load_skill("missing-skill")
 
+        assert (
+            exc_info.value.message
+            == "lazy skill source directory is unavailable; "
+            "LocalDirLazySkillSource expects a host filesystem path, not a path inside the sandbox"
+        )
+        assert exc_info.value.context == {
+            "skill_name": "missing-skill",
+            "configured_source_path": str(tmp_path / "missing-skills"),
+        }
+
     @pytest.mark.asyncio
     async def test_load_skill_rejects_ambiguous_skill_name(self, tmp_path: Path) -> None:
         workspace_root = tmp_path / "workspace"