feat(client): Agent Skills value types

[XieX]

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

1. feat(client): Agent Skills value types #29 — value types ← you are here
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

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

---

First of seven stacked PRs landing Agent Skills. The feature was built as one-way-dependent layers, and the stack follows that layering so each piece can be read on its own. This one is the leaf: nothing here imports another skills module.

What's here

types.ts gains the four frozen value types — SkillReference, Skill, ReconcileAction, ReconcileReport — plus the untrusted wire shape RawSkillObject, the structural SkillStore seam, the freezing factories, and the key/version validators. parseAiConfig now applies them to a variation's skills array.

That validation fails closed: one malformed reference fails the whole parse. Silently dropping it would materialize a partial skill set without telling anyone.

Skills are opaque byte buffers — by construction

Skill.content is a Uint8Array: the verified verbatim bytes, exactly what was hashed, with no encoding or file-format claim attached. The SDK never interprets skill content anywhere — there is deliberately no frontmatter accessor and no YAML dependency in this package. A consumer that wants structure (frontmatter, markdown, anything else) decodes and parses the bytes itself, with whatever parser and bounds it trusts.

One TypedArray caveat is documented at the factory: Object.freeze throws on an array-buffer view, so the frozen Skill wrapper makes the content binding immutable while the bytes themselves are shared with the caller.

Cross-language contract

Every type and field name here, including the camelCase wire field contentHash, is an identical string to the Python SDK, which carries the mirror bytes-typed content. A polyglot fleet has to agree on the shape it exchanges, so changing one is a cross-language breaking change.

The accessor outcome type (security review LA-2)

SkillOutcome and SkillOutcomeReason land here with the other value types, plus the createSkillOutcome factory that freezes them like every sibling. They are consumed in #31 by getSkillResult.

SkillOutcomeReason is a closed five-token vocabulary — absent, integrity_failure, ok, store_unavailable, wrong_version — listed alphabetically, and the Python SDK publishes the same five for the same conditions. It is deliberately coarser than the eight-token IntegrityReasonCode from the log record: the integrity tokens say which check failed and go to the operator, these say what the caller got.

SkillStore.getObject also gains its third parameter here — getObject(kind, key, version?), matching Python's get_object(kind, key, version=None). A store may hold several versions of one key and only the store can pick between them; without the parameter, a pin the store could have satisfied gets reported as a version mismatch. The post-hoc equality check at the accessor boundary is kept regardless, because the store is untrusted.

Verification

Client package 294 → 342 tests. typecheck and biome clean.

🤖 Generated with Claude Code

---

Note

Overview
Introduces the Agent Skills foundation in the client package: frozen value types (SkillReference, Skill, reconcile/report types, SkillOutcome/SkillStore seam), factories, and strict validators for skill keys (^[a-z0-9][a-z0-9-]*$, max 256 chars) and versions (integer ≥ 1).

AiConfigRep gains an optional skills array of { key, version } references. parseAiConfig now validates that array when present and fails the entire config on any bad entry (no silent partial skill sets). InitBaseClientOptions documents an optional skillStore hook for later accessors.

Public index exports the new types plus createSkill / createSkillReference. Tests cover exhaustive skills parse rules in schema.test.ts and immutability / ReconcileReport.ok / errors behavior in new skills.test.ts.

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