@rig-c/core 3.0.1 → 3.1.0

package/docs/AUTHORING.md

@@ -139,7 +139,7 @@ commands take it and what its default is.
 | `check --candidate <dir> --frames <dir> [--out <dir>]` | the candidate against reference pictures — the only instrument here that can see a *wrong animation*. `--out` also writes, for every frame the table lists, the picture its figures came from: reference, candidate, difference and overlay at native size <a id="cmd-check"></a> |
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder <a id="cmd-bench"></a> |
 | `guide <RULE>` / `guide §<n>[.<m>[.<k>]] [--all]` | the guide's row for the rule a failure line names — every `FAIL` line, `vote --record` refusal, `ingest` finding and coded compile error ends with ` (see rigc guide <RULE>)`; only legacy uncoded library errors point at `§5.1` — or a section's heading, own prose and subsection index, read from the installed `docs/AUTHORING.md` when it runs. `--all` includes the subsection bodies; a leaf prints its full text either way. Sizes describe full ledger spans. `--all` with a rule is refused, exit 2; an unknown name is refused with the nearest real ones, exit 1 <a id="cmd-guide"></a> |
-| `skills install [--dir …] [--copy]` | links every agent skill the package ships into `.agents/skills` (or `--dir`) as relative symlinks, or copies them with `--copy` — where Codex, Gemini CLI and Antigravity look. A second run has nothing to do; an entry already there that is not this command's is refused by name and nothing is written <a id="cmd-skills-install"></a> |
+| `skills install [--dir …] [--copy]` | links every agent skill this package and any installed `@rig-c/*` or rig-c alias package ship (`PACKAGE_ROOT/skills` and every `node_modules/@rig-c/*/skills/<name>/SKILL.md` and alias reachable from the project's `node_modules`) into `.agents/skills` (or `--dir`) as relative symlinks, or copies them with `--copy` — where Codex, Gemini CLI and Antigravity look — reporting which package each skill came from (`[<package>]`). In a consumer without `@rig-c/core` installed, reach the installer with `bunx @rig-c/core skills install`. A second run has nothing to do; an entry already there that is not this command's, or a duplicate skill name across two distinct packages (an alias or symlink resolving to the same `realpathSync` folder is deduplicated), is refused by name and nothing is written <a id="cmd-skills-install"></a> |
 | `review <dir> […]` | the human review of a build, handed to the `rig-review` bin of `@rig-c/review` installed beside the package; rigc does not depend on it and never installs it. `rigc review <dir> [--reference <video>] [--animation <name>] [--compare <dir>]` is `rig-review open <dir> …` with those flags 1:1 and prints the loopback URL to give a person; a first argument that is one of review's own words (`open`, `check`, `feedback`, `control`, `strip`, `compare`) or starts with `-` (`--help`, `--`) is handed over untouched. stdout is review's byte for byte, stderr review's plus the launcher's own refusals, the exit code review's. Refused by name, exit 2, before the bin starts: `REVIEW_OUTPUT_MISSING <path>` (the target is not a directory); `REVIEW_NOT_INSTALLED` with two lines, `bun add -d @rig-c/review` and `bunx @rig-c/review open <dir> …` carrying the flags given — the same on a terminal and off, with nothing installed or written; `REVIEW_BUN_TOO_OLD: Bun <found>, @rig-c/review needs <required>`, the floor read off the installed package's `engines.bun`; and an empty argument (`""`) under a Bun that drops one (Bun 1.2.0, measured by a probe), `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …`. docs/AUTHORING.md lists every line <a id="cmd-review"></a> |
 
 `diff`, `bonedist`, `check` and `bench` measure against something you were given; the
@@ -405,7 +405,7 @@ What the flags mean:
 | `--min-visible` | `chainfit` only: below this share of a part surviving the parts drawn over it, the placement is refused `occluded` instead of reported flat (default `0.25`) — §12.4 |
 | `--passes` | `chainfit` only: how many times the occluder masks are rebuilt from the answers and the fit rerun (default `2`) — §12.4 |
 | `--anchor-residual` | `chainfit` only: the residual a `pose` placement must be within to anchor a chain (default `0.16`) — §12.2 |
-| `--dir` | `skills install` only: the directory to install the agent skills into, resolved against your working directory (default `.agents/skills`, which Codex, Gemini CLI and Antigravity read). The skills are the `skills/` directory of the package the command runs from, never the working directory's |
+| `--dir` | `skills install` only: the directory to install the agent skills into, resolved against your working directory (default `.agents/skills`, which Codex, Gemini CLI and Antigravity read). The skills are scanned from the `skills/` directory of the package the command runs from and every `@rig-c/*` and rig-c alias package in the project's `node_modules`, never a loose `skills/` in the working directory |
 | `--copy` | `skills install` only: copy each skill folder instead of writing a relative symlink to it. A copy is not reached by an upgrade of the package; one that is no longer the package's bytes is refused on the next run, naming the first file that differs |
 
 `render` also takes `--fps <n>` (the rate it samples at, default 12 — the same
@@ -438,10 +438,28 @@ each under `sets[].dir` — read the folder from there, not from the animation's
 the subsections' bodies. A leaf prints its full text either way — §5 says when to reach for it.
 
 `skills install` is the other command that is not about a rig: it puts the agent
-skills the package ships where an agent host looks for them. Run it through the
+skills this package and every installed `@rig-c/*` or rig-c alias package ship where
+an agent host looks for them, scanning `PACKAGE_ROOT/skills` and every
+`node_modules/@rig-c/*/skills/<name>/SKILL.md` (and any unscoped alias package
+shipping `skills/<name>/SKILL.md` that resolves by `realpathSync` into `@rig-c/*` or
+declares a `github.com/rig-c/` `repository` in `package.json` — never by directory
+name alone) reachable from the project's `node_modules`, and
+reporting `[<package>]` on each line. Run it through the
 project's own install — `bun rigc skills install` — so the links point into that
-project's `node_modules/rig-c/skills/`. A second run has nothing to do and
-exits 0. An entry already at `<dir>/<name>` that is not a link to the same folder
+project's `node_modules/rig-c/skills/` (or `node_modules/@rig-c/core/skills/`) and
+its sibling packages; in a
+consumer without `@rig-c/core` installed (for example, a project with only
+`@rig-c/play` or a host adapter), run `bunx @rig-c/core skills install --copy`
+so every skill is written as a plain folder instead of linking `@rig-c/core`'s
+skills into a temporary `.bunx` cache that can be emptied. A second run has nothing to do and
+exits 0. An alias or symlink that resolves (`realpathSync`) to a skill folder
+already discovered is deduplicated; two copies of the same product (`rig-c` ↔
+`@rig-c/core`, `rig-<name>` ↔ `@rig-c/<name>`, or a project copy beside the running
+package) choose the copy inside the project's `node_modules` first and the scoped
+package (`@rig-c/*`) over the unscoped alias (`rig-*`), printing which copy was
+chosen; two different products shipping the same skill
+name refuse the call, exit 1, naming both sources (`<n> duplicate skill name(s)
+across packages, and nothing was written:`). An entry already at `<dir>/<name>` that is not a link to the same folder
 (or, under `--copy`, not the same bytes) is refused, exit 1, and **nothing is
 written** — every such entry is named with what is there and what was required:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/skills/rigc/SKILL.md

@@ -46,14 +46,20 @@ index within that same limit; only legacy uncoded library errors point at `§5.1
 ## Install
 
 ```shell
-bunx @rig-c/core --help       # run it without installing
-bun add -d @rig-c/core        # or pin it in the project; the command is `rigc`
-bun rigc skills install      # then link these skills into .agents/skills
+bunx @rig-c/core --help                  # run it without installing
+bun add -d @rig-c/core                   # or pin it in the project; the command is `rigc`
+bun rigc skills install                  # link this package's and every installed @rig-c/* package's skills into .agents/skills
+bunx @rig-c/core skills install --copy   # in a consumer without @rig-c/core installed (for example, only @rig-c/play)
 ```
 
 Codex, Gemini CLI and Antigravity read skills from `.agents/skills/` in the
-workspace and none of them reads `node_modules`; `rigc skills install` puts every
-skill the package ships there, and `rigc skills --help` says what it refuses.
+workspace and none of them reads `node_modules`; `rigc skills install` scans this
+package's `skills/` and every `node_modules/@rig-c/*/skills/<name>/SKILL.md` (and
+rig-c alias package) in the project, and `rigc skills --help` says what it refuses.
+In a consumer without `@rig-c/core` installed, run `bunx @rig-c/core skills install --copy`:
+it reaches the project's `node_modules` from the working directory and writes plain
+folders instead of linking `@rig-c/core`'s own skills into a temporary `.bunx` cache
+that can be emptied.
 
 The package links no Spine runtime. `build` writes `skeleton.json`,
 `skeleton.atlas` and `skeleton.model.json`. `preview`, `vote`, `bench` and `bonedist`
@@ -158,6 +164,18 @@ spec files field by field, the emission rules, the loop, and the failure map. Th
 | a **skeleton.json somebody else authored** — read it, repair it, extend it | [INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) | `rigc-ingest` |
 | you are the **person operating** the agent rather than the agent | [PROMPTING.md](https://github.com/rig-c/core/blob/main/docs/PROMPTING.md) | — |
 
+Other `@rig-c/*` packages ship their own agent skills (`node_modules/@rig-c/<pkg>/skills/<skill>/SKILL.md`), which `rigc skills install` links beside these; load that skill for its tool's flags and rules:
+
+| The request is… | Tool | Skill |
+| --- | --- | --- |
+| Turn one anime character painting and its See-through layer decomposition into a verified 2D character rig — measured parts, weighted meshes, bone chains and a looping idle | `@rig-c/parts` (`rig-parts`) | `rig-parts` |
+| Clean and retarget a body-18 (or COCO-17) pose sequence onto a rig built by `rigc` or `@rig-c/parts` — bone rotate keys, hip translate keys, leg foreshortening, alternate-drawing switches and skirt-physics fitting | `@rig-c/pose` (`rig-pose`) | `rig-pose` |
+| Hand a rig build or `rig-parts`/`rig-pose` output to a person for local inspection in a browser workspace (`rig-review open`) and retrieve their structured feedback (`rig-review feedback`), validate the delivery package (`rig-review check`), or export frame strips (`rig-review strip`) | `@rig-c/review` (`rig-review`) | `rig-review` |
+| Play a rig built by `rigc` (`skeleton.model.json`) on a web page as plain DOM or a standalone `<canvas>`, with multi-track playback, attachment sets, wind and gravity physics, bone adjustments and live-frame borrowing | `@rig-c/play` (`rig-play`) | `rig-play` |
+| Play a rig built by `rigc` (`skeleton.model.json`) inside a PixiJS 8 scene graph (`PixiRig` and `PixiRenderer`), posed through `@rig-c/play` with no Spine runtime | `@rig-c/pixi` | `rig-pixi` |
+| Play a rig built by `rigc` (`skeleton.model.json`) inside a Phaser 4.2+ WebGL scene (`PhaserRig` and `PhaserRenderer`), posed through `@rig-c/play` with shared GPU page textures and no Spine runtime | `@rig-c/phaser` | `rig-phaser` |
+| Play a rig built by `rigc` (`skeleton.model.json`) inside a native Three.js WebGL2 scene (`ThreeRig` and `ThreeRenderer`), posed through `@rig-c/play` under an orthographic or perspective camera with no Spine runtime | `@rig-c/three` | `rig-three` |
+
 Every guide linked here is in the installed package at `node_modules/@rig-c/core/docs/`,
 which is the copy that matches the rigc you run; the links go to the repository's
 `main`. Inside the Claude Code plugin the same files are at `${CLAUDE_PLUGIN_ROOT}/docs/`.

package/src/cli/core_commands.ts

@@ -2211,19 +2211,163 @@ interface SkillsInstallEntry {
   target: string;
   /** `<package>/skills/<name>`. */
   source: string;
+  /** Which package the skill came from (`package.json` `name`, or its `node_modules` directory name). */
+  packageName: string;
   action: SkillsInstallAction;
   /** The link text, relative to the directory it sits in, when the entry is a link. */
   link: string;
+  /** Other copies of the same product that this copy was chosen over, when more than one copy was present. */
+  chosenOver?: Array<{ packageName: string; source: string }>;
+}
+
+export interface DiscoveredSkillSource {
+  packageName: string;
+  skillsDir: string;
+  /** Whether this source lives inside a `node_modules` tree reached walking up from `process.cwd()`. */
+  inProjectNodeModules?: boolean;
+}
+
+/**
+ * Canonical product identity for a package name (issue #1672):
+ * `rig-c`, `spine-rigc` and `@rig-c/core` are the same product (`@rig-c/core`), and each unscoped convenience
+ * alias `rig-<name>` is the same product as `@rig-c/<name>`.
+ */
+function canonicalProduct(packageName: string): string {
+  if (packageName === 'rig-c' || packageName === 'spine-rigc' || packageName === '@rig-c/core') {
+    return '@rig-c/core';
+  }
+  if (packageName.startsWith('rig-')) {
+    return `@rig-c/${packageName.slice('rig-'.length)}`;
+  }
+  return packageName;
+}
+
+function isDirectoryThere(path: string): boolean {
+  try {
+    return existsSync(path) && statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
 }
 
 /** Every `<name>/` under `source` that holds a `SKILL.md`, in name order, so two runs print the same lines. */
 function shippedSkills(source: string): string[] {
-  if (!existsSync(source) || !statSync(source).isDirectory()) return [];
+  if (!isDirectoryThere(source)) return [];
   return readdirSync(source)
-    .filter((name) => statSync(join(source, name)).isDirectory() && existsSync(join(source, name, 'SKILL.md')))
+    .filter((name) => isDirectoryThere(join(source, name)) && existsSync(join(source, name, 'SKILL.md')))
     .sort();
 }
 
+/** Read `<pkgDir>/package.json`'s `name` when present and non-empty, falling back to `fallback`. */
+function readPackageName(pkgDir: string, fallback: string): string {
+  const manifestPath = join(pkgDir, 'package.json');
+  if (!existsSync(manifestPath)) return fallback;
+  try {
+    const raw = JSON.parse(readFileSync(manifestPath, 'utf8')) as { name?: unknown };
+    return typeof raw.name === 'string' && raw.name.trim() !== '' ? raw.name.trim() : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Whether an unscoped `<node_modules>/<entry>` directory is a rig-c alias package (issue #1672):
+ *   1. it resolves (`realpathSync`) into a `@rig-c/*` directory, or
+ *   2. its `package.json` `repository` (string or `{url}`) points at `github.com/rig-c/`.
+ * A directory or package name alone never qualifies, because any third party can publish an unscoped `rig-<anything>`
+ * package.
+ */
+function isRigcAliasDir(pkgDir: string): boolean {
+  try {
+    if (realpathSync(pkgDir).replaceAll('\\', '/').includes('/@rig-c/')) return true;
+  } catch {
+    return false;
+  }
+  const manifestPath = join(pkgDir, 'package.json');
+  if (!existsSync(manifestPath)) return false;
+  try {
+    const raw = JSON.parse(readFileSync(manifestPath, 'utf8')) as { repository?: unknown };
+    const repo =
+      typeof raw.repository === 'string'
+        ? raw.repository.trim()
+        : typeof raw.repository === 'object' && raw.repository !== null && typeof (raw.repository as { url?: unknown }).url === 'string'
+          ? (raw.repository as { url: string }).url.trim()
+          : '';
+    return /^(?:(?:git\+)?https?:\/\/|(?:git\+)?ssh:\/\/git@|git:\/\/)?github\.com[:/]rig-c\/[A-Za-z0-9._-]+(?:\.git)?\/?$/.test(repo);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every `node_modules` directory reachable from `cwd` (walking up `<dir>/node_modules`) and from an installed
+ * `packageRoot` (every ancestor directory named `node_modules`, which covers flat `@rig-c/core`, unscoped `rig-c`, and
+ * isolated `node_modules/.bun/.../node_modules/@rig-c/core` layouts), deduplicated by `realpathSync`.
+ */
+function nodeModulesRoots(cwd: string, packageRoot: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const add = (nm: string): void => {
+    if (!isDirectoryThere(nm)) return;
+    const real = realpathSync(nm);
+    if (seen.has(real)) return;
+    seen.add(real);
+    out.push(nm);
+  };
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    add(join(dir, 'node_modules'));
+    if (dirname(dir) === dir) break;
+  }
+  for (let dir = dirname(resolve(packageRoot)); dirname(dir) !== dir; dir = dirname(dir)) {
+    if (basename(dir) === 'node_modules') add(dir);
+  }
+  return out;
+}
+
+/**
+ * Every skill-shipping package source `rigc skills install` scans (issue #1672):
+ *   1. `join(packageRoot, 'skills')` — the package this command ran from, always first;
+ *   2. every `node_modules/@rig-c/<pkg>/skills` and every rig-c alias package's `skills/` reachable from the project's
+ *      `node_modules`, in deterministic sorted order.
+ */
+export function discoverSkillSources(cwd: string, packageRoot: string): DiscoveredSkillSource[] {
+  const projectNmReals = new Set<string>();
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    const nm = join(dir, 'node_modules');
+    if (isDirectoryThere(nm)) projectNmReals.add(realpathSync(nm));
+    if (dirname(dir) === dir) break;
+  }
+  const sources: DiscoveredSkillSource[] = [
+    {
+      packageName: readPackageName(packageRoot, basename(packageRoot)),
+      skillsDir: join(packageRoot, 'skills'),
+      inProjectNodeModules: false,
+    },
+  ];
+  for (const nm of nodeModulesRoots(cwd, packageRoot)) {
+    const inProjectNodeModules = projectNmReals.has(realpathSync(nm));
+    const scopeDir = join(nm, '@rig-c');
+    if (isDirectoryThere(scopeDir)) {
+      for (const sub of readdirSync(scopeDir).sort()) {
+        const pkgDir = join(scopeDir, sub);
+        const skillsDir = join(pkgDir, 'skills');
+        if (isDirectoryThere(pkgDir) && shippedSkills(skillsDir).length > 0) {
+          sources.push({ packageName: readPackageName(pkgDir, `@rig-c/${sub}`), skillsDir, inProjectNodeModules });
+        }
+      }
+    }
+    for (const entry of readdirSync(nm).sort()) {
+      if (entry.startsWith('@') || entry.startsWith('.')) continue;
+      const pkgDir = join(nm, entry);
+      const skillsDir = join(pkgDir, 'skills');
+      if (isDirectoryThere(pkgDir) && isRigcAliasDir(pkgDir) && shippedSkills(skillsDir).length > 0) {
+        sources.push({ packageName: readPackageName(pkgDir, entry), skillsDir, inProjectNodeModules });
+      }
+    }
+  }
+  return sources;
+}
+
 /**
  * The real path of `path` whether or not it exists yet: the real path of its
  * nearest existing ancestor with the rest appended. A relative link has to be
@@ -2266,30 +2410,90 @@ function firstDifference(copy: string, original: string): string | null {
 }
 
 /**
- * Install every shipped skill into `dir`, or refuse and write nothing.
+ * Install every discovered skill into `dir`, or refuse and write nothing.
  *
- * The plan is made in full before the first write: every entry is classified as
- * absent, already this command's, or in the way, and one entry in the way
- * refuses the whole call with every such entry named.
+ * The plan is made in full before the first write:
+ *   - two sources that resolve (`realpathSync`) to the same skill folder are one skill (an alias or symlink reached
+ *     twice is deduplicated);
+ *   - two copies of the same product (`rig-c` ↔ `@rig-c/core`, `rig-<name>` ↔ `@rig-c/<name>`, or a project copy beside
+ *     the running package) are not a collision: the copy in the project's `node_modules` wins over the running package,
+ *     and between two project copies the scoped package (`@rig-c/*`) wins over the unscoped alias (`rig-*`), with the
+ *     chosen copy reported on its line;
+ *   - two different products shipping the same skill name refuse the call naming both sources and write nothing;
+ *   - every target is classified as absent, already this command's, or in the way, and one entry in the way refuses the
+ *     whole call with every such entry named.
  */
-function installSkills(source: string, dir: string, copy: boolean): SkillsInstallEntry[] {
-  const names = shippedSkills(source);
-  if (names.length === 0) {
+function installSkills(sources: readonly DiscoveredSkillSource[], dir: string, copy: boolean): SkillsInstallEntry[] {
+  const own = sources[0];
+  if (own === undefined || shippedSkills(own.skillsDir).length === 0) {
+    const ownSource = own?.skillsDir ?? join(PACKAGE_ROOT, 'skills');
     throw new SkillsInstallError(
-      `no skill to install: ${source} ${existsSync(source) ? 'holds no <name>/SKILL.md' : 'is not there'}, and it is ` +
+      `no skill to install: ${ownSource} ${existsSync(ownSource) ? 'holds no <name>/SKILL.md' : 'is not there'}, and it is ` +
         'the skills/ directory of the package this command ran from; nothing was written',
     );
   }
+  interface CandidateSkill {
+    name: string;
+    packageName: string;
+    product: string;
+    source: string;
+    realFrom: string;
+    inProjectNodeModules: boolean;
+    isScoped: boolean;
+    chosenOver?: Array<{ packageName: string; source: string }>;
+  }
+  const byName = new Map<string, CandidateSkill[]>();
+  for (const src of sources) {
+    const inProject = Boolean(src.inProjectNodeModules);
+    const product = canonicalProduct(src.packageName);
+    const isScoped = src.packageName.startsWith('@rig-c/');
+    for (const name of shippedSkills(src.skillsDir)) {
+      const from = join(src.skillsDir, name);
+      const realFrom = realpathSync(from);
+      const list = byName.get(name) ?? [];
+      if (list.some((item) => item.realFrom === realFrom)) {
+        const existing = list.find((item) => item.realFrom === realFrom);
+        if (existing !== undefined && inProject) existing.inProjectNodeModules = true;
+        continue;
+      }
+      list.push({ name, packageName: src.packageName, product, source: from, realFrom, inProjectNodeModules: inProject, isScoped });
+      byName.set(name, list);
+    }
+  }
+  const collisions = [...byName.entries()]
+    .filter(([, list]) => new Set(list.map((item) => item.product)).size > 1)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  if (collisions.length > 0) {
+    throw new SkillsInstallError(
+      `${collisions.length} duplicate skill name(s) across packages, and nothing was written:\n` +
+        collisions
+          .map(([name, list]) => `  ${name} is shipped by ${list.map((item) => `${item.packageName} (${item.source})`).join(' and ')}`)
+          .join('\n'),
+    );
+  }
   if (existsSync(dir) && !statSync(dir).isDirectory()) {
     throw new SkillsInstallError(`${dir} exists and is not a directory, so no skill can be installed into it; nothing was written`);
   }
+  const discovered = [...byName.values()]
+    .map((list) => {
+      if (list.length === 1) return list[0];
+      const ranked = [...list].sort((a, b) => {
+        if (a.inProjectNodeModules !== b.inProjectNodeModules) return a.inProjectNodeModules ? -1 : 1;
+        if (a.isScoped !== b.isScoped) return a.isScoped ? -1 : 1;
+        return 0;
+      });
+      return {
+        ...ranked[0],
+        chosenOver: ranked.slice(1).map((item) => ({ packageName: item.packageName, source: item.source })),
+      };
+    })
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   const realDir = realpathAhead(dir);
   const planned: SkillsInstallEntry[] = [];
   const refused: string[] = [];
-  for (const name of names) {
+  for (const item of discovered) {
+    const { name, packageName, source: from, realFrom, chosenOver } = item;
     const target = join(dir, name);
-    const from = join(source, name);
-    const realFrom = realpathSync(from);
     const link = relative(realDir, realFrom);
     let action: SkillsInstallAction = copy ? 'copied' : 'linked';
     let found: string | null = null;
@@ -2312,11 +2516,11 @@ function installSkills(source: string, dir: string, copy: boolean): SkillsInstal
       found = 'a plain file';
     }
     if (found !== null) refused.push(`${target} is ${found}; ${copy ? `a copy of ${from}` : `a symlink to ${link}`} was required`);
-    else planned.push({ target, source: from, action, link });
+    else planned.push({ target, source: from, packageName, action, link, chosenOver });
   }
   if (refused.length > 0) {
     throw new SkillsInstallError(
-      `${refused.length} of the ${names.length} skill(s) cannot be installed into ${dir}, and nothing was written:\n` +
+      `${refused.length} of the ${discovered.length} skill(s) cannot be installed into ${dir}, and nothing was written:\n` +
         refused.map((line) => `  ${line}`).join('\n') +
         '\nRemove the entries named above, or pass --dir to install somewhere else.',
     );
@@ -2343,7 +2547,7 @@ export function cmdSkills(flags: Record<string, string>, positional: string[]):
   if (sub === undefined) {
     throw new UsageError(
       `skills takes a subcommand: ${SKILLS_SUBCOMMANDS.join(', ')} — \`rigc skills install\` links every skill this ` +
-        `package ships into ${DEFAULT_SKILLS_DIR}`,
+        `package and any installed @rig-c/* or alias package ship into ${DEFAULT_SKILLS_DIR}`,
     );
   }
   if (!SKILLS_SUBCOMMANDS.includes(sub)) {
@@ -2364,9 +2568,15 @@ export function cmdSkills(flags: Record<string, string>, positional: string[]):
   }
   const copy = flags.copy !== undefined;
   const dir = resolve(process.cwd(), flags.dir ?? DEFAULT_SKILLS_DIR);
-  const entries = installSkills(join(PACKAGE_ROOT, 'skills'), dir, copy);
+  const entries = installSkills(discoverSkillSources(process.cwd(), PACKAGE_ROOT), dir, copy);
   for (const entry of entries) {
-    const ends = entry.action.endsWith('linked') ? `${entry.target} -> ${entry.link}  (${entry.source})` : `${entry.target} <- ${entry.source}`;
+    const choiceNote =
+      entry.chosenOver !== undefined && entry.chosenOver.length > 0
+        ? `  (chose ${entry.packageName} at ${entry.source} over ${entry.chosenOver.map((o) => `${o.packageName} at ${o.source}`).join(', ')})`
+        : '';
+    const ends = entry.action.endsWith('linked')
+      ? `${entry.target} -> ${entry.link}  (${entry.source})  [${entry.packageName}]${choiceNote}`
+      : `${entry.target} <- ${entry.source}  [${entry.packageName}]${choiceNote}`;
     console.log(`  ${entry.action.padEnd(14)}  ${ends}`);
   }
   const wrote = entries.filter((entry) => entry.action === 'linked' || entry.action === 'copied').length;

package/src/cli/shared.ts

@@ -933,20 +933,26 @@ export const DEFAULT_BALLOT = 'ballot.html';
 export const DEFAULT_LEDGER = 'votes.jsonl';
 
 // ---------------------------------------------------------------------------
-// skills install — put the shipped skills where an agent host looks (issue #831)
+// skills install — put the shipped skills where an agent host looks (issues #831, #1672)
 // ---------------------------------------------------------------------------
 //
-// After `bun add -d rig-c` the skills sit at `node_modules/rig-c/skills/`,
-// which no host reads. Codex, Gemini CLI and Antigravity all read
-// `<workspace>/.agents/skills/<name>/`, so this links every `skills/<name>/` the
-// package ships into one directory — `.agents/skills` under the working
-// directory unless `--dir` says otherwise.
+// After `bun add -d @rig-c/core` (and sibling packages such as `@rig-c/parts` or
+// `@rig-c/play`) the skills sit at `node_modules/@rig-c/*/skills/`, which no
+// host reads. Codex, Gemini CLI and Antigravity all read
+// `<workspace>/.agents/skills/<name>/`, so this links every `skills/<name>/` this
+// package and every installed `@rig-c/*` or rig-c alias package ship into one
+// directory — `.agents/skills` under the working directory unless `--dir` says
+// otherwise.
 //
-// ⭐ The skills are found from THIS FILE's location, never from the working
-// directory: the command installs the package it is, and a cwd that happens to
-// hold some other `skills/` is not a source. That is also why it lives here and
-// not in `src/`: its one input is where the CLI was installed, nothing else
-// calls it, and `src/` is about rigs.
+// ⭐ The skills are found from `PACKAGE_ROOT/skills` and every `node_modules/@rig-c/*`
+// and rig-c alias package reachable from the working directory's and `PACKAGE_ROOT`'s
+// `node_modules` — never a loose `skills/` in the working directory itself. Two
+// paths that resolve (`realpathSync`) to the same skill folder are deduplicated;
+// two copies of the same product (`rig-c` ↔ `@rig-c/core`, `rig-<name>` ↔ `@rig-c/<name>`)
+// choose the project's `node_modules` copy over the running package and the scoped
+// package over the unscoped alias, printing which copy was chosen; two different
+// products shipping the same skill name refuse the call naming both sources and
+// write nothing.
 //
 // A RELATIVE symlink by default, so the directory survives the project being
 // moved or cloned elsewhere and an upgrade of the package is seen with no second
@@ -1986,15 +1992,26 @@ export const COMMANDS: CommandDoc[] = [
     name: 'skills',
     runtime: false,
     spineFormat: false,
-    usage: [`rigc skills install [--dir ${DEFAULT_SKILLS_DIR}] [--copy]   (every skill this package ships, where an agent host looks)`],
+    usage: [`rigc skills install [--dir ${DEFAULT_SKILLS_DIR}] [--copy]   (every skill this package and any installed rig-c package ship, where an agent host looks)`],
     flags: ['dir', 'copy'],
     notes: [
-      'the skills installed are the skills/ directory of the package this command runs from,',
-      'never whatever the working directory holds. Each becomes <dir>/<name>: a relative',
-      'symlink into that folder, or with --copy a copy of it. An entry already there that',
-      'is not a link to the same folder — or, with --copy, not the same bytes — is refused',
-      'by name, exit 1, and nothing is written; a run over only what this command made has',
-      'nothing to do and exits 0. Codex, Gemini CLI and Antigravity read',
+      'scans the skills/ directory of the package this command runs from and every',
+      'node_modules/@rig-c/*/skills/<name>/SKILL.md and rig-c alias package (resolving by',
+      'realpathSync into @rig-c/* or declaring a github.com/rig-c/ repository in',
+      'package.json, never by directory name alone) reachable',
+      'from the project\'s node_modules (never a loose skills/ in the working directory),',
+      'reporting which package each skill came from. An alias or symlink that resolves',
+      '(realpathSync) to the same skill folder is deduplicated; two copies of the same',
+      'product (rig-c ↔ @rig-c/core, rig-<name> ↔ @rig-c/<name>) choose the project\'s',
+      'node_modules copy first and the scoped package over the alias, printing which copy',
+      'was chosen; two different products shipping the same skill name refuse the call',
+      'naming both sources and write nothing. Each skill becomes <dir>/<name>: a relative',
+      'symlink into that folder, or with --copy a copy of it (use `bunx @rig-c/core skills',
+      'install --copy` in a project without @rig-c/core installed so no link points into a',
+      'temporary .bunx cache). An entry already there that is not a link to the same folder',
+      '— or, with --copy, not the same bytes — is refused by name, exit 1, and nothing is',
+      'written; a run over only what this command made has nothing to do and exits 0. Codex,',
+      'Gemini CLI and Antigravity read',
       `<workspace>/${DEFAULT_SKILLS_DIR}; Claude Code installs the plugin instead (README,`,
       '"Install it into your agent").',
     ],
@@ -2172,12 +2189,14 @@ const USAGE_PARAGRAPHS: ReadonlyArray<{ about: readonly string[] | { flag: strin
   {
     about: ['skills'],
     lines: () => [
-      'skills install puts the agent skills this package ships where an agent host looks',
-      'for them, since none of them reads node_modules:',
+      'skills install puts the agent skills this package and every installed @rig-c/* or',
+      'alias package ship where an agent host looks for them, since none reads node_modules:',
       `  rigc skills install               relative links in ${DEFAULT_SKILLS_DIR}, which Codex, Gemini CLI`,
       '                                    and Antigravity read; --copy writes the folders instead',
-      'An entry already there that this command did not make is refused by name and',
-      'nothing is written; a second run has nothing to do. See `rigc skills --help`.',
+      'Two copies of the same product choose the project copy first and the scoped package',
+      'over the alias; an entry already there that this command did not make, or a duplicate',
+      'skill name across two different products, is refused by name and nothing is written.',
+      'See `rigc skills --help`.',
     ],
   },
   {