[XieX]

Base is main: #135 (host options) has merged.

A skill attached to an agent-mode variation never reached a model run through createClaudeAgentsHandler. Measured on Agent SDK 0.3.220 by reading the CLI's init message: skills are discovered, but the handler's tools: [] removes the Skill tool, and no query({ skills }) value brings it back.

createClaudeAgentsSkillsHandler(options), from the new @launchdarkly/ai-claude-agents/experimental entry point, fixes that. On every invoke and stream it:

1. Writes skillRefs(config) with writeSkills, through the store configured with setSkillStore, into mkdtemp(<skillsTempDir>/ld-skills-)/launchdarkly/skills. Pinned versions are honored.
2. Passes plugins: [{ type: 'local', path: <dir>/launchdarkly, skipMcpDiscovery: true }] and skills: ['launchdarkly:<key>', …], and appends Skill to tools (not to allowedTools).
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 throws before query() and names each skill.
• No-skills path. A variation with no skills runs exactly as with the core handler, and needs no store.
• Telemetry. The tool hooks are installed whenever Skill is in tools, so a Skill call gets an execute_tool Skill span.
• Stage boundary. Core reaches this code only through a package-internal prepare hook on createClaudeAgentsHandlerInternal, which isn't part of the public factory options (§0.3).
• Packaging. ./experimental is an exports subpath plus a typesVersions entry and a second tsup entry. It typechecks under node10, node16 and bundler, and the integration test's manifest check now covers it.
• Options. ClaudeAgentsSkillsHandlerOptions is ContentCaptureOptions & ClaudeAgentsHostOptions & { skillsTempDir? }. ClaudeAgentsHostOptions is now exported from both the root and /experimental, which clears the ae-forgotten-export warnings in both claude-agents API reports.
• Not covered: skills through claudeAgents(), claudeGraph() and toClaudeAgents(). They take the host options (feat(claude-agents)!: accept trusted cwd and settingSources options, and load no host settings by default #135) but build the core handler, so a variation run through them doesn't get its skills. The README says so.

Tests: a new skills.test.ts with a mocked query() and a real store, filesystem and OTel provider, plus the usage row in sdk-usage.test.ts. Lint, typecheck/api:check and all 217 claude-agents tests pass locally.

Not verified yet: a live run where a model actually loads the skill, with Skill in tools but not in allowedTools. It's needed before GA. The spike key had no credits. The spike also showed that the handler returns the CLI's "Credit balance is too low" result as a successful output; that's tracked separately.

Spec: TESTING.md §2.x "Claude Agents Skills Integration" and A.21, in launchdarkly/ai-sdks-monorepo#59. Its EXPERIMENTAL.md row stays at Draft until this releases. Python twin: launchdarkly/python-ai-sdk#208, merged.

🤖 Generated with Claude Code

---

Note

Overview
Adds an experimental @launchdarkly/ai-claude-agents/experimental entry (dual tsup build, exports/typesVersions, API Extractor report) exposing createClaudeAgentsSkillsHandler, which materializes a variation’s LaunchDarkly skills into a per-run temp plugin directory and passes them to the Claude Agent SDK via local plugins, qualified skills, and the built-in Skill tool.

The core handler gains a package-internal prepare hook on createClaudeAgentsHandlerInternal (invoke and stream): optional extra query() options, appended built-ins, and finally cleanup. Variations with no skills behave like createClaudeAgentsHandler; if skills cannot be written (missing/uninitialized store, verification failure, bad pin), the run fails before query(). ClaudeAgentsHostOptions is now a documented public type on the main entry; claudeAgents / claudeGraph / toClaudeAgents are unchanged.

Docs cover setup with setSkillStore, plus a large skills.test.ts suite and packaging/integration checks for the experimental subpath.

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

[jeffdupont]

Merged main in and pushed 667abc0:

• ClaudeAgentsSkillsHandlerOptions is spelled out as ContentCaptureOptions & ClaudeAgentsHostOptions & { skillsTempDir? }. ClaudeAgentsHostOptions is now exported from both the root and /experimental, which clears the ae-forgotten-export warnings in both claude-agents reports, including the one main already had.
• realpath now runs on the parent before mkdtemp, so a realpath failure can no longer leak the directory.
• Removed the stale stacked-on-feat(claude-agents)!: accept trusted cwd and settingSources options, and load no host settings by default #135 and red-main notes from the body.

Locally, lint, typecheck/api:check and claude-agents tests pass (217). This needs a human reviewer. It still needs one live run with Skill in tools but not in allowedTools before GA. Python twin: python-ai-sdk#208.