feat(my-deepagent): v0.3 PR #4 — Agent Skills (LLM-routing, SKILL.md index inject)

Claude Code의 Agent Skills 동작을 그대로 구현 — deepagents `SkillsMiddleware`가
`<name>/SKILL.md` 디렉터리들을 스캔하고 `(name, description)` 인덱스만
시스템 프롬프트에 inject.  LLM이 필요한 skill을 골라 read_file 로 본문을
가져감 (progressive disclosure).  임베딩·벡터 검색 없음.

데이터·라이브러리:
- `skills.py` (신규):
  - `user_skills_dir(config)` — `<config.data_dir>/skills/`
  - `ensure_skills_initialized(dir)` — `mkdir -p`, 예제 skill 시드 안 함
  - `list_installed_skills(dir)` — `<name>/SKILL.md` frontmatter 파싱.
    malformed (frontmatter 없음/YAML 깨짐/name-dir mismatch/10MB 초과)는
    silently skip.  description 200자 트렁케이트.
  - `read_skill_body(dir, name)` — `/skill <name>` 본문 표시용
  - `resolve_skill_sources(config)` — deepagents 에 전달할 source 리스트
- `session.py`:
  - `build_agent(..., skills_sources_override=...)` 신규 kwarg.
    `persona.skills`와 합쳐 `deepagents.create_deep_agent(skills=...)`로 전달
    (empty 면 kwarg 생략 → middleware 미생성).
  - `_resolve_skill_sources` 헬퍼 추출.

REPL 통합 (`cli/interactive.py`):
- `InteractiveSession.__init__`에서 `ensure_skills_initialized` 호출
  → `self.skills_dir`.
- `build_agent_if_needed`가 매 재빌드 시 `resolve_skill_sources(config)` 전달.
- `_register_skills_slash`: `/skills` (목록), `/skill <name>` (본문) 등록.

테스트 (`tests/integration/test_skills.py`, 15 케이스):
- Bootstrap idempotency, 빈 디렉터리 정상 상태
- list: 정렬, SKILL.md 누락 스킵, YAML 깨짐 스킵, name-dir mismatch 스킵,
  description truncate, 누락된 디렉터리 빈 리스트, 긴 description 트렁케이트
- read_skill_body: 정상/누락/빈 이름
- resolve_skill_sources: user-scope 1개 반환
- **integration**: `build_agent(..., skills_sources_override=[...])` 가 실제로
  `create_deep_agent(skills=...)` 까지 monkeypatch 로 전달되는지 검증

게이트:
- ruff check / format --check / mypy: PASS
- pytest -q --ignore=tests/integration/test_e2e_workflow.py
  --ignore=tests/integration/test_openrouter_smoke.py: 648 passed (15 신규 포함)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

my-deepagent/CHANGELOG.md

@@ -3,6 +3,42 @@
 ## [Unreleased]
 
 ### Added
+- **v0.3 PR #4 — Agent Skills (LLM-routing, no embeddings)**.  Anthropic Agent
+  Skills 명세를 그대로 따르는 progressive-disclosure 패턴.  deepagents
+  `SkillsMiddleware`가 디렉터리를 스캔해 `(name, description)` 인덱스만
+  시스템 프롬프트에 인젝션하면 LLM이 필요한 skill을 골라 `read_file`로 본문을
+  읽음.  임베딩·벡터 검색 없음 — Claude Code의 실제 동작과 동일.
+  - `skills.py` (신규):
+    - `user_skills_dir(config)` — `<config.data_dir>/skills/`
+    - `ensure_skills_initialized(dir)` — 디렉터리 생성, idempotent.  예제
+      skill 시드하지 않음 (빈 디렉터리가 정상 신규 상태).
+    - `list_installed_skills(dir)` — `<name>/SKILL.md`를 스캔해 frontmatter
+      파싱.  malformed (frontmatter 없음/YAML 깨짐/name-dir mismatch/10MB 초과)
+      는 silently skip.  `SkillInfo(name, description, path)` 리스트.
+    - `read_skill_body(dir, name)` — `/skill <name>`의 본문 표시용.
+    - `resolve_skill_sources(config)` — deepagents 에 전달할 source 리스트
+      빌드 (현재는 user-scope 1개; 후속 PR이 project-scope 추가 가능).
+  - `session.py`:
+    - `build_agent(..., skills_sources_override: list[str] | None = None)`
+      신규 kwarg.  `persona.skills`와 합쳐 deepagents `skills=` kwarg로 전달
+      (empty 면 kwarg 생략 → `SkillsMiddleware` 미생성).
+    - `_resolve_skill_sources` 헬퍼 추출.
+  - `cli/interactive.py`:
+    - `InteractiveSession.__init__`에서 `user_skills_dir` 부트스트랩 후
+      `self.skills_dir`로 보관.
+    - `build_agent_if_needed`가 매 재빌드 시 `resolve_skill_sources(config)`로
+      현재 디렉터리 상태를 전달.
+    - `_register_skills_slash`: `/skills` (설치된 skill 목록), `/skill <name>`
+      (전체 SKILL.md 본문 표시) 슬래시 등록.
+  - `tests/integration/test_skills.py` (신규, 15 케이스):
+    - Bootstrap idempotency, 빈 디렉터리 기본 상태
+    - list: 정렬, SKILL.md 누락 스킵, YAML 깨짐 스킵, name-dir mismatch 스킵,
+      description 200자 트렁케이트, 누락된 디렉터리는 빈 리스트
+    - read_skill_body: 정상/누락/빈 이름
+    - resolve_skill_sources: user-scope 1개 반환
+    - **integration**: `build_agent(..., skills_sources_override=[...])`가
+      실제로 `create_deep_agent(skills=...)` 까지 전달되는지 monkeypatch 검증
+
 - **v0.3 PR #3 — auto-memory (project-scoped `MEMORY.md` + entry files)**.
   Claude Code의 auto-memory + `/remember`/`/forget` 슬래시 등가.  세션이 시작될
   때 `<config.data_dir>/projects/<project_key>/memory/` 디렉터리를 부트스트랩

my-deepagent/src/my_deepagent/cli/interactive.py

@@ -53,6 +53,13 @@ from ..persistence.db import Database
 from ..persistence.models import InteractiveSessionRow, MessageRow
 from ..persona import Persona, load_personas_from_dir
 from ..session import build_agent
+from ..skills import (
+    ensure_skills_initialized,
+    list_installed_skills,
+    read_skill_body,
+    resolve_skill_sources,
+    user_skills_dir,
+)
 from ..slash import SlashParsed, SlashRegistry, parse_slash
 
 _CONSOLE = Console()
@@ -158,6 +165,10 @@ class InteractiveSession:
         # the same repo across sessions hits the same memory.
         self.memory_dir: Path = project_memory_dir(config, project_key)
         ensure_memory_initialized(self.memory_dir)
+        # v0.3 PR #4: user-scope skills directory bootstrap.  Empty is normal —
+        # users drop `<name>/SKILL.md` directories under here to register skills.
+        self.skills_dir: Path = user_skills_dir(config)
+        ensure_skills_initialized(self.skills_dir)
 
     @property
     def thread_id(self) -> str:
@@ -223,6 +234,7 @@ class InteractiveSession:
         # Re-glob memory paths every time the agent is rebuilt — `/remember` and
         # `/forget` call `clear_agent_cache()` so this picks up new/removed files.
         memory_paths = list_memory_paths(self.memory_dir)
+        skill_sources = resolve_skill_sources(self.config)
         self._agent = build_agent(
             self._persona,
             self.config,
@@ -231,6 +243,7 @@ class InteractiveSession:
             model_override=self._model_override,
             checkpointer=self.saver,
             memory_paths_override=memory_paths,
+            skills_sources_override=skill_sources,
         )
         return self._agent
 
@@ -551,12 +564,45 @@ def _register_memory_slash(reg: SlashRegistry, sess: InteractiveSession) -> None
     reg.register("memory", _memory, help="list memory entries for this project")
 
 
+def _register_skills_slash(reg: SlashRegistry, sess: InteractiveSession) -> None:
+    """Register /skills (list) and /skill <name> (show body) slash handlers (PR #4)."""
+
+    async def _skills(_: SlashParsed) -> bool:
+        infos = list_installed_skills(sess.skills_dir)
+        _CONSOLE.print(f"[bold]installed skills[/]  ({sess.skills_dir})")
+        if not infos:
+            _CONSOLE.print(
+                "  [dim](none installed — drop a <name>/SKILL.md directory under the path above)[/]"
+            )
+            return False
+        for info in infos:
+            _CONSOLE.print(f"  - [cyan]{info.name}[/] — {info.description}")
+        return False
+
+    async def _skill(cmd: SlashParsed) -> bool:
+        if not cmd.args:
+            _CONSOLE.print("[yellow]usage:[/] /skill <name>  — show the full SKILL.md body")
+            return False
+        name = cmd.args[0]
+        body = read_skill_body(sess.skills_dir, name)
+        if body is None:
+            _CONSOLE.print(f"[yellow]no skill found:[/] {name}")
+            return False
+        _CONSOLE.print(f"[bold]{name}[/]  ({sess.skills_dir / name / 'SKILL.md'})")
+        _CONSOLE.print(body)
+        return False
+
+    reg.register("skills", _skills, help="list installed skills")
+    reg.register("skill", _skill, help="show a skill's body: /skill <name>")
+
+
 def _register_slash(reg: SlashRegistry, sess: InteractiveSession) -> None:
     _register_navigation_slash(reg, sess)
     _register_persona_slash(reg, sess)
     _register_telemetry_slash(reg)
     _register_compaction_slash(reg, sess)
     _register_memory_slash(reg, sess)
+    _register_skills_slash(reg, sess)
 
 
 def _completer(personas: list[Persona], slash_names: list[str]) -> WordCompleter:

my-deepagent/src/my_deepagent/session.py

@@ -206,6 +206,7 @@ def build_agent(
     phase_key: str | None = None,
     model_override: str | None = None,
     memory_paths_override: list[str] | None = None,
+    skills_sources_override: list[str] | None = None,
 ) -> Any:
     """Construct a deepagents CompiledStateGraph for the given persona.
 
@@ -268,8 +269,9 @@ def build_agent(
         kwargs["interrupt_on"] = persona.interrupt_on
     if checkpointer is not None:
         kwargs["checkpointer"] = checkpointer
-    if persona.skills:
+    skill_sources = _resolve_skill_sources(persona, skills_sources_override)
-        kwargs["skills"] = list(persona.skills)
+    if skill_sources:
+        kwargs["skills"] = skill_sources
     memory_paths = _resolve_memory_paths(persona, memory_paths_override)
     if memory_paths:
         kwargs["memory"] = memory_paths
@@ -290,3 +292,18 @@ def _resolve_memory_paths(persona: Persona, override: list[str] | None) -> list[
     if override:
         combined.extend(override)
     return combined
+
+
+def _resolve_skill_sources(persona: Persona, override: list[str] | None) -> list[str]:
+    """Combine persona-defined skill sources with caller-supplied directories.
+
+    v0.3 PR #4 — InteractiveSession passes `<config.data_dir>/skills/` so the
+    user-scope skills directory is always mounted in REPL sessions.  Workflow
+    runs (engine.py) currently don't pass an override, so they only see
+    persona-baked skills.  Order: persona skills first, then session/user
+    skills (last wins on name collision per `deepagents.SkillsMiddleware`).
+    """
+    combined: list[str] = list(persona.skills)
+    if override:
+        combined.extend(override)
+    return combined

my-deepagent/src/my_deepagent/skills.py

@@ -0,0 +1,170 @@
+"""Agent Skills (v0.3 PR #4) — LLM-routed progressive disclosure.
+
+Layout::
+
+    <config.data_dir>/skills/<skill-name>/SKILL.md
+                                          [optional supporting files]
+
+We mount this single directory as a source for ``deepagents.SkillsMiddleware``
+which:
+
+1. Parses every ``SKILL.md`` YAML frontmatter (``name``, ``description``, …)
+2. Injects an index of ``(name, description)`` pairs into the system prompt
+3. Lets the LLM decide which skill to invoke and read the full body with
+   ``read_file`` — no embeddings, no per-token vector lookup, no custom
+   routing logic.  Anthropic's Agent Skills specification verbatim.
+
+The skill name in the YAML frontmatter must match the parent directory name
+(``deepagents`` enforces this) — e.g. a skill directory ``web-research/``
+needs ``name: web-research`` inside its ``SKILL.md``.
+
+PR #4 keeps the surface area small: we mount one user-scope source and expose
+``/skills`` (list) and ``/skill <name>`` (show full body for inspection)
+slashes.  Project-scope skills (``<repo>/.mydeepagent/skills/``) are NOT wired
+in this PR — call sites can later layer them by passing additional sources
+through ``build_agent(skills_sources_override=...)``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from .config import Config
+
+#: Required filename inside each skill directory.
+SKILL_FILENAME = "SKILL.md"
+
+#: Maximum bytes we read from a SKILL.md when listing — guards against runaway
+#: files corrupting `/skills`.  10 MB matches deepagents' own DoS guard.
+_MAX_SKILL_READ_BYTES = 10 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class SkillInfo:
+    """Lightweight summary of one installed skill — used by `/skills` slash.
+
+    Fields are derived from the YAML frontmatter inside ``SKILL.md``:
+    - ``name``: directory name (also enforced inside frontmatter by deepagents)
+    - ``description``: 1-line summary, truncated if very long
+    - ``path``: absolute path of the ``SKILL.md`` for `/skill <name>` body display
+    """
+
+    name: str
+    description: str
+    path: Path
+
+
+def user_skills_dir(config: Config) -> Path:
+    """Return the user-scope skills directory (``<data_dir>/skills``)."""
+    return Path(config.data_dir) / "skills"
+
+
+def ensure_skills_initialized(skills_dir: Path) -> None:
+    """Create the skills directory if missing.
+
+    Unlike memory, we intentionally do NOT seed an example skill: an empty
+    skills directory is the normal new-install state.  Idempotent.
+    """
+    skills_dir.mkdir(parents=True, exist_ok=True)
+
+
+def _parse_skill_md(path: Path) -> SkillInfo | None:
+    """Parse a single SKILL.md file's frontmatter into a SkillInfo.
+
+    Returns None for unparseable or invalid files — callers list-iter and
+    silently skip bad entries rather than crashing the REPL on a malformed
+    SKILL.md.
+    """
+    try:
+        if path.stat().st_size > _MAX_SKILL_READ_BYTES:
+            return None
+        content = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    if not content.startswith("---"):
+        return None
+
+    # Extract YAML frontmatter between two `---` markers.  Anything else fails.
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        return None
+    try:
+        meta = yaml.safe_load(parts[1]) or {}
+    except yaml.YAMLError:
+        return None
+    if not isinstance(meta, dict):
+        return None
+
+    name = str(meta.get("name", "")).strip()
+    description = str(meta.get("description", "")).strip()
+    if not name or not description:
+        return None
+
+    # Per deepagents enforcement: the YAML name must match the parent dir.
+    parent_name = path.parent.name
+    if name != parent_name:
+        return None
+
+    # Truncate display description for `/skills` table — full body is shown by
+    # `/skill <name>`.
+    if len(description) > 200:
+        description = description[:200].rstrip() + "…"
+    return SkillInfo(name=name, description=description, path=path)
+
+
+def list_installed_skills(skills_dir: Path) -> list[SkillInfo]:
+    """Scan the directory for ``<name>/SKILL.md`` entries and return summaries.
+
+    - Sorted by name for deterministic UX
+    - Silently skips entries that fail validation (missing frontmatter,
+      name/dir mismatch, oversized files, …) so a single broken skill cannot
+      break `/skills` listing
+    - Returns an empty list if the directory does not exist
+    """
+    if not skills_dir.is_dir():
+        return []
+    found: list[SkillInfo] = []
+    for child in sorted(skills_dir.iterdir()):
+        if not child.is_dir():
+            continue
+        skill_md = child / SKILL_FILENAME
+        if not skill_md.is_file():
+            continue
+        info = _parse_skill_md(skill_md)
+        if info is not None:
+            found.append(info)
+    return found
+
+
+def read_skill_body(skills_dir: Path, name: str) -> str | None:
+    """Return the full SKILL.md content for the named skill, or None if missing.
+
+    Used by `/skill <name>` for quick inspection from the REPL.  The body
+    includes the YAML frontmatter — we deliberately don't strip it because
+    the user is likely interested in the metadata too.
+    """
+    if not name:
+        return None
+    skill_md = skills_dir / name / SKILL_FILENAME
+    if not skill_md.is_file():
+        return None
+    try:
+        if skill_md.stat().st_size > _MAX_SKILL_READ_BYTES:
+            return None
+        return skill_md.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+def resolve_skill_sources(config: Config) -> list[str]:
+    """Build the list of skill-directory sources to pass to deepagents.
+
+    Currently a single-entry list (user-scope).  Designed to be extended with
+    project-scope and team-scope sources in later PRs without changing the
+    caller interface.
+    """
+    return [str(user_skills_dir(config).resolve())]

my-deepagent/tests/integration/test_skills.py

@@ -0,0 +1,286 @@
+"""v0.3 PR #4 — Skills (LLM-routing) tests.
+
+Covers:
+1. Bootstrap creates the user skills directory (idempotent, no example seeded).
+2. `list_installed_skills` parses well-formed SKILL.md entries.
+3. Silently skips malformed entries (no frontmatter / bad YAML / name-dir mismatch).
+4. `read_skill_body` returns the full file contents or None for missing skills.
+5. `resolve_skill_sources` returns the user skills dir as a single source.
+6. End-to-end: `build_agent(..., skills_sources_override=[...])` forwards the
+   list as `create_deep_agent(skills=...)`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from textwrap import dedent
+from typing import Any
+
+import pytest
+
+from my_deepagent.config import load_config
+from my_deepagent.skills import (
+    SKILL_FILENAME,
+    SkillInfo,
+    ensure_skills_initialized,
+    list_installed_skills,
+    read_skill_body,
+    resolve_skill_sources,
+    user_skills_dir,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_skill(
+    skills_dir: Path, name: str, *, description: str | None = None, body: str = ""
+) -> Path:
+    """Drop a well-formed `<name>/SKILL.md` under skills_dir."""
+    skill_dir = skills_dir / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    desc = description if description is not None else f"description for {name}"
+    content = dedent(
+        f"""\
+        ---
+        name: {name}
+        description: {desc}
+        ---
+
+        # {name}
+        {body}
+        """
+    )
+    (skill_dir / SKILL_FILENAME).write_text(content, encoding="utf-8")
+    return skill_dir
+
+
+# ---------------------------------------------------------------------------
+# Bootstrap
+# ---------------------------------------------------------------------------
+
+
+def test_ensure_skills_initialized_creates_dir(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    assert not skills_dir.exists()
+    ensure_skills_initialized(skills_dir)
+    assert skills_dir.is_dir()
+    # Empty by design — no example skill seeded.
+    assert list(skills_dir.iterdir()) == []
+
+
+def test_ensure_skills_initialized_is_idempotent(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    ensure_skills_initialized(skills_dir)
+    _make_skill(skills_dir, "web-research")
+    # Should NOT wipe existing skills.
+    ensure_skills_initialized(skills_dir)
+    assert (skills_dir / "web-research" / SKILL_FILENAME).is_file()
+
+
+# ---------------------------------------------------------------------------
+# list_installed_skills
+# ---------------------------------------------------------------------------
+
+
+def test_list_installed_skills_returns_sorted_skillinfo(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    skills_dir.mkdir()
+    _make_skill(skills_dir, "b-tool", description="second")
+    _make_skill(skills_dir, "a-tool", description="first")
+    infos = list_installed_skills(skills_dir)
+    assert [i.name for i in infos] == ["a-tool", "b-tool"]
+    for info in infos:
+        assert isinstance(info, SkillInfo)
+        assert info.description
+        assert info.path.name == SKILL_FILENAME
+
+
+def test_list_installed_skills_skips_missing_skill_md(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    skills_dir.mkdir()
+    # Dir without SKILL.md should be skipped, not crash.
+    (skills_dir / "empty-skill").mkdir()
+    _make_skill(skills_dir, "good")
+    infos = list_installed_skills(skills_dir)
+    assert [i.name for i in infos] == ["good"]
+
+
+def test_list_installed_skills_skips_malformed_frontmatter(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    skills_dir.mkdir()
+
+    bad = skills_dir / "bad"
+    bad.mkdir()
+    (bad / SKILL_FILENAME).write_text("no frontmatter at all\nbody here", encoding="utf-8")
+
+    bad_yaml = skills_dir / "bad-yaml"
+    bad_yaml.mkdir()
+    (bad_yaml / SKILL_FILENAME).write_text(
+        "---\nname: bad-yaml\ndesc: [unclosed\n---\n", encoding="utf-8"
+    )
+
+    _make_skill(skills_dir, "good")
+
+    infos = list_installed_skills(skills_dir)
+    assert [i.name for i in infos] == ["good"]
+
+
+def test_list_installed_skills_skips_name_dir_mismatch(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    skills_dir.mkdir()
+    # Directory "mismatch" but frontmatter name "other-name" → invalid per deepagents.
+    skill_dir = skills_dir / "mismatch"
+    skill_dir.mkdir()
+    (skill_dir / SKILL_FILENAME).write_text(
+        "---\nname: other-name\ndescription: bad mismatch\n---\nbody\n", encoding="utf-8"
+    )
+    assert list_installed_skills(skills_dir) == []
+
+
+def test_list_installed_skills_missing_dir_returns_empty(tmp_path: Path) -> None:
+    assert list_installed_skills(tmp_path / "no-skills-dir") == []
+
+
+def test_list_installed_skills_truncates_long_description(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    skills_dir.mkdir()
+    long_desc = "x" * 500
+    _make_skill(skills_dir, "long", description=long_desc)
+    infos = list_installed_skills(skills_dir)
+    assert len(infos) == 1
+    # Truncated to 200 chars + ellipsis.
+    assert len(infos[0].description) <= 201
+    assert infos[0].description.endswith("…")
+
+
+# ---------------------------------------------------------------------------
+# read_skill_body
+# ---------------------------------------------------------------------------
+
+
+def test_read_skill_body_returns_full_text(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    skills_dir.mkdir()
+    _make_skill(skills_dir, "web-research", body="Use Google.")
+    body = read_skill_body(skills_dir, "web-research")
+    assert body is not None
+    assert "name: web-research" in body
+    assert "Use Google" in body
+
+
+def test_read_skill_body_missing_returns_none(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    skills_dir.mkdir()
+    assert read_skill_body(skills_dir, "nonexistent") is None
+
+
+def test_read_skill_body_empty_name_returns_none(tmp_path: Path) -> None:
+    skills_dir = tmp_path / "skills"
+    skills_dir.mkdir()
+    assert read_skill_body(skills_dir, "") is None
+
+
+# ---------------------------------------------------------------------------
+# user_skills_dir / resolve_skill_sources
+# ---------------------------------------------------------------------------
+
+
+def test_user_skills_dir_under_data_dir(tmp_path: Path) -> None:
+    cfg = load_config(workspace_root=tmp_path, data_dir=tmp_path / "data")
+    sd = user_skills_dir(cfg)
+    assert sd.parent == cfg.data_dir
+    assert sd.name == "skills"
+
+
+def test_resolve_skill_sources_returns_user_dir(tmp_path: Path) -> None:
+    cfg = load_config(workspace_root=tmp_path, data_dir=tmp_path / "data")
+    sources = resolve_skill_sources(cfg)
+    assert len(sources) == 1
+    assert sources[0] == str(user_skills_dir(cfg).resolve())
+
+
+# ---------------------------------------------------------------------------
+# Integration: build_agent threads skills sources to deepagents
+# ---------------------------------------------------------------------------
+
+
+def test_build_agent_passes_skills_sources_to_deepagents(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from my_deepagent import session as session_mod
+    from my_deepagent.persona import Persona
+
+    captured: dict[str, Any] = {}
+
+    def fake_create_deep_agent(**kwargs: Any) -> Any:
+        captured.update(kwargs)
+        return object()
+
+    monkeypatch.setattr(session_mod, "create_deep_agent", fake_create_deep_agent)
+
+    persona = Persona(
+        name="test-persona",
+        version=1,
+        backend="openrouter",
+        model="openrouter:deepseek/deepseek-chat",
+        provider_origin="CN/DeepSeek",
+        capabilities=("code_edit",),
+        max_risk_level="high",
+        system_prompt="System prompt for test persona (must be ≥10 chars)",
+        deepagents_backend="state",
+    )
+    cfg = load_config(
+        workspace_root=tmp_path,
+        data_dir=tmp_path / "data",
+        openrouter_api_key="test-key",
+    )
+
+    skills_dir = tmp_path / "user-skills"
+    ensure_skills_initialized(skills_dir)
+    _make_skill(skills_dir, "noop", description="does nothing")
+
+    _agent = session_mod.build_agent(
+        persona,
+        cfg,
+        root_dir=tmp_path,
+        skills_sources_override=[str(skills_dir)],
+    )
+    assert "skills" in captured
+    assert captured["skills"] == [str(skills_dir)]
+
+
+def test_build_agent_skips_skills_kwarg_when_none(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from my_deepagent import session as session_mod
+    from my_deepagent.persona import Persona
+
+    captured: dict[str, Any] = {}
+
+    def fake_create_deep_agent(**kwargs: Any) -> Any:
+        captured.update(kwargs)
+        return object()
+
+    monkeypatch.setattr(session_mod, "create_deep_agent", fake_create_deep_agent)
+
+    persona = Persona(
+        name="test-persona",
+        version=1,
+        backend="openrouter",
+        model="openrouter:deepseek/deepseek-chat",
+        provider_origin="CN/DeepSeek",
+        capabilities=("code_edit",),
+        max_risk_level="high",
+        system_prompt="System prompt for test persona (must be ≥10 chars)",
+        deepagents_backend="state",
+    )
+    cfg = load_config(
+        workspace_root=tmp_path,
+        data_dir=tmp_path / "data",
+        openrouter_api_key="test-key",
+    )
+
+    _agent = session_mod.build_agent(persona, cfg, root_dir=tmp_path)
+    assert "skills" not in captured