docs(client): document Agent Skills

[XieX]

Stacked PR 7 of 7 — merge bottom-up into xie/agent-skills-feature-ac9ac7.

1. feat(client): Agent Skills value types #29 — value types
2. feat(client): symlink-refusing filesystem primitives #30 — symlink-refusing filesystem primitives
3. feat(client): Agent Skills store seam, verification, and accessors #31 — store seam, verification, accessors
4. test(client): integrity verification and the accessor telemetry sweep #32 — integrity + telemetry tests
5. feat(client): writeSkills materialization and the abuse matrix #33 — writeSkills + abuse matrix
6. test(client): the rest of the writeSkills suite #34 — remaining writeSkills tests
7. docs(client): document Agent Skills #35 — docs ← you are here

Each PR targets the one below it, so GitHub already shows only this PR's own diff.

---

Last of seven. Documents the feature now that all of it exists. The README section and the contributor notes both span every layer in the stack, so they land once here rather than as six partial edits to the same two files.

README.md

The public API — the accessors, writeSkills, the store seam, the exported constants, and the types — plus three things stated plainly rather than left for a reader to discover:

Content delivery is not wired up in this release. Everything runs against SkillStore, the shipped default is absent, and the accessors throw an actionable error until one is configured.

Skill content is opaque to the SDK. A verified Skill carries content as a Uint8Array — the exact bytes that were hashed — and the SDK never parses, decodes, or interprets it. There is deliberately no frontmatter accessor and no YAML dependency; the docs show the one-line TextDecoder step for consumers who want a string, and leave frontmatter parsing to them.

The security posture, including its limitation. Node exposes no renameat/unlinkat, so the final rename cannot be performed relative to a pinned directory descriptor. An attacker who already has write permission on the managed root can still win a race to redirect a write or a delete outside it. Keep the managed root writable only by the process running the SDK.

The one narrow exception to the reconcile's conservatism, stated where the conservatism itself is described: a colliding file whose bytes already are the resolved content is adopted rather than refused, so a reconcile killed between the content writes and the final manifest write heals itself instead of wedging those skills forever. Nothing is overwritten, because nothing needs to be — the only file ever adopted is already byte-identical to what LaunchDarkly resolved. Differing bytes, and bytes that cannot be read at all, are still refused and left untouched.

The two key constraints the filesystem layer imposes that the data model does not — the 255-byte path-component bound and the 22 Windows reserved device names (con, prn, aux, nul, com1–com9, lpt1–lpt9) — including that a key like aux stays valid everywhere else, so an AI Config referencing it still parses and its other skills still materialize. Plus the residual the SDK cannot check for a caller: the bound is per component, not on the total path, so a deep root and a long key can still exceed Windows' 260-character MAX_PATH. One sentence, deliberately not a check — the root is the customer's.

agents.md

What a future change has to preserve:

• Module ownership rows for the new modules.
• The one-way dependency direction — types ← skills-core ← skills, and types + safe-fs + skills-core ← skills-fs — and why closing a cycle there would let the accessor and filesystem layers disagree about whether a store is configured.
• A Dependencies table giving a reason for every runtime dependency and optional peer.
• Skill content documented as what it is: Uint8Array of the verified verbatim bytes, opaque to the SDK, with the single wire-string encode living inside integrity verification and nowhere else.

Four new pitfalls, each a mistake that would otherwise pass review: interpreting skill content anywhere in the SDK (a parser, a convenience accessor, an encoding assumption), reading writeSkills's timeout as milliseconds, relaxing a path or manifest check in skills-fs.ts, and bypassing fsOps for a destructive call — which makes the operation invisible to the assertions that prove no operation was attempted, so they then pass vacuously.

The path-check pitfall now carries the three specifics a later contributor is most likely to widen without reading the reasoning first:

• Why the reserved-name rejection is unconditional rather than platform-gated, and why it lives in keyRejectionReason rather than in the key grammar: a grammar-level rejection would invalidate the whole AI Config for a customer who never touches Windows, and a dropped skillRefs entry lets prune delete the on-disk copy — turning "fails to write on Windows" into "gets deleted on Linux".
• That adoption is a narrowing of the clobber refusal and requires an exact hash match; anything weaker and the guarantee is gone. skipped_current is reused deliberately, since a new ReconcileActionKind member would break consumers with an exhaustive switch.
• That every flag in readRegularFile is load-bearing, O_NONBLOCK most of all, because opening a FIFO with no writer blocks forever — and that the sweep derives its filename pattern from tempNamePattern rather than copying it.

Also here

One pre-existing test renamed to describe its behaviour directly instead of citing a specification section.

getSkillResult (security review LA-2)

README.md gains the accessor in the Agent Skills table, SkillOutcome/SkillOutcomeReason in Shared Types, and a Fail closed on tampering subsection under the observability material — a worked example exiting on integrity_failure while treating absent as ordinary, a table of the five tokens, and an explicit statement that getSkill is unchanged and that the two accessors differ only in what they report.

agents.md records the five-token vocabulary, why it is coarser than IntegrityReasonCode, and the full Resolution → reason mapping including the two skills-fs.ts rows — so a later contributor adding a sixth internal outcome has to decide which public token it maps to rather than defaulting to absent. Plus the rule that the version goes into getObject while the equality check stays a defense, and that getSkill's contract is frozen.

Verification

Workspace 1172 passing (+2 skipped). typecheck, biome, and sherif clean.

🤖 Generated with Claude Code

---

Note

Overview
Documentation-only PR that publishes the Agent Skills stack for @launchdarkly/ai-server: a large Agent Skills section in README.md and matching contributor guidance in agents.md, after the feature landed in earlier stacked PRs.

The README now documents the public surface (skillRefs, getSkill / getSkillResult, writeSkills, SkillStore / InMemorySkillStore), states that remote content delivery is not wired yet (store must be configured), and spells out security/reconcile behavior (hash verification, manifest reconcile, ld.skills.integrity_failure SIEM logging, fail-closed tampering handling). It also updates initClient(client, options?) (optional skillStore on BYOC) and adds Agent Skills rows to the shared types table.

agents.md adds the skills module layout, one-way dependency rules, a Dependencies table, skillStore lifecycle notes, new pitfalls (opaque Uint8Array content, writeSkills timeout in seconds, non-relaxable fs checks, fsOps), and extended invariants (telemetry allowlist, vocabularies, frozen getSkill contract).

A single test in client.test.ts is renamed to drop a spec section reference; no runtime behavior changes in this diff.

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