@juno-ai/bind 10.0.0 → 11.0.0

package/README.md

@@ -33,6 +33,27 @@ constraints that will fail CI if you break them.
 
 ### Unreleased
 
+**Added**
+
+- **`@juno-ai/bind/skills`** — progressive disclosure for *instructions*, the
+  mirror of `@juno-ai/bind/plugins`. `createSkillRegistry` for what your source
+  ships, `partitionSkillCatalog` for the Tier-1 catalog and its token budget,
+  `resolveActiveSkillInstructions` for the bodies (live-head or pinned to a
+  completed run's hashes, over a batched `ExternalSkillSource` for skills your
+  users author), `createSkillActivation` to drive the loop's `activateSkills`
+  port, `admitSkillLoad` for the active-set bounds, `parseSkillMarkdown` /
+  `serializeSkillMarkdown` for the `SKILL.md` interchange format over your own
+  YAML, and `buildAgentSkillsDiscoveryIndex` for the Agent Skills Discovery RFC
+  v0.2.0 document. See "How to give an agent loadable skills".
+
+  Two notes for a host that already has something like this. The catalog
+  returns **data, not prose** — the wording is yours, for the same prompt-cache
+  reason `partitionPluginCatalog` gives. And the content digest is **the
+  package's**, not a port like the one `toolCallArgsHash` takes: a skill's hash
+  is computed at registration, which is synchronous, and it identifies build
+  content rather than being persisted across versions. `Sha256Hex` is still a
+  parameter if you would rather inject a native one.
+
 **Breaking**
 
 - `runToolLoop` now returns `ToolLoopResult` (`{ stopReason, stats }`) instead
@@ -1073,6 +1094,130 @@ data migration.
 system prompt's business, and re-rendering it byte-identically for unchanged
 inputs is what preserves a provider's prompt-cache prefix.
 
+### How to give an agent loadable skills
+
+A *skill* is a markdown procedure or reference module the model can pull into
+its own instructions: a catalog line it always sees, a body injected into the
+system prompt once loaded, and resources it may read after that. It is the same
+progressive disclosure as tool activation, applied to knowledge — and it exists
+because the accumulated know-how of a real workspace does not fit in a context
+window, while a catalog line costs about fifty tokens.
+
+Register what your own source ships:
+
+```ts
+import { createSkillRegistry, partitionSkillCatalog } from "@juno-ai/bind/skills";
+
+const skills = createSkillRegistry({ onWarn: (message, fields) => log.warn(message, fields) });
+
+skills.registerPlatform({
+  name: "triaging-inbound-work",
+  description: "How this team triages inbound requests.",
+  whenToUse: "When asked to sort, rank, or route a queue of incoming work.",
+  render: () => TRIAGE_BODY,
+});
+// A skill contributed by a plugin is offered only to an agent that can load
+// that plugin — a recipe for tools it cannot call is noise.
+skills.registerPlugin("documents", DRAFTING_SKILL);
+```
+
+Render the catalog from a partition, in your own words:
+
+```ts
+const active = new Set<string>(session.activeSkills);
+const available = skills.summaries({ availablePlugins: agent.plugins });
+const { active: loaded, loadable, truncated } = partitionSkillCatalog(active, available);
+```
+
+`partitionSkillCatalog` returns **data, not prose**, exactly as
+`partitionPluginCatalog` does. It also enforces a token budget by marking the
+overflow `name_only` rather than dropping it — a name is still enough for the
+model to call `load_skill` and read the real description, whereas a skill it
+cannot see is one it can never ask for. Pass your own `cost` if your line format
+differs from `- name: description — whenToUse`; a budget is only as honest as
+its measurement.
+
+Then wire activation into the loop, and bound how much can be loaded:
+
+```ts
+import {
+  admitSkillLoad,
+  createSkillActivation,
+  estimateSkillBodyTokens,
+  resolveActiveSkillInstructions,
+} from "@juno-ai/bind/skills";
+
+const loadedSkillShas: Record<string, string> = {};
+const resolveActiveInstructions = (activeRefs: string[]) =>
+  resolveActiveSkillInstructions({ activeRefs, available, registry: skills });
+
+const activation = createSkillActivation({
+  availableSkills: available,
+  activeSkills: active,          // yours: seeded before the first turn, persisted after the last
+  loadedSkillShas,               // yours: hoist it so a failed run still records what it read
+  store: { resolveActiveInstructions },
+  applyInstructions: (instructions) => renderSystemPrompt({ instructions }),
+});
+
+await runToolLoop({ ...params, activateSkills: (refs) => activation.activateSkills(refs) });
+```
+
+Two details are worth knowing before you wire your own `load_skill` tool. The
+resolver renders in a **total order** (origin, then name) rather than the order
+skills were loaded, because these bodies sit high in the system prompt and a
+resumed session's persisted order would otherwise byte-shift the cacheable
+prefix. And `admitSkillLoad` is what keeps a looping model from loading its way
+into a context-limit error — you measure, it judges:
+
+```ts
+// Cheapest first. The count is a `Set.size`; the token bound needs the
+// resolver, which for a host-stored skill is a query plus the wrapping of every
+// active body. A model that has hit the cap keeps calling `load_skill`, so
+// folding these into one pass pays that cost on every call purely to refuse.
+const byCount = admitSkillLoad({ activeCount: active.size });
+if (!byCount.admitted) return { success: false, kind: "validation", error: byCount.reason };
+
+const { instructions } = await resolveActiveInstructions([...active, ref]);
+const byTokens = admitSkillLoad({ projectedBodyTokens: estimateSkillBodyTokens(instructions) });
+if (!byTokens.admitted) return { success: false, kind: "validation", error: byTokens.reason };
+```
+
+Omitting a measurement omits its bound, which is what makes the two-pass shape
+expressible — and a measurement that arrives broken (`NaN`, negative) refuses
+rather than admits, because a nonsense count is not evidence of room.
+
+Skills your *users* author live in your database, not the registry. Hand the
+resolver an `externalSource` and it routes any ref that is not `platform:<name>`
+to you — batched, so one activation stays one query:
+
+```ts
+resolveActiveSkillInstructions({
+  activeRefs,
+  available,
+  registry: skills,
+  externalSource: async (refs, pinnedShas) => loadWorkspaceSkills(workspaceId, refs, pinnedShas),
+});
+```
+
+`pinnedShas` is how a replay stays honest. Each resolution records the
+`contentSha` it actually rendered; feed a completed run's map back in and every
+skill resolves to the body that run saw, so an eval is not silently grading
+against instructions that were edited afterwards.
+
+To read or write the interchange format, pass your own YAML implementation —
+the package takes peer dependencies only:
+
+```ts
+import { parseSkillMarkdown } from "@juno-ai/bind/skills";
+import yaml from "js-yaml";
+
+const parsed = parseSkillMarkdown(raw, { parse: yaml.load, stringify: (v) => yaml.dump(v, { lineWidth: -1 }) });
+```
+
+Import is deliberately lenient — it repairs the unquoted-colon frontmatter
+mistake and warns — and fails only on frontmatter that is not YAML and on a
+missing `description`, the one field with no sensible default.
+
 ### How to restore a persisted activation set
 
 ```ts
@@ -1135,6 +1280,7 @@ keeps a consumer who only wants routing from pulling in the rest.
 | `@juno-ai/bind/transcript` | `validateAndHealMessages` | You send transcripts to more than one provider, or you build them across turns |
 | `@juno-ai/bind/tools` | `sanitizeToolSchema` | Any tool schema reaches a provider — especially third-party ones |
 | `@juno-ai/bind/plugins` | Tool/plugin vocabulary, `defineTool` / `pluginFromTools`, the wire-definition and tool-result encoders, the registry factory, progressive-disclosure activation | You are authoring tools, or you have more of them than fit comfortably in one prompt |
+| `@juno-ai/bind/skills` | Skill vocabulary — the code-skill registry, the `SKILL.md` codec, the content hash, the catalog's total order and token budget, the active-instruction resolver, the activation controller, active-set bounds, and the Agent Skills Discovery document | Your agent needs loadable instructions, not just tools — a workspace's procedures, a house style, a runbook |
 | `@juno-ai/bind/testing` | Scripted-model fixtures — `loopHarness`, `scriptedModel`, `toolCallTurn`, `finalAnswer`, `freshState`, `recordingSink`, `steppingClock` | You want multi-turn, multi-tool tests without a credential or a mocked chat client |
 
 ### Contracts the types do not carry

package/index.d.ts

@@ -11,9 +11,12 @@
  * coalesced heartbeat, failure classification, tool-batch pooling, child-run
  * lineage and admission), the streaming-completion watchdog and completion
  * defect detection (`src/completion/`), transcript validation/healing, provider
- * tool-schema sanitization, and the plugin/tool vocabulary with its registry and
+ * tool-schema sanitization, the plugin/tool vocabulary with its registry and
  * progressive-disclosure activation — generic over the host's invocation
- * context. What is NOT here is
+ * context — and the skill vocabulary that applies the same disclosure to
+ * instructions (`src/skills/` — the code-skill registry, the `SKILL.md` codec,
+ * the content hash that makes a replay honest, the catalog budget, the
+ * active-instruction resolver and its activation controller). What is NOT here is
  * the run driver: starting a run, recording what it did, and delivering its
  * output. See the README for the rest of what is deliberately absent.
  */
@@ -24,4 +27,5 @@ export * from "./run/index.js";
 export * from "./transcript/index.js";
 export * from "./tools/index.js";
 export * from "./plugins/index.js";
+export * from "./skills/index.js";
 export * from "./loop/index.js";

package/index.js

@@ -11,9 +11,12 @@
  * coalesced heartbeat, failure classification, tool-batch pooling, child-run
  * lineage and admission), the streaming-completion watchdog and completion
  * defect detection (`src/completion/`), transcript validation/healing, provider
- * tool-schema sanitization, and the plugin/tool vocabulary with its registry and
+ * tool-schema sanitization, the plugin/tool vocabulary with its registry and
  * progressive-disclosure activation — generic over the host's invocation
- * context. What is NOT here is
+ * context — and the skill vocabulary that applies the same disclosure to
+ * instructions (`src/skills/` — the code-skill registry, the `SKILL.md` codec,
+ * the content hash that makes a replay honest, the catalog budget, the
+ * active-instruction resolver and its activation controller). What is NOT here is
  * the run driver: starting a run, recording what it did, and delivering its
  * output. See the README for the rest of what is deliberately absent.
  */
@@ -24,4 +27,5 @@ export * from "./run/index.js";
 export * from "./transcript/index.js";
 export * from "./tools/index.js";
 export * from "./plugins/index.js";
+export * from "./skills/index.js";
 export * from "./loop/index.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juno-ai/bind",
-  "version": "10.0.0",
-  "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing with transport-error classification, the streaming-completion watchdog, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, and the plugin/tool vocabulary. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
+  "version": "11.0.0",
+  "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing with transport-error classification, the streaming-completion watchdog, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, the plugin/tool vocabulary, and the skill vocabulary (`./skills`) for progressive knowledge disclosure. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",
   "main": "./index.js",
@@ -43,6 +43,10 @@
       "types": "./plugins/index.d.ts",
       "import": "./plugins/index.js"
     },
+    "./skills": {
+      "types": "./skills/index.d.ts",
+      "import": "./skills/index.js"
+    },
     "./testing": {
       "types": "./testing/index.d.ts",
       "import": "./testing/index.js"

package/skills/activation.d.ts

@@ -0,0 +1,64 @@
+import type { ResolvedSkillInstructions } from "./resolve.js";
+import type { SkillSummary, SkillWarn } from "./types.js";
+/**
+ * Progressive knowledge disclosure — the skill half of `plugins/activation.ts`.
+ *
+ * The controller does one thing and refuses to do a second: it adds refs to the
+ * run's active set, resolves the bodies, records the hash pin, and hands the
+ * full resolved set back. It **never touches the transcript**. The system
+ * message is a pure render of run state, so a host re-renders it from the
+ * instructions it is given rather than splicing a marker or mutating a string
+ * in place — the difference shows up the first time a run is resumed and the
+ * spliced text is already there twice.
+ */
+/**
+ * The skill read path, injectable. The other half of the source — the Tier-1
+ * catalog — is the `availableSkills` array, so a host customizes both
+ * independently: an in-memory store for a test, an isolated one-skill store for
+ * an always-on persona, the real registry plus its database for a live run.
+ */
+export interface SkillStore {
+    resolveActiveInstructions(activeRefs: string[]): Promise<ResolvedSkillInstructions>;
+}
+export interface SkillActivation {
+    /**
+     * Activate skills for this run: admit the refs that are in the catalog,
+     * resolve the bodies for the **whole** active set, pin their hashes, and hand
+     * the instructions to `applyInstructions`.
+     *
+     * Resolution covers the whole set rather than the delta because the caller
+     * re-renders one section from the result; a delta would make it the caller's
+     * job to concatenate in the right order, which is the ordering guarantee the
+     * resolver exists to own. A call that admits nothing new is a no-op.
+     */
+    activateSkills(refs: Iterable<string>): Promise<void>;
+}
+export interface SkillActivationParams {
+    /** This run's Tier-1 catalog — the set a ref must be in to be activatable. */
+    availableSkills: readonly SkillSummary[];
+    /**
+     * Caller-owned active-ref set, mutated in place.
+     *
+     * Owned by the caller because two other things read it: conversation assembly
+     * seeds it before the first turn (it is what the initial catalog renders as
+     * active), and the host persists it when the run ends.
+     */
+    activeSkills: Set<string>;
+    /**
+     * Caller-owned ref → `contentSha` pin, grown on each activation.
+     *
+     * Also caller-owned, and for a sharper reason: a host hoists it above the try
+     * block so the terminal-path catch can still persist what the run had loaded.
+     * A pin the controller owned would be lost on exactly the failed runs an eval
+     * most wants to reproduce.
+     */
+    loadedSkillShas: Record<string, string>;
+    store: SkillStore;
+    /**
+     * Called after each activation that changed the set, with the freshly
+     * resolved bodies for the full active set.
+     */
+    applyInstructions: (instructions: string[]) => void;
+    onWarn?: SkillWarn;
+}
+export declare function createSkillActivation(params: SkillActivationParams): SkillActivation;

package/skills/activation.js

@@ -0,0 +1,39 @@
+export function createSkillActivation(params) {
+    const { activeSkills, loadedSkillShas, store, applyInstructions } = params;
+    const availableRefs = new Set(params.availableSkills.map((summary) => summary.ref));
+    return {
+        async activateSkills(refs) {
+            const admitted = [];
+            for (const ref of refs) {
+                // The catalog is the authorization boundary for reading a skill: it is
+                // already gated on the agent's plugins and the host's scope, so a ref
+                // outside it is refused here rather than resolved and then filtered.
+                if (!availableRefs.has(ref)) {
+                    params.onWarn?.("refusing to activate unavailable skill", { ref });
+                    continue;
+                }
+                if (!activeSkills.has(ref) && !admitted.includes(ref))
+                    admitted.push(ref);
+            }
+            if (admitted.length === 0)
+                return;
+            // Resolve against the *would-be* set, and commit only if that succeeds.
+            //
+            // Adding first is the obvious order and it is wrong. A store that throws
+            // — a database blip, an external source that times out — would leave the
+            // caller's set claiming the skill is active while `applyInstructions`
+            // never ran, so the body is not in the prompt. The retry then finds
+            // nothing new to admit and returns early, and the run finishes with a
+            // catalog that lists a skill as loaded whose instructions the model never
+            // saw. Failing cleanly is what makes a retry able to fix it.
+            const next = new Set(activeSkills);
+            for (const ref of admitted)
+                next.add(ref);
+            const { instructions, shas } = await store.resolveActiveInstructions([...next]);
+            for (const ref of admitted)
+                activeSkills.add(ref);
+            Object.assign(loadedSkillShas, shas);
+            applyInstructions(instructions);
+        },
+    };
+}

package/skills/admission.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Whether a run may load one more skill.
+ *
+ * Two bounds, and they are not redundant. The **count** is cheap and is checked
+ * before anything is resolved. The **token total** is the one that actually
+ * protects the context window: twelve short skills fit and three long ones do
+ * not, so a count cap alone bounds the wrong quantity. Without the second, a
+ * model in a loop loads its way to a context-limit error mid-run, which reads
+ * to a user as the agent breaking rather than as it over-reaching.
+ *
+ * Shaped like `admitChildRun` in `run/children.ts`, and for the same reason:
+ * **the host measures, the harness judges.** Estimating the token cost of the
+ * would-be active set means resolving bodies, which is I/O; comparing a number
+ * to a limit is not. So each bound arrives with the measurement it judges, and
+ * a bound whose number the host could not produce is simply omitted — a rule
+ * that silently never fires is worse than one that is visibly absent.
+ */
+export type SkillLoadRefusal = {
+    kind: "active_count";
+    active: number;
+    max: number;
+} | {
+    kind: "active_body_tokens";
+    tokens: number;
+    max: number;
+};
+export type SkillLoadDecision = {
+    admitted: true;
+} | {
+    admitted: false;
+    refusal: SkillLoadRefusal;
+    /**
+     * A noun phrase, carrying no identifiers. Hosts surface a refusal to the
+     * model as a tool error and sometimes to a person, so it must be safe to
+     * render in both places and must read after a host's own prefix.
+     */
+    reason: string;
+};
+export interface SkillLoadBounds {
+    /**
+     * Refs already active. Omit the pair to skip the count bound; a non-finite or
+     * negative count **refuses**, because a broken measurement is not evidence
+     * that there is room.
+     */
+    activeCount?: number;
+    maxActive?: number;
+    /**
+     * Estimated tokens of the instruction set the load would produce — the whole
+     * would-be active set, not the increment. Omit the pair to skip the bound.
+     */
+    projectedBodyTokens?: number;
+    maxBodyTokens?: number;
+}
+/**
+ * Judge a `load_skill` against the active-set bounds. A skill that is already
+ * active is never subject to either bound — reloading it adds nothing — so
+ * callers should short-circuit before calling.
+ */
+export declare function admitSkillLoad(bounds: SkillLoadBounds): SkillLoadDecision;
+/** Estimated token cost of a resolved instruction set — the input to the body bound. */
+export declare function estimateSkillBodyTokens(instructions: readonly string[]): number;

package/skills/admission.js

@@ -0,0 +1,41 @@
+import { SKILL_MAX_ACTIVE_BODY_TOKENS, SKILL_MAX_ACTIVE_PER_SESSION, estimateSkillTokens, } from "./types.js";
+function bounded(measurement) {
+    return measurement !== undefined;
+}
+/**
+ * Judge a `load_skill` against the active-set bounds. A skill that is already
+ * active is never subject to either bound — reloading it adds nothing — so
+ * callers should short-circuit before calling.
+ */
+export function admitSkillLoad(bounds) {
+    const maxActive = bounds.maxActive ?? SKILL_MAX_ACTIVE_PER_SESSION;
+    if (bounded(bounds.activeCount)) {
+        const active = bounds.activeCount;
+        // `!(active < max)` rather than `active >= max`: every comparison is false
+        // against NaN, so the naive form admits on a broken count instead of
+        // refusing on one.
+        if (!(Number.isFinite(active) && active >= 0 && active < maxActive)) {
+            return {
+                admitted: false,
+                refusal: { kind: "active_count", active, max: maxActive },
+                reason: `active-skill limit reached (${maxActive} loaded). Work from the skills already loaded rather than loading more.`,
+            };
+        }
+    }
+    const maxBodyTokens = bounds.maxBodyTokens ?? SKILL_MAX_ACTIVE_BODY_TOKENS;
+    if (bounded(bounds.projectedBodyTokens)) {
+        const tokens = bounds.projectedBodyTokens;
+        if (!(Number.isFinite(tokens) && tokens >= 0 && tokens <= maxBodyTokens)) {
+            return {
+                admitted: false,
+                refusal: { kind: "active_body_tokens", tokens, max: maxBodyTokens },
+                reason: `loading this skill would take the loaded instructions to about ${tokens} tokens, over the ${maxBodyTokens}-token budget. Work from the skills already loaded instead of loading more.`,
+            };
+        }
+    }
+    return { admitted: true };
+}
+/** Estimated token cost of a resolved instruction set — the input to the body bound. */
+export function estimateSkillBodyTokens(instructions) {
+    return instructions.reduce((total, body) => total + estimateSkillTokens(body), 0);
+}

package/skills/catalog.d.ts

@@ -0,0 +1,54 @@
+import { type SkillSummary } from "./types.js";
+/**
+ * Total order over summaries: origin, then name, then ref.
+ *
+ * A **total** order, not just a stable one: `ref` is the unique tiebreak so two
+ * skills that collide on name still sort deterministically. Both the catalog
+ * and the injected instruction bodies use this comparator, which is what keeps
+ * the system prompt byte-stable across a fresh run and a resumed one — the
+ * active set is persisted in load order, and rendering in *that* order would
+ * shift the prefix on every resume.
+ */
+export declare function compareSkillSummaries(a: SkillSummary, b: SkillSummary): number;
+/** How much of a skill's catalog entry survived the budget. */
+export type SkillCatalogDetail = "full" | "name_only";
+export interface SkillCatalogEntry {
+    summary: SkillSummary;
+    detail: SkillCatalogDetail;
+}
+export interface SkillCatalogPartition {
+    /** Already loaded. Always rendered in full — the body's cost is already paid. */
+    active: SkillSummary[];
+    /** Loadable, each marked with the detail the budget allows. */
+    loadable: SkillCatalogEntry[];
+    /** How many loadable entries were demoted to `name_only`. */
+    truncated: number;
+}
+export interface SkillCatalogOptions {
+    /** Defaults to {@link SKILL_CATALOG_TOKEN_BUDGET}. */
+    tokenBudget?: number;
+    /**
+     * Cost of one entry at a given detail, in tokens. Defaults to an estimate of
+     * `- name: description — whenToUse`.
+     *
+     * A host that renders a different line should pass its own: the budget is
+     * only as honest as its measurement, and a default that under-counts a
+     * verbose format silently overruns the prefix it was meant to protect.
+     */
+    cost?: (summary: SkillSummary, detail: SkillCatalogDetail) => number;
+}
+/**
+ * Split the catalog into active and loadable, demoting the loadable tail to
+ * names only once the budget is spent.
+ *
+ * **Demote, never drop.** A skill the model cannot see is a skill it cannot
+ * ask for, and a workspace's library grows past any budget worth setting. A
+ * bare name still routes: it is enough for the model to call `load_skill` and
+ * read the real description. The host is expected to say so in the line it
+ * renders for the truncated tail — `truncated` is there to let it.
+ *
+ * The active set is charged against the budget but never demoted: those bodies
+ * are already in the prompt, so shortening their catalog lines would save
+ * nothing that matters while hiding what the agent is currently working from.
+ */
+export declare function partitionSkillCatalog(activeSkills: ReadonlySet<string>, available: readonly SkillSummary[], options?: SkillCatalogOptions): SkillCatalogPartition;

package/skills/catalog.js

@@ -0,0 +1,77 @@
+import { SKILL_CATALOG_TOKEN_BUDGET, estimateSkillTokens, } from "./types.js";
+/**
+ * The Tier-1 catalog — what the model sees for every skill on every turn,
+ * whether or not it ever loads one.
+ *
+ * This module returns **data, not prose**, exactly as `partitionPluginCatalog`
+ * does and for the same two reasons: catalog wording is a product surface with
+ * the host's voice, and it sits in the cacheable system prefix, where the host
+ * needs byte-identical output for unchanged inputs or it loses the provider's
+ * prompt cache for everything below it. What is genuinely shared is the
+ * *ordering* and the *budget*, and both are here.
+ */
+/**
+ * Origin precedence. Deployment-owned knowledge is described before
+ * plugin-specific recipes, and both before what the workspace wrote — so the
+ * general instruction is read before the specialization, and so the tail that
+ * a budget demotes is the tail that grows without bound.
+ */
+const ORIGIN_RANK = {
+    platform: 0,
+    plugin: 1,
+    tenant: 2,
+};
+/**
+ * Total order over summaries: origin, then name, then ref.
+ *
+ * A **total** order, not just a stable one: `ref` is the unique tiebreak so two
+ * skills that collide on name still sort deterministically. Both the catalog
+ * and the injected instruction bodies use this comparator, which is what keeps
+ * the system prompt byte-stable across a fresh run and a resumed one — the
+ * active set is persisted in load order, and rendering in *that* order would
+ * shift the prefix on every resume.
+ */
+export function compareSkillSummaries(a, b) {
+    return (ORIGIN_RANK[a.origin] - ORIGIN_RANK[b.origin] ||
+        a.name.localeCompare(b.name) ||
+        a.ref.localeCompare(b.ref));
+}
+function defaultCost(summary, detail) {
+    if (detail === "name_only")
+        return estimateSkillTokens(`- ${summary.name}`);
+    const hint = summary.whenToUse ? ` — ${summary.whenToUse}` : "";
+    return estimateSkillTokens(`- ${summary.name}: ${summary.description}${hint}`);
+}
+/**
+ * Split the catalog into active and loadable, demoting the loadable tail to
+ * names only once the budget is spent.
+ *
+ * **Demote, never drop.** A skill the model cannot see is a skill it cannot
+ * ask for, and a workspace's library grows past any budget worth setting. A
+ * bare name still routes: it is enough for the model to call `load_skill` and
+ * read the real description. The host is expected to say so in the line it
+ * renders for the truncated tail — `truncated` is there to let it.
+ *
+ * The active set is charged against the budget but never demoted: those bodies
+ * are already in the prompt, so shortening their catalog lines would save
+ * nothing that matters while hiding what the agent is currently working from.
+ */
+export function partitionSkillCatalog(activeSkills, available, options = {}) {
+    const budget = options.tokenBudget ?? SKILL_CATALOG_TOKEN_BUDGET;
+    const cost = options.cost ?? defaultCost;
+    const ordered = [...available].sort(compareSkillSummaries);
+    const active = ordered.filter((summary) => activeSkills.has(summary.ref));
+    const loadableSummaries = ordered.filter((summary) => !activeSkills.has(summary.ref));
+    let spent = active.reduce((total, summary) => total + cost(summary, "full"), 0);
+    let truncated = 0;
+    const loadable = loadableSummaries.map((summary) => {
+        const full = cost(summary, "full");
+        if (spent + full <= budget) {
+            spent += full;
+            return { summary, detail: "full" };
+        }
+        truncated += 1;
+        return { summary, detail: "name_only" };
+    });
+    return { active, loadable, truncated };
+}

package/skills/discovery.d.ts

@@ -0,0 +1,82 @@
+import { type SkillYamlCodec } from "./skill-md.js";
+import { type Sha256Hex } from "./sha256.js";
+import type { RegisteredSkill } from "./types.js";
+/**
+ * The Agent Skills **discovery index** — how a deployment advertises skills to
+ * agents that are not its own.
+ *
+ * Per the Agent Skills Discovery RFC v0.2.0
+ * (https://github.com/cloudflare/agent-skills-discovery-rfc,
+ * https://agentskills.io/), an external agent fetches
+ * `/.well-known/agent-skills/index.json`, reads the `skills[]` catalogue, pulls
+ * each `SKILL.md` from its advertised `url`, and verifies the bytes against the
+ * published `digest`. Both documents are generated from the same registry here,
+ * so the digest a reader sees always matches the bytes served.
+ *
+ * **What to publish is a product decision and stays with the host** — hence the
+ * explicit `include` allowlist rather than "every platform skill". The
+ * criterion that matters is whether a skill helps an outside agent drive
+ * *something the deployment actually exposes externally*. A skill about the
+ * host's internal agent runtime cannot help an external client and does not
+ * belong in a public document; a plugin-contributed skill is tied to tools that
+ * are not on the external surface; a workspace's own skills are private data.
+ * Making the list an argument also means dropping a new file into a skills
+ * folder never publishes it by accident.
+ */
+/** The RFC v0.2.0 schema URL advertised in the index's `$schema` field. */
+export declare const AGENT_SKILLS_DISCOVERY_SCHEMA_URL = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+/** Root of the well-known discovery namespace (host-relative per RFC 3986). */
+export declare const AGENT_SKILLS_WELL_KNOWN_BASE = "/.well-known/agent-skills";
+/** Host-relative URL of the `SKILL.md` artifact for a skill name. */
+export declare function skillMarkdownUrl(name: string, base?: string): string;
+/** One entry in the discovery index's `skills[]` array. */
+export interface DiscoverySkillEntry {
+    /** Lower-kebab skill identifier. */
+    name: string;
+    /** Distribution format. Single-file `SKILL.md` skills only. */
+    type: "skill-md";
+    /** Tier-1 catalogue line (≤ 1024 chars per the RFC). */
+    description: string;
+    /** Location of the `SKILL.md`, resolved per RFC 3986. */
+    url: string;
+    /** SHA-256 of the served `SKILL.md` bytes, `sha256:{64-hex}`. */
+    digest: string;
+}
+/** The full `/.well-known/agent-skills/index.json` document. */
+export interface AgentSkillsDiscoveryIndex {
+    $schema: string;
+    skills: DiscoverySkillEntry[];
+}
+export interface SkillDiscoveryOptions {
+    /**
+     * Names to publish. Anything not registered as a `platform` skill is skipped.
+     *
+     * Deliberately **not** `Iterable<string>`: this options object is built once
+     * and read by both functions below, and a one-shot iterable (a generator, a
+     * `Map.keys()`) would be drained by the first call — so the index would
+     * publish the allowlist and every subsequent `SKILL.md` fetch would 404, with
+     * nothing in either signature to suggest why. Both accepted forms are
+     * re-iterable, which makes that failure unrepresentable rather than merely
+     * documented.
+     */
+    include: readonly string[] | ReadonlySet<string>;
+    /** The registry to read from; the host bootstraps it before calling. */
+    registry: {
+        get(name: string): RegisteredSkill | undefined;
+    };
+    yaml: SkillYamlCodec;
+    /** Base for the advertised `url`. Host-relative by default. */
+    baseUrl?: string;
+    sha256Hex?: Sha256Hex;
+}
+/** Build the discovery index from the allowlisted, registered platform skills. */
+export declare function buildAgentSkillsDiscoveryIndex(options: SkillDiscoveryOptions): AgentSkillsDiscoveryIndex;
+/**
+ * The published `SKILL.md` text for a name, or `null` when it is not published.
+ *
+ * One return value for "not on the allowlist", "not registered", and
+ * "registered but not a platform skill": the caller serves a 404 for all three,
+ * and distinguishing them would tell an anonymous reader which internal skills
+ * exist.
+ */
+export declare function getPublishedSkillMarkdown(name: string, options: SkillDiscoveryOptions): string | null;