agentfootprint 1.15.0 → 1.16.0

package/dist/esm/index.js

@@ -30,6 +30,8 @@ export { LLMError } from './types';
 export { agentLoop } from './executor';
 // ── Instructions (also available from agentfootprint/instructions) ──
 export { defineInstruction, AgentPattern, quickBind } from './instructions.barrel';
+// ── Skills (also available from agentfootprint/skills) ──
+export { defineSkill, SkillRegistry } from './skills.barrel';
 // ── Recorders (also available from agentfootprint/observe) ──
 export { TokenRecorder, ToolUsageRecorder, TurnRecorder, CostRecorder } from './observe.barrel';
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAQpB,sEAAsE;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAc3E,+DAA+D;AAC/D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA0BnC,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGnF,+DAA+D;AAC/D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAQpB,sEAAsE;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAc3E,+DAA+D;AAC/D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA0BnC,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGnF,2DAA2D;AAC3D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAG7D,+DAA+D;AAC/D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/esm/lib/concepts/AgentBuilder.js

@@ -25,6 +25,8 @@ export class Agent {
     agentPattern = AgentPattern.Regular;
     overrides = new Map();
     agentInstructions = [];
+    skillsPromptAddition;
+    skillsTools;
     initialDecisionScope;
     enableStreaming = false;
     enableVerboseNarrative = false;
@@ -250,6 +252,63 @@ export class Agent {
             this.agentInstructions.push(i);
         return this;
     }
+    /**
+     * Attach a `SkillRegistry` — a typed, versioned bundle of procedures
+     * the model can discover via `list_skills` and activate via
+     * `read_skill(id)`. Registry's skills are wired through the existing
+     * AgentInstruction pipeline (each skill IS-A AgentInstruction) so
+     * per-skill `activeWhen` / `prompt` / `tools` / `onToolResult` rules
+     * fire exactly as with plain `.instruction(...)`.
+     *
+     * Idempotent: calling `.skills()` twice REPLACES the prior registry
+     * (panel #6). For additive composition, compose registries yourself
+     * before passing them in.
+     *
+     * @example
+     * ```ts
+     * const registry = new SkillRegistry<MyDecision>({ surfaceMode: 'auto' });
+     * registry.register(defineSkill({ id: 'port-triage', ... }));
+     *
+     * Agent.create({ provider: anthropic('claude-sonnet-4-5') })
+     *   .skills(registry)
+     *   .build();
+     * ```
+     */
+    skills(registry) {
+        // Drop any previously-mounted skill state — idempotent replace.
+        this.agentInstructions = this.agentInstructions.filter((i) => !i.__skillMount);
+        if (this.skillsTools) {
+            for (const t of this.skillsTools)
+                this.registry.unregister(t.id);
+        }
+        this.skillsPromptAddition = undefined;
+        this.skillsTools = undefined;
+        // 1. Skill bodies → AgentInstructions (per-skill prompt/tools/onToolResult/activeWhen)
+        for (const instr of registry.toInstructions()) {
+            // Mark so a later .skills() call can strip this one without
+            // affecting hand-registered instructions.
+            const tagged = { ...instr, __skillMount: true };
+            this.agentInstructions.push(tagged);
+        }
+        // 2. Auto-generated tools (list_skills, read_skill). Always registered —
+        //    these are the discovery path for the model and must remain callable
+        //    regardless of any skill's `activeWhen`. The `has()` guard handles
+        //    the edge case where a caller registered a tool with the same id
+        //    manually BEFORE calling `.skills()`.
+        const { listSkills, readSkill } = registry.toTools();
+        this.skillsTools = [listSkills, readSkill];
+        if (!this.registry.has(listSkills.id))
+            this.registry.register(listSkills);
+        if (!this.registry.has(readSkill.id))
+            this.registry.register(readSkill);
+        // 3. System-prompt fragment (only under 'system-prompt' / 'both' modes).
+        //    Stored as a separate field so it can be stripped if `.skills()` is
+        //    called again with a different registry.
+        const fragment = registry.toPromptFragment();
+        if (fragment)
+            this.skillsPromptAddition = fragment;
+        return this;
+    }
     /**
      * Set the initial Decision Scope values.
      * Tool handlers update these values; InstructionsToLLM reads them
@@ -303,10 +362,16 @@ export class Agent {
     }
     /** Build the agent and return a runner. */
     build() {
+        // If `.skills(registry)` supplied a system-prompt fragment, append
+        // it to the user's base prompt. Separated with a blank line so the
+        // two blocks read as distinct sections to the model.
+        const effectivePrompt = this.skillsPromptAddition
+            ? [this.systemPromptText, this.skillsPromptAddition].filter(Boolean).join('\n\n')
+            : this.systemPromptText;
         return new AgentRunner({
             provider: this.provider,
             name: this.agentName,
-            systemPromptText: this.systemPromptText,
+            systemPromptText: effectivePrompt,
             registry: this.registry,
             maxIterations: this.maxIter,
             recorders: [...this.recorders],

package/dist/esm/lib/concepts/AgentBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentBuilder.js","sourceRoot":"","sources":["../../../../src/lib/concepts/AgentBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentBuilder.js","sourceRoot":"","sources":["../../../../src/lib/concepts/AgentBuilder.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/skills/defineSkill.js

@@ -0,0 +1,13 @@
+export function defineSkill(skill) {
+    // Dev-mode: warn on empty description (panel #3: descriptions ≤200 chars
+    // are load-bearing for classification; empty strings are almost certainly
+    // a bug).
+    if (typeof process !== 'undefined' &&
+        process.env?.['NODE_ENV'] !== 'production' &&
+        skill.description.trim().length === 0) {
+        // eslint-disable-next-line no-console
+        console.warn(`[agentfootprint] defineSkill('${skill.id}'): empty description — the model classifies skills by description, an empty one will never be picked.`);
+    }
+    return skill;
+}
+//# sourceMappingURL=defineSkill.js.map

package/dist/esm/lib/skills/defineSkill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineSkill.js","sourceRoot":"","sources":["../../../../src/lib/skills/defineSkill.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,WAAW,CAAsB,KAAuB;IACtE,yEAAyE;IACzE,0EAA0E;IAC1E,UAAU;IACV,IACE,OAAO,OAAO,KAAK,WAAW;QAC9B,OAAO,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,YAAY;QAC1C,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EACrC,CAAC;QACD,sCAAsC;QACtC,OAAO,CAAC,IAAI,CACV,iCAAiC,KAAK,CAAC,EAAE,wGAAwG,CAClJ,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/esm/lib/skills/index.js

@@ -0,0 +1,5 @@
+export { defineSkill } from './defineSkill';
+export { SkillRegistry } from './registry';
+export { renderSkillBody, resolveSkillBody } from './renderBody';
+export { resolveSurfaceMode, parseAnthropicVersion, isClaudeStrongAdherence } from './surfaceMode';
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/skills/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/skills/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/lib/skills/registry.js

@@ -0,0 +1,197 @@
+import { defineTool } from '../../tools';
+import { resolveSkillBody } from './renderBody';
+import { resolveSurfaceMode } from './surfaceMode';
+const DEFAULT_PROMPT_HEADER = 'Available skills — call `read_skill({ id })` to activate one:';
+export class SkillRegistry {
+    skills = new Map();
+    options;
+    constructor(options = {}) {
+        this.options = {
+            surfaceMode: options.surfaceMode ?? 'tool-only',
+            promptHeader: options.promptHeader ?? DEFAULT_PROMPT_HEADER,
+            ...(options.providerHint && { providerHint: options.providerHint }),
+        };
+    }
+    /**
+     * Register a skill.
+     *
+     * Behavior on duplicate `id`:
+     *   - Same `version`: silent no-op (idempotent — safe to call during
+     *     module init multiple times).
+     *   - Different `version`: REPLACES the existing entry AND fires a
+     *     dev-mode `console.warn`. Evals almost certainly need pinning
+     *     to one version at a time, so the warning nudges authors to
+     *     make the replacement intentional.
+     *
+     * Registration order is preserved by `list()` / `toPromptFragment()`.
+     *
+     * TODO(phase-2): when `refreshPolicy.afterTokens` lands, the registry
+     * must also expose a `hash` of its contents so the runtime can detect
+     * "registry changed since last read_skill surface" and re-inject.
+     */
+    register(skill) {
+        const existing = this.skills.get(skill.id);
+        if (existing) {
+            if (existing.version === skill.version) {
+                // Idempotent — same version, no-op.
+                return this;
+            }
+            if (typeof process !== 'undefined' && process.env?.['NODE_ENV'] !== 'production') {
+                // eslint-disable-next-line no-console
+                console.warn(`[agentfootprint] SkillRegistry: replacing skill '${skill.id}' v${existing.version} → v${skill.version}. Pin explicitly if this is not intentional.`);
+            }
+        }
+        this.skills.set(skill.id, skill);
+        return this;
+    }
+    /** Register multiple skills. */
+    registerAll(skills) {
+        for (const s of skills)
+            this.register(s);
+        return this;
+    }
+    /** Look up a skill by id. Returns undefined when unknown. */
+    getById(id) {
+        return this.skills.get(id);
+    }
+    /** All registered skills, in insertion order. */
+    list() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Filter skills by scope tag and/or case-insensitive query over
+     * `title + description`. Used by the auto-generated `list_skills`
+     * tool — panel #3 (`scope` / `query` filtering in the signature
+     * from day one).
+     */
+    search(options = {}) {
+        const { scope, query } = options;
+        const q = query?.trim().toLowerCase();
+        const out = [];
+        for (const s of this.skills.values()) {
+            if (scope && !(s.scope ?? []).includes(scope))
+                continue;
+            if (q) {
+                const haystack = `${s.title} ${s.description}`.toLowerCase();
+                if (!haystack.includes(q))
+                    continue;
+            }
+            out.push(s);
+        }
+        return out;
+    }
+    /**
+     * Resolve the effective surface mode for this registry, consulting
+     * the provider hint when `'auto'`. Stable — consumers can call this
+     * once at build time.
+     */
+    effectiveSurfaceMode() {
+        return resolveSurfaceMode(this.options.surfaceMode, this.options.providerHint);
+    }
+    /**
+     * Compile skills into the `AgentInstruction[]` the Agent loop already
+     * knows how to evaluate. Every Skill already extends AgentInstruction —
+     * this is a type-narrowed passthrough.
+     */
+    toInstructions() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Generate the `list_skills` + `read_skill` tool pair. Both tools go
+     * through `defineTool()` so they appear correctly in manifest /
+     * narrative / toOpenAPI output (panel #6).
+     */
+    toTools() {
+        const registry = this;
+        const listSkills = defineTool({
+            id: 'list_skills',
+            description: 'List available skills. Returns {id, title, description, version} for each. Optional `scope` and `query` filters.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    scope: {
+                        type: 'string',
+                        description: 'Only return skills whose scope array includes this tag.',
+                    },
+                    query: {
+                        type: 'string',
+                        description: 'Case-insensitive search across title + description.',
+                    },
+                },
+            },
+            handler: async (input) => {
+                const matches = registry.search({
+                    ...(input?.scope && { scope: input.scope }),
+                    ...(input?.query && { query: input.query }),
+                });
+                const entries = matches.map((s) => ({
+                    id: s.id,
+                    title: s.title,
+                    description: s.description,
+                    version: s.version,
+                    ...(s.scope && { scope: s.scope }),
+                }));
+                return { content: JSON.stringify({ skills: entries }, null, 2) };
+            },
+        });
+        const readSkill = defineTool({
+            id: 'read_skill',
+            description: 'Read a skill body by id. The returned text is the procedure to follow — treat it as active guidance for the current turn.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'The skill id returned by list_skills.' },
+                },
+                required: ['id'],
+            },
+            handler: async (input) => {
+                const id = input?.id;
+                if (typeof id !== 'string' || id.length === 0) {
+                    return {
+                        content: 'Error: read_skill requires a non-empty `id` string.',
+                        isError: true,
+                    };
+                }
+                const skill = registry.getById(id);
+                if (!skill) {
+                    // Panel #3 + #8: unknown id is a tool-result error the model
+                    // can recover from — NOT a thrown exception.
+                    return {
+                        content: `Error: skill '${id}' not found. Call list_skills to see available skills.`,
+                        isError: true,
+                    };
+                }
+                try {
+                    const body = await resolveSkillBody(skill);
+                    return { content: body };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: `Error loading skill '${id}': ${msg}`,
+                        isError: true,
+                    };
+                }
+            },
+        });
+        return { listSkills, readSkill };
+    }
+    /**
+     * System-prompt fragment listing skills + their descriptions. Returns
+     * `null` when the effective surface mode is `'tool-only'` (no prompt
+     * injection) OR when the registry is empty (no ghost header).
+     */
+    toPromptFragment() {
+        const mode = this.effectiveSurfaceMode();
+        if (mode === 'tool-only')
+            return null;
+        if (this.skills.size === 0)
+            return null;
+        const lines = [this.options.promptHeader, ''];
+        for (const s of this.skills.values()) {
+            lines.push(`- ${s.id} — ${s.title}: ${s.description}`);
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/esm/lib/skills/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/lib/skills/registry.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AASnD,MAAM,qBAAqB,GAAG,+DAA+D,CAAC;AAE9F,MAAM,OAAO,aAAa;IACP,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IAC7C,OAAO,CACqB;IAE7C,YAAY,UAAgC,EAAE;QAC5C,IAAI,CAAC,OAAO,GAAG;YACb,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,WAAW;YAC/C,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,qBAAqB;YAC3D,GAAG,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;SACpE,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,KAAuB;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC3C,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,QAAQ,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;gBACvC,oCAAoC;gBACpC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,YAAY,EAAE,CAAC;gBACjF,sCAAsC;gBACtC,OAAO,CAAC,IAAI,CACV,oDAAoD,KAAK,CAAC,EAAE,MAAM,QAAQ,CAAC,OAAO,OAAO,KAAK,CAAC,OAAO,8CAA8C,CACrJ,CAAC;YACJ,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,WAAW,CAAC,MAAmC;QAC7C,KAAK,MAAM,CAAC,IAAI,MAAM;YAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6DAA6D;IAC7D,OAAO,CAAC,EAAU;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED,iDAAiD;IACjD,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,UAA8C,EAAE;QACrD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;QACjC,MAAM,CAAC,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACtC,MAAM,GAAG,GAAuB,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,SAAS;YACxD,IAAI,CAAC,EAAE,CAAC;gBACN,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,CAAC;gBAC7D,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;oBAAE,SAAS;YACtC,CAAC;YACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACd,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;OAIG;IACH,oBAAoB;QAClB,OAAO,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACjF,CAAC;IAED;;;;OAIG;IACH,cAAc;QACZ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,OAAO;QACL,MAAM,QAAQ,GAAG,IAAI,CAAC;QAEtB,MAAM,UAAU,GAAG,UAAU,CAAC;YAC5B,EAAE,EAAE,aAAa;YACjB,WAAW,EACT,kHAAkH;YACpH,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,yDAAyD;qBACvE;oBACD,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,qDAAqD;qBACnE;iBACF;aACF;YACD,OAAO,EAAE,KAAK,EAAE,KAAyC,EAAE,EAAE;gBAC3D,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC;oBAC9B,GAAG,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;oBAC3C,GAAG,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;iBAC5C,CAAC,CAAC;gBACH,MAAM,OAAO,GAAqB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACpD,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,WAAW,EAAE,CAAC,CAAC,WAAW;oBAC1B,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;iBACnC,CAAC,CAAC,CAAC;gBACJ,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YACnE,CAAC;SACF,CAAC,CAAC;QAEH,MAAM,SAAS,GAAG,UAAU,CAAC;YAC3B,EAAE,EAAE,YAAY;YAChB,WAAW,EACT,2HAA2H;YAC7H,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,uCAAuC,EAAE;iBAC7E;gBACD,QAAQ,EAAE,CAAC,IAAI,CAAC;aACjB;YACD,OAAO,EAAE,KAAK,EAAE,KAAqB,EAAE,EAAE;gBACvC,MAAM,EAAE,GAAG,KAAK,EAAE,EAAE,CAAC;gBACrB,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC9C,OAAO;wBACL,OAAO,EAAE,qDAAqD;wBAC9D,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;gBACnC,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,6DAA6D;oBAC7D,6CAA6C;oBAC7C,OAAO;wBACL,OAAO,EAAE,iBAAiB,EAAE,wDAAwD;wBACpF,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;gBACD,IAAI,CAAC;oBACH,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,CAAC;oBAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;gBAC3B,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC7D,OAAO;wBACL,OAAO,EAAE,wBAAwB,EAAE,MAAM,GAAG,EAAE;wBAC9C,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;YACH,CAAC;SACF,CAAC,CAAC;QAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,gBAAgB;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC;QACzC,IAAI,IAAI,KAAK,WAAW;YAAE,OAAO,IAAI,CAAC;QACtC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAExC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAC9C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/esm/lib/skills/renderBody.js

@@ -0,0 +1,34 @@
+const TAG_REGEX = /<\/(memory|tool_use|skill)>/gi;
+function escape(text) {
+    return text.replace(TAG_REGEX, (m) => `</m\u200D${m.slice(3)}`);
+}
+export function renderSkillBody(skill) {
+    const lines = [];
+    lines.push(`You are now following skill: ${skill.id} (v${skill.version}).`);
+    lines.push('');
+    lines.push(`Title: ${escape(skill.title)}`);
+    lines.push(`Purpose: ${escape(skill.description)}`);
+    if (skill.steps && skill.steps.length > 0) {
+        lines.push('');
+        lines.push('Procedure:');
+        for (let i = 0; i < skill.steps.length; i++) {
+            lines.push(`${i + 1}. ${escape(skill.steps[i])}`);
+        }
+    }
+    if (skill.prompt) {
+        lines.push('');
+        lines.push(`Guidance: ${escape(skill.prompt)}`);
+    }
+    return lines.join('\n');
+}
+/** Resolve the body override — string, async loader, or default render. */
+export async function resolveSkillBody(skill) {
+    if (typeof skill.body === 'string')
+        return skill.body;
+    if (typeof skill.body === 'function') {
+        const result = skill.body();
+        return result instanceof Promise ? await result : result;
+    }
+    return renderSkillBody(skill);
+}
+//# sourceMappingURL=renderBody.js.map

package/dist/esm/lib/skills/renderBody.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderBody.js","sourceRoot":"","sources":["../../../../src/lib/skills/renderBody.ts"],"names":[],"mappings":"AAmBA,MAAM,SAAS,GAAG,+BAA+B,CAAC;AAElD,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,eAAe,CAAI,KAAe;IAChD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,gCAAgC,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;IAC5E,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5C,KAAK,CAAC,IAAI,CAAC,YAAY,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAEpD,IAAI,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAI,KAAe;IACvD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC;IACtD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC5B,OAAO,MAAM,YAAY,OAAO,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3D,CAAC;IACD,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC"}

package/dist/esm/lib/skills/surfaceMode.js

@@ -0,0 +1,52 @@
+/**
+ * Parse Anthropic model ids like `claude-3-5-sonnet-20240620`,
+ * `claude-sonnet-4-5-20250514`, `claude-opus-4-7` into a `{major, minor}`
+ * tuple. Returns `null` for ids we can't parse (unknown → fall back to
+ * the pre-3.5 path, which is the safe default).
+ *
+ * Handles the two id formats Anthropic has shipped:
+ *   - Legacy: `claude-3-5-sonnet` / `claude-3-opus` (major.minor before family)
+ *   - Current: `claude-sonnet-4-5` / `claude-opus-4-7` (family before major.minor)
+ */
+export function parseAnthropicVersion(modelId) {
+    // Current format: claude-{family}-{major}-{minor}[-date]
+    const current = modelId.match(/^claude-[a-z]+-(\d+)-(\d+)(?:[-].*)?$/);
+    if (current) {
+        const major = Number(current[1]);
+        const minor = Number(current[2]);
+        if (Number.isFinite(major) && Number.isFinite(minor))
+            return { major, minor };
+    }
+    // Legacy format: claude-{major}-{minor}-{family}[-date]
+    const legacy = modelId.match(/^claude-(\d+)(?:-(\d+))?-[a-z]+(?:[-].*)?$/);
+    if (legacy) {
+        const major = Number(legacy[1]);
+        const minor = legacy[2] !== undefined ? Number(legacy[2]) : 0;
+        if (Number.isFinite(major) && Number.isFinite(minor))
+            return { major, minor };
+    }
+    return null;
+}
+/** True if the parsed version is Claude ≥ 3.5. */
+export function isClaudeStrongAdherence(version) {
+    if (!version)
+        return false;
+    if (version.major > 3)
+        return true;
+    if (version.major === 3 && version.minor >= 5)
+        return true;
+    return false;
+}
+export function resolveSurfaceMode(mode, hint) {
+    if (mode !== 'auto')
+        return mode;
+    if (!hint)
+        return 'tool-only';
+    if (hint.provider === 'anthropic' && hint.modelId) {
+        const version = parseAnthropicVersion(hint.modelId);
+        return isClaudeStrongAdherence(version) ? 'both' : 'tool-only';
+    }
+    // OpenAI / Ollama / Bedrock / mock / unknown → portable default
+    return 'tool-only';
+}
+//# sourceMappingURL=surfaceMode.js.map

package/dist/esm/lib/skills/surfaceMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceMode.js","sourceRoot":"","sources":["../../../../src/lib/skills/surfaceMode.ts"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,yDAAyD;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACvE,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAChF,CAAC;IAED,wDAAwD;IACxD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAC3E,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAChF,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,uBAAuB,CAAC,OAAgD;IACtF,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,OAAO,CAAC,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,OAAO,CAAC,KAAK,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,IAAiB,EACjB,IAAmB;IAEnB,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC,IAAI;QAAE,OAAO,WAAW,CAAC;IAE9B,IAAI,IAAI,CAAC,QAAQ,KAAK,WAAW,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClD,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpD,OAAO,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;IACjE,CAAC;IAED,gEAAgE;IAChE,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/esm/lib/skills/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/lib/skills/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/skills/types.ts"],"names":[],"mappings":""}

package/dist/esm/providers/prompt/skillBasedPrompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"skillBasedPrompt.js","sourceRoot":"","sources":["../../../../src/providers/prompt/skillBasedPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAwBH,gEAAgE;AAEhE,MAAM,UAAU,gBAAgB,CAC9B,MAAwB,EACxB,UAAmC,EAAE;IAErC,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,QAAQ,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAE5D,OAAO;QACL,OAAO,EAAE,CAAC,GAAkB,EAAE,EAAE;YAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YACnD,MAAM,KAAK,GAAa,EAAE,CAAC;YAE3B,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,CAAC;YAED,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACpE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC5C,OAAO;gBACL,KAAK;gBACL,MAAM,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU;gBAC/E,SAAS,EACP,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,iBAAiB,CAAC,CAAC,CAAC,mBAAmB;aACtF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"skillBasedPrompt.js","sourceRoot":"","sources":["../../../../src/providers/prompt/skillBasedPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAwBH,gEAAgE;AAEhE,MAAM,UAAU,gBAAgB,CAC9B,MAA8B,EAC9B,UAAmC,EAAE;IAErC,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,QAAQ,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAE5D,OAAO;QACL,OAAO,EAAE,CAAC,GAAkB,EAAE,EAAE;YAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YACnD,MAAM,KAAK,GAAa,EAAE,CAAC;YAE3B,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,CAAC;YAED,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACpE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC5C,OAAO;gBACL,KAAK;gBACL,MAAM,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU;gBAC/E,SAAS,EACP,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,iBAAiB,CAAC,CAAC,CAAC,mBAAmB;aACtF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/skills.barrel.js

@@ -0,0 +1,42 @@
+/**
+ * agentfootprint/skills — typed, versioned agent skills.
+ *
+ * A `Skill` is a named procedure the agent can discover via `list_skills`
+ * and activate via `read_skill(id)`. Each Skill is a typed bundle of
+ * prompt + tools + tool-result rules + metadata, composed over the
+ * existing `AgentInstruction` primitive.
+ *
+ * The pattern Anthropic popularized in the Claude Agent SDK, packaged
+ * at `agentfootprint`'s framework layer with two agentfootprint-native
+ * advantages over the Agent SDK: cross-provider correctness (recency-
+ * first delivery by default) and typed / composable authoring.
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { defineSkill, SkillRegistry } from 'agentfootprint/skills';
+ *
+ * const portTriage = defineSkill<TriageDecision>({
+ *   id: 'port-error-triage',
+ *   version: '1.0.0',
+ *   title: 'Port error triage',
+ *   description: 'Investigate interfaces reporting CRC or input errors.',
+ *   steps: [
+ *     'Fetch interface metrics',
+ *     'Pull last 5m of logs',
+ *     'Report findings to operator',
+ *   ],
+ *   tools: [getMetrics, getLogs],
+ *   activeWhen: (d) => d.currentSkill === 'port-error-triage',
+ * });
+ *
+ * const registry = new SkillRegistry<TriageDecision>({ surfaceMode: 'auto' });
+ * registry.register(portTriage);
+ *
+ * const agent = Agent.create({ provider: anthropic('claude-sonnet-4-5') })
+ *   .skills(registry)
+ *   .build();
+ * ```
+ */
+export { defineSkill, SkillRegistry, renderSkillBody } from './lib/skills';
+//# sourceMappingURL=skills.barrel.js.map

package/dist/esm/skills.barrel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.barrel.js","sourceRoot":"","sources":["../../src/skills.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/tools/ToolRegistry.js

@@ -12,6 +12,19 @@ export class ToolRegistry {
         this.tools.set(tool.id, tool);
         return this;
     }
+    /**
+     * Remove a tool by ID. Silently no-ops when the tool isn't registered
+     * so callers can call safely before a re-registration.
+     *
+     * Intended for builder-layer idempotent replace flows (e.g.
+     * `AgentBuilder.skills(registry)` re-mounting skill tools) — NOT for
+     * runtime tool hot-removal, which would require coordinating with the
+     * LLM's recency window.
+     */
+    unregister(id) {
+        this.tools.delete(id);
+        return this;
+    }
     /** Get a tool by ID. */
     get(id) {
         return this.tools.get(id);

package/dist/esm/tools/ToolRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"ToolRegistry.js","sourceRoot":"","sources":["../../../src/tools/ToolRegistry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEjE,MAAM,OAAO,YAAY;IACN,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE3D,wDAAwD;IACxD,QAAQ,CAAC,IAAoB;QAC3B,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,CAAC,EAAE,sBAAsB,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wBAAwB;IACxB,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,qCAAqC;IACrC,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,mCAAmC;IACnC,GAAG;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,gCAAgC;IAChC,GAAG;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,wEAAwE;IACxE,YAAY,CAAC,OAAkB;QAC7B,MAAM,KAAK,GAAG,OAAO;YACnB,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE;gBACjB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAChC,IAAI,CAAC,IAAI;oBAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC;gBACnE,OAAO,IAAI,CAAC;YACd,CAAC,CAAC;YACJ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAEf,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1B,IAAI,EAAE,IAAI,CAAC,EAAE;YACb,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,kCAAkC;IAClC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,UAAU,CAAC,IAAoB;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;IAEhC,iEAAiE;IACjE,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,eAAe,CAAC,MAAa,CAAC,EAAE,CAAC;IAClE,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"ToolRegistry.js","sourceRoot":"","sources":["../../../src/tools/ToolRegistry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEjE,MAAM,OAAO,YAAY;IACN,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE3D,wDAAwD;IACxD,QAAQ,CAAC,IAAoB;QAC3B,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,CAAC,EAAE,sBAAsB,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAU;QACnB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wBAAwB;IACxB,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,qCAAqC;IACrC,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,mCAAmC;IACnC,GAAG;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,gCAAgC;IAChC,GAAG;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,wEAAwE;IACxE,YAAY,CAAC,OAAkB;QAC7B,MAAM,KAAK,GAAG,OAAO;YACnB,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE;gBACjB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAChC,IAAI,CAAC,IAAI;oBAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC;gBACnE,OAAO,IAAI,CAAC;YACd,CAAC,CAAC;YACJ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAEf,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1B,IAAI,EAAE,IAAI,CAAC,EAAE;YACb,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,kCAAkC;IAClC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,UAAU,CAAC,IAAoB;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;IAEhC,iEAAiE;IACjE,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,eAAe,CAAC,MAAa,CAAC,EAAE,CAAC;IAClE,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.js

@@ -13,7 +13,8 @@
  *   agentfootprint/stream        → Real-time lifecycle events
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CostRecorder = exports.TurnRecorder = exports.ToolUsageRecorder = exports.TokenRecorder = exports.quickBind = exports.AgentPattern = exports.defineInstruction = exports.agentLoop = exports.LLMError = exports.urlImage = exports.base64Image = exports.imageBlock = exports.textBlock = exports.toolResultMessage = exports.assistantMessage = exports.userMessage = exports.systemMessage = exports.BrowserOpenAIAdapter = exports.BrowserAnthropicAdapter = exports.BedrockAdapter = exports.OpenAIAdapter = exports.AnthropicAdapter = exports.bedrock = exports.ollama = exports.openai = exports.anthropic = exports.createProvider = exports.MockRetriever = exports.mockRetriever = exports.MockAdapter = exports.mock = exports.ToolRegistry = exports.askHuman = exports.defineTool = exports.exportTrace = exports.ConditionalRunner = exports.Conditional = exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
+exports.TurnRecorder = exports.ToolUsageRecorder = exports.TokenRecorder = exports.SkillRegistry = exports.defineSkill = exports.quickBind = exports.AgentPattern = exports.defineInstruction = exports.agentLoop = exports.LLMError = exports.urlImage = exports.base64Image = exports.imageBlock = exports.textBlock = exports.toolResultMessage = exports.assistantMessage = exports.userMessage = exports.systemMessage = exports.BrowserOpenAIAdapter = exports.BrowserAnthropicAdapter = exports.BedrockAdapter = exports.OpenAIAdapter = exports.AnthropicAdapter = exports.bedrock = exports.ollama = exports.openai = exports.anthropic = exports.createProvider = exports.MockRetriever = exports.mockRetriever = exports.MockAdapter = exports.mock = exports.ToolRegistry = exports.askHuman = exports.defineTool = exports.exportTrace = exports.ConditionalRunner = exports.Conditional = exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
+exports.CostRecorder = void 0;
 // ── Concepts (Builders + Runners) ───────────────────────────
 var concepts_1 = require("./concepts");
 Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return concepts_1.Agent; } });
@@ -78,6 +79,10 @@ var instructions_barrel_1 = require("./instructions.barrel");
 Object.defineProperty(exports, "defineInstruction", { enumerable: true, get: function () { return instructions_barrel_1.defineInstruction; } });
 Object.defineProperty(exports, "AgentPattern", { enumerable: true, get: function () { return instructions_barrel_1.AgentPattern; } });
 Object.defineProperty(exports, "quickBind", { enumerable: true, get: function () { return instructions_barrel_1.quickBind; } });
+// ── Skills (also available from agentfootprint/skills) ──
+var skills_barrel_1 = require("./skills.barrel");
+Object.defineProperty(exports, "defineSkill", { enumerable: true, get: function () { return skills_barrel_1.defineSkill; } });
+Object.defineProperty(exports, "SkillRegistry", { enumerable: true, get: function () { return skills_barrel_1.SkillRegistry; } });
 // ── Recorders (also available from agentfootprint/observe) ──
 var observe_barrel_1 = require("./observe.barrel");
 Object.defineProperty(exports, "TokenRecorder", { enumerable: true, get: function () { return observe_barrel_1.TokenRecorder; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,+DAA+D;AAC/D,uCAeoB;AAdlB,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,+FAAA,GAAG,OAAA;AACH,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,2GAAA,eAAe,OAAA;AACf,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AACd,uGAAA,WAAW,OAAA;AACX,6GAAA,iBAAiB,OAAA;AASnB,sEAAsE;AACtE,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AAGpB,+DAA+D;AAC/D,iCAA6D;AAApD,mGAAA,UAAU,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,qGAAA,YAAY,OAAA;AAE3C,iEAAiE;AACjE,uCAA6F;AAApF,gGAAA,IAAI,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxE,mCAA8D;AAArD,mGAAA,SAAS,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,iGAAA,OAAO,OAAA;AAC3C,uCAA6E;AAApE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxD,uCAA2E;AAAlE,mHAAA,uBAAuB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AActD,+DAA+D;AAC/D,iCASiB;AARf,sGAAA,aAAa,OAAA;AACb,oGAAA,WAAW,OAAA;AACX,yGAAA,gBAAgB,OAAA;AAChB,0GAAA,iBAAiB,OAAA;AACjB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,oGAAA,WAAW,OAAA;AACX,iGAAA,QAAQ,OAAA;AAGV,+DAA+D;AAC/D,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AA0BjB,8DAA8D;AAC9D,uCAAuC;AAA9B,qGAAA,SAAS,OAAA;AAGlB,uEAAuE;AACvE,6DAAmF;AAA1E,wHAAA,iBAAiB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAAE,gHAAA,SAAS,OAAA;AAGnD,+DAA+D;AAC/D,mDAAgG;AAAvF,+GAAA,aAAa,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AAAE,8GAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;AAEH,+DAA+D;AAC/D,uCAeoB;AAdlB,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,+FAAA,GAAG,OAAA;AACH,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,2GAAA,eAAe,OAAA;AACf,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AACd,uGAAA,WAAW,OAAA;AACX,6GAAA,iBAAiB,OAAA;AASnB,sEAAsE;AACtE,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AAGpB,+DAA+D;AAC/D,iCAA6D;AAApD,mGAAA,UAAU,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,qGAAA,YAAY,OAAA;AAE3C,iEAAiE;AACjE,uCAA6F;AAApF,gGAAA,IAAI,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxE,mCAA8D;AAArD,mGAAA,SAAS,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,iGAAA,OAAO,OAAA;AAC3C,uCAA6E;AAApE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxD,uCAA2E;AAAlE,mHAAA,uBAAuB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AActD,+DAA+D;AAC/D,iCASiB;AARf,sGAAA,aAAa,OAAA;AACb,oGAAA,WAAW,OAAA;AACX,yGAAA,gBAAgB,OAAA;AAChB,0GAAA,iBAAiB,OAAA;AACjB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,oGAAA,WAAW,OAAA;AACX,iGAAA,QAAQ,OAAA;AAGV,+DAA+D;AAC/D,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AA0BjB,8DAA8D;AAC9D,uCAAuC;AAA9B,qGAAA,SAAS,OAAA;AAGlB,uEAAuE;AACvE,6DAAmF;AAA1E,wHAAA,iBAAiB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAAE,gHAAA,SAAS,OAAA;AAGnD,2DAA2D;AAC3D,iDAA6D;AAApD,4GAAA,WAAW,OAAA;AAAE,8GAAA,aAAa,OAAA;AAGnC,+DAA+D;AAC/D,mDAAgG;AAAvF,+GAAA,aAAa,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AAAE,8GAAA,YAAY,OAAA"}