[XieX]

Stacked on #201 (host options and built-in tool set). Review that one first. This PR's base is its branch.

A skill attached to an agent-mode variation never reached a model run through create_claude_agents_handler. #201's tools=[] removes the Skill tool, and nothing hands the CLI the skill files.

create_claude_agents_skills_handler(*, capture_content=None, cwd=None, setting_sources=None, skills_temp_dir=None), from the new launchdarkly_ai_claude_agents.experimental.skills module, fixes that. On every invoke and stream it:

1. Writes skill_refs(config) with write_skills, through the store configured with set_skill_store, into mkdtemp(<skills_temp_dir>/ld-skills-)/launchdarkly/skills. Pinned versions are honored.
2. Passes plugins=[{"type": "local", "path": <dir>/launchdarkly}] and skills=["launchdarkly:<key>", …], and appends Skill to tools (not to allowed_tools).
3. Removes the directory when the run ends, however it ends.

• One directory per run. There's no shared root, no watcher and no prune. Detaching a skill from a variation takes effect on the next run, and concurrent runs never share files.
• Fail closed. If the reconcile isn't ok (no store, store not yet initialized, a skill withheld by verification, or an absent pin), the run raises before query() and names each skill.
• No-skills path. A variation with no skills sends exactly the core handler's options and needs no store.
• setting_sources is never None. With skills set and setting_sources=None, claude-agent-sdk sends --setting-sources=user,project. The core handler already always sends it ([] unless given), and this handler inherits that.
• Telemetry. The tool hooks are installed whenever Skill is in tools, so a Skill call gets an execute_tool Skill span, with no $ld:ai:tool_call event.
• Stage boundary. Core reaches this code only through a private _prepare keyword argument on _create_claude_agents_handler. It is not an option of the public factory. The package root doesn't import the experimental module, and a test checks that in a fresh interpreter.
• Not covered: claude_agents(), claude_graph() and to_claude_agents(). The README says so.

Differences from TypeScript

• No skipMcpDiscovery. claude-agent-sdk's SdkPluginConfig has no such key, so the plugin entry carries only type and path. The directory holds no MCP config, so there is nothing to discover.
• Synchronous removal. The directory is removed with a synchronous shutil.rmtree, so a cancellation during teardown can't interrupt it. A failed removal is logged and doesn't replace the run's outcome.

Tests

• A new test_skills.py (49 tests) uses a mocked query() with a real InMemorySkillStore, a real filesystem (tmp_path as skills_temp_dir) and a real OTel provider. Each spec bullet runs on both invoke and stream where it applies.
• test_sdk_usage.py adds the experimental.createClaudeAgentsSkillsHandler row.
• Mutation-checked: making the cleanup a no-op fails 9 tests. Dropping Skill from the hook-install condition fails the span tests.

Checks:

• uv run pytest: everything passes except opencode-agents test_a_fake_opencode_is_started_spoken_to_and_stopped, the macOS /private/var temp-path failure already on main.
• make lint, make format-check and make typecheck are clean.

Follow-ups in the monorepo

• The A.18 Python rows and an EXPERIMENTAL.md row for Python.
• api-surface/python/launchdarkly_ai_claude_agents.experimental.skills.txt.
• python on experimental.createClaudeAgentsSkillsHandler in usage-ids.txt.

Not verified yet: a live run where a model actually loads the skill.

Spec: TESTING.md §2.x "Claude Agents Skills Integration" and A.18, in launchdarkly/ai-sdks-monorepo#59. The TypeScript side is launchdarkly/js-ai-sdk#136.

🤖 Generated with Claude Code

---

Note

Overview
Adds experimental create_claude_agents_skills_handler() under launchdarkly_ai_claude_agents.experimental.skills so Claude Agent runs get the skills attached to their AI Config variation. The core create_claude_agents_handler() path is unchanged and still ignores variation skills.

On each invoke/stream with skills, the handler writes skill files from set_skill_store into a per-run temp directory, passes it to query() as a local launchdarkly plugin with qualified launchdarkly:<key> skill names, enables the Skill built-in (via new internal _prepare / QueryPreparation on _create_claude_agents_handler), and removes the directory in a final cleanup on success, failure, cancel, or stream abandonment. Reconcile failures fail closed before query(); empty skills behave like the core handler.

Docs, API report, usage tracking for experimental.createClaudeAgentsSkillsHandler, and a large test_skills.py suite cover materialization, concurrency, telemetry (execute_tool Skill), and that claude_agents / graph helpers are not wired yet.

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

[jeffdupont]

Pushed 5acd989 and 85d37ee:

• Merged origin/main (fix(claude-agents)!: switch the built-ins off by default and load no host settings #201). The only conflicts were in handler.py, where this branch adds the _prepare hook beside main's lines. I kept both.
• Added launchdarkly_ai_claude_agents.experimental.skills: set() to FORWARDED_LISTS in tests/test_never_forwarded_parameters.py. The module delegates to the core handler.
• Moved await prepared.cleanup() in _call_impl into its own finally, so the temp dir is removed even if finish_root_span or end_unfinished_spans raises. Added test_removes_the_directory_when_closing_the_blocking_spans_raises. I checked that it fails without the fix.
• The module stays experimental and still imports launchdarkly_ai_server.experimental.skills until feat(skills)!: promote Agent Skills to core #210 lands.

This needs a human reviewer.

[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 85d37ee. Configure here.}