[jeffdupont]

Promotes Agent Skills from launchdarkly_ai_server.experimental.skills to the package root. Jira: AIC-3655.

Do not merge yet. This PR must not merge until the blockers linked on AIC-3655 are fixed. It releases together with the JS and Go promotion PRs (links to be added).

Migration

Import Agent Skills names from launchdarkly_ai_server instead of launchdarkly_ai_server.experimental.skills. Nothing else changes: the names, signatures and behaviour are the same.

# before
from launchdarkly_ai_server.experimental.skills import get_skill, write_skills
# after
from launchdarkly_ai_server import get_skill, write_skills

This is a breaking change (!), which bumps the minor version while the package is 0.x.

What changed

• Root exports. All 24 names that experimental/skills.py exported are now in launchdarkly_ai_server.__all__, same spelling. launchdarkly-ai-python re-exports root __all__ with import *, so it gets them with no code change; its existing re-export tests cover it.
• Experimental module removed. experimental/skills.py is deleted. experimental/__init__.py is only a docstring, so nothing else there referenced it. Evaluations from Code stays in experimental.evaluations, untouched.
• API reports. Regenerated with make api-report: the skills names appear in launchdarkly_ai_server.txt, and launchdarkly_ai_server.experimental.skills.txt is deleted.
• Changelog. The three skills → Experimental rows are removed from changelog-sections in release-please-config.json, so feat(skills): now lands under Features.
• Docs. The client README, the launchdarkly-ai-python README, packages/client/agents.md and AGENTS.md no longer call Agent Skills experimental. Code samples import from the root.
• Core strings. Docstrings and error messages in skills_core.py, skills_watch.py, types.py, types_validation.py, shutdown_hooks.py and lifecycle.py no longer name the experimental module. For example, the "no skill store" error now says set_skill_store(store) from launchdarkly_ai_server.
• Usage IDs. None. main reports no skills usage IDs today, so this PR adds none. When skills usage reporting is added, it must use client.* IDs, not experimental.*.
• Unchanged behaviour. parse_ai_config still passes skills through unvalidated, and skill_refs still validates it. shutdown() still clears the skill store through the internal shutdown hook. The lifecycle module still imports no skills module.

Tests

• test_skills.py: every skills name is in root __all__ and on the root module. launchdarkly_ai_server.experimental.skills raises ImportError, and launchdarkly_ai_server.experimental has none of the names.
• test_public_surface.py: the skills names are added to the ROOT_SURFACE snapshot.
• test_lifecycle.py: the "core loads no experimental module" check now checks evaluations and experimental only, since the root now imports the skills modules.
• The skills test suites and conftest.py import from the root.

Test plan

Run in the PR worktree after uv sync (exit 0):

• make lint — exit 0
• make format-check — exit 0
• make typecheck — exit 0 (Success: no issues found in 101 source files)
• make api-report-check — exit 0 (14 API reports are current)
• uv run pytest -q packages/client packages/ai — 1709 passed, 1 skipped
• make test — exit 2: 3282 passed, 18 skipped, 3 failed. The same 3 tests fail on unmodified origin/main (e3afb3f) in the same checkout, and CI on main is green. None of them involves skills:
  • test_lifecycle.py::TestInitClientSDKKeyPath::test_uses_options_sdk_key_over_env_var and ::test_retries_after_a_failed_init_instead_of_replaying_it: they get a staging stream_uri. My unverified guess is a local .env above the checkout leaking into the full run. Both pass when run alone.
  • opencode-agents/tests/test_handler.py::TestProcess::test_a_fake_opencode_is_started_spoken_to_and_stopped: on macOS the temp path comes back as /var/... in one place and /private/var/... in another.

🤖 Generated with Claude Code

Related PRs

Releases together with:

• feat(skills)!: promote Agent Skills to core js-ai-sdk#159
• feat(AIC-3655)!: promote Agent Skills to core go-ai-sdk#14

---

Note

Overview
Promotes Agent Skills from experimental to core on launchdarkly-ai-server: all 24 skills APIs now live on launchdarkly_ai_server (and flow through launchdarkly-ai-python via re-export). launchdarkly_ai_server.experimental.skills is removed—callers must switch imports to the package root (feat(skills)!).

The public contract is refreshed: API reports move skills entries into launchdarkly_ai_server.txt, release-please drops the skills Experimental changelog scope, and docs/README samples use root imports. Skills helpers now emit SDK-wide report_usage("client.*") events (once per helper per client); watcher-driven reconciles call internal _write_skills so they do not double-count writeSkills.

Downstream packages (e.g. claude-agents) import store/skill APIs from launchdarkly_ai_server instead of experimental.skills; the Claude skills handler stays under experimental. Tests and lifecycle wording are updated so skills modules are core, while Evaluations remains experimental.

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

[jeffdupont]

Pushed 4825587, which merges origin/main into this branch with no conflicts. make api-report showed no drift, and make lint-fix and make typecheck are clean. No other changes.

This needs a human reviewer.

[XieX]

I reviewed the promotion, and the code move itself looks clean: no references to experimental.skills remain, and the root __all__ matches the old module's 24 names. My inline comments are mostly about the docs and packaging around it.

One thing outside the diff: the title's scope is AIC-3655. release-please shows the scope in bold in the changelog entry, so the Jira key would appear in the customer-facing changelog. feat(skills)!: promote Agent Skills to core would land under Features in the same way.

[cursor]

Stale Bugbot comment from a previous run.

[XieX]

Approving. All eight comments from the first round are settled: six are fixed, and the shim and lazy-import decisions are backed by §0.5 and AIC-3674. Thanks for the spec links on the keyless-object rule; ai-sdks-monorepo#86 §3.25 reads the way you described.

Before merging, could you also deal with the follow-ups below?

Docs vs. the new usage reporting (4d6b3cb). The code is right per §3.27, but three places still say skills never calls client.track() or reports telemetry. Details are in the inline comments.

PR description. It still says "Usage IDs. None… this PR adds none." It should now list the seven client.* IDs: skillRefs, getSkill, getSkillResult, getSkills, allSkills, writeSkills and watchSkills.

Changelog. The squash commit only carries the promotion title. Since skills calls now send a usage event, a BEGIN_COMMIT_OVERRIDE with a second line such as feat(skills): report helper usage for the Agent Skills functions would give that its own changelog entry.

Merge timing. This approval doesn't change the "Do not merge yet" note. Please hold until the AIC-3655 blockers are cleared, and make sure this ships as the 1.0 release (AIC-3672). The barrel README now says skills need launchdarkly-ai-server 1.0.0, but the open release PR (#206) would cut 0.5.0. If this lands in a 0.5.0 release, that README note and its pip install "launchdarkly-ai-server>=1.0.0" command would point at a version that doesn't exist.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d679fd2. Configure here.}

[cursor]

Skills imports need a newer server

Medium Severity

create_claude_agents_skills_handler now imports ReconcileReport, SkillReference, skill_refs, and write_skills from the launchdarkly_ai_server root, but launchdarkly-ai-claude-agents still depends on launchdarkly-ai-server>=0.4.1, which only exported those names from experimental.skills. Upgrading the handler alone raises ImportError.

Additional Locations (1)

• packages/claude-agents/README.md#L141-L142

 

^{Reviewed by Cursor Bugbot for commit d679fd2. Configure here.}