Agent skills

This topic explains how to use agent skills with LaunchDarkly AI SDKs. This feature is available for AI SDKs only.

An agent skill is a single versioned SKILL.md document, with YAML front matter plus a Markdown body, that you manage in LaunchDarkly. Skills live in a project-scoped library, and you can attach them to an AgentControl config variation. LaunchDarkly AI SDKs let your application do various things with a skill:

• Discover which skills a config variation references after LaunchDarkly resolves it.
• Retrieve a skill’s content after LaunchDarkly verifies it.
• Materialize skills as files, which means agent runtimes, such as the Claude Agent SDK, can read them directly from disk.

How agent skills work

Keep the following in mind as you build with agent skills:

• A skill reference pins a version: A config variation names a skill reference in the form of a { key, version } pair. The SDK resolves the pinned version. A referenced skill has no “latest” version.
• Skills have no targeting of their own: The skill a context receives is decided entirely by which config variation LaunchDarkly serves that context. Content accessors do not take a context argument.
• Content is opaque bytes: A skill’s content is bytes in Python and Uint8Array in Node.js. The SDK never parses it and does not expose a frontmatter accessor. If you need the front matter, decode and parse it manually. A skill’s name and description come from metadata that LaunchDarkly stores, not from the content. This means they are available without decoding anything.
• Integrity is verified before anything is returned: Every skill’s SHA-256 hash is checked against the hash LaunchDarkly delivered. Content that does not verify is withheld and is never returned or written to disk.
• *Skills are server-side only: Skill content is customer-confidential agent instruction text. Mobile keys and client-side IDs are rejected.

Prerequisites

To use agent skills, you need:

• A LaunchDarkly project with agent skills enabled and at least one skill created. To learn more, read Agent skills.
• The environment’s server-side SDK key.
• Python 3.12 or later for the Python AI SDK, or Node.js 20 or above for the Node.js (server-side) AI SDK.
• An agent runtime or provider integration that consumes skills, matching one of the patterns described in the Agent skill integration patterns section.

Install the SDK

Agent skills ships inside the existing AI SDK server packages. You do not install a separate package:

pip install launchdarkly-ai-server

Agent skill integration patterns

The pattern you need decides which part of the API you use.

Provider-uploaded references do not need a skill store. skill_refs/skillRefs works on any resolved config, including a config evaluated with a client you supply yourself. If that is the only pattern you need, skip to Discover references on a resolved config.

AI SDKs

This feature is available for the following AI SDKs:

• Python AI
• Node.js (server-side) AI

Python AI

import os
from launchdarkly_ai_server import FDv2SkillStore, init_client
store = FDv2SkillStore(os.environ["LD_SDK_KEY"]).start()
if not store.wait_for_skills(timeout=10):
    # No payload arrived. Reconciling now would find an empty store.
    log.warning("skill delivery has not answered: %s", store.failed or "still waiting")
await init_client(options={"skillStore": store})
# ... at shutdown:
store.close()

import hashlib
from launchdarkly_ai_server import InMemorySkillStore, init_client
SKILL_MD = "---\nname: PDF Extraction\n---\nExtract text from PDFs.\n"
store = InMemorySkillStore()
store.put({
    "key": "pdf-extraction",
    "version": 2,
    "content": SKILL_MD,
    "contentHash": hashlib.sha256(SKILL_MD.encode("utf-8")).hexdigest(),
})
await init_client(options={"skillStore": store})

from launchdarkly_ai_server import inspect_config, skill_refs
info = await inspect_config("doc-agent", {"kind": "user", "key": "user-123"})
refs = skill_refs(info["config"])   # [SkillReference(key='pdf-extraction', version=2)]

skills = []
for r in refs:
    skill_id, provider_version = PROVIDER_SKILLS[(r.key, r.version)]
    skills.append({"type": "custom", "skill_id": skill_id, "version": provider_version})
response = anthropic.beta.messages.create(..., container={"skills": skills})

from launchdarkly_ai_server import get_skill, get_skills, all_skills, get_skill_result
skill = await get_skill("pdf-extraction")               # newest available, or None
pinned = await get_skill("pdf-extraction", version=2)   # exactly version 2, or None
batch = await get_skills(refs)                          # input order; misses omitted
everything = await all_skills()                         # one per key, newest version
text = skill.content.decode("utf-8") if skill else None

outcome = await get_skill_result("pdf-extraction")
if outcome.reason == "integrity_failure":
    raise SystemExit(f"refusing to start: {outcome.detail}")
elif outcome.reason == "store_unavailable":
    ...  # outage, not revocation: retry or run degraded
elif outcome.reason in ("absent", "wrong_version"):
    ...  # carry on without the skill
else:
    print(outcome.skill.content)

from pathlib import Path
from launchdarkly_ai_server import init_client, inspect_config, skill_refs, write_skills
await init_client(options={"skillStore": store})
info = await inspect_config("doc-agent", context)
Path(".claude").mkdir(exist_ok=True)         # the root's parent must already exist
if info["meta"] is None:
    log.error("config unavailable; skipping reconcile")
else:
    report = await write_skills(skill_refs(info["config"]), ".claude/skills")
    for action in report.errors:
        log.error("skill %s: %s", action.key or "<run>", action.error)
run_agent()   # the agent discovers .claude/skills/<key>/SKILL.md

from launchdarkly_ai_server import watch_skills
watcher = None
if info["meta"] is None:
    log.error("config unavailable; skipping reconcile")
else:
    report, watcher = await watch_skills(skill_refs(info["config"]), ".claude/skills")
try:
    run_agent()
finally:
    if watcher is not None:
        watcher.close()
    store.close()

Node.js (server-side) AI

import { FDv2SkillStore, initClient } from '@launchdarkly/ai-server';
const store = new FDv2SkillStore(process.env.LD_SDK_KEY!).start();
if (!(await store.waitForSkills(10_000))) {
  console.warn(`skill delivery has not answered: ${store.failed ?? 'still waiting'}`);
}
await initClient({ skillStore: store });
// ... at shutdown:
await store.close();

import { InMemorySkillStore, initClient } from '@launchdarkly/ai-server';
const store = new InMemorySkillStore();
store.put({
  key: 'pdf-extraction',
  version: 2,
  content: skillMd,
  contentHash: computedSha256Hex,
});
await initClient({ skillStore: store });

import { inspectConfig, skillRefs } from '@launchdarkly/ai-server';
const info = await inspectConfig('doc-agent', { kind: 'user', key: 'user-123' });
const refs = skillRefs(info.config);   // [{ key: 'pdf-extraction', version: 2 }]

import { getSkill, getSkills, allSkills, getSkillResult } from '@launchdarkly/ai-server';
const newest = await getSkill('pdf-extraction');
const pinned = await getSkill('pdf-extraction', { version: 2 });
const batch = await getSkills(refs);
const everything = await allSkills();
const text = new TextDecoder().decode(newest?.content);

import { initClient, inspectConfig, skillRefs, writeSkills } from '@launchdarkly/ai-server';
await initClient({ skillStore: store });
const info = await inspectConfig('doc-agent', context);
if (info.meta === null) {
  console.error('config unavailable; skipping reconcile');
} else {
  const report = await writeSkills(skillRefs(info.config), '.claude/skills');
  if (!report.ok) {
    for (const action of report.errors) console.error(`skill ${action.key}: ${action.error}`);
  }
}

import { watchSkills } from '@launchdarkly/ai-server';
const { report, watcher } = await watchSkills(skillRefs(info.config), '.claude/skills');
try {
  // run the agent
} finally {
  await watcher.close();
  await store.close();
}

Store options

The skill store accepts the following options to control delivery mode, endpoints, and retry behavior. Each option has a different name in Python and Node.js:

Materialize skills safely

The following explains what materializing does and does not do:

• Layout is <root>/<skill-key>/SKILL.md, matching the agentskills.io convention. This means you can point the root straight at .claude/skills/ or an equivalent directory.
• Materializing is a reconciliation. write_skills/writeSkills records what it owns in a manifest at <root>/.launchdarkly-skills.json and only ever overwrites or deletes paths that the manifest lists. If you place a file yourself at a managed path, it’s reported as an error and left untouched. If you do not commit materialized skills, add the manifest to .gitignore.
• A byte-identical file is adopted. If an unmanaged file’s bytes already exactly match the content LaunchDarkly resolved, it is adopted into the manifest and reported skipped_current. This is what makes a reconcile recoverable after a process is killed between writing a skill file and rewriting the manifest. Bytes that differ in any way are still refused.
• LaunchDarkly content takes precedence at execution time. A managed file whose bytes differ from the resolved content, whether from a stale version or a local edit, is overwritten and reported updated.
• The root’s parent must exist. The call creates the leaf root directory only. A missing parent, a root that is a file, or a root that is a symlink is a caller error, distinct from a per-skill error action.
• A requested skill that was never delivered is an error. In that case, report.ok is false. A pinned reference resolving to nothing is not a silent success.
• A store with no first payload does not prune. The run reports the retrieval as unavailable and leaves disk untouched, rather than reading an empty store as a full revocation.
• "*" materializes the entire project library. This is an explicit opt-in that puts every skill’s description into the agent’s context, including skills no config references. Present the config-scoped form as the default, and "*" as a choice.

Options

The write_skills/writeSkills function accepts the following options to control pruning, timeout, and how it behaves when retrieval is unavailable:

Distinguish an absent skill from a tampered one

get_skill_result/getSkillResult runs the same retrieval as get_skill/getSkill, but reports why instead of collapsing to None/null. Use it to fail closed on suspected tampering while tolerating a merely absent skill.

.detail is human-readable and safe to log. It does not contain skill content or a filesystem path. There is no batch form of get_skill_result/getSkillResult. Call it per key where the outcome matters.

Security guidance

This section covers how to detect tampering, isolate privileges between the reconcile process and the agent, and account for platform and beta-specific limitations when you materialize skills onto disk.

Integrity verification and the audit log line

Every withheld skill emits one structured ERROR log record intended for security information and event management (SIEM) ingestion, regardless of your telemetry configuration.

In Python, it is on the logger launchdarkly_ai_server.skills_core. In Node.js, it is one console.error line prefixed [LaunchDarkly].

The event name ld.skills.integrity_failure is a stability commitment. It and its field names will not change outside a major release, which means you can alert on it directly.

Each record’s reason_code field holds one of the following values:

Here’s an example of what the log record looks like:

ld.skills.integrity_failure {"action":"withheld","event":"ld.skills.integrity_failure","expected_hash":"0000…0000","language":"python","observed_hash":"5fc8…6ec0","reason":"content hash mismatch","reason_code":"hash_mismatch","skill_key":"pdf-extraction","version":2}

The hash_mismatch, over_size_cap, and not_utf8 codes are the shapes of active tampering and warrant a page. The other reason codes indicate a malformed, truncated, or misbehaving payload. Skill content, filesystem paths, and credentials never appear in the record.

Privilege separation

Run the reconcile (write_skills/writeSkills) as a different identity than the agent. A SKILL.md is agent instructions, which means an agent that can write its own skills directory can rewrite its own instructions, and write access to the manifest is worse because it controls what the next reconcile may delete.

The SDK sets skill files and the manifest to mode 0644 and skill directories to 0755, with no execute bit, but those modes provide protection only if the two identities differ.

Write access to any directory above the managed root is write access to the root by another route, because it permits renaming the root aside and leaving a symlink in its place. Check each directory above the managed root, all the way up to /, and confirm the agent’s identity can write to none of them.

Platform guarantee differences

Python on POSIX and Node.js on Linux close the swap window. The managed root is opened once per reconcile and held for the duration of the call. This means a directory swapped for a symlink after its checks cannot redirect a write or a delete. Python on Windows and Node.js on macOS and Windows fall back to a per-component check immediately before each filesystem operation. This is a narrow check-then-use race, and an attacker with write permission on the managed root or its ancestors can win it. Windows is not a tested platform for materialization in this release.

Beta caveats

Some limitations for the beta version include:

• No payload signing. Delivery is TLS-only. The content hash establishes self-consistency, not origin authenticity.
• No LaunchDarkly telemetry is emitted for skills. Customer-visible detection is the log record described above.
• Do not use view-scoped SDK keys for skills. Use an environment-level SDK key.

Troubleshooting

This table includes possible errors and their solutions: