@owlmeans/agent-skills 0.1.14 → 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/instructions/agent-memory.instructions.md

@@ -137,3 +137,7 @@ Fact-shaped ("what is true") stays here. Procedure-shaped ("to do X, do Y") beco
 instruction/skill — follow `.github/instructions/memory-promotion.instructions.md` where present,
 otherwise the skill-authoring guidance. Repeated use of a node to *perform* tasks, and over-cap
 nodes full of steps, are promotion triggers.
+
+Promotion is a **rewrite, never a move**: never paste node text into an instruction. "Record the
+rule, not the story" and the size caps above bind instruction bodies at least as tightly as they
+bind nodes (memory-promotion instruction → Distillation).

package/agent-meta/instructions/memory-promotion.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: "Promote procedure-shaped or hot memory into skills/instructions — triggers (procedure test, promote? flags, over-cap), update-vs-create rule, post-promotion pointer state. Apply when converting memory content into guidance files or when a promote? flag appears in a memory node."
+description: "Promote procedure-shaped or hot memory into skills/instructions — triggers (procedure test, promote? flags, over-cap), the mandatory distillation rewrite, update-vs-create rule, post-promotion pointer state. Apply when converting memory content into guidance files or when a promote? flag appears in a memory node."
 applyTo: "**/.agents/memory/**, **/.claude/skills/**, **/.github/instructions/**"
 scope: general
 ---
@@ -11,6 +11,9 @@ Memory holds **facts**; **procedures** belong in instructions/skills, where they
 stop consuming memory-read cycles. Promotion is how the store stays compact and the harness
 teaches itself.
 
+Promotion is a **rewrite, never a move**. Memory text pasted into an instruction is the single
+most common way this harness degrades — see Distillation below.
+
 ## Triggers
 
 - **Procedure shape**: the content answers *how to do X* — ordered steps, imperative verbs,
@@ -27,7 +30,44 @@ teaches itself.
 
 Procedure-shaped answers *how to do X*: ordered steps, imperative verbs, commands, action tables.
 Fact-shaped answers *what is true*: declarative structure, invariants, symptom→cause pairs.
-Mixed entries split — the fact stays in the node, the "then do" moves out.
+Mixed entries split — the fact stays in the node, the "then do" is distilled into a rule in the
+instruction.
+
+## Distillation (mandatory)
+
+**Never paste memory text into an instruction.** A promoted line leaves the node as prose about a
+past occurrence and enters the instruction as **one general rule**: *when this applies → do this
+→ or this breaks*, stated so it holds next time rather than describing last time.
+
+| Strip | Keep |
+|---|---|
+| dates, phase/status markers, "COMPLETE", "landed" | the condition that makes the rule apply |
+| versions, image tags, SHAs — unless the rule turns on the version | the step to take |
+| "was X, now Y", "the former X was removed" | the failure it prevents |
+| who did it, attempt sequences, incident narrative | the recognition fingerprint (symptom) |
+| point-in-time inventories, counts, snapshots | |
+
+Before (memory): "2026-07-05 — the control-board git card was removed; the dialog now owns all
+git actions."
+After (rule): "Git actions live in the git dialog; the control board holds none."
+
+Before (memory): "Phase 3 (COMPLETE, 2026-06-13): added the init-container build, publisher
+`src/build.ts`, kephemeral v0.1.5."
+After (rule): "Production images build in an init container driven by `publisher/src/build.ts`."
+
+**If the rule cannot be stated without saying when it happened, it is not promotable** — it stays
+a memory fact, or it is dropped.
+
+### Budget
+
+A promotion normally adds **1–5 lines** to an existing instruction, and a single rule is ≤ 3 lines.
+A whole new section, or more text added than the node lost, means the content was moved rather than
+distilled — redo it.
+
+An instruction may legitimately run long when it maps a large subsystem, so length alone is not the
+test: **every line must be a rule, a contract, or a pointer.** A section that reads as the story of
+how the code got there is pollution at any length. "Record the rule, not the story"
+(`agent-memory.instructions.md`) binds instruction bodies at least as tightly as it binds nodes.
 
 ## Flagging (how content earns promotion)
 
@@ -45,18 +85,22 @@ even partially; keep both twins in sync. Create a NEW pair only when:
   re-encountered ` → promote?` flag);
 - (c) an external technology required internet docs and has no governing instruction.
 
-New instructions multiply lookup cost — compactness applies to the guidance population too.
+New instructions multiply lookup cost — compactness applies to the guidance population *and* to
+each instruction's body.
 
 ## Procedure
 
 1. Collect the flagged / procedure-shaped memory lines.
-2. Author or extend the `.github/instructions/<name>.instructions.md` and its
+2. **Distill** each into a general rule (section above). Not optional — skipping it is the
+   failure mode this instruction exists to prevent.
+3. Author or extend the `.github/instructions/<name>.instructions.md` and its
    `.claude/skills/<name>/SKILL.md` twin, following the repo's skill-authoring / create-skill
-   conventions.
-3. Shrink the node: delete the promoted prose; leave one pointer line (format below).
-4. Remove the ` → promote?` flags.
-5. Update the node's index hook if its main value moved; bump `updated:`.
-6. Report per the Reporting rule.
+   conventions. Where an existing rule already covers the ground, **rewrite that rule in place**;
+   append only when nothing covers it.
+4. Shrink the node: delete the source lines; leave one pointer line (format below).
+5. Remove the ` → promote?` flags.
+6. Update the node's index hook if its main value moved; bump `updated:`.
+7. Report per the Reporting rule.
 
 ## Post-promotion state
 

package/agent-meta/instructions/memory-recompact.instructions.md

@@ -40,7 +40,8 @@ For each old file or section:
 3. On conflict between records, the version consistent with **current code** wins — check the
    code, don't average.
 4. Procedure-shaped survivors do not enter nodes — route them to
-   `.github/instructions/memory-promotion.instructions.md`.
+   `.github/instructions/memory-promotion.instructions.md`. Routing means distilling them into
+   general rules, never handing the text over verbatim.
 
 ## Legacy-store merge (migration)
 

package/agent-meta/instructions/self-education.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: "Mandatory post-development skill/instruction updating — after adding or changing functionality, update touched project guidance, note external-doc findings in the governing instruction, or add instructions for new subsystems/technologies; required before the completion report when development started from an agreed plan. Apply when editing skills or instruction files after development."
+description: "Mandatory post-development skill/instruction updating — after adding or changing functionality, rewrite touched project guidance as current rules (never as change notes), note external-doc findings in the governing instruction, or add instructions for new subsystems/technologies; required before the completion report when development started from an agreed plan. Apply when editing skills or instruction files after development."
 applyTo: "**/.claude/skills/**, **/.github/instructions/**"
 scope: general
 ---
@@ -28,7 +28,23 @@ For each area the work touched:
 1. Which existing instruction/skill covers it? (Check `.github/instructions/` +
    `.claude/skills/`.)
 2. Do its commands, paths, APIs, and behavior claims still hold after the change?
-3. Fix in place — and keep the instruction and its skill twin in sync.
+3. Fix in place — rewrite the affected lines so they describe current behavior; never append a
+   note about what this change did. Keep the instruction and its skill twin in sync.
+
+## Shape of an update
+
+Instructions and skills state **current rules, not what changed**. Every edit is a rewrite in
+place of the affected lines.
+
+Never write into an instruction or skill: dated bulletins ("2026-07-05 — …"), phase or migration
+status ("Phase 3 complete", "migration done", "landed"), "formerly X, now Y", incident
+narratives, fixed-bug logs, or point-in-time inventories. If a line only makes sense to someone
+who watched the change happen, it does not belong in guidance — the rule it taught does, stated
+timelessly. Facts too specific to generalize go to `.agents/memory/`
+(`.github/instructions/agent-memory.instructions.md`); the rewrite recipe is
+`.github/instructions/memory-promotion.instructions.md` → Distillation.
+
+Test: a finished instruction reads as though the feature was always this way.
 
 ## Non-project instructions
 

package/agent-meta/instructions/skill-authoring.instructions.md

@@ -55,8 +55,12 @@ Cross-reference related guidance by name.
   specific to this project's history. See the agent-memory instruction; promotion triggers live
   in the memory-promotion instruction.
 
+Never paste memory text into guidance. Memory content enters an instruction or skill only as a
+restated general rule — trigger, step, and the failure it prevents, with dates, phase/status
+markers, versions and incident narrative stripped (memory-promotion instruction → Distillation).
+
 ## After adding a skill
 
-If it absorbed memory content, shrink the source `.agents/memory/` node to a pointer line
+If it distilled memory content into rules, shrink the source `.agents/memory/` node to a pointer line
 (memory-promotion instruction) — the memory index does not list skills. Reference it from
 `.github/copilot-instructions.md` / `CLAUDE.md` if it should be discoverable every session.

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/agent-skills",
-  "version": "0.1.14",
-  "generatedAt": "2026-08-05T16:56:53.376Z",
+  "version": "0.1.16-rc.0",
+  "generatedAt": "2026-08-11T14:02:34.977Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/agent-memory/SKILL.md

@@ -136,3 +136,7 @@ each repo — fan every fix out to all copies; verify with `diff`. Correct re-ru
 Fact-shaped ("what is true") stays here. Procedure-shaped ("to do X, do Y") becomes a skill —
 follow `memory-promotion` where present, otherwise `skill-authoring`. Repeated use of a node to
 *perform* tasks, and over-cap nodes full of steps, are promotion triggers.
+
+Promotion is a **rewrite, never a move**: never paste node text into a skill. "Record the rule,
+not the story" and the size caps above bind skill bodies at least as tightly as they bind nodes
+(`memory-promotion` → Distillation).

package/agent-meta/skills/memory-promotion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-promotion
-description: Transform procedure-shaped or repeatedly-used memory into skills and instructions — the procedure-shape test, promote? repeated-touch flags, over-cap trigger, update-vs-create decision, and the post-promotion pointer state. Use when memory content reads as "how to", when a promote? flag is encountered again, or during recompaction.
+description: Transform procedure-shaped or repeatedly-used memory into skills and instructions — the procedure-shape test, the mandatory distillation rewrite, promote? repeated-touch flags, over-cap trigger, update-vs-create decision, and the post-promotion pointer state. Use when memory content reads as "how to", when a promote? flag is encountered again, when writing memory-derived content into a skill, or during recompaction.
 user-invocable: true
 scope: general
 ---
@@ -12,6 +12,9 @@ Memory holds **facts**; **procedures** belong in skills/instructions, where they
 stop consuming memory-read cycles. Promotion is how the store stays compact and the harness
 teaches itself.
 
+Promotion is a **rewrite, never a move**. Memory text pasted into a skill is the single most
+common way this harness degrades — see Distillation below.
+
 ## Triggers
 
 - **Procedure shape**: the content answers *how to do X* — ordered steps, imperative verbs,
@@ -28,7 +31,44 @@ teaches itself.
 
 Procedure-shaped answers *how to do X*: ordered steps, imperative verbs, commands, action tables.
 Fact-shaped answers *what is true*: declarative structure, invariants, symptom→cause pairs.
-Mixed entries split — the fact stays in the node, the "then do" moves out.
+Mixed entries split — the fact stays in the node, the "then do" is distilled into a rule in the
+skill.
+
+## Distillation (mandatory)
+
+**Never paste memory text into a skill.** A promoted line leaves the node as prose about a past
+occurrence and enters the skill as **one general rule**: *when this applies → do this → or this
+breaks*, stated so it holds next time rather than describing last time.
+
+| Strip | Keep |
+|---|---|
+| dates, phase/status markers, "COMPLETE", "landed" | the condition that makes the rule apply |
+| versions, image tags, SHAs — unless the rule turns on the version | the step to take |
+| "was X, now Y", "the former X was removed" | the failure it prevents |
+| who did it, attempt sequences, incident narrative | the recognition fingerprint (symptom) |
+| point-in-time inventories, counts, snapshots | |
+
+Before (memory): "2026-07-05 — the control-board git card was removed; the dialog now owns all
+git actions."
+After (rule): "Git actions live in the git dialog; the control board holds none."
+
+Before (memory): "Phase 3 (COMPLETE, 2026-06-13): added the init-container build, publisher
+`src/build.ts`, kephemeral v0.1.5."
+After (rule): "Production images build in an init container driven by `publisher/src/build.ts`."
+
+**If the rule cannot be stated without saying when it happened, it is not promotable** — it stays
+a memory fact, or it is dropped.
+
+### Budget
+
+A promotion normally adds **1–5 lines** to an existing skill, and a single rule is ≤ 3 lines. A
+whole new section, or more text added than the node lost, means the content was moved rather than
+distilled — redo it.
+
+A skill may legitimately run long when it maps a large subsystem, so length alone is not the test:
+**every line must be a rule, a contract, or a pointer.** A section that reads as the story of how
+the code got there is pollution at any length. "Record the rule, not the story" (`agent-memory`)
+binds skill bodies at least as tightly as it binds nodes.
 
 ## Flagging (how content earns promotion)
 
@@ -46,17 +86,21 @@ even partially; keep both twins in sync. Create a NEW pair only when:
   re-encountered ` → promote?` flag);
 - (c) an external technology required internet docs and has no governing skill.
 
-New skills multiply lookup cost — compactness applies to the skill population too.
+New skills multiply lookup cost — compactness applies to the skill population *and* to each
+skill's body.
 
 ## Procedure
 
 1. Collect the flagged / procedure-shaped memory lines.
-2. Author or extend the SKILL.md and its `.github/instructions/<name>.instructions.md` twin,
-   following the repo's `skill-authoring` or `create-skill` conventions.
-3. Shrink the node: delete the promoted prose; leave one pointer line (format below).
-4. Remove the ` → promote?` flags.
-5. Update the node's index hook if its main value moved; bump `updated:`.
-6. Report per the Reporting rule.
+2. **Distill** each into a general rule (section above). Not optional — skipping it is the
+   failure mode this skill exists to prevent.
+3. Author or extend the SKILL.md and its `.github/instructions/<name>.instructions.md` twin,
+   following the repo's `skill-authoring` or `create-skill` conventions. Where an existing rule
+   already covers the ground, **rewrite that rule in place**; append only when nothing covers it.
+4. Shrink the node: delete the source lines; leave one pointer line (format below).
+5. Remove the ` → promote?` flags.
+6. Update the node's index hook if its main value moved; bump `updated:`.
+7. Report per the Reporting rule.
 
 ## Post-promotion state
 

package/agent-meta/skills/memory-recompact/SKILL.md

@@ -39,7 +39,8 @@ For each old file or section:
    genuinely in-flight state → `Status`, dated).
 3. On conflict between records, the version consistent with **current code** wins — check the
    code, don't average.
-4. Procedure-shaped survivors do not enter nodes — route them to `memory-promotion`.
+4. Procedure-shaped survivors do not enter nodes — route them to `memory-promotion`. Routing
+   means distilling them into general rules, never handing the text over verbatim.
 
 ## Legacy-store merge (migration)
 

package/agent-meta/skills/self-education/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: self-education
-description: Mandatory post-development guidance updating — after functionality is added or changed, update the project skills/instructions the work touched, record external-doc findings (URL + gist) in the governing skill, or add skills/instructions for new subsystems and technologies. Required before the completion report whenever development started from a plan agreed with the agent.
+description: Mandatory post-development guidance updating — after functionality is added or changed, rewrite the project skills/instructions the work touched as current rules (never as change notes), record external-doc findings (URL + gist) in the governing skill, or add skills/instructions for new subsystems and technologies. Required before the completion report whenever development started from a plan agreed with the agent.
 user-invocable: true
 scope: general
 ---
@@ -29,7 +29,22 @@ For each area the work touched:
 1. Which existing skill/instruction covers it? (Check `.claude/skills/` +
    `.github/instructions/`.)
 2. Do its commands, paths, APIs, and behavior claims still hold after the change?
-3. Fix in place — and keep the skill and its instruction twin in sync.
+3. Fix in place — rewrite the affected lines so they describe current behavior; never append a
+   note about what this change did. Keep the skill and its instruction twin in sync.
+
+## Shape of an update
+
+Skills and instructions state **current rules, not what changed**. Every edit is a rewrite in
+place of the affected lines.
+
+Never write into a skill or instruction: dated bulletins ("2026-07-05 — …"), phase or migration
+status ("Phase 3 complete", "migration done", "landed"), "formerly X, now Y", incident
+narratives, fixed-bug logs, or point-in-time inventories. If a line only makes sense to someone
+who watched the change happen, it does not belong in guidance — the rule it taught does, stated
+timelessly. Facts too specific to generalize go to `.agents/memory/` (`agent-memory`); the
+rewrite recipe is `memory-promotion` → Distillation.
+
+Test: a finished skill reads as though the feature was always this way.
 
 ## Non-project skills
 

package/agent-meta/skills/skill-authoring/SKILL.md

@@ -71,10 +71,14 @@ skill").
 If you find yourself writing "last time we…", that is memory. If you are writing "to do X, do Y",
 that is a skill.
 
+Never paste memory text into a skill. Memory content enters guidance only as a restated general
+rule — trigger, step, and the failure it prevents, with dates, phase/status markers, versions and
+incident narrative stripped (`memory-promotion` → Distillation).
+
 ## After adding a skill
 
 1. If it replaces an ad-hoc `.claude/<topic>.md`, remove that file.
-2. If it absorbed memory content, shrink the source `.agents/memory/` node to a pointer line
-   (`memory-promotion`) — the memory index does not list skills.
+2. If it distilled memory content into rules, shrink the source `.agents/memory/` node to a
+   pointer line (`memory-promotion`) — the memory index does not list skills.
 3. Reference it from `CLAUDE.md` / `.github/copilot-instructions.md` if it should be discoverable
    every session.

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