[XieX]

#208 added create_claude_agents_skills_handler at launchdarkly_ai_claude_agents.experimental.skills. The spec now promotes it with Agent Skills (launchdarkly/ai-sdks-monorepo#59, following #86), and no release has shipped it, so it moves to the package root with no deprecated alias:

• create_claude_agents_skills_handler is exported from launchdarkly_ai_claude_agents, from a new skills module (moved from experimental/skills.py). The experimental subpackage and its API report are deleted.
• It reports claude-agents.createClaudeAgentsSkillsHandler instead of experimental.createClaudeAgentsSkillsHandler.
• The README section loses its experimental notice, and the example imports from the package root. agents.md follows.
• Tests: the fresh-interpreter test that the package root never loaded the experimental module is replaced by one that the root exports the handler. The usage test, and tests/test_never_forwarded_parameters.py's module map, use the new module and ID.

Phantom usage events (review follow-up). The handler called the public skill_refs and write_skills, so every run with skills also reported client.skillRefs and client.writeSkills, calls the customer never made. This was already on main from #208/#210; this PR makes the handler a core export, so it fixes it here:

• Core gains a non-reporting _skill_refs in launchdarkly_ai_server.skills; skill_refs reports and then delegates to it. Not a public name, so no API report changes.
• The handler uses _skill_refs and the existing _write_skills from launchdarkly_ai_server.skills_fs, as skills_watch.py already does.
• packages/claude-agents/tests/test_sdk_usage.py gains a run with skills, over invoke and stream, that sends only claude-agents.createClaudeAgentsSkillsHandler. The test fails against the public helpers.

The TypeScript twin is launchdarkly/js-ai-sdk#136, which makes the same move before it merges and likely has the same usage pattern to fix.

Tests: rebased onto main after #210 squash-merged, so the branch carries only its own commits. make api-report-check reports every report current. make lint, make format-check and make typecheck pass, and the full suite passes locally.

🤖 Generated with Claude Code

---

Note

Overview
create_claude_agents_skills_handler graduates from launchdarkly_ai_claude_agents.experimental.skills to a top-level skills module and is re-exported from launchdarkly_ai_claude_agents. The experimental subpackage and its API report are removed; docs and examples import from the package root, and SDK usage is reported as claude-agents.createClaudeAgentsSkillsHandler instead of the experimental helper id.

Runs that materialize variation skills no longer emit phantom client.skillRefs / client.writeSkills events. The handler calls internal _skill_refs and _write_skills (core adds _skill_refs as the non-reporting body behind public skill_refs). New usage tests assert invoke/stream with skills only records the factory helper.

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

[jeffdupont]

Thanks, the move looks right: root export, API report, docs, and the usage ID now follows the claude-agents.* pattern. Two things before this can merge:

1. Rebase onto main. #210 was squash-merged, so this branch still carries its 10 original commits and conflicts in packages/claude-agents/README.md and skills.py. Main's tree is identical to d679fd2e, so git rebase --onto origin/main d679fd2e leaves only your commit and applies cleanly (checked with git merge-tree). CI then reruns against main.

2. Phantom usage events. skills.py:90 and :100 call the public skill_refs and write_skills, so every customer who uses create_claude_agents_skills_handler also reports client.skillRefs and client.writeSkills, calls they never made. This bug is already on main (it came from #208/#210), but this PR is the one making the handler a core export, so it's the right place to fix it:

   • Use the existing private _write_skills from launchdarkly_ai_server.skills_fs, as skills_watch.py already does.
   • Add a non-reporting _skill_refs in core (have skill_refs call it after report_usage) and use that here.
   • Extend the "its own ID, and not also the core factory's" case in test_sdk_usage.py so that a run with skills sends neither client.skillRefs nor client.writeSkills.

   The JS twin (js-ai-sdk#136) probably has the same pattern. Worth checking there too.

[jeffdupont]

Approving on d288473. The rebase leaves only your three commits on main, the handler now calls the non-reporting _skill_refs / _write_skills from the core root (as ai-sdks-monorepo#59's A.12 row specifies), and test_skills_run_reports_only_the_factory pins that invoke and stream send only claude-agents.createClaudeAgentsSkillsHandler.