feat(client): publish Agent Skills from the experimental entry point

[XieX]

Summary

Reorganizes Agent Skills to ship as an experimental feature.

Every Skills name is exported from launchdarkly_ai_server.experimental.skills, and none from the package root. Applications opt in by importing from that module. While the feature is experimental, its names may change in a minor release, so review the changelog when you upgrade.

Additionally, the store is configured via a set_skill_store(store) setter rather than injected into init_client, which logs a warning for any option key it does not read, so a retired skillStore option is reported rather than dropped silently. The check is generic and does not name the feature.

Other changes:

• Shutdown: shutdown() clears the skill store in a way that logs a failure rather than raising it into the core call. The test reset clears it directly, so a failed reset fails the test.
• Messages and docs: error messages, docstrings, the README and agents.md now point at set_skill_store and the experimental import path. The init_client docstring and README list all seven options it reads. The README quickstart stops before write_skills when inspect_config returns no config, since an empty reference list would prune every managed skill. The launchdarkly-ai-python README notes that experimental features are not re-exported and are imported from launchdarkly_ai_server.experimental. agents.md clarifies that the experimental part is the SDK's API, not the LaunchDarkly data model, so AiConfigRep still documents a config's skills references.
• Tests:
  • The experimental exports are pinned to an exact list, so a new export fails. The module's public dir() is pinned too.
  • The root __all__ is pinned to a checked-in snapshot (tests/test_public_surface.py), so a new root export fails.
  • A failure clearing experimental state in shutdown() is logged, and the client is still closed.
  • set_skill_store raises TypeError for a value without callable get_object and all_objects, as in the JS SDK.
  • No Skills name is reachable from the package root.
  • init_client ignores a skillStore option and warns about it; unknown options warn and documented ones do not.
  • set_skill_store(None) is ignored and leaves the configured store in place, as in the JS SDK.
  • SKILL_OBJECT_KIND and MAX_SKILL_CONTENT_BYTES stay unexported from both the root and the experimental module.

Open questions

• The config parser still validates skills. parse_ai_config fails a whole config when its skills array is malformed, so a bad Skills field can fail an ordinary config().invoke(). That conflicts with "experimental behaviour must not break a core call". The behaviour is unchanged here, pending a decision.
• Evaluations is still exported from the package root. It was already released from there, so moving it to experimental.evaluations needs deprecated aliases. That is left for a separate change.

Test plan

• make lint, make format-check, make typecheck
• uv run pytest: 2217 passed, 11 skipped

🤖 Generated with Claude Code, updated by @XieX

---

Note

Overview
Moves Agent Skills off the stable package root into launchdarkly_ai_server.experimental.skills, so those APIs may change in minor releases while the root export list stays pinned in tests.

Configuration: skill stores are wired with set_skill_store(store) instead of init_client(options={"skillStore": ...}). init_client only accepts seven documented option keys and logs a warning for anything else (including retired skillStore). shutdown() clears experimental state in a path that logs failures instead of breaking core teardown.

Validation split: parse_ai_config no longer rejects variations for a malformed skills field (core config().invoke() / inspect_config keep working). skill_refs now validates fail-closed and raises ValueError (including for skills: null) so pruning reconciles never treat a bad field as “no skills.”

Docs and tests are updated for the experimental import path, set_skill_store, and frozen snapshots of root vs experimental __all__.

^{Reviewed by Cursor Bugbot for commit 40fd647. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jeffdupont]

Reviewed at 01bfad1d; re-checked against 56bfacaa (set_skill_store(None) now ignored, matching JS).

The move itself is clean. Every Skills name is gone from the root and from launchdarkly_ai_python, skillStore is gone from code, docs and error messages, and the wheel ships experimental/. At 01bfad1d I get 2210 passed, 11 skipped, and ruff, format and mypy are clean.

I ran mutations against the export tests. These ones fail the tests, which is what we want:

• adding frontmatter to experimental/skills.py and its __all__
• adding get_skill to the root
• adding SKILL_OBJECT_KIND to the experimental module
• adding MAX_SKILL_CONTENT_BYTES to the root
• adding SKILL_OBJECT_KIND to the root as a bare attribute

Dropping the unknown-option warning fails 2 tests. Bringing skillStore back fails 1.

Two of the mutations get through. Details are inline.

1. The root half of the export test is still a denylist. If I add def frontmatter plus __all__.append("frontmatter") to the root __init__.py, all 8 tests pass (TestPackageExports and packages/ai/tests). #33 says neither the root nor the experimental entry point may expose a frontmatter accessor, and A.14 asks for a checked-in __all__ snapshot for the root as well as for each experimental module. js #114 checks in API reports for both entry points. Please pin the root __all__ (114 names) the same way you pinned EXPERIMENTAL_SKILLS_SURFACE.
2. "Logged, not raised" in shutdown has no test. If I remove the try/except in _clear_experimental_state (lifecycle.py:292-295), the client suite still passes (1396). Nothing can fail there today, because clear_state only assigns two globals (skills_core.py:186-190). That makes the test cheap to add now, before a hook that can raise shows up. Patch skills._clear_state to raise, then assert that shutdown() returns, the client is closed, and the warning is logged.

Open questions from the PR body

(a) Malformed skills fails core calls. I think this needs a decision before 1.0, not in this PR. I tested skills[0].key = "My_Skill", skills: null, version: 0 and a non-list value. Each one makes extract_variation raise Invalid AI config variation ..., so config().invoke(), config().stream() and graph nodes fail (client.py:81, :184; graph.py:163). inspect_config returns enabled=True, config=None. main has no skills validation at all, so this behaviour arrives with #87. If any existing skill keys fall outside the gonfalon #73433 grammar (still unverified), apps that never import Skills will start failing invoke. My suggestion:

• stop validating skills in parse_ai_config (types_validation.py:151-156)
• make skill_refs raise on an array that is present but malformed, instead of dropping entries with a warning

write_skills then still never sees a partial or empty list, so the prune-safety reason for the check holds, and §0.3 is met. The core parse behaviour freezes at 1.0, and JS needs the same change.

(b) Evaluations were released from the root. init_evaluations, EvaluationsModule, EvaluationsError, EvalRunResult, GenerationConfig and RunSummary are in the root __all__ of launchdarkly-ai-server 0.2.2 (PyPI, 8 Sep). 0.2.3 has the same. 0.2.4 (30 Sep) adds Judge, Scorer and Criterion. I checked the wheels. launchdarkly-ai-python 0.1.6-0.1.8 re-exports them through import *. So people can import them from the root today. 1.0 is a major release, so semver allows the move, but deprecated root aliases are cheap (module __getattr__ with a DeprecationWarning). Leaving that out of this PR is fine. #33 needs fixing, though: its register marks Evaluations as experimental and "absent from the package root", and §0 only describes forward moves, so it has no path for demoting a released feature. Either drop Evaluations from the register, or add the alias step. #41 (merged today) also lists client.init_evaluations as a helper string, which clashes with #33's experimental. prefix rule.

Smaller items

• Parity with js #114: two of the three differences I found are now settled. 56bfacaa makes set_skill_store(None) a no-op like JS, and js #114's 5f3779b2 switches JS to the same generic unknown-option warning as here. The one left: JS adds @launchdarkly/ai-node/experimental, while the Python barrel deliberately doesn't (packages/ai/README.md:78-83). Either is defensible; #33's A.14 should record which.
• README quickstart deletes skills when inspect_config fails (README.md:388, :398). The quickstart passes skill_refs(info["config"]) to write_skills with the default prune=True. If inspect_config fails (LaunchDarkly unreachable, or case (a) above), config is None, the refs come back [], and every managed skill is removed with report.ok == True. I reproduced this. The bug predates this PR, but this PR rewrites that block. Please check info["config"] is not None before writing. This is the Python half of the JS README issue.
• The init_client allowlist is complete. lifecycle.py reads exactly those seven keys, nothing else reads init_client options, and the SDK's own lazy calls pass no options, so there are no false warnings. The keys aren't actually documented, though. The docstring (lifecycle.py:161-171) mentions only sdkKey, and the README table (packages/client/README.md:197) lists none. Please list them in both. Also, since skillStore never shipped in a Python release, the generic warning is enough here.
• set_skill_store accepts anything that isn't None. A string, a dict or an int all succeed. The first accessor call then logs an ERROR traceback and returns store_unavailable ("'str' object has no attribute 'get_object'"). Checking callable(getattr(store, "get_object", None)) would catch this when the store is set. Optional.
• AiConfigRep's docstring (types.py:96) says "see skill_refs". That's a core public type pointing at an experimental name. Please point at experimental.skills.skill_refs or drop the reference.
• watch_skills's no-store message (skills_watch.py:229-231) leaves out the import path. NO_STORE_MESSAGE includes it.
• Not a change request, but worth a line in the set_skill_store docstring. Swapping the store doesn't close the old one, and a running watcher keeps listening on the store it captured (skills_watch.py:227). Thread-safety is fine: there's one global, and each accessor reads it once.

Merge order

This PR implements monorepo #33, which is still open. main's TESTING.md still requires root exports and init_client({"skillStore"}) (:1031, :1539, :1647, :2860). Merging this into #87's branch is fine. #87 shouldn't reach main before #33. #33 also needs work before it lands:

• It needs a new appendix number, because main now has "A.14 Helper usage strings".
• #35 needs rebasing onto #33. #35's A.12 paragraph names _resolve_client and test_failed_init_client_leaves_no_store_configured, and this PR removes both. #35's §3.9 skillStore bullet is the one #33 deletes. The retry rule still holds: test_retries_after_a_failed_init_instead_of_replaying_it is at test_lifecycle.py:297.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: c9bcdca8-149b-407d-b97e-265a8e2509b8)

[XieX]

Thanks @jeffdupont. f5c9aa2 covers the two mutations that got through and the smaller items. Inline replies have the details.

• Root export test: the root __all__ is now pinned to a snapshot.
• Shutdown "logged, not raised": now tested.
• README quickstart: it stops before write_skills when inspect_config returns no config, and the comment says why.
• init_client options: all seven are listed in the docstring and in a README table.
• set_skill_store: raises TypeError for a non-store, and JS matches. The docstring now says replacing a store does not close the old one, and a running watcher keeps the store it started with.
• AiConfigRep points at experimental.skills.skill_refs. watch_skills's no-store message names the import path.

Not changed here:

• (a) Malformed skills failing core calls: I'm working on another pair of PRs to move skills validation into the skills functions.
• (b) Evaluations at the root, the ai-node /experimental parity note, and the generic unknown-option rule would need spec changes. Not in scope here.