@owlmeans/agent-skills 0.1.15 → 0.1.16

package/README.md

@@ -1,8 +1,7 @@
 # @owlmeans/agent-skills
 
-CLI installer that lifts embedded Claude Code skills and GitHub Copilot instructions
-out of installed `@owlmeans/*` packages and places them into your project's native
-agent-guidance locations.
+CLI installer that lifts embedded agent skills out of installed `@owlmeans/*` packages
+and places them into your project's skill store.
 
 ## Usage
 
@@ -13,10 +12,14 @@ npx @owlmeans/agent-skills
 ```
 
 The installer scans `node_modules/@owlmeans/*/agent-meta/`, shows you what guidance
-is available, and (with your confirmation) copies it into:
+is available, and (with your confirmation) copies it into
+`.agents/skills/<name>/SKILL.md` — the [Agent Skills](https://agentskills.io) standard
+location, discovered natively by GitHub Copilot, Codex and other agents.
 
-- **Claude Code**: `.claude/skills/<name>/SKILL.md`
-- **GitHub Copilot**: `.github/instructions/<name>.instructions.md`
+Claude Code reads skills only from `.claude/skills/`, so a project that already has a
+`.claude/` directory also gets a per-skill symlink there. Repos generated by
+`@owlmeans/create-app` keep those symlinks fresh with
+`sh .agents/scripts/link-skills.sh`, run automatically at session start.
 
 Re-run after updating `@owlmeans/*` packages to pick up revised guidance.
 
@@ -26,8 +29,6 @@ Re-run after updating `@owlmeans/*` packages to pick up revised guidance.
 --dir <path>        target project directory (default: current working directory)
 --yes, -y           skip interactive confirmation (non-destructive; conflicts still skip)
 --only <pkg,...>    install guidance from these packages only (comma-separated @owlmeans/* names)
---claude-only       install only Claude Code skills (.claude/skills/)
---copilot-only      install only Copilot instructions (.github/instructions/)
 --extras            include extras bundled in the installer itself (default: on)
 --no-extras         skip extras bundled in the installer
 --force             overwrite locally-edited files (no AUTO-GENERATED banner)
@@ -35,6 +36,9 @@ Re-run after updating `@owlmeans/*` packages to pick up revised guidance.
 --help, -h          show this help
 ```
 
+`--claude-only` and `--copilot-only` are accepted but do nothing: one skill store now
+serves every agent.
+
 ## Conflict policy
 
 Files managed by the installer carry an `AUTO-GENERATED` banner. On re-run:
@@ -53,8 +57,8 @@ are installed by default alongside package-specific guidance from `node_modules`
 
 If any `@owlmeans/*` packages are **symlinked** (e.g. via a `libraries/` workspace
 link in an OwlMeans monorepo), the installer refuses and exits with code 4. In that
-setup agents already load guidance from the linked monorepo's root `.claude/skills/`
-and `.github/instructions/` — running the installer would install stale copies.
+setup agents already load guidance from the linked monorepo's root `AGENTS.md` and
+`.agents/skills/` — running the installer would install stale copies.
 
 Pass `--force` only if you understand this and want to proceed anyway.
 
@@ -64,23 +68,23 @@ Each `@owlmeans/*` package ships its embedded guidance under:
 
 ```
 agent-meta/
-  manifest.json          # package, version, entries list
+  manifest.json          # package, version, entries list (schemaVersion 2)
   skills/<name>/
-    SKILL.md             # Claude Code skill
-  instructions/
-    <name>.instructions.md   # GitHub Copilot instruction
+    SKILL.md             # agent skill
 ```
 
+Packages published before schema v2 also carry `instructions/<name>.instructions.md`,
+the GitHub Copilot twin of the same knowledge. Those entries are ignored on install.
+
 Embedded files are **generated and read-only**. To contribute guidance edits, open
 a PR against [owlmeans/common](https://github.com/owlmeans/common).
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
 
-This package ships embedded Claude Code skills and GitHub Copilot instructions under
-`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
-agent-skills installer to place them into your project's native locations
-(`.claude/skills/` and `.github/instructions/`):
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
 
 ```sh
 npx @owlmeans/agent-skills
@@ -90,3 +94,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,
+  "schemaVersion": 2,
   "package": "@owlmeans/agent-skills",
-  "version": "0.1.15",
-  "generatedAt": "2026-08-07T17:06:32.899Z",
+  "version": "0.1.16",
+  "generatedAt": "2026-08-14T10:14:48.850Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -10,168 +10,84 @@
       "name": "self-education",
       "category": "general",
       "file": "skills/self-education/SKILL.md",
-      "canonicalPath": ".claude/skills/self-education/SKILL.md"
+      "canonicalPath": ".agents/skills/self-education/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "router-plugins",
       "category": "general",
       "file": "skills/router-plugins/SKILL.md",
-      "canonicalPath": ".claude/skills/router-plugins/SKILL.md"
+      "canonicalPath": ".agents/skills/router-plugins/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "getting-started",
       "category": "general",
       "file": "skills/getting-started/SKILL.md",
-      "canonicalPath": ".claude/skills/getting-started/SKILL.md"
+      "canonicalPath": ".agents/skills/getting-started/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "shadcn-web",
       "category": "general",
       "file": "skills/shadcn-web/SKILL.md",
-      "canonicalPath": ".claude/skills/shadcn-web/SKILL.md"
+      "canonicalPath": ".agents/skills/shadcn-web/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "memory-recompact",
       "category": "general",
       "file": "skills/memory-recompact/SKILL.md",
-      "canonicalPath": ".claude/skills/memory-recompact/SKILL.md"
+      "canonicalPath": ".agents/skills/memory-recompact/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "git",
       "category": "general",
       "file": "skills/git/SKILL.md",
-      "canonicalPath": ".claude/skills/git/SKILL.md"
+      "canonicalPath": ".agents/skills/git/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "agent-memory",
       "category": "general",
       "file": "skills/agent-memory/SKILL.md",
-      "canonicalPath": ".claude/skills/agent-memory/SKILL.md"
+      "canonicalPath": ".agents/skills/agent-memory/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "reuse-code",
       "category": "general",
       "file": "skills/reuse-code/SKILL.md",
-      "canonicalPath": ".claude/skills/reuse-code/SKILL.md"
+      "canonicalPath": ".agents/skills/reuse-code/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "scaffolding",
       "category": "general",
       "file": "skills/scaffolding/SKILL.md",
-      "canonicalPath": ".claude/skills/scaffolding/SKILL.md"
+      "canonicalPath": ".agents/skills/scaffolding/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "skill-authoring",
       "category": "general",
       "file": "skills/skill-authoring/SKILL.md",
-      "canonicalPath": ".claude/skills/skill-authoring/SKILL.md"
+      "canonicalPath": ".agents/skills/skill-authoring/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "memory-promotion",
       "category": "general",
       "file": "skills/memory-promotion/SKILL.md",
-      "canonicalPath": ".claude/skills/memory-promotion/SKILL.md"
+      "canonicalPath": ".agents/skills/memory-promotion/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "shadcn-versions",
       "category": "general",
       "file": "skills/shadcn-versions/SKILL.md",
-      "canonicalPath": ".claude/skills/shadcn-versions/SKILL.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "reuse-code",
-      "category": "general",
-      "file": "instructions/reuse-code.instructions.md",
-      "canonicalPath": ".github/instructions/reuse-code.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "getting-started",
-      "category": "general",
-      "file": "instructions/getting-started.instructions.md",
-      "canonicalPath": ".github/instructions/getting-started.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "self-education",
-      "category": "general",
-      "file": "instructions/self-education.instructions.md",
-      "canonicalPath": ".github/instructions/self-education.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "memory-recompact",
-      "category": "general",
-      "file": "instructions/memory-recompact.instructions.md",
-      "canonicalPath": ".github/instructions/memory-recompact.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "scaffolding",
-      "category": "general",
-      "file": "instructions/scaffolding.instructions.md",
-      "canonicalPath": ".github/instructions/scaffolding.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "skill-authoring",
-      "category": "general",
-      "file": "instructions/skill-authoring.instructions.md",
-      "canonicalPath": ".github/instructions/skill-authoring.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "router-plugins",
-      "category": "general",
-      "file": "instructions/router-plugins.instructions.md",
-      "canonicalPath": ".github/instructions/router-plugins.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "shadcn-versions",
-      "category": "general",
-      "file": "instructions/shadcn-versions.instructions.md",
-      "canonicalPath": ".github/instructions/shadcn-versions.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "memory-promotion",
-      "category": "general",
-      "file": "instructions/memory-promotion.instructions.md",
-      "canonicalPath": ".github/instructions/memory-promotion.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "agent-memory",
-      "category": "general",
-      "file": "instructions/agent-memory.instructions.md",
-      "canonicalPath": ".github/instructions/agent-memory.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "shadcn-web",
-      "category": "general",
-      "file": "instructions/shadcn-web.instructions.md",
-      "canonicalPath": ".github/instructions/shadcn-web.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "git",
-      "category": "general",
-      "file": "instructions/git.instructions.md",
-      "canonicalPath": ".github/instructions/git.instructions.md"
+      "canonicalPath": ".agents/skills/shadcn-versions/SKILL.md"
     }
   ]
 }

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

@@ -1,15 +1,16 @@
 ---
 name: agent-memory
-description: Shared agent memory protocol — the .agents/memory/ graph store used by both Claude Code and GitHub Copilot: MEMORY.md index, subsystem nodes, compact-on-write merging, size caps, and the read protocol. Use when reading or writing project memory, when asked to remember something, or to decide where knowledge belongs.
+description: Shared agent memory protocol — the .agents/memory/ graph store every agent reads and writes: MEMORY.md index, subsystem nodes, compact-on-write merging, size caps, and the read protocol. Use when reading or writing project memory, when asked to remember something, or to decide where knowledge belongs.
 user-invocable: true
-scope: general
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
 # Agent memory (`.agents/memory/`)
 
-One shared memory store per repository, used by **both** Claude Code and GitHub Copilot: a graph
-of subsystem nodes rooted in the `MEMORY.md` index. Compactness is the core value — every write
+One shared memory store per repository, used by every agent: a graph of subsystem nodes rooted in
+the `MEMORY.md` index. Compactness is the core value — every write
 merges and compacts; nothing is ever appended as a log.
 
 Never write memory to `.claude/memory/`, `.github/memory/`, `~/.claude/`, `~/.copilot/`, or
@@ -30,7 +31,7 @@ Flat directory — graph structure lives in scopes and wiki-links, not subdirect
 
 Node id = lowercase-kebab name of the **project-structure part** the knowledge attaches to:
 
-1. **Subsystem** — workspace dir / package name: `manager-web`, `auth`, `vslots`. Deepest
+1. **Subsystem** — workspace dir / package name: `manager-web`, `auth`, `deploy`. Deepest
    unambiguous segment; prefix with the parent only on collision.
 2. **Cross-cutting concern** spanning subsystems: `build`, `testing`, `deploy`, `routing`, `i18n`.
 3. **Integration** — external service/library: `stripe`, `cloudflare`, `openrouter`.
@@ -66,8 +67,8 @@ Frontmatter — exactly three fields:
 
 ```yaml
 ---
-node: vslots                 # = filename without .md; = wiki-link target
-scope: "scripts/vslots/**"   # repo-relative globs; ext:<service> for integrations; . for workspace
+node: deploy                 # = filename without .md; = wiki-link target
+scope: "deploy/**"           # repo-relative globs; ext:<service> for integrations; . for workspace
 updated: 2026-08             # month granularity only
 ---
 ```

package/agent-meta/skills/getting-started/SKILL.md

@@ -2,7 +2,8 @@
 name: getting-started
 description: How to build a fullstack OwlMeans Common app from scratch — the common/api/web three-workspace pattern, context bootstrap on server and web, shared entrypoints + elevate(), and a session-scoped in-memory resource with @owlmeans/static-resource. Use when starting a new OwlMeans project, wiring web↔api, or asked how the pieces fit together.
 user-invocable: true
-scope: general
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 

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

@@ -2,7 +2,8 @@
 name: git
 description: "Git workflow policy — never run state-changing git without an explicit instruction, commit only under the repository's configured identity (no AI-attribution trailer), report finished git work as a Markdown table, never commit a conflicted working copy. Use before any git operation."
 user-invocable: false
-scope: general
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 

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

@@ -2,7 +2,8 @@
 name: memory-promotion
 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
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
@@ -94,8 +95,8 @@ skill's body.
 1. Collect the flagged / procedure-shaped memory lines.
 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
+3. Author or extend the skill at `.agents/skills/<name>/SKILL.md`, 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.
@@ -107,5 +108,5 @@ skill's body.
 The node keeps exactly one line under `## Pointers`:
 
 ```
-- <activity> → skill `<name>` (procedure lives in .claude/skills/<name>/ + .github/instructions/<name>.instructions.md)
+- <activity> → skill `<name>` (procedure lives in .agents/skills/<name>/)
 ```

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

@@ -2,7 +2,8 @@
 name: memory-recompact
 description: Recompact or migrate a whole .agents/memory/ store — rebuild the node map from project structure, merge event-shaped records into subsystem nodes, deduplicate, enforce caps, regenerate the MEMORY.md index, and fold in legacy .claude/memory and .github/memory stores. Use when a store degrades into event logs, indexes bloat or conflict, or for one-time migration.
 disable-model-invocation: true
-scope: general
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
@@ -48,8 +49,7 @@ For each old file or section:
    ONE node — merge both; the code-consistent version wins.
 2. Index-only entries with no backing file: extract the fact into its node, or drop if stale.
 3. Old `## Skills` / "Key Files" index sections are dropped — skills self-describe; harness
-   layout belongs to `CLAUDE.md` / `.github/copilot-instructions.md`. Move genuinely non-obvious
-   dispatch hints there.
+   layout belongs to `AGENTS.md`. Move genuinely non-obvious dispatch hints there.
 4. When the new store verifies (below), delete both legacy dirs entirely.
 
 ## Regenerate the index

package/agent-meta/skills/reuse-code/SKILL.md

@@ -2,7 +2,8 @@
 name: reuse-code
 description: Discovery-first, reuse-first workflow for OwlMeans projects. Use BEFORE planning or building any feature, before proposing a third-party library or a custom solution, and after writing code. Find an existing @owlmeans/* package or existing code first; extend before writing new; simplify what you write.
 user-invocable: true
-scope: general
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
@@ -18,7 +19,7 @@ Before suggesting any external library or writing custom code, look for an `@owl
 already solves the problem.
 
 - **Consult the deployed skills.** Each installed `@owlmeans/*` package ships a skill at
-  `.claude/skills/<pkg>/SKILL.md` (and `.github/instructions/<pkg>.instructions.md`) describing what it
+  `.agents/skills/<pkg>/SKILL.md` describing what it
   does. Read those first — they are your local catalogue of installed capabilities.
 - **Scan installed packages.** Look in `node_modules/@owlmeans/*` **and**, in a workspace monorepo,
   the nested `sources/*/node_modules/@owlmeans/*` (bun nests workspace deps).
@@ -32,7 +33,7 @@ How you research the repo depends on whether `@owlmeans/*` is linked locally:
 - Run `ls -la node_modules/@owlmeans/<pkg>` (try a package you know is installed). If it is a **symlink
   whose target escapes `node_modules`** — or if the project's *own* workspace publishes `@owlmeans/*`
   packages (i.e. **this is the common repo**) — you have the source locally. **Research locally:** read
-  `tree.md`, browse the framework's package sources, and read the canonical `.claude/skills/`. **Do
+  `tree.md`, browse the framework's package sources, and read the canonical `.agents/skills/`. **Do
   not** use the internet.
 - Otherwise (a clean install from npm), **research the web**: fetch/search
   **https://github.com/owlmeans/common** — `tree.md` and package READMEs — to find the right package.

package/agent-meta/skills/router-plugins/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: router-plugins
 description: How OwlMeans UI routing plugins work — the RouterPlugin contract, cascade selection, choosing/switching the router at context provisioning (default OwlMeans vs opt-in react-router), and authoring a new plugin (e.g. SSR). Read before wiring routing in an app or writing a routing plugin.
-scope: general
 user-invocable: false
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 

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

@@ -2,7 +2,8 @@
 name: scaffolding
 description: How to scaffold a new OwlMeans Common project — the @owlmeans/create-app CLI (npm/bun/yarn create), its flags, what it generates, and the manual alternative. Use when asked to create/bootstrap/start a new OwlMeans app or set up a fresh project.
 user-invocable: true
-scope: general
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
@@ -22,8 +23,8 @@ npx @owlmeans/create-app my-app
 ```
 
 By default it copies the template, runs `git init`, installs dependencies, and **deploys agent
-guidance** into the project via [[bun]]-installed `@owlmeans/agent-skills` (`.claude/skills/` +
-`.github/instructions/`). With `--no-install` the deploy still runs — the installer's own bundled
+guidance** into the project via [[bun]]-installed `@owlmeans/agent-skills` (`.agents/skills/`).
+With `--no-install` the deploy still runs — the installer's own bundled
 extras give the project its general/harness guidance; only the package-specific skills wait for
 `npx @owlmeans/agent-skills` after the install.
 
@@ -52,12 +53,11 @@ primitives + layout/nav/screens). Finish with `npx @owlmeans/agent-skills` to ad
 ```
 my-app/
 ├── package.json            # bun workspaces: sources/*
-├── CLAUDE.md               # git/reporting/memory/self-education rules + project-purpose placeholder
-├── .github/
-│   ├── copilot-instructions.md   # same directives for Copilot
-│   └── instructions/             # seeded harness instructions (+ deployed ones)
-├── .claude/skills/               # seeded harness skills (+ deployed ones)
-├── .agents/memory/MEMORY.md      # starter shared memory graph index (both tools)
+├── AGENTS.md               # git/reporting/memory/self-education rules + project-purpose placeholder
+├── CLAUDE.md               # thin bridge: imports AGENTS.md, documents the skill symlinks
+├── .agents/skills/         # seeded harness skills (+ deployed ones)
+├── .agents/scripts/link-skills.sh  # refreshes the .claude/skills symlinks Claude Code needs
+├── .agents/memory/MEMORY.md      # starter shared memory graph index
 ├── sources/common/         # consts, types, schemas, config, modules (entrypoints)
 ├── sources/api/            # context.ts (appendStaticResource), app/session/*, modules.ts, index.ts
 └── sources/web/            # vite + tailwind v4, components/ui/*, layout, nav, screens, render.tsx
@@ -72,11 +72,13 @@ The session demo stores items in `@owlmeans/static-resource`, namespaced by a cl
 
 ## Generated agent guidance
 
-`CLAUDE.md` and `.github/copilot-instructions.md` carry the same four mandatory sections as a real
-OwlMeans monorepo — **Git Workflow**, **Reporting**, **Memory** (the `.agents/memory/` graph store),
-**Self-Education** — plus the mandatory [[reuse-code]] section and a **project-purpose placeholder**
+`AGENTS.md` carries the same four mandatory sections as a real OwlMeans monorepo — **Git
+Workflow**, **Reporting**, **Memory** (the `.agents/memory/` graph store), **Self-Education** —
+plus the mandatory [[reuse-code]] section and a **project-purpose placeholder**
 (`<!-- OWLMEANS:PROJECT-PURPOSE -->`). On the first agent session that block instructs the agent to
-ask the user what the project is for and replace it in both files.
+ask the user what the project is for and replace it. `CLAUDE.md` is a thin bridge that imports
+`AGENTS.md` and keeps the gitignored `.claude/skills/` symlinks fresh through a `SessionStart`
+hook; Copilot and Codex need nothing beyond `AGENTS.md` and `.agents/skills/`.
 
 The harness guidance is **seeded into the template** as generated, banner-carrying copies, so a
 project has it even before the installer runs: [[agent-memory]], [[memory-promotion]],

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

@@ -1,8 +1,9 @@
 ---
 name: self-education
-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.
+description: Mandatory post-development guidance updating — after functionality is added or changed, rewrite the project skills the work touched as current rules (never as change notes), record external-doc findings (URL + gist) in the governing skill, or add skills 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
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
@@ -20,24 +21,23 @@ a proposed approach. **Approval of a plan is simultaneously approval of its impl
 this self-education pass.** A planned task is not finishable without it. If guidance files cannot
 be edited (read-only run), list the required updates in the report instead.
 
-Also recommended after any unplanned change that made an existing skill/instruction inaccurate.
+Also recommended after any unplanned change that made an existing skill inaccurate.
 
 ## Review checklist
 
 For each area the work touched:
 
-1. Which existing skill/instruction covers it? (Check `.claude/skills/` +
-   `.github/instructions/`.)
+1. Which existing skill covers it? (Check `.agents/skills/`.)
 2. Do its commands, paths, APIs, and behavior claims still hold after the change?
 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.
+   note about what this change did.
 
 ## Shape of an update
 
-Skills and instructions state **current rules, not what changed**. Every edit is a rewrite in
+A skill states **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
+Never write into a 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
@@ -67,8 +67,8 @@ library; if none exists and the technology will recur, create one (update-vs-cre
 
 ## New subsystems / technologies
 
-When new technology or a new subsystem entered the repo: create the skill/instruction pair for
-its procedures, and/or the `.agents/memory/` node for its facts — split along the
+When new technology or a new subsystem entered the repo: create the skill for its procedures,
+and/or the `.agents/memory/` node for its facts — split along the
 memory-vs-skill boundary (`agent-memory` / `memory-promotion`).
 
 ## Completion gate

package/agent-meta/skills/shadcn-versions/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: shadcn-versions
 description: How to update versions of shadcn UI primitives, Tailwind CSS v4, and related UI libs across all shadcn-based OwlMeans web packages. Distinct from the @owlmeans/* package version sync (see [[versions]] skill). Use when bumping tailwind, shadcn components, or utility libs.
-allowed-tools: Bash(grep *), Bash(sed *), Bash(bun install)
-scope: general
+allowed-tools: Bash(grep *) Bash(sed *) Bash(bun install)
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 

package/agent-meta/skills/shadcn-web/SKILL.md

@@ -2,7 +2,8 @@
 name: shadcn-web
 description: How to build and maintain shadcn UI + Tailwind v4 web packages in the OwlMeans framework. Auto-invoked when editing components.json, tailwind.config.*, globals.css, or files under components/ui/. Use when creating a new shadcn-based web package or adding shadcn components.
 user-invocable: false
-scope: general
+metadata:
+  scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->