bareagent-cli 0.1.0__py3-none-any.whl

bareagent/permission/rules.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def parse_permission_rules(config: dict[str, Any]) -> tuple[list[str], list[str]]:
+    """Parse allow and deny permission rules from config data."""
+    permission_config = config.get("permission", {})
+    allow = _coerce_rule_list(permission_config.get("allow", []))
+    deny = _coerce_rule_list(permission_config.get("deny", []))
+    return allow, deny
+
+
+def _coerce_rule_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    return [str(rule) for rule in value]

bareagent/planning/__init__.py

@@ -0,0 +1,19 @@
+"""Planning modules for BareAgent."""
+
+from bareagent.planning.agent_types import BUILTIN_AGENT_TYPES, DEFAULT_AGENT_TYPE, AgentType
+from bareagent.planning.skills import SkillLoader, SkillMeta
+from bareagent.planning.subagent import run_subagent
+from bareagent.planning.tasks import Task, TaskManager
+from bareagent.planning.todo import TodoManager
+
+__all__ = [
+    "AgentType",
+    "BUILTIN_AGENT_TYPES",
+    "DEFAULT_AGENT_TYPE",
+    "SkillLoader",
+    "SkillMeta",
+    "Task",
+    "TaskManager",
+    "TodoManager",
+    "run_subagent",
+]

bareagent/planning/agent_types.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from bareagent.permission.guard import PermissionMode
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class AgentType:
+    """Definition for a built-in child-agent profile."""
+
+    name: str
+    description: str
+    system_prompt: str = ""
+    tools: list[str] | None = None
+    disallowed_tools: list[str] | None = None
+    max_turns: int = 200
+    allow_nesting: bool = True
+    permission_mode: PermissionMode | None = None
+    # When False, ``filter_tools`` strips every ``mcp__*`` tool. Used by
+    # read-only agent types (explore / plan / code-review) to keep MCP side
+    # effects out of subagent contexts. Defaults to True for backwards
+    # compatibility with custom user-defined agent types.
+    mcp_tools_enabled: bool = True
+    # When False, ``filter_tools`` strips every ``lsp_*`` tool. The four
+    # Tier-1 LSP tools are read-only (outline / definition / references /
+    # diagnostics), so read-only agent types keep them enabled by default —
+    # this flag exists for tighter sandboxes that want a strict allow-list.
+    lsp_tools_enabled: bool = True
+    # The ``memory`` tool is a single tool with a ``command`` enum, so it
+    # cannot be downgraded to read-only by name-filtering like mcp/lsp. When
+    # False, the subagent layer wraps the handler to reject the write commands
+    # (create/str_replace/insert/delete/rename) while still allowing ``view``.
+    # Read-only agent types default to False so they can recall but not mutate
+    # shared memory.
+    memory_writable: bool = True
+
+
+# Tools that only make sense in the main REPL loop and must never reach a
+# sub-agent, regardless of agent type. ``exit_plan_mode`` flips the *parent's*
+# permission mode through an interactive approval prompt -- a sub-agent has no
+# human to ask and no business mutating the parent's mode. ``workflow`` fans out
+# its own subagents; letting a sub-agent call it would allow unbounded nesting
+# (out of scope for the MVP). ``subagent_send`` resumes a foreground subagent
+# from the REPL-scoped registry; only the main loop spawns resumable contexts,
+# so a sub-agent has nothing to continue. ``skill_create`` stays out of
+# sub-agents by never joining the global tool set; ``exit_plan_mode`` /
+# ``workflow`` / ``subagent_send`` do live in the main loop's set, so they are
+# stripped here as a centralized, agent-type-independent guarantee
+# (filter_handlers then drops the orphaned handler).
+MAIN_LOOP_ONLY_TOOLS = frozenset({"exit_plan_mode", "workflow", "subagent_send"})
+
+
+_READ_ONLY_DEFAULTS: dict[str, Any] = {
+    # ``semantic_rename`` is a write tool that does not carry the ``lsp_`` name
+    # prefix (so ``lsp_tools_enabled=True`` does not filter it). It must be
+    # denied explicitly here, otherwise read-only agents would keep a tool that
+    # mutates files across the workspace.
+    "disallowed_tools": [
+        "write_file",
+        "edit_file",
+        "bash",
+        "subagent",
+        "semantic_rename",
+    ],
+    "max_turns": 50,
+    "allow_nesting": False,
+    "permission_mode": PermissionMode.PLAN,
+    "mcp_tools_enabled": False,
+    "lsp_tools_enabled": True,
+    "memory_writable": False,
+}
+
+BUILTIN_AGENT_TYPES: dict[str, AgentType] = {
+    "general-purpose": AgentType(
+        name="general-purpose",
+        description="General child agent with the full inherited toolset.",
+    ),
+    "explore": AgentType(
+        name="explore",
+        description="Read-only agent for code search and repository understanding.",
+        system_prompt=(
+            "You are a read-only exploration agent. Search and inspect the repository, "
+            "but do not modify files or perform side effects."
+        ),
+        **_READ_ONLY_DEFAULTS,
+    ),
+    "plan": AgentType(
+        name="plan",
+        description="Planning agent for implementation design without repository mutation.",
+        system_prompt=(
+            "You are a planning agent. Analyze the codebase and produce an implementation "
+            "plan, but do not modify files or perform side effects."
+        ),
+        **_READ_ONLY_DEFAULTS,
+    ),
+    "code-review": AgentType(
+        name="code-review",
+        description="Read-only review agent for bugs, regressions, and code quality issues.",
+        system_prompt=(
+            "You are a code review agent. Inspect code for defects, regressions, security "
+            "issues, and maintainability risks. Do not modify files."
+        ),
+        **_READ_ONLY_DEFAULTS,
+    ),
+}
+
+DEFAULT_AGENT_TYPE = "general-purpose"
+
+
+def resolve_agent_type(
+    name: str | None,
+    *,
+    default_name: str = DEFAULT_AGENT_TYPE,
+) -> AgentType:
+    """Resolve a child-agent type, falling back to the configured default."""
+
+    resolved_default = BUILTIN_AGENT_TYPES.get(
+        default_name, BUILTIN_AGENT_TYPES[DEFAULT_AGENT_TYPE]
+    )
+    if name is None:
+        return resolved_default
+    if name not in BUILTIN_AGENT_TYPES:
+        _log.warning("Unknown agent type %r, falling back to %r", name, resolved_default.name)
+        return resolved_default
+    return BUILTIN_AGENT_TYPES[name]
+
+
+def filter_tools(
+    all_tools: list[dict[str, Any]],
+    agent_type: AgentType,
+) -> list[dict[str, Any]]:
+    """Apply whitelist, blacklist, and nesting controls to a tool schema list."""
+
+    allowed = set(agent_type.tools) if agent_type.tools is not None else None
+    denied = set(agent_type.disallowed_tools) if agent_type.disallowed_tools is not None else None
+    strip_nesting = not agent_type.allow_nesting
+
+    def _keep(tool: dict[str, Any]) -> bool:
+        name = str(tool.get("name"))
+        if name in MAIN_LOOP_ONLY_TOOLS:
+            return False
+        if allowed is not None and name not in allowed:
+            return False
+        if denied is not None and name in denied:
+            return False
+        if strip_nesting and name == "subagent":
+            return False
+        if not agent_type.mcp_tools_enabled and name.startswith("mcp__"):
+            return False
+        if not agent_type.lsp_tools_enabled and name.startswith("lsp_"):
+            return False
+        return True
+
+    return [tool for tool in all_tools if _keep(tool)]
+
+
+def filter_handlers(
+    all_handlers: dict[str, Any],
+    filtered_tools: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Keep only handlers that still have a matching tool schema."""
+
+    allowed_names = {str(tool.get("name")) for tool in filtered_tools}
+    return {name: handler for name, handler in all_handlers.items() if name in allowed_names}

bareagent/planning/skill_gen.py

@@ -0,0 +1,141 @@
+"""Experiential skill generation: decide when to draft a reusable skill.
+
+Pure logic with no LLM / loop / SDK dependencies so it is unit-testable in
+isolation (mirrors the ``src/core/retry.py`` pure-module pattern). The agent
+loop feeds per-turn tool-call counts into :class:`SkillGenerator`, which
+accumulates them across user turns and reports when both thresholds are crossed.
+The actual reflection LLM call + draft persistence live in the REPL / store
+layers; this module only owns the *trigger decision* and the draft instruction
+text.
+
+Design (see task 06-01-experiential-skill-gen):
+- A "task worth saving" spans multiple user turns AND involves real tool work.
+  So the trigger is a double AND: cumulative ``tool_calls >= min_tool_calls``
+  and cumulative ``user_replies >= min_user_replies``.
+- Counters accumulate from session start / last draft and reset on each trigger,
+  so one multi-turn workflow is packed into a single skill rather than firing
+  every turn.
+- ``enabled=False`` short-circuits everything: no counting, never drafts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class SkillGenConfig:
+    """Thresholds + master switch for experiential skill generation.
+
+    Mirrors the user-facing ``[skills]`` config (``main.py`` builds this from
+    ``SkillsConfig`` the same way ``_build_retry_policy`` adapts ``RetryConfig``
+    to ``RetryPolicy``).
+    """
+
+    enabled: bool = True
+    min_tool_calls: int = 5
+    min_user_replies: int = 3
+
+
+def should_draft_skill(
+    tool_calls: int,
+    user_replies: int,
+    config: SkillGenConfig,
+) -> bool:
+    """Return True when the accumulated activity warrants drafting a skill.
+
+    Double AND on the two thresholds; always False when disabled. Pure function
+    so the decision is directly unit-testable without constructing a generator.
+    """
+    if not config.enabled:
+        return False
+    return tool_calls >= config.min_tool_calls and user_replies >= config.min_user_replies
+
+
+# Instruction injected as a user turn for the isolated reflection call. It lets
+# the model DECLINE (respond "no skill") so a low-value, one-off task does not
+# get forced into a skill — a second quality gate on top of the user-promote
+# step. The model is told to call ``skill_create`` exactly once when it does
+# decide the workflow is worth preserving.
+DRAFT_INSTRUCTION = (
+    "You just finished a multi-step task spanning several turns. If — and only "
+    "if — there is a genuinely reusable, non-trivial workflow worth preserving "
+    "for next time, capture it as a skill by calling the `skill_create` tool "
+    "exactly once.\n\n"
+    "Distill the procedure so a future agent with no memory of this session "
+    "could follow it:\n"
+    '- name: short kebab-case identifier (e.g. "add-config-section").\n'
+    '- description: one line starting with "Use this when".\n'
+    "- body: markdown with sections like Steps / Pitfalls / Verification, "
+    "including dead-ends you hit and how you got past them.\n\n"
+    "If the work was too trivial or one-off to generalize, do NOT call the "
+    'tool — reply with the single line "no skill" instead.'
+)
+
+
+def render_reflection_prompt(candidates: list[tuple[str, str]]) -> str:
+    """Build the reflection user message, optionally offering skills to refine.
+
+    Self-evolution (task 06-01-skill-self-evolution): when generated skills
+    already exist they are listed as refinement targets — the model is told to
+    reuse a skill's EXACT name (after reading it with ``load_skill``) so the new
+    draft supersedes it on promotion, rather than piling up a near-duplicate.
+
+    With no candidates this returns the bare :data:`DRAFT_INSTRUCTION`
+    (byte-identical to the pre-evolution create-only behavior).
+    """
+    if not candidates:
+        return DRAFT_INSTRUCTION
+    listing = "\n".join(f"- {name}: {desc}" for name, desc in candidates)
+    prefix = (
+        "Existing generated skills you may REFINE instead of duplicating. If "
+        "this session improves one of them, read it first with `load_skill`, "
+        "then call `skill_create` with that skill's EXACT name so your improved "
+        "version supersedes it. Otherwise use a fresh name. Never reuse a "
+        "built-in (repo) skill name.\n"
+        f"{listing}\n\n"
+    )
+    return prefix + DRAFT_INSTRUCTION
+
+
+class SkillGenerator:
+    """Accumulates per-turn activity and decides when to draft a skill.
+
+    Lives for the whole REPL session and is passed into the *main* ``agent_loop``
+    only (sub-agents never receive it, so background / nested agents never
+    trigger generation — same isolation stance as ``hook_engine``). The loop
+    calls :meth:`note_turn` once per completed user turn; the REPL then checks
+    :meth:`should_draft` and runs the reflection.
+    """
+
+    __slots__ = ("config", "_tool_calls", "_user_replies")
+
+    def __init__(self, config: SkillGenConfig) -> None:
+        self.config = config
+        self._tool_calls = 0
+        self._user_replies = 0
+
+    @property
+    def enabled(self) -> bool:
+        return self.config.enabled
+
+    @property
+    def counters(self) -> tuple[int, int]:
+        """Current ``(tool_calls, user_replies)`` accumulators (for tests / logs)."""
+        return (self._tool_calls, self._user_replies)
+
+    def note_turn(self, turn_tool_calls: int) -> None:
+        """Record one completed user turn that ran ``turn_tool_calls`` tools."""
+        if not self.config.enabled:
+            return
+        self._tool_calls += max(0, int(turn_tool_calls))
+        self._user_replies += 1
+
+    def should_draft(self) -> bool:
+        """Whether the accumulated activity has crossed both thresholds."""
+        return should_draft_skill(self._tool_calls, self._user_replies, self.config)
+
+    def reset(self) -> None:
+        """Zero the accumulators (on trigger, or on session boundary)."""
+        self._tool_calls = 0
+        self._user_replies = 0

bareagent/planning/skill_store.py

@@ -0,0 +1,173 @@
+"""Storage for experientially generated skills (drafts + promotion).
+
+Generated skills live OUTSIDE the repo's checked-in ``skills/`` (which is the
+hand-written canon) to avoid polluting version control. They go under the
+user-global BareAgent home, project-isolated by workspace slug — mirroring the
+persistent-memory directory convention (``derive_memory_slug``). Drafts land in
+a ``.pending/`` subdirectory and only become loadable once the user promotes
+them with ``/skill keep``.
+
+Layout (``root`` = generated skills root for this project)::
+
+    <root>/<skill>/SKILL.md            # live (loadable) generated skills
+    <root>/.pending/<skill>/SKILL.md   # drafts awaiting /skill keep
+
+Pure filesystem logic with no LLM/loop dependency — unit-testable in isolation.
+The agent-facing ``skill_create`` tool and the ``/skill`` REPL command are thin
+layers over this store.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from bareagent.core.fileutil import atomic_write_text
+from bareagent.memory.persistent import derive_memory_slug
+
+PENDING_DIRNAME = ".pending"
+_SKILL_FILE = "SKILL.md"
+
+
+class SkillStoreError(ValueError):
+    """Raised for caller-facing storage failures (bad name, missing draft)."""
+
+
+def derive_skill_slug(name: str) -> str:
+    """Slugify a skill name into a safe single path segment.
+
+    Lowercases, collapses any non ``[a-z0-9]`` run to a single hyphen, and
+    strips leading/trailing hyphens. This also neutralizes path traversal
+    (``../`` etc.) since separators become hyphens. Empty result is rejected by
+    the callers as an invalid name.
+    """
+    slug = re.sub(r"[^a-z0-9]+", "-", name.strip().lower()).strip("-")
+    return slug
+
+
+def default_generated_skills_root(workspace: Path) -> Path:
+    """Per-project generated-skills directory under the user-global home."""
+    return Path.home() / ".bareagent" / "projects" / derive_memory_slug(workspace) / "skills"
+
+
+def resolve_generated_skills_root(workspace: Path, configured_dir: str) -> Path:
+    """Resolve the generated-skills root from config.
+
+    Empty ``configured_dir`` falls back to :func:`default_generated_skills_root`.
+    A relative override is taken relative to the workspace; an absolute one is
+    used as-is. Mirrors ``resolve_memory_root``.
+    """
+    configured = (configured_dir or "").strip()
+    if not configured:
+        return default_generated_skills_root(workspace)
+    candidate = Path(configured).expanduser()
+    if not candidate.is_absolute():
+        candidate = workspace / candidate
+    return candidate
+
+
+def _render_skill_md(name: str, description: str, body: str) -> str:
+    """Render SKILL.md in the format ``SkillLoader`` expects.
+
+    The description must be the first non-empty, non-``#`` line so
+    ``SkillLoader._extract_description`` picks it up.
+    """
+    desc = description.strip() or "No description provided."
+    sections = [f"# {name}", "", desc]
+    body = body.strip()
+    if body:
+        sections += ["", body]
+    return "\n".join(sections).rstrip() + "\n"
+
+
+@dataclass(slots=True)
+class SkillStore:
+    """Create / promote / discard / list generated skills under ``root``."""
+
+    root: Path
+
+    @property
+    def pending_root(self) -> Path:
+        return self.root / PENDING_DIRNAME
+
+    def create_draft(self, name: str, description: str, body: str) -> str:
+        """Write a draft SKILL.md under ``.pending/<slug>/`` and return a note."""
+        slug = derive_skill_slug(name)
+        if not slug:
+            raise SkillStoreError(f"invalid skill name: {name!r}")
+        target = self.pending_root / slug / _SKILL_FILE
+        atomic_write_text(target, _render_skill_md(slug, description, body))
+        return f"Drafted skill '{slug}' to pending (use /skill keep {slug} to keep it)."
+
+    def promote(self, name: str) -> str:
+        """Move a draft from ``.pending/`` to the live root (replacing any live)."""
+        slug = derive_skill_slug(name)
+        src = self.pending_root / slug
+        if not (src / _SKILL_FILE).exists():
+            raise SkillStoreError(f"no pending draft named {slug!r}")
+        dest = self.root / slug
+        if dest.exists():
+            shutil.rmtree(dest, ignore_errors=True)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(src), str(dest))
+        return f"Promoted skill '{slug}' — it is now loadable."
+
+    def discard(self, name: str) -> str:
+        """Delete a pending draft."""
+        slug = derive_skill_slug(name)
+        src = self.pending_root / slug
+        if not (src / _SKILL_FILE).exists():
+            raise SkillStoreError(f"no pending draft named {slug!r}")
+        shutil.rmtree(src, ignore_errors=True)
+        return f"Discarded pending skill '{slug}'."
+
+    def list_live(self) -> list[str]:
+        """Names of promoted (loadable) generated skills, sorted."""
+        return self._list_skill_dirs(self.root)
+
+    def list_pending(self) -> list[str]:
+        """Names of pending drafts, sorted."""
+        return self._list_skill_dirs(self.pending_root)
+
+    def prune_pending(self, max_pending: int) -> list[str]:
+        """Drop oldest pending drafts beyond ``max_pending``; return removed names.
+
+        Count-based soft cap (no time TTL): keep the ``max_pending`` newest
+        drafts by SKILL.md mtime, remove the rest. ``max_pending <= 0`` disables
+        pruning.
+        """
+        if max_pending <= 0:
+            return []
+        entries = self._pending_entries_by_mtime()
+        if len(entries) <= max_pending:
+            return []
+        removed: list[str] = []
+        for _mtime, slug, path in entries[: len(entries) - max_pending]:
+            shutil.rmtree(path, ignore_errors=True)
+            removed.append(slug)
+        return removed
+
+    def _pending_entries_by_mtime(self) -> list[tuple[float, str, Path]]:
+        """Pending ``(mtime, slug, dir)`` tuples, oldest first (ties by name)."""
+        entries: list[tuple[float, str, Path]] = []
+        try:
+            paths = sorted(self.pending_root.glob(f"*/{_SKILL_FILE}"))
+        except OSError:
+            return []
+        for skill_file in paths:
+            try:
+                mtime = skill_file.stat().st_mtime
+            except OSError:
+                mtime = 0.0
+            entries.append((mtime, skill_file.parent.name, skill_file.parent))
+        entries.sort(key=lambda item: (item[0], item[1]))
+        return entries
+
+    @staticmethod
+    def _list_skill_dirs(base: Path) -> list[str]:
+        try:
+            return sorted(p.parent.name for p in base.glob(f"*/{_SKILL_FILE}"))
+        except OSError:
+            return []

bareagent/planning/skills.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from bareagent.core.schema import tool_schema as _schema
+
+LOAD_SKILL_TOOL_SCHEMAS: list[dict[str, Any]] = [
+    _schema(
+        "load_skill",
+        "Load the full content of a named SKILL.md file on demand.",
+        {
+            "skill_name": {
+                "type": "string",
+                "description": "The skill directory name to load.",
+            }
+        },
+        ["skill_name"],
+    )
+]
+
+
+@dataclass(slots=True)
+class SkillMeta:
+    skill_name: str
+    description: str
+    path: Path
+
+
+def resolve_skills_dir() -> Path:
+    """Locate the bundled canon skills directory.
+
+    Honors the ``BAREAGENT_SKILLS_DIR`` override first (if it exists); otherwise
+    resolves the ``skills/`` tree bundled inside the package
+    (``src/bareagent/skills``) via importlib.resources, which works for both
+    editable and wheel installs. BareAgent is never a zipapp, so the resource is
+    a real on-disk directory that supports ``.glob()``.
+    """
+    env_path = os.getenv("BAREAGENT_SKILLS_DIR")
+    if env_path:
+        candidate = Path(env_path).expanduser()
+        if candidate.exists():
+            return candidate.resolve()
+
+    return Path(str(files("bareagent").joinpath("skills"))).resolve()
+
+
+class SkillLoader:
+    def __init__(self, skills_dir: Path, generated_root: Path | None = None) -> None:
+        # ``skills_dir`` is the repo's checked-in canon. ``generated_root`` is the
+        # optional experiential-skill layer (live promoted skills only — its
+        # ``.pending/`` drafts are NOT scanned because the glob is one level
+        # deep). Canon wins on name conflicts.
+        self.skills_dir = skills_dir
+        self.generated_root = generated_root
+        self._cache: dict[str, SkillMeta] = {}
+
+    def scan(self) -> list[SkillMeta]:
+        skills: list[SkillMeta] = []
+        cache: dict[str, SkillMeta] = {}
+
+        # Order matters: scan canon first so a generated skill never shadows a
+        # repo skill of the same name.
+        roots = [self.skills_dir]
+        if self.generated_root is not None:
+            roots.append(self.generated_root)
+
+        for root in roots:
+            try:
+                entries = sorted(root.glob("*/SKILL.md"))
+            except OSError:
+                continue
+            for skill_file in entries:
+                skill_name = skill_file.parent.name
+                if skill_name in cache:
+                    continue
+                description = self._extract_description(skill_file)
+                meta = SkillMeta(
+                    skill_name=skill_name,
+                    description=description,
+                    path=skill_file,
+                )
+                skills.append(meta)
+                cache[skill_name] = meta
+
+        self._cache = cache
+        return skills
+
+    def load(self, skill_name: str) -> str:
+        meta = self._lookup(skill_name)
+        return meta.path.read_text(encoding="utf-8").strip()
+
+    def canon_skill_names(self) -> set[str]:
+        """Names of the repo's checked-in canon skills (``skills_dir`` only).
+
+        Used by the self-evolution reflection to forbid generated skills from
+        colliding with a canon name — such a generated skill would be shadowed
+        (canon wins in :meth:`scan`) and never load, i.e. a dead skill.
+        """
+        try:
+            return {skill_file.parent.name for skill_file in self.skills_dir.glob("*/SKILL.md")}
+        except OSError:
+            return set()
+
+    def get_skill_list_prompt(self) -> str:
+        skills = self.scan()
+        if not skills:
+            return "No skills are available."
+
+        lines = [
+            "Available skills (load the full SKILL.md only when you need the details):"
+        ]
+        for skill in skills:
+            lines.append(f"- {skill.skill_name}: {skill.description}")
+        return "\n".join(lines)
+
+    def _lookup(self, skill_name: str) -> SkillMeta:
+        normalized = skill_name.strip()
+        if not normalized:
+            raise ValueError("skill_name must not be empty")
+
+        meta = self._cache.get(normalized)
+        if meta is None:
+            self.scan()
+            meta = self._cache.get(normalized)
+        if meta is None:
+            raise ValueError(f"Unknown skill: {skill_name}")
+        return meta
+
+    def _extract_description(self, skill_file: Path) -> str:
+        with skill_file.open(encoding="utf-8") as fh:
+            for raw_line in fh:
+                line = raw_line.strip()
+                if not line:
+                    continue
+                if line.startswith("#"):
+                    continue
+                return line
+        return "No description provided."
+
+
+def make_skill_handlers(skill_loader: SkillLoader) -> dict[str, Any]:
+    return {"load_skill": skill_loader.load}