@juspay/neurolink 9.85.1 → 9.86.0

package/dist/skills/skillMatcher.d.ts

@@ -9,12 +9,41 @@
 import type { SkillDefinition, SkillIndexItem, SkillSearchQuery } from "../types/index.js";
 /** Strip instructions from a full definition to form an index entry. */
 export declare function toSkillIndexItem(skill: SkillDefinition): SkillIndexItem;
+/**
+ * Sort index entries by name (byte order, locale-independent) so every
+ * listing renders byte-identically across calls and store backends.
+ * Store enumeration order (Redis SCAN, fs.readdir, S3 listings) is not
+ * stable — an unsorted listing would shuffle between calls and invalidate
+ * provider prompt caches. Returns a new array.
+ */
+export declare function sortSkillIndex(items: SkillIndexItem[]): SkillIndexItem[];
 /** Filter index entries by query/tag/scope. Active skills only. */
 export declare function filterSkillIndex(items: SkillIndexItem[], query: SkillSearchQuery): SkillIndexItem[];
 /**
- * Render the compact skills index injected into the system prompt.
- * Names + descriptions only — instructions are never included; the model
- * loads them via search_skills. Returns null when nothing is visible so
- * callers can skip injection entirely.
+ * Reject resource paths that could escape a skill's namespace: absolute
+ * paths, traversal segments, and empty segments. The manager validates
+ * before reaching any store — this is defense in depth for stores whose
+ * keys are built by concatenation (S3, Redis) or path joining.
+ */
+export declare function isSafeSkillResourcePath(resourcePath: string): boolean;
+/** Whether a skill is visible from the calling scope. */
+export declare function isSkillVisibleInScope(skill: Pick<SkillDefinition, "scope" | "scopeIds">, scopeId?: string): boolean;
+/**
+ * Render the `<available_skills>` block embedded in the use_skill tool
+ * description ("tool" discovery mode). One line per skill — name,
+ * description, tags — instructions never appear here.
+ *
+ * Budget handling is uniform and stateless: over budget, every
+ * description drops to its first sentence, then to a hard 80-char cap.
+ * The render is a pure function of the (sorted) index, so the tool
+ * description stays byte-identical across calls — a prerequisite for
+ * provider prompt caching. Names are never dropped.
+ */
+export declare function renderSkillListing(items: SkillIndexItem[], budgetChars: number): string | null;
+/**
+ * Render the compact skills index appended to the system prompt
+ * ("system-prompt" discovery mode). Names + descriptions only —
+ * instructions are never included; the model loads them via use_skill.
+ * Returns null when nothing is visible so callers can skip injection.
  */
 export declare function formatSkillsPromptIndex(items: SkillIndexItem[], maxItems: number): string | null;

package/dist/skills/skillMatcher.js

@@ -11,6 +11,16 @@ export function toSkillIndexItem(skill) {
     const { instructions: _instructions, ...indexItem } = skill;
     return indexItem;
 }
+/**
+ * Sort index entries by name (byte order, locale-independent) so every
+ * listing renders byte-identically across calls and store backends.
+ * Store enumeration order (Redis SCAN, fs.readdir, S3 listings) is not
+ * stable — an unsorted listing would shuffle between calls and invalidate
+ * provider prompt caches. Returns a new array.
+ */
+export function sortSkillIndex(items) {
+    return [...items].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
 /** Filter index entries by query/tag/scope. Active skills only. */
 export function filterSkillIndex(items, query) {
     const lowerQuery = query.query?.toLowerCase();
@@ -46,10 +56,75 @@ export function filterSkillIndex(items, query) {
     return query.limit !== undefined ? matched.slice(0, query.limit) : matched;
 }
 /**
- * Render the compact skills index injected into the system prompt.
- * Names + descriptions only — instructions are never included; the model
- * loads them via search_skills. Returns null when nothing is visible so
- * callers can skip injection entirely.
+ * Reject resource paths that could escape a skill's namespace: absolute
+ * paths, traversal segments, and empty segments. The manager validates
+ * before reaching any store — this is defense in depth for stores whose
+ * keys are built by concatenation (S3, Redis) or path joining.
+ */
+export function isSafeSkillResourcePath(resourcePath) {
+    const normalized = resourcePath.replace(/\\/g, "/");
+    return (normalized.length > 0 &&
+        !normalized.startsWith("/") &&
+        !normalized.split("/").some((segment) => segment === ".." || segment === ""));
+}
+/** Whether a skill is visible from the calling scope. */
+export function isSkillVisibleInScope(skill, scopeId) {
+    if (!scopeId || skill.scope !== "scoped") {
+        return true;
+    }
+    return (skill.scopeIds ?? []).includes(scopeId);
+}
+/** Trim a description to its first sentence (or the whole text when unsplittable). */
+function firstSentence(description) {
+    const match = description.match(/^[^.!?]*[.!?]/);
+    return match ? match[0].trim() : description;
+}
+/**
+ * Render the `<available_skills>` block embedded in the use_skill tool
+ * description ("tool" discovery mode). One line per skill — name,
+ * description, tags — instructions never appear here.
+ *
+ * Budget handling is uniform and stateless: over budget, every
+ * description drops to its first sentence, then to a hard 80-char cap.
+ * The render is a pure function of the (sorted) index, so the tool
+ * description stays byte-identical across calls — a prerequisite for
+ * provider prompt caching. Names are never dropped.
+ */
+export function renderSkillListing(items, budgetChars) {
+    if (items.length === 0) {
+        return null;
+    }
+    const render = (describe) => {
+        const lines = items.map((item) => {
+            const tags = item.tags && item.tags.length > 0
+                ? ` [tags: ${item.tags.join(", ")}]`
+                : "";
+            return `- ${item.name}: ${describe(item)}${tags}`;
+        });
+        return ["<available_skills>", ...lines, "</available_skills>"].join("\n");
+    };
+    const full = render((item) => item.description);
+    if (full.length <= budgetChars) {
+        return full;
+    }
+    const sentences = render((item) => firstSentence(item.description));
+    if (sentences.length <= budgetChars) {
+        return sentences;
+    }
+    const HARD_CAP = 80;
+    // Floor render — returned even if it still exceeds the budget.
+    return render((item) => {
+        const sentence = firstSentence(item.description);
+        return sentence.length > HARD_CAP
+            ? `${sentence.slice(0, HARD_CAP - 1)}…`
+            : sentence;
+    });
+}
+/**
+ * Render the compact skills index appended to the system prompt
+ * ("system-prompt" discovery mode). Names + descriptions only —
+ * instructions are never included; the model loads them via use_skill.
+ * Returns null when nothing is visible so callers can skip injection.
  */
 export function formatSkillsPromptIndex(items, maxItems) {
     if (items.length === 0) {
@@ -66,13 +141,13 @@ export function formatSkillsPromptIndex(items, maxItems) {
         return `- ${label}: ${item.description}${tags}`;
     });
     const truncationNote = items.length > visible.length
-        ? `\n(${items.length - visible.length} more skills exist — use search_skills or list_skills to discover them.)`
+        ? `\n(${items.length - visible.length} more skills exist — use list_skills to discover them.)`
         : "";
     return ([
         "## Available Skills",
         "The following team-defined skills (SOPs, playbooks, workflows) are available.",
         "Before answering from general knowledge, check whether one applies to the user's request.",
-        "To use a skill, call the search_skills tool to load its full instructions, then follow them exactly.",
+        "To use a skill, call the use_skill tool with its name to load the full instructions, then follow them exactly.",
         "",
         ...lines,
     ].join("\n") + truncationNote);

package/dist/skills/skillSessionTracker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-session skill activation state.
+ *
+ * A skill activated via use_skill is pinned to its session: the tracker
+ * holds the pinned instruction message until the turn is persisted
+ * (drainPending → StoreConversationTurnOptions.skillMessages) and answers
+ * "is this skill already loaded?" so re-invocations return a cheap
+ * already_loaded note instead of the full body.
+ *
+ * The stored session history is the source of truth — pinned messages
+ * carry `metadata.isSkill`. hydrate() rebuilds a session's active set from
+ * stored messages on every activation attempt (use_skill is rare, one
+ * history read per attempt), so dedup stays correct across process
+ * restarts, multiple instances sharing a Redis memory backend, and failed
+ * persistence: a pin that never reached storage simply re-activates on
+ * the next turn instead of being falsely reported as loaded.
+ */
+import type { ChatMessage, SkillActivationRecord, SkillDefinition } from "../types/index.js";
+/** Render the pinned history message for an activated skill. */
+export declare function buildSkillActivationMessage(skill: SkillDefinition): ChatMessage;
+export declare class SkillSessionTracker {
+    /** sessionId → skillId → activation record. */
+    private active;
+    /** sessionId → pinned messages awaiting persistence into the session turn. */
+    private pending;
+    /** Whether the skill is already active (loaded) in this session. */
+    isActive(sessionId: string, skillId: string, name: string): boolean;
+    /** Activation record for an active skill (by id, falling back to name). */
+    getActivation(sessionId: string, skillId: string, name?: string): SkillActivationRecord | undefined;
+    /**
+     * Record an activation: marks the skill active and queues its pinned
+     * message for persistence when the turn is stored.
+     */
+    recordActivation(sessionId: string, skill: SkillDefinition): ChatMessage;
+    /**
+     * Rebuild the active set from stored session history, then merge the
+     * in-process pending activations (this turn's pins, not yet stored).
+     * Called before every dedup check — the rebuild keeps state truthful
+     * when other instances pinned skills or when a past pin never reached
+     * storage.
+     */
+    hydrate(sessionId: string, storedMessages: ChatMessage[]): void;
+    /**
+     * Remove and return the pinned messages queued for this session. Called
+     * once per turn by the memory-store path; an empty result means nothing
+     * was activated this turn.
+     */
+    drainPending(sessionId: string): ChatMessage[];
+    /** Active skill records for a session (listing/debugging). */
+    listActive(sessionId: string): SkillActivationRecord[];
+    private recordsFor;
+}

package/dist/skills/skillSessionTracker.js

@@ -0,0 +1,149 @@
+/**
+ * Per-session skill activation state.
+ *
+ * A skill activated via use_skill is pinned to its session: the tracker
+ * holds the pinned instruction message until the turn is persisted
+ * (drainPending → StoreConversationTurnOptions.skillMessages) and answers
+ * "is this skill already loaded?" so re-invocations return a cheap
+ * already_loaded note instead of the full body.
+ *
+ * The stored session history is the source of truth — pinned messages
+ * carry `metadata.isSkill`. hydrate() rebuilds a session's active set from
+ * stored messages on every activation attempt (use_skill is rare, one
+ * history read per attempt), so dedup stays correct across process
+ * restarts, multiple instances sharing a Redis memory backend, and failed
+ * persistence: a pin that never reached storage simply re-activates on
+ * the next turn instead of being falsely reported as loaded.
+ */
+import { randomUUID } from "node:crypto";
+/** Upper bound on tracked sessions; oldest are evicted first (insertion order). */
+const MAX_TRACKED_SESSIONS = 1000;
+/** Render the pinned history message for an activated skill. */
+export function buildSkillActivationMessage(skill) {
+    const version = skill.version ?? 1;
+    return {
+        id: `skill-${randomUUID()}`,
+        role: "user",
+        content: `[Skill loaded: ${skill.name} v${version}]\n\n${skill.instructions}`,
+        timestamp: new Date().toISOString(),
+        metadata: {
+            isSkill: true,
+            skillId: skill.id,
+            skillName: skill.name,
+            skillVersion: version,
+        },
+    };
+}
+/** Activation record derived from a pinned history message, when it is one. */
+function recordFromMessage(message) {
+    const meta = message.metadata;
+    if (!meta?.isSkill || !meta.skillId || !meta.skillName) {
+        return null;
+    }
+    return {
+        skillId: meta.skillId,
+        name: meta.skillName,
+        version: meta.skillVersion ?? 1,
+        activatedAt: message.timestamp ?? new Date(0).toISOString(),
+    };
+}
+export class SkillSessionTracker {
+    /** sessionId → skillId → activation record. */
+    active = new Map();
+    /** sessionId → pinned messages awaiting persistence into the session turn. */
+    pending = new Map();
+    /** Whether the skill is already active (loaded) in this session. */
+    isActive(sessionId, skillId, name) {
+        return Boolean(this.getActivation(sessionId, skillId, name));
+    }
+    /** Activation record for an active skill (by id, falling back to name). */
+    getActivation(sessionId, skillId, name) {
+        const records = this.active.get(sessionId);
+        if (!records) {
+            return undefined;
+        }
+        const byId = records.get(skillId);
+        if (byId || !name) {
+            return byId;
+        }
+        for (const record of records.values()) {
+            if (record.name === name) {
+                return record;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Record an activation: marks the skill active and queues its pinned
+     * message for persistence when the turn is stored.
+     */
+    recordActivation(sessionId, skill) {
+        const message = buildSkillActivationMessage(skill);
+        const record = recordFromMessage(message);
+        this.recordsFor(sessionId).set(skill.id, record);
+        const queue = this.pending.get(sessionId);
+        if (queue) {
+            queue.push(message);
+        }
+        else {
+            this.pending.set(sessionId, [message]);
+        }
+        return message;
+    }
+    /**
+     * Rebuild the active set from stored session history, then merge the
+     * in-process pending activations (this turn's pins, not yet stored).
+     * Called before every dedup check — the rebuild keeps state truthful
+     * when other instances pinned skills or when a past pin never reached
+     * storage.
+     */
+    hydrate(sessionId, storedMessages) {
+        const records = new Map();
+        for (const message of storedMessages) {
+            const record = recordFromMessage(message);
+            if (record && !records.has(record.skillId)) {
+                records.set(record.skillId, record);
+            }
+        }
+        for (const message of this.pending.get(sessionId) ?? []) {
+            const record = recordFromMessage(message);
+            if (record) {
+                records.set(record.skillId, record);
+            }
+        }
+        this.recordsFor(sessionId); // reserve the slot (applies the session cap)
+        this.active.set(sessionId, records);
+    }
+    /**
+     * Remove and return the pinned messages queued for this session. Called
+     * once per turn by the memory-store path; an empty result means nothing
+     * was activated this turn.
+     */
+    drainPending(sessionId) {
+        const queue = this.pending.get(sessionId);
+        if (!queue || queue.length === 0) {
+            return [];
+        }
+        this.pending.delete(sessionId);
+        return queue;
+    }
+    /** Active skill records for a session (listing/debugging). */
+    listActive(sessionId) {
+        return Array.from(this.active.get(sessionId)?.values() ?? []);
+    }
+    recordsFor(sessionId) {
+        let records = this.active.get(sessionId);
+        if (!records) {
+            if (this.active.size >= MAX_TRACKED_SESSIONS) {
+                const oldest = this.active.keys().next().value;
+                if (oldest !== undefined) {
+                    this.active.delete(oldest);
+                    this.pending.delete(oldest);
+                }
+            }
+            records = new Map();
+            this.active.set(sessionId, records);
+        }
+        return records;
+    }
+}

package/dist/skills/skillStoreRedis.d.ts

@@ -9,11 +9,19 @@
 import type { SkillDefinition, SkillIndexItem, SkillRedisStorageConfig, SkillStore } from "../types/index.js";
 export declare class RedisSkillStore implements SkillStore {
     private readonly keyPrefix;
+    /**
+     * Resources live under `<keyPrefix>__resources__:` — a reserved segment
+     * inside the skill prefix, explicitly excluded from the index SCAN so
+     * resource values are never mistaken for skills, whatever the
+     * configured keyPrefix looks like.
+     */
+    private readonly resourcePrefix;
     private readonly normalizedConfig;
     private clientPromise;
     constructor(config: SkillRedisStorageConfig);
     private getClient;
     private skillKey;
+    getResource(id: string, resourcePath: string): Promise<string | null>;
     get(id: string): Promise<SkillDefinition | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;

package/dist/skills/skillStoreRedis.js

@@ -8,14 +8,22 @@
  */
 import { getNormalizedConfig, getPooledRedisClient, scanKeys, } from "../utils/redis.js";
 import { logger } from "../utils/logger.js";
-import { toSkillIndexItem } from "./skillMatcher.js";
+import { isSafeSkillResourcePath, toSkillIndexItem } from "./skillMatcher.js";
 const DEFAULT_KEY_PREFIX = "neurolink:skills:";
 export class RedisSkillStore {
     keyPrefix;
+    /**
+     * Resources live under `<keyPrefix>__resources__:` — a reserved segment
+     * inside the skill prefix, explicitly excluded from the index SCAN so
+     * resource values are never mistaken for skills, whatever the
+     * configured keyPrefix looks like.
+     */
+    resourcePrefix;
     normalizedConfig;
     clientPromise = null;
     constructor(config) {
         this.keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
+        this.resourcePrefix = `${this.keyPrefix}__resources__:`;
         this.normalizedConfig = getNormalizedConfig({
             ...(config.url ? { url: config.url } : {}),
             ...(config.host ? { host: config.host } : {}),
@@ -39,6 +47,14 @@ export class RedisSkillStore {
     skillKey(id) {
         return `${this.keyPrefix}${id}`;
     }
+    async getResource(id, resourcePath) {
+        if (!isSafeSkillResourcePath(resourcePath)) {
+            return null;
+        }
+        const client = await this.getClient();
+        const raw = await client.get(`${this.resourcePrefix}${id}:${resourcePath}`);
+        return raw ? String(raw) : null;
+    }
     async get(id) {
         const client = await this.getClient();
         const raw = await client.get(this.skillKey(id));
@@ -55,7 +71,7 @@ export class RedisSkillStore {
     }
     async index() {
         const client = await this.getClient();
-        const keys = await scanKeys(client, `${this.keyPrefix}*`);
+        const keys = (await scanKeys(client, `${this.keyPrefix}*`)).filter((key) => !key.startsWith(this.resourcePrefix));
         if (keys.length === 0) {
             return [];
         }

package/dist/skills/skillStoreS3.d.ts

@@ -22,20 +22,35 @@ export declare class S3SkillStore implements SkillStore {
     private readonly injectedOps?;
     private readonly prefix;
     private ops;
+    /** Last parsed index + its ETag, revalidated with If-None-Match reads. */
+    private cachedIndexDoc;
+    private cachedIndexEtag;
     constructor(config: SkillS3StorageConfig, 
     /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
     injectedOps?: SkillS3ObjectOps | undefined);
+    invalidate(): void;
     private getOps;
     private skillKey;
     private indexKey;
+    /** Resources live beside the skill object: <prefix>skills/<id>/<path>. */
+    private resourceKey;
+    getResource(id: string, resourcePath: string): Promise<string | null>;
     get(id: string): Promise<SkillDefinition | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;
     index(): Promise<SkillIndexItem[]>;
     private writeIndex;
     /**
-     * Read index.json; when missing or unparsable, rebuild it from a listing
-     * of the skills/ prefix and persist the rebuilt document (self-heal).
+     * Raw index.json read. Returns the body (with its ETag when available),
+     * null body when the object is absent, or notModified when a
+     * conditional read reported the cached copy unchanged.
+     */
+    private readIndexObject;
+    /**
+     * Read index.json (ETag-revalidated when the ops support conditional
+     * reads — an unchanged index costs a 304, not a download); when missing
+     * or unparsable, rebuild it from a listing of the skills/ prefix and
+     * persist the rebuilt document (self-heal).
      */
     private readOrRebuildIndex;
 }

package/dist/skills/skillStoreS3.js

@@ -17,7 +17,7 @@
  */
 import { createRequire } from "node:module";
 import { logger } from "../utils/logger.js";
-import { toSkillIndexItem } from "./skillMatcher.js";
+import { isSafeSkillResourcePath, toSkillIndexItem } from "./skillMatcher.js";
 const lazyRequire = createRequire(import.meta.url);
 let cachedS3Module;
 function loadS3Module() {
@@ -97,6 +97,32 @@ function createDefaultOps(config) {
             } while (continuationToken);
             return keys;
         },
+        async getObjectConditional(key, etag) {
+            try {
+                const response = (await client.send(new mod.GetObjectCommand({
+                    Bucket: bucket,
+                    Key: key,
+                    ...(etag ? { IfNoneMatch: etag } : {}),
+                })));
+                const body = (await response.Body?.transformToString()) ?? null;
+                return {
+                    body,
+                    ...(response.ETag ? { etag: response.ETag } : {}),
+                };
+            }
+            catch (error) {
+                const name = error.name;
+                const status = error
+                    .$metadata?.httpStatusCode;
+                if (status === 304 || name === "304" || name === "NotModified") {
+                    return { body: null, notModified: true };
+                }
+                if (name === "NoSuchKey" || name === "NotFound") {
+                    return { body: null };
+                }
+                throw error;
+            }
+        },
     };
 }
 export class S3SkillStore {
@@ -104,6 +130,9 @@ export class S3SkillStore {
     injectedOps;
     prefix;
     ops = null;
+    /** Last parsed index + its ETag, revalidated with If-None-Match reads. */
+    cachedIndexDoc = null;
+    cachedIndexEtag;
     constructor(config, 
     /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
     injectedOps) {
@@ -113,6 +142,10 @@ export class S3SkillStore {
         this.prefix =
             rawPrefix === "" || rawPrefix.endsWith("/") ? rawPrefix : `${rawPrefix}/`;
     }
+    invalidate() {
+        this.cachedIndexDoc = null;
+        this.cachedIndexEtag = undefined;
+    }
     getOps() {
         if (!this.ops) {
             this.ops = this.injectedOps ?? createDefaultOps(this.config);
@@ -125,6 +158,16 @@ export class S3SkillStore {
     indexKey() {
         return `${this.prefix}index.json`;
     }
+    /** Resources live beside the skill object: <prefix>skills/<id>/<path>. */
+    resourceKey(id, resourcePath) {
+        return `${this.prefix}skills/${id}/${resourcePath}`;
+    }
+    async getResource(id, resourcePath) {
+        if (!isSafeSkillResourcePath(resourcePath)) {
+            return null;
+        }
+        return this.getOps().getObject(this.resourceKey(id, resourcePath));
+    }
     async get(id) {
         const body = await this.getOps().getObject(this.skillKey(id));
         if (!body) {
@@ -169,18 +212,42 @@ export class S3SkillStore {
     async writeIndex(index) {
         index.lastUpdated = new Date().toISOString();
         await this.getOps().putObject(this.indexKey(), JSON.stringify(index, null, 2));
+        // The write changed the object's ETag; keep the doc, revalidate next read.
+        this.cachedIndexDoc = index;
+        this.cachedIndexEtag = undefined;
     }
     /**
-     * Read index.json; when missing or unparsable, rebuild it from a listing
-     * of the skills/ prefix and persist the rebuilt document (self-heal).
+     * Raw index.json read. Returns the body (with its ETag when available),
+     * null body when the object is absent, or notModified when a
+     * conditional read reported the cached copy unchanged.
+     */
+    async readIndexObject(ops) {
+        if (ops.getObjectConditional) {
+            return ops.getObjectConditional(this.indexKey(), this.cachedIndexDoc ? this.cachedIndexEtag : undefined);
+        }
+        return { body: await ops.getObject(this.indexKey()) };
+    }
+    /**
+     * Read index.json (ETag-revalidated when the ops support conditional
+     * reads — an unchanged index costs a 304, not a download); when missing
+     * or unparsable, rebuild it from a listing of the skills/ prefix and
+     * persist the rebuilt document (self-heal).
      */
     async readOrRebuildIndex() {
         const ops = this.getOps();
-        const raw = await ops.getObject(this.indexKey());
-        if (raw) {
+        const read = await this.readIndexObject(ops);
+        if (read.notModified && this.cachedIndexDoc) {
+            return this.cachedIndexDoc;
+        }
+        if (read.body) {
             try {
-                const parsed = JSON.parse(raw);
+                const parsed = JSON.parse(read.body);
                 if (Array.isArray(parsed.skills)) {
+                    this.cachedIndexDoc = parsed;
+                    // Cache the ETag only for a body that parsed: pairing a corrupt
+                    // object's ETag with the previous good doc would make every
+                    // later conditional read 304 into permanently stale data.
+                    this.cachedIndexEtag = read.etag;
                     return parsed;
                 }
             }
@@ -189,6 +256,7 @@ export class S3SkillStore {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
+            this.cachedIndexEtag = undefined;
         }
         const skillsPrefix = `${this.prefix}skills/`;
         const keys = await ops.listKeys(skillsPrefix);
@@ -214,6 +282,10 @@ export class S3SkillStore {
             lastUpdated: new Date().toISOString(),
             skills,
         };
+        // Cache the rebuilt doc even when persistence below fails, so reads
+        // don't fall back to a stale pre-rebuild copy.
+        this.cachedIndexDoc = rebuilt;
+        this.cachedIndexEtag = undefined;
         try {
             await this.writeIndex(rebuilt);
             logger.info("[SkillStoreS3] Rebuilt skills index", {

package/dist/skills/skillStores.d.ts

@@ -11,26 +11,40 @@ import type { SkillDefinition, SkillIndexItem, SkillStore, SkillsStorageConfig }
 /** In-process store backed by a Map. */
 export declare class InMemorySkillStore implements SkillStore {
     private skills;
-    constructor(seed?: SkillDefinition[]);
+    /** skill id → relative path → content. */
+    private resources;
+    constructor(seed?: SkillDefinition[], resources?: Record<string, Record<string, string>>);
     get(id: string): Promise<SkillDefinition | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;
     index(): Promise<SkillIndexItem[]>;
+    getResource(id: string, resourcePath: string): Promise<string | null>;
 }
 /**
  * Directory-backed store. Read layouts:
  *  - `<dir>/<id>.json`      — JSON SkillDefinition (mutable)
  *  - `<dir>/<name>.md`      — frontmatter markdown (read-only source)
- *  - `<dir>/<name>/SKILL.md` — Claude-skills directory layout (read-only source)
+ *  - `<dir>/<name>/SKILL.md` — Claude-skills directory layout (read-only source);
+ *    sibling files become on-demand resources (read_skill_resource)
  * Mutations always write `<id>.json`; a JSON file shadows a markdown skill
  * with the same id, so updating a markdown-sourced skill "copies up" to JSON.
  */
 export declare class FileSystemSkillStore implements SkillStore {
     private readonly baseDir;
     private cache;
+    /** skill id → directory, for skills loaded from the SKILL.md layout. */
+    private skillDirs;
     constructor(baseDir: string);
     invalidate(): void;
     get(id: string): Promise<SkillDefinition | null>;
+    /**
+     * Resources exist only for directory-layout skills (`<name>/SKILL.md`) —
+     * every sibling file of SKILL.md is addressable by its relative path.
+     * The REAL path must stay inside the skill directory: lexical
+     * containment alone would follow a symlink planted inside the skill dir
+     * to anywhere on the host.
+     */
+    getResource(id: string, resourcePath: string): Promise<string | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;
     index(): Promise<SkillIndexItem[]>;