@owlmeans/agent-skills 0.1.15 → 0.1.16-rc.0

package/README.md

@@ -90,3 +90,27 @@ The embedded files are version-matched to this package release. Do not edit them
 directly — they are regenerated on each publish. To contribute guidance edits,
 open a PR against the source monorepo.
 <!-- owlmeans:agent-guidance:end -->
+
+## Package skills in a prompt (`@owlmeans/agent-skills/llm`)
+
+`owlmeansPackagesPlugin(options)` notices which `@owlmeans/*` packages a request mentions
+and loads their published skills into the `Packages` block. Everything a package documents
+is loaded — there is no relevance filtering, by design.
+
+Resolution order per package: the host's `LlmFileProvider` (the only path that sees a
+sandbox or remote workspace) → an installed copy under `node_modules` → the canonical
+repository over HTTPS. Every failure is a miss, never a throw. Results, including misses,
+are cached per plugin instance.
+
+```typescript
+ctx.prompts().use(owlmeansPackagesPlugin({
+  files: () => ctx.files(),      // tried first
+  exclude: ['@owlmeans/llm'],    // already covered by the static Skills block
+  fetch: false,                  // air-gapped: skip the repository fallback
+}))
+```
+
+The manifest deliberately carries no git ref — version-matching comes from shipping the
+copy inside the tarball, so for a package that is NOT installed the ref is a plugin option
+(`ref`, default `main`).
+

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/agent-skills",
-  "version": "0.1.15",
-  "generatedAt": "2026-08-07T17:06:32.899Z",
+  "version": "0.1.16-rc.0",
+  "generatedAt": "2026-08-11T14:02:34.977Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/build/llm/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The LLM-facing half of this package: a prompt plugin that turns a mention of an
+ * `@owlmeans/*` package in a prompt into that package's published skills.
+ *
+ * Deliberately NOT re-exported from the package index. The installer CLI has no runtime
+ * dependencies and must keep it that way; this entry point resolves `@owlmeans/llm` and
+ * `@owlmeans/llm-common`, which only a consumer already using the LLM layer will have.
+ */
+export * from './types.js';
+export * from './manifest.js';
+export * from './resolve.js';
+export * from './plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/build/llm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA"}

package/build/llm/index.js

@@ -0,0 +1,13 @@
+/**
+ * The LLM-facing half of this package: a prompt plugin that turns a mention of an
+ * `@owlmeans/*` package in a prompt into that package's published skills.
+ *
+ * Deliberately NOT re-exported from the package index. The installer CLI has no runtime
+ * dependencies and must keep it that way; this entry point resolves `@owlmeans/llm` and
+ * `@owlmeans/llm-common`, which only a consumer already using the LLM layer will have.
+ */
+export * from './types.js';
+export * from './manifest.js';
+export * from './resolve.js';
+export * from './plugin.js';
+//# sourceMappingURL=index.js.map

package/build/llm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA"}

package/build/llm/manifest.d.ts

@@ -0,0 +1,29 @@
+import type { SkillDefinition } from '@owlmeans/llm-common';
+import type { Manifest, ManifestEntry } from '../discover.js';
+/** `@owlmeans/foo` → `foo`; the repo lays packages out under their unscoped name. */
+export declare const unscoped: (packageName: string) => string;
+export declare const parseManifest: (raw: string) => Manifest | null;
+/**
+ * Strip the YAML frontmatter and the generated-file banner from an embedded SKILL.md.
+ *
+ * Both are installer bookkeeping — `name`, `description`, `applyTo`, "do not edit". Sent
+ * to a model they are pure noise in the most expensive part of the prompt, and the
+ * "do not edit" line actively misleads it about what it is being shown.
+ */
+export declare const stripMeta: (content: string) => string;
+/**
+ * Skill entries worth loading, in a deterministic order.
+ *
+ * Instruction entries are dropped: they are the Copilot twin of the same knowledge, so
+ * including both would double the token cost of every package for no added information.
+ */
+export declare const skillEntries: (manifest: Manifest, categories: readonly string[]) => ManifestEntry[];
+/**
+ * Turn one embedded skill file into a definition bound to the `Packages` block.
+ *
+ * The alias is namespaced by package so two packages documenting the same concept cannot
+ * collide in the registry, and the order weight is pushed past the default so package
+ * knowledge always renders after whatever the host declared itself.
+ */
+export declare const toSkill: (packageName: string, entry: ManifestEntry, body: string) => SkillDefinition;
+//# sourceMappingURL=manifest.d.ts.map

package/build/llm/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/llm/manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE7D,qFAAqF;AACrF,eAAO,MAAM,QAAQ,GAAI,aAAa,MAAM,KAAG,MACE,CAAA;AAEjD,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,QAAQ,GAAG,IAUtD,CAAA;AAID;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,KAAG,MAW3C,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GACvB,UAAU,QAAQ,EAClB,YAAY,SAAS,MAAM,EAAE,KAC5B,aAAa,EAGmD,CAAA;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAClB,aAAa,MAAM,EACnB,OAAO,aAAa,EACpB,MAAM,MAAM,KACX,eAMD,CAAA"}

package/build/llm/manifest.js

@@ -0,0 +1,58 @@
+import { DEFAULT_SKILL_ORDER, PromptBlock } from '@owlmeans/llm-common';
+/** `@owlmeans/foo` → `foo`; the repo lays packages out under their unscoped name. */
+export const unscoped = (packageName) => packageName.slice(packageName.indexOf('/') + 1);
+export const parseManifest = (raw) => {
+    try {
+        const manifest = JSON.parse(raw);
+        if (typeof manifest.schemaVersion !== 'number' || !Array.isArray(manifest.entries)) {
+            return null;
+        }
+        return manifest;
+    }
+    catch {
+        return null;
+    }
+};
+const BANNER = /^<!--\s*AUTO-GENERATED[^>]*-->\s*/;
+/**
+ * Strip the YAML frontmatter and the generated-file banner from an embedded SKILL.md.
+ *
+ * Both are installer bookkeeping — `name`, `description`, `applyTo`, "do not edit". Sent
+ * to a model they are pure noise in the most expensive part of the prompt, and the
+ * "do not edit" line actively misleads it about what it is being shown.
+ */
+export const stripMeta = (content) => {
+    let body = content.replace(/^/, '');
+    if (body.startsWith('---')) {
+        const end = body.indexOf('\n---', 3);
+        if (end >= 0) {
+            const after = body.indexOf('\n', end + 1);
+            body = after >= 0 ? body.slice(after + 1) : '';
+        }
+    }
+    return body.replace(BANNER, '').trim();
+};
+/**
+ * Skill entries worth loading, in a deterministic order.
+ *
+ * Instruction entries are dropped: they are the Copilot twin of the same knowledge, so
+ * including both would double the token cost of every package for no added information.
+ */
+export const skillEntries = (manifest, categories) => manifest.entries
+    .filter(entry => entry.kind === 'skill' && categories.includes(entry.category))
+    .sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+/**
+ * Turn one embedded skill file into a definition bound to the `Packages` block.
+ *
+ * The alias is namespaced by package so two packages documenting the same concept cannot
+ * collide in the registry, and the order weight is pushed past the default so package
+ * knowledge always renders after whatever the host declared itself.
+ */
+export const toSkill = (packageName, entry, body) => ({
+    alias: `${packageName}#${entry.name}`,
+    title: `${packageName} — ${entry.name}`,
+    body,
+    block: PromptBlock.Packages,
+    order: DEFAULT_SKILL_ORDER + 1,
+});
+//# sourceMappingURL=manifest.js.map

package/build/llm/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/llm/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAIvE,qFAAqF;AACrF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,WAAmB,EAAU,EAAE,CACtD,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;AAEjD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAW,EAAmB,EAAE;IAC5D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAa,CAAA;QAC5C,IAAI,OAAO,QAAQ,CAAC,aAAa,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACnF,OAAO,IAAI,CAAA;QACb,CAAC;QACD,OAAO,QAAQ,CAAA;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,MAAM,MAAM,GAAG,mCAAmC,CAAA;AAElD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAe,EAAU,EAAE;IACnD,IAAI,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IACpC,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;QACpC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,CAAA;YACzC,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;QAChD,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;AACxC,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,QAAkB,EAClB,UAA6B,EACZ,EAAE,CACnB,QAAQ,CAAC,OAAO;KACb,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;KAC9E,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAEnE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,WAAmB,EACnB,KAAoB,EACpB,IAAY,EACK,EAAE,CAAC,CAAC;IACrB,KAAK,EAAE,GAAG,WAAW,IAAI,KAAK,CAAC,IAAI,EAAE;IACrC,KAAK,EAAE,GAAG,WAAW,MAAM,KAAK,CAAC,IAAI,EAAE;IACvC,IAAI;IACJ,KAAK,EAAE,WAAW,CAAC,QAAQ;IAC3B,KAAK,EAAE,mBAAmB,GAAG,CAAC;CAC/B,CAAC,CAAA"}

package/build/llm/plugin.d.ts

@@ -0,0 +1,17 @@
+import type { LlmPromptPlugin } from '@owlmeans/llm';
+import type { PackageSkillsOptions } from './types.js';
+export declare const PACKAGE_SKILLS_PLUGIN = "owlmeans-packages";
+/**
+ * A prompt plugin that notices which `@owlmeans/*` packages a request talks about and
+ * loads their published skills into the system prompt.
+ *
+ * Everything the package documents is loaded — there is no relevance filtering, by
+ * design: choosing a subset would need a judgement the model is better placed to make
+ * than a regex, and a partial answer about an API is worse than none.
+ *
+ * The result lands in the `Packages` block, which sits behind its own cache breakpoint.
+ * That is the whole reason the block exists: what a request mentions changes call to
+ * call, and it must not shift a single byte of the role and skills every call shares.
+ */
+export declare const owlmeansPackagesPlugin: (options?: PackageSkillsOptions) => LlmPromptPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/build/llm/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/llm/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,eAAe,CAAA;AAGnE,OAAO,KAAK,EAAiB,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAErE,eAAO,MAAM,qBAAqB,sBAAsB,CAAA;AAuBxD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GAAI,UAAS,oBAAyB,KAAG,eA0F3E,CAAA"}

package/build/llm/plugin.js

@@ -0,0 +1,115 @@
+import { PromptBlock, resolveFileProvider } from '@owlmeans/llm-common';
+import { renderSkill } from '@owlmeans/llm/prompt';
+import { loadPackageSkills } from './resolve.js';
+import { OWLMEANS_SCOPE } from './types.js';
+export const PACKAGE_SKILLS_PLUGIN = 'owlmeans-packages';
+const DEFAULT_MAX_PACKAGES = 5;
+const DEFAULT_CATEGORIES = ['package-specific', 'multi-package'];
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const textOf = (content) => {
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        return content
+            .map(part => {
+            const text = part.text;
+            return typeof text === 'string' ? text : '';
+        })
+            .join('\n');
+    }
+    return '';
+};
+/**
+ * A prompt plugin that notices which `@owlmeans/*` packages a request talks about and
+ * loads their published skills into the system prompt.
+ *
+ * Everything the package documents is loaded — there is no relevance filtering, by
+ * design: choosing a subset would need a judgement the model is better placed to make
+ * than a regex, and a partial answer about an API is worse than none.
+ *
+ * The result lands in the `Packages` block, which sits behind its own cache breakpoint.
+ * That is the whole reason the block exists: what a request mentions changes call to
+ * call, and it must not shift a single byte of the role and skills every call shares.
+ */
+export const owlmeansPackagesPlugin = (options = {}) => {
+    const scopes = options.scopes ?? [OWLMEANS_SCOPE];
+    // No dots and no trailing hyphen, so `@owlmeans/llm.` yields `@owlmeans/llm` — prose
+    // and code both end package names with punctuation.
+    const pattern = new RegExp(`(?:${scopes.map(escape).join('|')})\\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?`, 'g');
+    const exclude = options.exclude ?? [];
+    const maxPackages = options.maxPackages ?? DEFAULT_MAX_PACKAGES;
+    const categories = options.categories ?? [...DEFAULT_CATEGORIES];
+    /**
+     * Resolved packages, negatives included. Without caching the misses, a prompt that
+     * mentions a package which does not publish skills would hit GitHub on every call.
+     */
+    const cache = new Map();
+    /**
+     * Per-provider caches, keyed by the provider INSTANCE.
+     *
+     * A host's file provider is usually per-project (a sandbox, a slot, one checkout), so
+     * two executions can resolve the same package name to different content. Sharing one
+     * cache across them would serve project A's skills to project B. A `WeakMap` keeps the
+     * entries alive exactly as long as the provider is.
+     */
+    const perProvider = new WeakMap();
+    const load = (packageName, ctx) => {
+        // The context's provider is the specific one — it sees the project this call is
+        // actually about. The constructor option is the fallback for a host that wires one
+        // globally. Without this, a per-execution provider was never consulted at all.
+        const provider = resolveFileProvider(ctx.files) ?? resolveFileProvider(options.files);
+        const store = provider != null
+            ? perProvider.get(provider) ?? (() => {
+                const fresh = new Map();
+                perProvider.set(provider, fresh);
+                return fresh;
+            })()
+            : cache;
+        const pending = store.get(packageName);
+        if (pending != null) {
+            return pending;
+        }
+        const promise = loadPackageSkills(packageName, { ...options, files: provider }, categories);
+        store.set(packageName, promise);
+        return promise;
+    };
+    const detect = (ctx) => {
+        const found = new Set();
+        for (const message of ctx.messages) {
+            const text = textOf(message.content);
+            if (text === '') {
+                continue;
+            }
+            for (const match of text.matchAll(pattern)) {
+                found.add(match[0]);
+            }
+        }
+        // Alphabetical, not first-seen: two prompts that mention the same packages in a
+        // different order must still produce the same bytes.
+        return [...found]
+            .filter(name => !exclude.includes(name))
+            .sort()
+            .slice(0, maxPackages);
+    };
+    return {
+        alias: PACKAGE_SKILLS_PLUGIN,
+        order: 50,
+        inspect: async (ctx) => {
+            const names = detect(ctx);
+            if (names.length === 0) {
+                return;
+            }
+            const resolved = await Promise.all(names.map(name => load(name, ctx)));
+            for (const found of resolved) {
+                if (found == null) {
+                    continue;
+                }
+                for (const skill of found.skills) {
+                    ctx.add(PromptBlock.Packages, renderSkill(skill));
+                }
+            }
+        },
+    };
+};
+//# sourceMappingURL=plugin.js.map

package/build/llm/plugin.js.map

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

package/build/llm/resolve.d.ts

@@ -0,0 +1,4 @@
+import type { PackageSkills, PackageSkillsOptions } from './types.js';
+/** Try each source in order of trustworthiness and cost. */
+export declare const loadPackageSkills: (packageName: string, options: PackageSkillsOptions, categories: readonly string[]) => Promise<PackageSkills | null>;
+//# sourceMappingURL=resolve.d.ts.map

package/build/llm/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/llm/resolve.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AA0JrE,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,GAC5B,aAAa,MAAM,EACnB,SAAS,oBAAoB,EAC7B,YAAY,SAAS,MAAM,EAAE,KAC5B,OAAO,CAAC,aAAa,GAAG,IAAI,CAe9B,CAAA"}

package/build/llm/resolve.js

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { resolveFileProvider } from '@owlmeans/llm-common';
+import { parseManifest, skillEntries, stripMeta, toSkill, unscoped } from './manifest.js';
+const AGENT_META = 'agent-meta';
+const MANIFEST = 'manifest.json';
+const DEFAULT_REPO = 'owlmeans/common';
+const DEFAULT_REF = 'main';
+const DEFAULT_TIMEOUT = 5000;
+/** Path of an embedded file relative to a project root, in the host's own terms. */
+const projectPath = (packageName, ...parts) => ['node_modules', packageName, AGENT_META, ...parts].join('/');
+/**
+ * Source 1 — the host's own file access.
+ *
+ * Tried first because it is the only one that sees the project the model is actually
+ * working on: a sandbox, a remote workspace, a container this process cannot reach.
+ */
+const fromFiles = async (packageName, provider, categories) => {
+    const read = async (path) => {
+        try {
+            return await provider.readFile(path, true) ?? '';
+        }
+        catch {
+            return '';
+        }
+    };
+    const manifest = parseManifest(await read(projectPath(packageName, MANIFEST)));
+    if (manifest == null) {
+        return null;
+    }
+    const skills = [];
+    for (const entry of skillEntries(manifest, categories)) {
+        const body = stripMeta(await read(projectPath(packageName, entry.file)));
+        if (body !== '') {
+            skills.push(toSkill(packageName, entry, body));
+        }
+    }
+    return skills.length > 0
+        ? { packageName, version: manifest.version, source: 'files', skills }
+        : null;
+};
+/**
+ * Source 2 — an installed copy on this filesystem.
+ *
+ * Walks upward rather than assuming a layout: a hoisted install puts the package at the
+ * workspace root, a nested one puts it beside the consumer.
+ */
+const findLocalDir = (packageName, from) => {
+    let current = resolvePath(from);
+    for (;;) {
+        const candidate = join(current, 'node_modules', packageName, AGENT_META);
+        if (existsSync(join(candidate, MANIFEST))) {
+            return candidate;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+};
+const fromLocal = (packageName, from, categories) => {
+    const dir = findLocalDir(packageName, from);
+    if (dir == null) {
+        return null;
+    }
+    const read = (path) => {
+        try {
+            return readFileSync(path, 'utf8');
+        }
+        catch {
+            return '';
+        }
+    };
+    const manifest = parseManifest(read(join(dir, MANIFEST)));
+    if (manifest == null) {
+        return null;
+    }
+    const skills = [];
+    for (const entry of skillEntries(manifest, categories)) {
+        const body = stripMeta(read(join(dir, ...entry.file.split('/'))));
+        if (body !== '') {
+            skills.push(toSkill(packageName, entry, body));
+        }
+    }
+    return skills.length > 0
+        ? { packageName, version: manifest.version, source: 'local', skills }
+        : null;
+};
+/**
+ * Source 3 — the canonical repository, for a package that is mentioned but not installed.
+ *
+ * It reads the EMBEDDED copies (`packages/<name>/agent-meta/`) rather than the canonical
+ * root ones: the embedded layout is uniform across packages and is exactly what the
+ * manifest describes, so one shape of URL works for every package.
+ */
+const fromRemote = async (packageName, options, categories) => {
+    if (options.fetch === false || typeof globalThis.fetch !== 'function') {
+        return null;
+    }
+    const repo = options.repo ?? DEFAULT_REPO;
+    const ref = options.ref ?? DEFAULT_REF;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const url = (file) => `https://raw.githubusercontent.com/${repo}/${ref}/packages/${unscoped(packageName)}/${AGENT_META}/${file}`;
+    // Every failure here is a miss, never a throw: a prompt plugin that breaks the call
+    // because GitHub was slow is worse than a prompt without one package's knowledge.
+    const get = async (file) => {
+        try {
+            const response = await fetch(url(file), { signal: AbortSignal.timeout(timeout) });
+            return response.ok ? await response.text() : '';
+        }
+        catch {
+            return '';
+        }
+    };
+    const manifest = parseManifest(await get(MANIFEST));
+    if (manifest == null) {
+        return null;
+    }
+    const entries = skillEntries(manifest, categories);
+    const bodies = await Promise.all(entries.map(async (entry) => stripMeta(await get(entry.file))));
+    const skills = entries
+        .map((entry, i) => ({ entry, body: bodies[i] }))
+        .filter(({ body }) => body !== '')
+        .map(({ entry, body }) => toSkill(packageName, entry, body));
+    return skills.length > 0
+        ? { packageName, version: manifest.version, source: 'remote', skills }
+        : null;
+};
+/** Try each source in order of trustworthiness and cost. */
+export const loadPackageSkills = async (packageName, options, categories) => {
+    const provider = resolveFileProvider(options.files);
+    if (provider != null) {
+        const found = await fromFiles(packageName, provider, categories);
+        if (found != null) {
+            return found;
+        }
+    }
+    const local = fromLocal(packageName, options.dir ?? process.cwd(), categories);
+    if (local != null) {
+        return local;
+    }
+    return fromRemote(packageName, options, categories);
+};
+//# sourceMappingURL=resolve.js.map

package/build/llm/resolve.js.map

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

package/build/llm/types.d.ts

@@ -0,0 +1,59 @@
+import type { FileProviderRef, SkillDefinition } from '@owlmeans/llm-common';
+/** The default scope the plugin looks for in a prompt. */
+export declare const OWLMEANS_SCOPE = "@owlmeans";
+/** Where a package's skills came from — surfaced in logs, useful when a lookup surprises you. */
+export type SkillSource = 'files' | 'local' | 'remote';
+export interface PackageSkills {
+    packageName: string;
+    version: string;
+    source: SkillSource;
+    skills: SkillDefinition[];
+}
+export interface PackageSkillsOptions {
+    /**
+     * Host file access, tried FIRST. It reads the consuming project's own tree, so it is
+     * the only path that works when the project lives somewhere this process cannot reach
+     * directly — a sandbox, a remote workspace, a container.
+     */
+    files?: FileProviderRef;
+    /** Package scopes to detect. Defaults to `['@owlmeans']`. */
+    scopes?: string[];
+    /**
+     * Directory the local `node_modules` lookup starts from, walking upward.
+     * Defaults to `process.cwd()`.
+     */
+    dir?: string;
+    /** GitHub `owner/repo` holding the canonical packages. Defaults to `owlmeans/common`. */
+    repo?: string;
+    /**
+     * Git ref to read the embedded copies from. Defaults to `main`.
+     *
+     * The manifest deliberately carries no ref of its own — version-matching is guaranteed
+     * by shipping the copy inside the tarball, so there is nothing to pin against for a
+     * package that is NOT installed. Set this to a tag when reproducibility matters more
+     * than freshness.
+     */
+    ref?: string;
+    /** Set to `false` to skip the GitHub fallback entirely (air-gapped runs). */
+    fetch?: boolean;
+    /** Milliseconds before a remote lookup is abandoned. Defaults to 5000. */
+    timeout?: number;
+    /**
+     * Packages to ignore — typically the ones whose skills the static `Skills` block
+     * already carries, so they are not paid for twice.
+     */
+    exclude?: string[];
+    /**
+     * Ceiling on how many mentioned packages are loaded into one prompt. Defaults to 5.
+     * A prompt that name-drops a dozen packages is usually not asking about all of them,
+     * and every one of them costs context.
+     */
+    maxPackages?: number;
+    /**
+     * Manifest categories to include. Defaults to package knowledge only — `general`
+     * entries describe how an agent should behave, not what a package does, and belong in
+     * the host's own skill catalogue rather than in a package lookup.
+     */
+    categories?: Array<'package-specific' | 'multi-package' | 'general'>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/llm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE5E,0DAA0D;AAC1D,eAAO,MAAM,cAAc,cAAc,CAAA;AAEzC,iGAAiG;AACjG,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,eAAe,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,KAAK,CAAC,EAAE,eAAe,CAAA;IAEvB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IAEjB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAElB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,kBAAkB,GAAG,eAAe,GAAG,SAAS,CAAC,CAAA;CACrE"}

package/build/llm/types.js

@@ -0,0 +1,3 @@
+/** The default scope the plugin looks for in a prompt. */
+export const OWLMEANS_SCOPE = '@owlmeans';
+//# sourceMappingURL=types.js.map

package/build/llm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAEA,0DAA0D;AAC1D,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/agent-skills",
-  "version": "0.1.15",
+  "version": "0.1.16-rc.0",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,15 +22,37 @@
       "default": "./build/index.js",
       "module": "./build/index.js",
       "types": "./build/index.d.ts"
+    },
+    "./llm": {
+      "import": "./build/llm/index.js",
+      "require": "./build/llm/index.js",
+      "default": "./build/llm/index.js",
+      "module": "./build/llm/index.js",
+      "types": "./build/llm/index.d.ts"
     }
   },
   "devDependencies": {
+    "@langchain/core": "^1.1.39",
     "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/llm": "^0.1.16-rc.0",
+    "@owlmeans/llm-common": "^0.1.16-rc.0",
     "@types/bun": "^1.3.14",
     "@types/node": "^26.1.0",
     "nodemon": "^3.1.14",
     "typescript": "^6.0.3"
   },
+  "peerDependencies": {
+    "@owlmeans/llm": "^0.1.16-rc.0",
+    "@owlmeans/llm-common": "^0.1.16-rc.0"
+  },
+  "peerDependenciesMeta": {
+    "@owlmeans/llm": {
+      "optional": true
+    },
+    "@owlmeans/llm-common": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/llm/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The LLM-facing half of this package: a prompt plugin that turns a mention of an
+ * `@owlmeans/*` package in a prompt into that package's published skills.
+ *
+ * Deliberately NOT re-exported from the package index. The installer CLI has no runtime
+ * dependencies and must keep it that way; this entry point resolves `@owlmeans/llm` and
+ * `@owlmeans/llm-common`, which only a consumer already using the LLM layer will have.
+ */
+
+export * from './types.js'
+export * from './manifest.js'
+export * from './resolve.js'
+export * from './plugin.js'

package/src/llm/manifest.ts

@@ -0,0 +1,74 @@
+import { DEFAULT_SKILL_ORDER, PromptBlock } from '@owlmeans/llm-common'
+import type { SkillDefinition } from '@owlmeans/llm-common'
+import type { Manifest, ManifestEntry } from '../discover.js'
+
+/** `@owlmeans/foo` → `foo`; the repo lays packages out under their unscoped name. */
+export const unscoped = (packageName: string): string =>
+  packageName.slice(packageName.indexOf('/') + 1)
+
+export const parseManifest = (raw: string): Manifest | null => {
+  try {
+    const manifest = JSON.parse(raw) as Manifest
+    if (typeof manifest.schemaVersion !== 'number' || !Array.isArray(manifest.entries)) {
+      return null
+    }
+    return manifest
+  } catch {
+    return null
+  }
+}
+
+const BANNER = /^<!--\s*AUTO-GENERATED[^>]*-->\s*/
+
+/**
+ * Strip the YAML frontmatter and the generated-file banner from an embedded SKILL.md.
+ *
+ * Both are installer bookkeeping — `name`, `description`, `applyTo`, "do not edit". Sent
+ * to a model they are pure noise in the most expensive part of the prompt, and the
+ * "do not edit" line actively misleads it about what it is being shown.
+ */
+export const stripMeta = (content: string): string => {
+  let body = content.replace(/^/, '')
+  if (body.startsWith('---')) {
+    const end = body.indexOf('\n---', 3)
+    if (end >= 0) {
+      const after = body.indexOf('\n', end + 1)
+      body = after >= 0 ? body.slice(after + 1) : ''
+    }
+  }
+
+  return body.replace(BANNER, '').trim()
+}
+
+/**
+ * Skill entries worth loading, in a deterministic order.
+ *
+ * Instruction entries are dropped: they are the Copilot twin of the same knowledge, so
+ * including both would double the token cost of every package for no added information.
+ */
+export const skillEntries = (
+  manifest: Manifest,
+  categories: readonly string[],
+): ManifestEntry[] =>
+  manifest.entries
+    .filter(entry => entry.kind === 'skill' && categories.includes(entry.category))
+    .sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+
+/**
+ * Turn one embedded skill file into a definition bound to the `Packages` block.
+ *
+ * The alias is namespaced by package so two packages documenting the same concept cannot
+ * collide in the registry, and the order weight is pushed past the default so package
+ * knowledge always renders after whatever the host declared itself.
+ */
+export const toSkill = (
+  packageName: string,
+  entry: ManifestEntry,
+  body: string,
+): SkillDefinition => ({
+  alias: `${packageName}#${entry.name}`,
+  title: `${packageName} — ${entry.name}`,
+  body,
+  block: PromptBlock.Packages,
+  order: DEFAULT_SKILL_ORDER + 1,
+})

package/src/llm/plugin.ts

@@ -0,0 +1,133 @@
+import { PromptBlock, resolveFileProvider } from '@owlmeans/llm-common'
+import { renderSkill } from '@owlmeans/llm/prompt'
+import type { LlmPromptPlugin, PromptContext } from '@owlmeans/llm'
+import { loadPackageSkills } from './resolve.js'
+import { OWLMEANS_SCOPE } from './types.js'
+import type { PackageSkills, PackageSkillsOptions } from './types.js'
+
+export const PACKAGE_SKILLS_PLUGIN = 'owlmeans-packages'
+
+const DEFAULT_MAX_PACKAGES = 5
+const DEFAULT_CATEGORIES = ['package-specific', 'multi-package'] as const
+
+const escape = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+const textOf = (content: unknown): string => {
+  if (typeof content === 'string') {
+    return content
+  }
+  if (Array.isArray(content)) {
+    return content
+      .map(part => {
+        const text = (part as { text?: unknown }).text
+        return typeof text === 'string' ? text : ''
+      })
+      .join('\n')
+  }
+
+  return ''
+}
+
+/**
+ * A prompt plugin that notices which `@owlmeans/*` packages a request talks about and
+ * loads their published skills into the system prompt.
+ *
+ * Everything the package documents is loaded — there is no relevance filtering, by
+ * design: choosing a subset would need a judgement the model is better placed to make
+ * than a regex, and a partial answer about an API is worse than none.
+ *
+ * The result lands in the `Packages` block, which sits behind its own cache breakpoint.
+ * That is the whole reason the block exists: what a request mentions changes call to
+ * call, and it must not shift a single byte of the role and skills every call shares.
+ */
+export const owlmeansPackagesPlugin = (options: PackageSkillsOptions = {}): LlmPromptPlugin => {
+  const scopes = options.scopes ?? [OWLMEANS_SCOPE]
+  // No dots and no trailing hyphen, so `@owlmeans/llm.` yields `@owlmeans/llm` — prose
+  // and code both end package names with punctuation.
+  const pattern = new RegExp(
+    `(?:${scopes.map(escape).join('|')})\\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?`, 'g'
+  )
+  const exclude = options.exclude ?? []
+  const maxPackages = options.maxPackages ?? DEFAULT_MAX_PACKAGES
+  const categories = options.categories ?? [...DEFAULT_CATEGORIES]
+
+  /**
+   * Resolved packages, negatives included. Without caching the misses, a prompt that
+   * mentions a package which does not publish skills would hit GitHub on every call.
+   */
+  const cache = new Map<string, Promise<PackageSkills | null>>()
+
+  /**
+   * Per-provider caches, keyed by the provider INSTANCE.
+   *
+   * A host's file provider is usually per-project (a sandbox, a slot, one checkout), so
+   * two executions can resolve the same package name to different content. Sharing one
+   * cache across them would serve project A's skills to project B. A `WeakMap` keeps the
+   * entries alive exactly as long as the provider is.
+   */
+  const perProvider = new WeakMap<object, Map<string, Promise<PackageSkills | null>>>()
+
+  const load = (packageName: string, ctx: PromptContext): Promise<PackageSkills | null> => {
+    // The context's provider is the specific one — it sees the project this call is
+    // actually about. The constructor option is the fallback for a host that wires one
+    // globally. Without this, a per-execution provider was never consulted at all.
+    const provider = resolveFileProvider(ctx.files) ?? resolveFileProvider(options.files)
+    const store = provider != null
+      ? perProvider.get(provider) ?? (() => {
+        const fresh = new Map<string, Promise<PackageSkills | null>>()
+        perProvider.set(provider, fresh)
+        return fresh
+      })()
+      : cache
+
+    const pending = store.get(packageName)
+    if (pending != null) {
+      return pending
+    }
+    const promise = loadPackageSkills(packageName, { ...options, files: provider }, categories)
+    store.set(packageName, promise)
+
+    return promise
+  }
+
+  const detect = (ctx: PromptContext): string[] => {
+    const found = new Set<string>()
+    for (const message of ctx.messages) {
+      const text = textOf((message as { content?: unknown }).content)
+      if (text === '') {
+        continue
+      }
+      for (const match of text.matchAll(pattern)) {
+        found.add(match[0])
+      }
+    }
+
+    // Alphabetical, not first-seen: two prompts that mention the same packages in a
+    // different order must still produce the same bytes.
+    return [...found]
+      .filter(name => !exclude.includes(name))
+      .sort()
+      .slice(0, maxPackages)
+  }
+
+  return {
+    alias: PACKAGE_SKILLS_PLUGIN,
+    order: 50,
+
+    inspect: async ctx => {
+      const names = detect(ctx)
+      if (names.length === 0) {
+        return
+      }
+      const resolved = await Promise.all(names.map(name => load(name, ctx)))
+      for (const found of resolved) {
+        if (found == null) {
+          continue
+        }
+        for (const skill of found.skills) {
+          ctx.add(PromptBlock.Packages, renderSkill(skill))
+        }
+      }
+    },
+  }
+}

package/src/llm/resolve.ts

@@ -0,0 +1,180 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve as resolvePath } from 'node:path'
+import { resolveFileProvider } from '@owlmeans/llm-common'
+import type { LlmFileProvider, SkillDefinition } from '@owlmeans/llm-common'
+import { parseManifest, skillEntries, stripMeta, toSkill, unscoped } from './manifest.js'
+import type { PackageSkills, PackageSkillsOptions } from './types.js'
+
+const AGENT_META = 'agent-meta'
+const MANIFEST = 'manifest.json'
+const DEFAULT_REPO = 'owlmeans/common'
+const DEFAULT_REF = 'main'
+const DEFAULT_TIMEOUT = 5000
+
+/** Path of an embedded file relative to a project root, in the host's own terms. */
+const projectPath = (packageName: string, ...parts: string[]): string =>
+  ['node_modules', packageName, AGENT_META, ...parts].join('/')
+
+/**
+ * Source 1 — the host's own file access.
+ *
+ * Tried first because it is the only one that sees the project the model is actually
+ * working on: a sandbox, a remote workspace, a container this process cannot reach.
+ */
+const fromFiles = async (
+  packageName: string,
+  provider: LlmFileProvider,
+  categories: readonly string[],
+): Promise<PackageSkills | null> => {
+  const read = async (path: string): Promise<string> => {
+    try {
+      return await provider.readFile(path, true) ?? ''
+    } catch {
+      return ''
+    }
+  }
+
+  const manifest = parseManifest(await read(projectPath(packageName, MANIFEST)))
+  if (manifest == null) {
+    return null
+  }
+
+  const skills: SkillDefinition[] = []
+  for (const entry of skillEntries(manifest, categories)) {
+    const body = stripMeta(await read(projectPath(packageName, entry.file)))
+    if (body !== '') {
+      skills.push(toSkill(packageName, entry, body))
+    }
+  }
+
+  return skills.length > 0
+    ? { packageName, version: manifest.version, source: 'files', skills }
+    : null
+}
+
+/**
+ * Source 2 — an installed copy on this filesystem.
+ *
+ * Walks upward rather than assuming a layout: a hoisted install puts the package at the
+ * workspace root, a nested one puts it beside the consumer.
+ */
+const findLocalDir = (packageName: string, from: string): string | null => {
+  let current = resolvePath(from)
+  for (; ;) {
+    const candidate = join(current, 'node_modules', packageName, AGENT_META)
+    if (existsSync(join(candidate, MANIFEST))) {
+      return candidate
+    }
+    const parent = dirname(current)
+    if (parent === current) {
+      return null
+    }
+    current = parent
+  }
+}
+
+const fromLocal = (
+  packageName: string,
+  from: string,
+  categories: readonly string[],
+): PackageSkills | null => {
+  const dir = findLocalDir(packageName, from)
+  if (dir == null) {
+    return null
+  }
+  const read = (path: string): string => {
+    try {
+      return readFileSync(path, 'utf8')
+    } catch {
+      return ''
+    }
+  }
+
+  const manifest = parseManifest(read(join(dir, MANIFEST)))
+  if (manifest == null) {
+    return null
+  }
+
+  const skills: SkillDefinition[] = []
+  for (const entry of skillEntries(manifest, categories)) {
+    const body = stripMeta(read(join(dir, ...entry.file.split('/'))))
+    if (body !== '') {
+      skills.push(toSkill(packageName, entry, body))
+    }
+  }
+
+  return skills.length > 0
+    ? { packageName, version: manifest.version, source: 'local', skills }
+    : null
+}
+
+/**
+ * Source 3 — the canonical repository, for a package that is mentioned but not installed.
+ *
+ * It reads the EMBEDDED copies (`packages/<name>/agent-meta/`) rather than the canonical
+ * root ones: the embedded layout is uniform across packages and is exactly what the
+ * manifest describes, so one shape of URL works for every package.
+ */
+const fromRemote = async (
+  packageName: string,
+  options: PackageSkillsOptions,
+  categories: readonly string[],
+): Promise<PackageSkills | null> => {
+  if (options.fetch === false || typeof globalThis.fetch !== 'function') {
+    return null
+  }
+  const repo = options.repo ?? DEFAULT_REPO
+  const ref = options.ref ?? DEFAULT_REF
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT
+  const url = (file: string): string =>
+    `https://raw.githubusercontent.com/${repo}/${ref}/packages/${unscoped(packageName)}/${AGENT_META}/${file}`
+
+  // Every failure here is a miss, never a throw: a prompt plugin that breaks the call
+  // because GitHub was slow is worse than a prompt without one package's knowledge.
+  const get = async (file: string): Promise<string> => {
+    try {
+      const response = await fetch(url(file), { signal: AbortSignal.timeout(timeout) })
+      return response.ok ? await response.text() : ''
+    } catch {
+      return ''
+    }
+  }
+
+  const manifest = parseManifest(await get(MANIFEST))
+  if (manifest == null) {
+    return null
+  }
+
+  const entries = skillEntries(manifest, categories)
+  const bodies = await Promise.all(entries.map(async entry => stripMeta(await get(entry.file))))
+  const skills = entries
+    .map((entry, i) => ({ entry, body: bodies[i]! }))
+    .filter(({ body }) => body !== '')
+    .map(({ entry, body }) => toSkill(packageName, entry, body))
+
+  return skills.length > 0
+    ? { packageName, version: manifest.version, source: 'remote', skills }
+    : null
+}
+
+/** Try each source in order of trustworthiness and cost. */
+export const loadPackageSkills = async (
+  packageName: string,
+  options: PackageSkillsOptions,
+  categories: readonly string[],
+): Promise<PackageSkills | null> => {
+  const provider = resolveFileProvider(options.files)
+  if (provider != null) {
+    const found = await fromFiles(packageName, provider, categories)
+    if (found != null) {
+      return found
+    }
+  }
+
+  const local = fromLocal(packageName, options.dir ?? process.cwd(), categories)
+  if (local != null) {
+    return local
+  }
+
+  return fromRemote(packageName, options, categories)
+}

package/src/llm/types.ts

@@ -0,0 +1,71 @@
+import type { FileProviderRef, SkillDefinition } from '@owlmeans/llm-common'
+
+/** The default scope the plugin looks for in a prompt. */
+export const OWLMEANS_SCOPE = '@owlmeans'
+
+/** Where a package's skills came from — surfaced in logs, useful when a lookup surprises you. */
+export type SkillSource = 'files' | 'local' | 'remote'
+
+export interface PackageSkills {
+  packageName: string
+  version: string
+  source: SkillSource
+  skills: SkillDefinition[]
+}
+
+export interface PackageSkillsOptions {
+  /**
+   * Host file access, tried FIRST. It reads the consuming project's own tree, so it is
+   * the only path that works when the project lives somewhere this process cannot reach
+   * directly — a sandbox, a remote workspace, a container.
+   */
+  files?: FileProviderRef
+
+  /** Package scopes to detect. Defaults to `['@owlmeans']`. */
+  scopes?: string[]
+
+  /**
+   * Directory the local `node_modules` lookup starts from, walking upward.
+   * Defaults to `process.cwd()`.
+   */
+  dir?: string
+
+  /** GitHub `owner/repo` holding the canonical packages. Defaults to `owlmeans/common`. */
+  repo?: string
+
+  /**
+   * Git ref to read the embedded copies from. Defaults to `main`.
+   *
+   * The manifest deliberately carries no ref of its own — version-matching is guaranteed
+   * by shipping the copy inside the tarball, so there is nothing to pin against for a
+   * package that is NOT installed. Set this to a tag when reproducibility matters more
+   * than freshness.
+   */
+  ref?: string
+
+  /** Set to `false` to skip the GitHub fallback entirely (air-gapped runs). */
+  fetch?: boolean
+
+  /** Milliseconds before a remote lookup is abandoned. Defaults to 5000. */
+  timeout?: number
+
+  /**
+   * Packages to ignore — typically the ones whose skills the static `Skills` block
+   * already carries, so they are not paid for twice.
+   */
+  exclude?: string[]
+
+  /**
+   * Ceiling on how many mentioned packages are loaded into one prompt. Defaults to 5.
+   * A prompt that name-drops a dozen packages is usually not asking about all of them,
+   * and every one of them costs context.
+   */
+  maxPackages?: number
+
+  /**
+   * Manifest categories to include. Defaults to package knowledge only — `general`
+   * entries describe how an agent should behave, not what a package does, and belong in
+   * the host's own skill catalogue rather than in a package lookup.
+   */
+  categories?: Array<'package-specific' | 'multi-package' | 'general'>
+}

package/tests/llm-plugin.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, test } from 'bun:test'
+import { PromptBlock } from '@owlmeans/llm-common'
+import type { LlmFileProvider } from '@owlmeans/llm-common'
+import { anthropicPlugin, makePromptService } from '@owlmeans/llm'
+import type { ModelConfig, PromptService } from '@owlmeans/llm'
+import { owlmeansPackagesPlugin, stripMeta, unscoped } from '@owlmeans/agent-skills/llm'
+
+const model = anthropicPlugin.build({
+  alias: 'spec',
+  secret: 'sk-test',
+  callbacks: [],
+  config: { alias: 'spec', model: 'claude-haiku-4-5-20251001' } as ModelConfig,
+})
+
+let seq = 0
+const compose = (svc: PromptService, text: string) =>
+  svc.compose({}, [{ role: 'user', content: text }], { model, provider: anthropicPlugin })
+
+const withPlugin = (options: Parameters<typeof owlmeansPackagesPlugin>[0] = {}): PromptService =>
+  makePromptService(
+    { plugins: [owlmeansPackagesPlugin({ fetch: false, ...options })] },
+    `spec-pkg-${seq++}`,
+  )
+
+/** A host file provider that serves one package, recording every path it is asked for. */
+const fakeProvider = (asked: string[], body: string): LlmFileProvider => ({
+  getSourceList: async () => [],
+  writeFile: async () => { },
+  deleteFile: async () => { },
+  readFile: async path => {
+    asked.push(path)
+    if (path.endsWith('manifest.json')) {
+      return JSON.stringify({
+        schemaVersion: 1,
+        package: '@owlmeans/auth',
+        version: '9.9.9',
+        generatedAt: '',
+        canonicalRepo: '',
+        entries: [{
+          kind: 'skill',
+          name: 'auth',
+          category: 'package-specific',
+          file: 'skills/auth/SKILL.md',
+          canonicalPath: '.claude/skills/auth/SKILL.md',
+        }],
+      })
+    }
+    return `---\nname: auth\n---\n${body}`
+  },
+})
+
+describe('@owlmeans/agent-skills — embedded metadata', () => {
+  test('frontmatter and the generated banner are stripped from a skill body', () => {
+    const body = stripMeta([
+      '---',
+      'name: auth',
+      'description: something',
+      '---',
+      '<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->',
+      '',
+      '# @owlmeans/auth',
+    ].join('\n'))
+    expect(body).toBe('# @owlmeans/auth')
+  })
+
+  test('content without frontmatter survives untouched', () => {
+    expect(stripMeta('# Plain\n\nbody')).toBe('# Plain\n\nbody')
+  })
+
+  test('the repo lays packages out under their unscoped name', () => {
+    expect(unscoped('@owlmeans/llm-common')).toBe('llm-common')
+  })
+})
+
+describe('@owlmeans/agent-skills — package skills plugin', () => {
+  test('a mentioned package contributes its skills to the packages block', async () => {
+    const result = await compose(withPlugin(), 'How do I use @owlmeans/auth in a handler?')
+    const packages = result.blocks.find(block => block.block === PromptBlock.Packages)
+    expect(packages?.text).toContain('@owlmeans/auth — auth')
+  })
+
+  test('a package nobody mentioned is not loaded', async () => {
+    const result = await compose(withPlugin(), 'How do I write a handler?')
+    expect(result.blocks.find(block => block.block === PromptBlock.Packages)).toBeUndefined()
+  })
+
+  test('an excluded package is skipped even when mentioned', async () => {
+    const result = await compose(
+      withPlugin({ exclude: ['@owlmeans/auth'] }), 'How do I use @owlmeans/auth?'
+    )
+    expect(result.blocks.find(block => block.block === PromptBlock.Packages)).toBeUndefined()
+  })
+
+  // Two prompts that name the same packages in a different order must produce the same
+  // bytes, or they can never share a cache entry.
+  test('mention order does not change the composed bytes', async () => {
+    const first = await compose(withPlugin(), 'compare @owlmeans/auth with @owlmeans/context')
+    const second = await compose(withPlugin(), 'compare @owlmeans/context with @owlmeans/auth')
+    const packages = (result: typeof first) =>
+      result.blocks.find(block => block.block === PromptBlock.Packages)?.text
+    expect(packages(second)).toBe(packages(first))
+  })
+
+  test('trailing punctuation is not part of the package name', async () => {
+    const result = await compose(withPlugin(), 'What about @owlmeans/auth. And @owlmeans/auth,')
+    expect(result.blocks.find(block => block.block === PromptBlock.Packages)?.text)
+      .toContain('@owlmeans/auth — auth')
+  })
+
+  test('a provider wired at construction is preferred over the local filesystem', async () => {
+    const asked: string[] = []
+    const files = fakeProvider(asked, 'HOSTED BODY')
+    const result = await compose(withPlugin({ files: () => files }), 'about @owlmeans/auth')
+    expect(asked[0]).toBe('node_modules/@owlmeans/auth/agent-meta/manifest.json')
+    expect(result.blocks.find(block => block.block === PromptBlock.Packages)?.text)
+      .toContain('HOSTED BODY')
+  })
+
+  // The host's provider is per-execution (a sandbox, a slot, one checkout), so it can only
+  // arrive on the compose context — a plugin built once at context composition cannot know
+  // it. Reading only the constructor option left this path dead.
+  test('a provider supplied on the compose context is used and preferred', async () => {
+    const asked: string[] = []
+    const files = fakeProvider(asked, 'CONTEXT BODY')
+    const svc = withPlugin()
+    const result = await svc.compose(
+      {},
+      [{ role: 'user', content: 'about @owlmeans/auth' }],
+      { model, provider: anthropicPlugin, files: () => files },
+    )
+    expect(asked[0]).toBe('node_modules/@owlmeans/auth/agent-meta/manifest.json')
+    expect(result.blocks.find(block => block.block === PromptBlock.Packages)?.text)
+      .toContain('CONTEXT BODY')
+  })
+
+  test('two providers do not share each other\'s cached packages', async () => {
+    const svc = withPlugin()
+    const one = fakeProvider([], 'FIRST PROJECT')
+    const two = fakeProvider([], 'SECOND PROJECT')
+    const run = (files: LlmFileProvider) => svc.compose(
+      {},
+      [{ role: 'user', content: 'about @owlmeans/auth' }],
+      { model, provider: anthropicPlugin, files: () => files },
+    )
+    const first = await run(one)
+    const second = await run(two)
+    const packages = (r: typeof first) =>
+      r.blocks.find(block => block.block === PromptBlock.Packages)?.text
+    expect(packages(first)).toContain('FIRST PROJECT')
+    expect(packages(second)).toContain('SECOND PROJECT')
+  })
+
+  // A prompt plugin that throws takes the whole model call with it.
+  test('an unreachable package degrades the prompt instead of failing the call', async () => {
+    const result = await compose(withPlugin(), 'about @owlmeans/does-not-exist-anywhere')
+    expect(result.blocks.find(block => block.block === PromptBlock.Packages)).toBeUndefined()
+  })
+})