Merge origin/main into xie/skills-config-source

Resolves two conflicts with #217 (Claude Agents skills handler on the
package root): `__init__.py` keeps both the `_write_skills` re-export
and the `config_skills` import, and `_skill_refs`'s docstring names
both of its callers, the handler and the source `config_skills` builds.

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

Author: XieX

packages/claude-agents/README.md

@@ -131,18 +131,14 @@ async def main():
 asyncio.run(main())
 ```
 
-## Agent Skills (experimental)
-
-> **Experimental.** Imported from `launchdarkly_ai_claude_agents.experimental.skills`. The name and behavior may change in a minor release, and each change is listed under **Experimental** in the changelog.
+## Agent Skills
 
 `create_claude_agents_handler()` doesn't give the model a variation's skills. `create_claude_agents_skills_handler()` does. It takes the same options, plus `skills_temp_dir`.
 
 ```python
 import os
 from launchdarkly_ai_server import FDv2SkillStore, config, set_skill_store
-from launchdarkly_ai_claude_agents.experimental.skills import (
-    create_claude_agents_skills_handler,
-)
+from launchdarkly_ai_claude_agents import create_claude_agents_skills_handler
 
 store = FDv2SkillStore(os.environ["LD_SDK_KEY"]).start()
 store.wait_for_skills(timeout=10)

packages/claude-agents/agents.md

@@ -30,7 +30,7 @@ That means the LaunchDarkly flag variation must have `provider.name == "Anthropi
 | `src/launchdarkly_ai_claude_agents/graph.py` | `claude_graph()` convenience wrapper around `graph()` |
 | `src/launchdarkly_ai_claude_agents/native_graph.py` | `to_claude_agents()` native graph adapter |
 | `src/launchdarkly_ai_claude_agents/builtins.py` | Pre-constructed `NativeTool` sentinels for Claude built-in tools |
-| `src/launchdarkly_ai_claude_agents/experimental/skills.py` | Experimental `create_claude_agents_skills_handler()`. Not imported by the package `__init__.py` |
+| `src/launchdarkly_ai_claude_agents/skills.py` | `create_claude_agents_skills_handler()`, exported from the package root |
 | `src/launchdarkly_ai_claude_agents/__init__.py` | Package exports |
 | `src/launchdarkly_ai_claude_agents/_version.py` | `PACKAGE_NAME` and `__version__`, sent with `$ld:ai:sdk:info` and `$ld:ai:sdk:usage` |
 
@@ -169,11 +169,11 @@ On error: `span.record_exception(exc)`, status set to ERROR, span ended, error r
 id wins. An app that opens a fresh CLI session per turn and re-feeds history must pass its own
 conversation id, or each turn becomes its own conversation.
 
-### 5. Agent Skills (experimental, `experimental/skills.py`)
+### 5. Agent Skills (`skills.py`)
 
-`create_claude_agents_skills_handler(...)` is importable only from `launchdarkly_ai_claude_agents.experimental.skills`, and the package root never imports it (a test checks this in a fresh interpreter). It reports `experimental.createClaudeAgentsSkillsHandler` and builds the handler through `_create_claude_agents_handler(..., _prepare=...)`.
+`create_claude_agents_skills_handler(...)` is exported from the package root. It reports `claude-agents.createClaudeAgentsSkillsHandler` and builds the handler through `_create_claude_agents_handler(..., _prepare=...)`.
 
-`_prepare` is a package-internal hook, a private keyword argument of the internal factory only, so core names nothing experimental. It runs at the start of every invoke and stream, inside the `invoke_agent` span, and returns `None` (the run is exactly the core handler's) or a `QueryPreparation`. That holds extra `query()` options, extra built-ins appended to `tools` (never to `allowed_tools`), and a `cleanup` that both paths await last in their `finally`.
+`_prepare` is a package-internal hook, a private keyword argument of the internal factory only, so `create_claude_agents_handler`'s signature stays unchanged. It runs at the start of every invoke and stream, inside the `invoke_agent` span, and returns `None` (the run is exactly the core handler's) or a `QueryPreparation`. That holds extra `query()` options, extra built-ins appended to `tools` (never to `allowed_tools`), and a `cleanup` that both paths await last in their `finally`.
 
 For a variation with skills, `_prepare_skills`:
 

packages/claude-agents/api-report/launchdarkly_ai_claude_agents.experimental.skills.txt

@@ -14,5 +14,6 @@ ClaudeWebFetch = NativeTool('WebFetch')
 ClaudeWebSearch = NativeTool('WebSearch')
 ClaudeWrite = NativeTool('Write')
 create_claude_agents_handler(*, capture_content: bool | None = None, cwd: str | os.PathLike[str] | None = None, setting_sources: list[SettingSource] | None = None) -> ProviderHandler
+create_claude_agents_skills_handler(*, capture_content: bool | None = None, cwd: str | os.PathLike[str] | None = None, setting_sources: list[SettingSource] | None = None, skills_temp_dir: str | os.PathLike[str] | None = None) -> ProviderHandler
 partition_tools(config_tools: dict[str, Any] | None, tool_handlers: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any], list[str]]
 to_claude_agents(def_promise: Any, opts: dict[str, Any] | None = None) -> Any

packages/claude-agents/api-report/launchdarkly_ai_claude_agents.txt

@@ -28,6 +28,7 @@
     partition_tools,
 )
 from .native_graph import to_claude_agents
+from .skills import create_claude_agents_skills_handler
 
 __all__ = [
     "ClaudeBash",
@@ -45,6 +46,7 @@
     "claude_agents",
     "claude_graph",
     "create_claude_agents_handler",
+    "create_claude_agents_skills_handler",
     "partition_tools",
     "to_claude_agents",
 ]

packages/claude-agents/src/launchdarkly_ai_claude_agents/__init__.py

@@ -1,9 +1,8 @@
 """
-Agent Skills for Claude Agents (experimental).
+Agent Skills for Claude Agents.
 
 ``create_claude_agents_skills_handler`` builds a Claude Agents handler that gives each run the
-skills attached to its variation. This name may change in a minor release, so review the
-changelog when you upgrade.
+skills attached to its variation. Exported from the package root.
 """
 
 from __future__ import annotations
@@ -16,18 +15,22 @@
 
 from claude_agent_sdk import SettingSource
 
+# ``_skill_refs`` and ``_write_skills`` are the non-reporting forms of ``skill_refs`` and
+# ``write_skills``. A run reports only the factory's own helper event: the customer called
+# ``create_claude_agents_skills_handler``, not ``skill_refs`` or ``write_skills``, so sending
+# ``client.skillRefs`` or ``client.writeSkills`` from here would attribute calls they never made.
 from launchdarkly_ai_server import (
     AiConfigRep,
     ProviderHandler,
     ReconcileReport,
     SkillReference,
+    _skill_refs,
+    _write_skills,
     report_usage,
-    skill_refs,
-    write_skills,
 )
 
-from .._version import PACKAGE_NAME, __version__
-from ..handler import QueryPreparation, _create_claude_agents_handler
+from ._version import PACKAGE_NAME, __version__
+from .handler import QueryPreparation, _create_claude_agents_handler
 
 __all__ = ["create_claude_agents_skills_handler"]
 
@@ -88,17 +91,17 @@ async def _prepare_skills(
     Fails closed: if any skill cannot be written, the run does not start. The variation names
     that skill, so running without it would run a different agent from the one configured.
     """
-    refs = skill_refs(config)
+    refs = _skill_refs(config)
     if not refs:
         return None
 
     run_dir = os.path.realpath(tempfile.mkdtemp(prefix=_RUN_DIR_PREFIX, dir=parent))
     try:
         plugin_root = os.path.join(run_dir, PLUGIN_NAME)
-        # ``write_skills`` creates only the missing leaf of its root.
+        # ``_write_skills`` creates only the missing leaf of its root.
         os.mkdir(plugin_root)
         # A fresh directory: there is nothing to prune, and nothing else writes here.
-        report = await write_skills(
+        report = await _write_skills(
             refs, os.path.join(plugin_root, "skills"), prune=False
         )
         if not report.ok:
@@ -134,11 +137,12 @@ def create_claude_agents_skills_handler(
     *skills_temp_dir*: the parent of the directory each run writes its skills into, by default
     ``tempfile.gettempdir()``.
 
-    On every invoke and stream, the variation's ``skills`` are written with ``write_skills``,
-    through the store configured with ``set_skill_store``, into a new directory under
-    *skills_temp_dir*. That directory is passed to ``query()`` as a local plugin, only those
-    skills are enabled, the ``Skill`` tool is turned on, and the directory is removed when the
-    run ends. A variation with no skills runs exactly as with ``create_claude_agents_handler``.
+    On every invoke and stream, the variation's ``skills`` are written, as ``write_skills``
+    writes them, through the store configured with ``set_skill_store`` into a new directory
+    under *skills_temp_dir*. That directory is passed to ``query()`` as a local plugin, only
+    those skills are enabled, the ``Skill`` tool is turned on, and the directory is removed
+    when the run ends. A variation with no skills runs exactly as with
+    ``create_claude_agents_handler``.
 
     ``setting_sources`` is always sent, ``[]`` unless given. ``claude-agent-sdk`` would
     otherwise load the ``user`` and ``project`` settings sources whenever ``skills`` is set.
@@ -152,9 +156,7 @@ def create_claude_agents_skills_handler(
         import os
 
         from launchdarkly_ai_server import FDv2SkillStore, config, set_skill_store
-        from launchdarkly_ai_claude_agents.experimental.skills import (
-            create_claude_agents_skills_handler,
-        )
+        from launchdarkly_ai_claude_agents import create_claude_agents_skills_handler
 
         store = FDv2SkillStore(os.environ["LD_SDK_KEY"]).start()
         store.wait_for_skills(timeout=10)
@@ -163,7 +165,7 @@ def create_claude_agents_skills_handler(
         triage = config(key="triage-agent", handler=create_claude_agents_skills_handler())
     """
     report_usage(
-        "experimental.createClaudeAgentsSkillsHandler", PACKAGE_NAME, __version__
+        "claude-agents.createClaudeAgentsSkillsHandler", PACKAGE_NAME, __version__
     )
 
     async def _prepare(config: AiConfigRep) -> QueryPreparation | None:

packages/claude-agents/src/launchdarkly_ai_claude_agents/experimental/__init__.py

@@ -1,24 +1,33 @@
 """Tests for TESTING.md §3.27 — claude-agents."""
 
+import hashlib
+from pathlib import Path
 from types import SimpleNamespace
 from typing import Any
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
+from claude_agent_sdk import ResultMessage
 
+import launchdarkly_ai_claude_agents.handler as handler_mod
 import launchdarkly_ai_server.lifecycle as lifecycle_module
 from launchdarkly_ai_claude_agents import (
     claude_agents,
     claude_graph,
     create_claude_agents_handler,
+    create_claude_agents_skills_handler,
     to_claude_agents,
 )
 from launchdarkly_ai_claude_agents._version import PACKAGE_NAME
 from launchdarkly_ai_claude_agents._version import __version__ as PACKAGE_VERSION
-from launchdarkly_ai_claude_agents.experimental.skills import (
-    create_claude_agents_skills_handler,
+from launchdarkly_ai_server import (
+    SDK_INFO_CONTEXT,
+    InMemorySkillStore,
+    __version__,
+    init_client,
+    set_skill_store,
+    shutdown,
 )
-from launchdarkly_ai_server import SDK_INFO_CONTEXT, __version__, init_client, shutdown
 
 CONTEXT = {"kind": "user", "key": "user-1"}
 
@@ -60,7 +69,7 @@ async def client() -> Any:
         ("claude-agents.toClaudeAgents", lambda: to_claude_agents(None)),
         # Its own ID, and not also the core factory's.
         (
-            "experimental.createClaudeAgentsSkillsHandler",
+            "claude-agents.createClaudeAgentsSkillsHandler",
             create_claude_agents_skills_handler,
         ),
     ],
@@ -128,6 +137,54 @@ async def _definition() -> Any:
     assert _helpers(client) == ["claude-agents.toClaudeAgents"]
 
 
+_SKILL_BODY = "---\nname: a\n---\nSkill a.\n"
+_SKILLS_CONFIG: dict[str, Any] = {
+    "model": {"name": "claude-opus-4-5"},
+    "provider": {"name": "Anthropic"},
+    "instructions": "You are helpful.",
+    "skills": [{"key": "a", "version": 1}],
+}
+
+
+async def _fake_query(**_kwargs: Any) -> Any:
+    yield ResultMessage(
+        subtype="success",
+        duration_ms=1,
+        duration_api_ms=1,
+        is_error=False,
+        num_turns=1,
+        session_id="sess-1",
+        usage={"input_tokens": 3, "output_tokens": 2},
+        result="done",
+    )
+
+
+@pytest.mark.parametrize("path", ["invoke", "stream"])
+async def test_skills_run_reports_only_the_factory(
+    client: MagicMock, monkeypatch: pytest.MonkeyPatch, tmp_path: Path, path: str
+) -> None:
+    """A run with skills reads the variation's references and writes the skills on the
+    customer's behalf. They never called ``skill_refs`` or ``write_skills``, so neither
+    ``client.skillRefs`` nor ``client.writeSkills`` is sent for them."""
+    store = InMemorySkillStore()
+    store.put(
+        {
+            "key": "a",
+            "version": 1,
+            "content": _SKILL_BODY,
+            "contentHash": hashlib.sha256(_SKILL_BODY.encode()).hexdigest(),
+        }
+    )
+    set_skill_store(store)
+    monkeypatch.setattr(handler_mod, "query", _fake_query)
+    handler = create_claude_agents_skills_handler(skills_temp_dir=tmp_path)
+    if path == "invoke":
+        await handler(_SKILLS_CONFIG, "q", {})
+    else:
+        await _drain(await handler.stream(_SKILLS_CONFIG, "q", {}))
+    assert _helpers(client) == ["claude-agents.createClaudeAgentsSkillsHandler"]
+
+
 async def test_held_helper_flushes_with_its_package() -> None:
     """A helper called before init keeps its package fields until the flush."""
     await shutdown()

…_ai_claude_agents/experimental/skills.py …/launchdarkly_ai_claude_agents/skills.pypackages/claude-agents/src/launchdarkly_ai_claude_agents/experimental/skills.py renamed to packages/claude-agents/src/launchdarkly_ai_claude_agents/skills.py packages/claude-agents/src/launchdarkly_ai_claude_agents/experimental/skills.py renamed to packages/claude-agents/src/launchdarkly_ai_claude_agents/skills.py

@@ -12,8 +12,6 @@
 import asyncio
 import hashlib
 import os
-import subprocess
-import sys
 from collections.abc import AsyncIterator, Awaitable, Callable
 from pathlib import Path
 from typing import Any
@@ -28,8 +26,9 @@
 
 import launchdarkly_ai_claude_agents.handler as handler_mod
 import launchdarkly_ai_server.lifecycle as lifecycle_module
-from launchdarkly_ai_claude_agents import ClaudeRead, create_claude_agents_handler
-from launchdarkly_ai_claude_agents.experimental.skills import (
+from launchdarkly_ai_claude_agents import (
+    ClaudeRead,
+    create_claude_agents_handler,
     create_claude_agents_skills_handler,
 )
 from launchdarkly_ai_server import (
@@ -198,15 +197,15 @@ def test_routes_exactly_as_the_core_handler_does(self) -> None:
             "agent",
         )
 
-    def test_is_absent_from_the_package_root(self) -> None:
-        """A fresh interpreter, so this module's own import of the entry point doesn't count."""
-        probe = (
-            "import sys, launchdarkly_ai_claude_agents as p;"
-            "assert 'launchdarkly_ai_claude_agents.experimental' not in sys.modules;"
-            "assert not hasattr(p, 'create_claude_agents_skills_handler');"
-            "assert 'create_claude_agents_skills_handler' not in p.__all__"
+    def test_is_exported_from_the_package_root(self) -> None:
+        import launchdarkly_ai_claude_agents as package_root
+        import launchdarkly_ai_claude_agents.skills as skills_mod
+
+        assert "create_claude_agents_skills_handler" in package_root.__all__
+        assert (
+            package_root.create_claude_agents_skills_handler
+            is skills_mod.create_claude_agents_skills_handler
         )
-        subprocess.run([sys.executable, "-c", probe], check=True)
 
     @pytest.mark.parametrize("path", _PATHS)
     async def test_forwards_the_host_options(
@@ -247,21 +246,21 @@ async def test_a_config_with_no_skills_runs_as_the_core_handler_would(
     ) -> None:
         """No store is configured: a variation with no skills needs none."""
         cfg = dict(BASE_CONFIG) if skills is None else {**BASE_CONFIG, "skills": skills}
-        core, experimental = _FakeQuery(), _FakeQuery()
+        core, with_skills = _FakeQuery(), _FakeQuery()
         monkeypatch.setattr(handler_mod, "query", core)
         await _run(create_claude_agents_handler(cwd="/srv/app"), path, cfg)
-        monkeypatch.setattr(handler_mod, "query", experimental)
+        monkeypatch.setattr(handler_mod, "query", with_skills)
         await _run(
             create_claude_agents_skills_handler(
                 cwd="/srv/app", skills_temp_dir=tmp_path
             ),
             path,
             cfg,
         )
-        assert experimental.options == core.options
-        assert experimental.options.plugins == []
-        assert experimental.options.skills is None
-        assert "Skill" not in experimental.options.tools
+        assert with_skills.options == core.options
+        assert with_skills.options.plugins == []
+        assert with_skills.options.skills is None
+        assert "Skill" not in with_skills.options.tools
         assert list(tmp_path.iterdir()) == []
 
 
@@ -457,7 +456,7 @@ async def during(kwargs: dict[str, Any]) -> None:
 async def test_a_failed_removal_is_logged_and_does_not_replace_the_outcome(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path, caplog: pytest.LogCaptureFixture
 ) -> None:
-    import launchdarkly_ai_claude_agents.experimental.skills as skills_mod
+    import launchdarkly_ai_claude_agents.skills as skills_mod
 
     _store(_raw("a", 1))
     monkeypatch.setattr(handler_mod, "query", _FakeQuery())

packages/claude-agents/tests/test_sdk_usage.py

@@ -64,6 +64,7 @@
     set_skill_store,
     skill_refs,
 )
+from .skills import _skill_refs as _skill_refs
 from .skills_core import SkillStore
 from .skills_fdv2 import FDv2SkillStore, StoreDiagnostics
 from .skills_fs import (
@@ -73,6 +74,7 @@
     OnUnavailable,
     write_skills,
 )
+from .skills_fs import _write_skills as _write_skills
 from .skills_source import config_skills
 from .skills_watch import SkillWatcher, watch_skills
 from .tracking import execute_and_stream, execute_and_track, wrap_tool_handlers