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>
This commit is contained in:
chungyeong
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
kwargs["skills"] = list(persona.skills)
|
||||
skill_sources = _resolve_skill_sources(persona, skills_sources_override)
|
||||
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
|
||||
|
||||
170
my-deepagent/src/my_deepagent/skills.py
Normal file
170
my-deepagent/src/my_deepagent/skills.py
Normal file
@@ -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())]
|
||||
Reference in New Issue
Block a user