feat(skills): auto-injectable skill manifest + discovery="inject" mode

Progressive-disclosure discovery (Anthropic Agent-Skills style): instead of the
model spending a tool turn on list_skills to learn the catalog, the caller can
inject the catalog into the system prompt once at startup.

- render_skills_manifest(skill_dir, header=None): one `- name: description` line
  per skill; "" when empty. The discovery-level metadata to inject.
- load_skills_as_tools(skill_dir, discovery="list"|"inject"): "list" (default,
  backward-compatible) returns [list_skills, read_skill]; "inject" returns
  [read_skill] only (discovery handled by the injected manifest). read_skill stays
  as the just-in-time full-body activation path in both modes.

Default is unchanged, so existing consumers keep the 2-tuple. Export
render_skills_manifest from the package root.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: qazbnm456

rlm_kit/__init__.py

@@ -24,7 +24,7 @@
 from .dataset import export_actions, export_rl, export_sft_turns
 from .replay import RecordedToolProvider, load_timeline, reconstruct
 from .sandbox import SandboxSecurityError
-from .skills import discover_skills, load_skills_as_tools
+from .skills import discover_skills, load_skills_as_tools, render_skills_manifest
 from .sub_lm import SubLMValidationError, intercept_sub_lm, model_as_tool
 from .trace import (
     TraceRecorder,
@@ -46,6 +46,7 @@
     "SubLMValidationError",
     "model_as_tool",
     "load_skills_as_tools",
+    "render_skills_manifest",
     "discover_skills",
     # tracing (Phase B)
     "TraceRecorder",

rlm_kit/skills.py

@@ -2,9 +2,19 @@
 
 A "Skill" here follows the common convention of a folder containing a ``SKILL.md``
 (with optional YAML-ish frontmatter for ``name``/``description``), or a flat
-``<name>.md`` file. We surface two tools to the main LM so it can decide, inside
-the REPL, which skill to read — keeping control flow in the LM's hands (the run
-stays an RLM, and the decision lands in the trajectory).
+``<name>.md`` file. The main LM decides, inside the REPL, which skill to read —
+keeping control flow in the LM's hands (the run stays an RLM, and the decision
+lands in the trajectory).
+
+Two DISCOVERY models, per the ``discovery`` arg of :func:`load_skills_as_tools`
+(progressive disclosure, Anthropic Agent-Skills style):
+
+- ``"list"`` — surface a ``list_skills`` tool; the LM calls it to see the catalog
+  (a discovery round-trip that costs one tool turn). The default; backward-compatible.
+- ``"inject"`` — the caller injects the catalog into the system prompt once at
+  startup via :func:`render_skills_manifest`, so the LM always knows which skills
+  exist without a tool call; only ``read_skill`` (the just-in-time full-body pull)
+  is surfaced as a tool.
 
 Pure stdlib; no dspy import.
 """
@@ -84,12 +94,42 @@ def _safe_read(path: str) -> str:
         return ""
 
 
-def load_skills_as_tools(skill_dir: str) -> list[Callable]:
-    """Return two tools — ``list_skills`` and ``read_skill`` — over ``skill_dir``.
+def render_skills_manifest(skill_dir: str, *, header: Optional[str] = None) -> str:
+    """Render the skill catalog — one ``- name: description`` line per skill — for injection
+    into a system prompt. This is the DISCOVERY level of progressive disclosure (Anthropic
+    Agent Skills): surface every skill's metadata ONCE at startup so the model always knows
+    which skills exist, instead of spending a turn calling ``list_skills`` to find out. Pair it
+    with ``load_skills_as_tools(skill_dir, discovery="inject")``, which then omits ``list_skills``
+    and keeps only ``read_skill`` (the just-in-time full-body pull).
+
+    Returns ``""`` when the directory holds no skills (nothing to inject). ``header``, when
+    given, is prepended on its own line (e.g. an ``<available_skills>`` label).
+    """
+    skills = discover_skills(skill_dir)
+    if not skills:
+        return ""
+    body = "\n".join(
+        f"- {s.name}: {s.description or '(no description)'}" for s in skills
+    )
+    return f"{header}\n{body}" if header else body
+
+
+def load_skills_as_tools(skill_dir: str, *, discovery: str = "list") -> list[Callable]:
+    """Return the skill tools over ``skill_dir``.
+
+    ``discovery`` selects HOW the model learns which skills exist:
+
+    - ``"list"`` (default): return ``[list_skills, read_skill]``. The model calls ``list_skills``
+      to see the catalog — a discovery round-trip that costs one tool turn. Backward-compatible.
+    - ``"inject"``: return ``[read_skill]`` ONLY. The caller injects the catalog into the system
+      prompt via :func:`render_skills_manifest` (skill metadata auto-surfaced at startup, no
+      discovery tool call). ``read_skill`` stays as the just-in-time activation path.
 
-    Both record a ``tool_call`` event so skill access shows up in the trajectory
-    and the RL dataset.
+    ``read_skill`` (and ``list_skills`` when present) records a ``tool_call`` event so skill
+    access shows up in the trajectory and the RL dataset.
     """
+    if discovery not in ("list", "inject"):
+        raise ValueError(f"discovery must be 'list' or 'inject', got {discovery!r}")
     skills = {s.name: s for s in discover_skills(skill_dir)}
 
     def list_skills() -> str:
@@ -114,4 +154,4 @@ def read_skill(name: str) -> str:
                          preview=result[:_PREVIEW_CHARS])
         return result
 
-    return [list_skills, read_skill]
+    return [read_skill] if discovery == "inject" else [list_skills, read_skill]

tests/test_skills.py

@@ -1,4 +1,10 @@
-from rlm_kit.skills import discover_skills, load_skills_as_tools
+import pytest
+
+from rlm_kit.skills import (
+    discover_skills,
+    load_skills_as_tools,
+    render_skills_manifest,
+)
 from rlm_kit.trace import EVENT_TOOL_CALL, TraceRecorder, load_events
 
 
@@ -42,3 +48,38 @@ def test_skills_tools_record_events(tmp_path):
         read_skill("recon")
     tools = [e for e in load_events(path) if e["type"] == EVENT_TOOL_CALL]
     assert [t["payload"]["tool"] for t in tools] == ["list_skills", "read_skill"]
+
+
+def test_render_skills_manifest(tmp_path):
+    sd = _make_skill_dir(tmp_path)
+    manifest = render_skills_manifest(sd)
+    # one `- name: description` line per skill; missing description falls back to a placeholder
+    assert "- recon: Recon helper" in manifest
+    assert "- triage: (no description)" in manifest
+    # header, when given, is prepended on its own line
+    with_header = render_skills_manifest(sd, header="<available_skills>")
+    assert with_header.startswith("<available_skills>\n- ")
+
+
+def test_render_manifest_empty_when_no_skills():
+    # nothing to inject → empty string (caller can skip the block)
+    assert render_skills_manifest("/no/such/dir") == ""
+
+
+def test_load_skills_discovery_inject_omits_list_skills(tmp_path):
+    # discovery="inject" surfaces ONLY read_skill (the JIT pull); discovery is handled by the
+    # injected manifest, so there is no list_skills tool.
+    tools = load_skills_as_tools(_make_skill_dir(tmp_path), discovery="inject")
+    assert [t.__name__ for t in tools] == ["read_skill"]
+    assert "recon steps" in tools[0]("recon")
+
+
+def test_load_skills_discovery_list_is_default_and_backward_compatible(tmp_path):
+    # default stays the 2-tuple [list_skills, read_skill] so existing callers keep working.
+    tools = load_skills_as_tools(_make_skill_dir(tmp_path))
+    assert [t.__name__ for t in tools] == ["list_skills", "read_skill"]
+
+
+def test_load_skills_discovery_invalid_raises(tmp_path):
+    with pytest.raises(ValueError, match="discovery must be"):
+        load_skills_as_tools(_make_skill_dir(tmp_path), discovery="bogus")