spine-rigc 1.0.1 → 1.1.0

package/README.md

@@ -146,8 +146,9 @@ to do with it, and it is the one instrument here that can see a wrong animation.
 
 The guides under [Documentation](#documentation) also ship as
 [Agent Skills](https://agentskills.io) — `skills/<name>/SKILL.md`, in this
-repository and in the npm package — so an agent finds rigc the way it finds its
-other tools. Each skill is a router and nothing more: when to load it, the
+repository and in the npm package — which a host reads once they are where it
+looks: Claude Code through the plugin below, Codex, Gemini CLI and Antigravity
+through `rigc skills install`. Each skill is a router and nothing more: when to load it, the
 non-negotiables in a line apiece, and a link to the guide that owns every rule, so
 a rule keeps living in exactly one place. The repository is also a Claude Code
 plugin marketplace:
@@ -162,6 +163,35 @@ loads the same skills without a marketplace. The plugin carries no version of it
 own — `/plugin update` follows `main` commit by commit, and the only version on
 disk stays the one in `package.json`.
 
+Codex, Gemini CLI and Antigravity read skills from one directory in the workspace,
+`.agents/skills/` ([Codex](https://learn.chatgpt.com/docs/build-skills),
+[Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md),
+[Antigravity](https://antigravity.google/docs/skills/)), and none of them reads
+`node_modules`. With the package installed, one command puts every skill there:
+
+```shell
+bun add -d spine-rigc
+bun rigc skills install          # relative links: .agents/skills/rigc -> ../../node_modules/spine-rigc/skills/rigc
+bun rigc skills install --copy   # the folders themselves, for a host that does not follow a link
+```
+
+Run it through the project's own install, as above: `bunx spine-rigc skills install`
+in a project that has the package was measured running the registry's copy instead
+of the project's. A link reaches every upgrade of the package with no second run,
+and a second run has nothing to do; an entry already there that this command did not
+make is refused by name and nothing is written. Gemini CLI 0.41.1 was measured
+listing a linked skill from both its workspace and its user directory — the
+workspace one only in a folder it trusts. Codex's documentation says it follows a
+symlinked skill folder, which is not measured here, and Antigravity CLI 1.1.9 has no
+way to list skills without starting a session, so what it does with a link is not
+measured either; `--copy` is the shape that asks nothing of a host. Gemini CLI can
+also fetch a skill itself, one folder at a time:
+`gemini skills install https://github.com/firejune/rigc.git --path skills/rigc --scope workspace`.
+The routers are named `rigc-rigging`, `rigc-motion`, `rigc-face` and `rigc-ingest`
+because that directory is flat — beside another tool's `motion`, a bare name is
+whichever one the host picked — and under the Claude Code plugin they read
+`rigc:rigc-motion` and so on.
+
 ## First rig in ten minutes
 
 A whole rig, end to end, in a scratch directory: three tiny plates, two JSON
@@ -478,8 +508,8 @@ the shot: both silhouette edges move apart, which a flat slide cannot do, becaus
 feature carries its own depth. The rig guarantees the seams — <code>idle</code> loops
 while <code>gaze</code> and <code>turn</code> return to rest, so the hand-offs meet at 0
 differing pixels — and the composing is the consumer's. Authorable on plain Spine 4.3, no
-plugin, no runtime patch; the split was authoring cost rather than runtime capability, and
-the cost is now one stated expression per key. Compiled and rendered entirely by the
+plugin, no runtime patch; what the turn costs is authoring rather than runtime capability,
+and that cost is one stated expression per key. Compiled and rendered entirely by the
 published package.</em></p>
 
 🎞️ **How the three films on this page were made** is kept with them, one directory per
@@ -511,6 +541,7 @@ commands take it and what its default is.
 | `bonedist --candidate … --reference … --bones …` | per-frame, per-bone world-transform distance against another skeleton — the ladder's stage 3, run on its own. `--bones <correspondence.json \| identity>` is required rather than defaulted: a candidate is entitled to its own bone names, so the pairing is stated |
 | `check --candidate <dir> --frames <dir>` | the candidate against reference pictures — the only instrument here that can see a *wrong animation* |
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
+| `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 |
 
 `diff`, `bonedist`, `check` and `bench` measure against something you were given; the
 first three work on any reference you have, and `bench` is a repository workflow that needs a clone
@@ -553,20 +584,20 @@ holds no art — every rebuild then has to repeat `build --images parts/`.
 
 **`build(ingest(x))` is `x`.** Over the eleven rigs this repository builds — the seven
 gallery examples, the three generated probes and a coverage probe written for the
-purpose — the rebuilt `skeleton.json` is byte for byte the file the decompiler read,
-and `bun run selftest` holds it there on every run. The atlas is held to a weaker
+purpose — the rebuilt `skeleton.json` is byte for byte the file the decompiler read.
+The atlas is held to a weaker
 claim on purpose, and the weakening is measured rather than assumed: it comes back
 equal as a **multiset of region blocks**, because the order the pages are collected in
 is in no field of the skeleton.
 
-**And over twelve skeletons nobody here wrote.** The same run ingests every editor
-export in the fetched example corpus, rebuilds it through the pack beside it and
-`diff`s the result against the source: **12 of 12, no blockers, 1.000 on every measure
-the report carries** — and each rebuild is its export's own text in canonical form,
-apart from the header's `hash` and `spine`: the editor's project hash and the runtime
-version rigc stamps, the two keys the rig spec has no field for by design (`IG83`,
-12 of 12). [INGEST.md §2.3](docs/INGEST.md) states that pass line and why those two
-are the exceptions.
+**And over twelve skeletons nobody here wrote.** Every editor export in the fetched
+example corpus, ingested, rebuilt through the pack beside it and `diff`ed against the
+source, comes back **12 of 12, no blockers, 1.000 on every measure the report
+carries** — and each rebuild is its export's own text in canonical form, apart from
+the header's `hash` and `spine`: the editor's project hash and the runtime version
+rigc stamps, the two keys the rig spec has no field for by design (12 of 12).
+[INGEST.md §2.3](docs/INGEST.md) states that pass line and why those two are the
+exceptions.
 
 **What it reads is skeleton JSON and nothing else** — no `.spine` project, no binary
 `.skel`, no atlas, no art. So it never invents, and the things it cannot get out of
@@ -579,16 +610,13 @@ specs are still written — a spec plus a list of what is missing from it beats
 
 - **The stage.** `skeleton.width`/`height`. A skeleton that declares none is carried as
   declaring none — the rig spec states `"width": null, "height": null` and the rebuild
-  carries no box either, byte for byte
-  ([#714](https://github.com/firejune/rigc/issues/714)) — and `--stage x,y,w,h` is how a
+  carries no box either, byte for byte — and `--stage x,y,w,h` is how a
   caller *adds* one, recorded as a judgement. It is not derivable — posing the rig gives
   the *animated* extent, which is a different number from the setup box. ⛔ **And `--stage` beside a box the file already states is refused
   too**, for the opposite reason: two sources for one value, where the file is the record
-  of what was measured. It used to be read after the box and therefore never
-  ([#626](https://github.com/firejune/rigc/issues/626)). ⚠️ This said *"an editor export carries none"* until #594 measured
-  it: **all twelve exports in the example corpus carry a stage** and none of them needs
-  the flag. It is still the value that costs least to get wrong, because `diff` reports
-  the box and gates nothing on it.
+  of what was measured. **All twelve exports in the example corpus carry a stage** and
+  none of them needs the flag. It is the value that costs least to get wrong, because
+  `diff` reports the box and gates nothing on it.
 - **An animation's duration.** The format has no such field. The largest key time is
   the only derivable answer and it is what a runtime plays to; it is wrong for an
   animation that holds its last pose past its last key, so it is recorded as a finding
@@ -620,17 +648,14 @@ render-and-check block per skin, with a per-skin roll-up under them, because a
 rig's contested art lives in its named skins and a single un-skinned check draws
 none of it; a skin only one side declares is a FAIL naming it as **lost** (or
 **added**) **by the export**, with `diff`'s `attachments.skins` beside it, and is
-rendered on neither side ([#801](https://github.com/firejune/rigc/issues/801)) — and a
+rendered on neither side — and a
 field-by-field list of what the editor rewrote. Every step quotes what its child
 said when that child did not do what it was for, the renderers included; a skin
 **neither** side can draw — a hit-box rig, say — is a **SKIP** naming that, not a
 red, because `check` had nothing to compare and `diff` and `validate` have
 already measured the rig. One side drawing where the other does not is the
-divergence the trip exists to find and stays a failure. On its first
-run it found three emitter defects — [#368](https://github.com/firejune/rigc/issues/368),
-[#369](https://github.com/firejune/rigc/issues/369),
-[#370](https://github.com/firejune/rigc/issues/370) — and then showed that a
-human edit made in the editor survives the trip back.
+divergence the trip exists to find and stays a failure. A human edit made in the
+editor survives the trip back.
 
 🔒 **It requires a licensed Spine editor on the machine, by construction**, and
 drives only the [documented command line](https://esotericsoftware.com/spine-command-line-interface)
@@ -643,14 +668,8 @@ and failing downstream. Both refusals point at `--exported <file>`, which
 measures an export the editor already made and is the half of this tool that
 needs no editor at all.
 
-⛔ **The round trip is not, and must not become, a selftest control.** `bun run
-selftest` is self-contained and CI has no editor; a control that needed one would
-report SKIP for ever, which is how a gate comes to look kept while checking
-nothing. Run the round trip by hand, on a machine that has the editor. Its
-**refusals** are gated, because they are the half a machine with no editor can
-answer for: the suite points the tool at stubs in a temp directory and reads what
-comes back, including the case that must *not* be refused — an editor at an
-unfamiliar path, which is who `--editor` exists for.
+⛔ **Run the round trip by hand, on a machine that has the editor.** CI has no
+editor, so no automated check runs it.
 
 ⚠️ Build with `--copy-images`. An ordinary build's atlas names its pages by a
 relative path back to the art directory, and the round trip copies that atlas to
@@ -667,9 +686,10 @@ letting `A17` blame the editor for the harness's own doing.
 | 🙂 **[docs/FACE.md](docs/FACE.md)** | **authoring a face.** A blink, a gaze and a 2.5D head turn on plain Spine data: the one line of yaw arithmetic every number in a turn comes from, depth as the parameter you are actually authoring, where to put a grid's columns and the angle at which any grid folds, what foreshortens and what does not, channel allocation before the first key, and the three cliffs with their angles. Also the deform audit gap, demonstrated — a folded mesh gates green — and the differential check that works today |
 | 📥 **[docs/INGEST.md](docs/INGEST.md)** | **working with a skeleton you did not author.** What every command can and cannot do with a foreign `skeleton.json`, reading it with the toolchain, transcription as the route that makes it yours, what each validator complaint means on an export, and the re-pivot/rename/extend recipes. Ships in the package too |
 | 🤖 **[docs/PROMPTING.md](docs/PROMPTING.md)** | **handing the authoring to an AI agent** — the prompt clauses a measured pilot run paid for, and what you can leave unsaid. Ships in the package too |
-| 🔬 **[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md)** | Spine 4.3's full export surface against what rigc emits and what the official examples measurably use, with the ordered gap list |
+| 🔬 **[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md)** | **the Spine 4.3 format, field by field.** Every key the 4.3 JSON parser and atlas reader take, what each defaults to, and the parser line it comes from — the rows rigc's refusals cite by part number. Ships in the package too |
 | 🎓 **[the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 49 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
 | 📋 [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) · [GATE.md](https://github.com/firejune/rigc/blob/main/docs/GATE.md) · [PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) | the live rung ledger, the clause statements a candidate is graded against, and how to run an agent through the ladder and score what comes back |
+| 🔬 [SURVEY_2026-08-22.md](https://github.com/firejune/rigc/blob/main/docs/SURVEY_2026-08-22.md) | the survey the ladder was climbed by: rigc and the official examples as measured on 2026-08-22, and the gap list ordered by rung. A dated record, not kept current. Repository material |
 | 🧬 [GENERATIONS.md](https://github.com/firejune/rigc/blob/main/docs/GENERATIONS.md) | **Spine data from another generation.** Why a 3.8–4.2 file read as 4.3 fails in silence, the policy that follows (detect from `skeleton.spine`, never guess, play on the matching runtime), what `A16` and `ingest` do with such a file, and the editor as the migration path. Repository material |
 | 🗺️ [ROADMAP.md](https://github.com/firejune/rigc/blob/main/ROADMAP.md) | where this is going, and where it has been. What 1.0 had to mean before the number was claimed, and what it was claimed on — conditions rather than a feature list, because direction here comes from what users hit |
 | 📐 [CLAUDE.md](https://github.com/firejune/rigc/blob/main/CLAUDE.md) | **the doctrine** — why the validator's messages are the product, why nothing reaches disk before green, why no number is ever invented, and what a change has to keep. [CONTRIBUTING.md](https://github.com/firejune/rigc/blob/main/CONTRIBUTING.md) calls it worth ten minutes before a first patch. Repository material |
@@ -680,7 +700,7 @@ rigc is measured against **Spine's own official example projects** — the
 `1-weight-and-mass` … `8-follow-through` series as a difficulty ladder, with spineboy
 as the graduation exam.
 
-🎓 **The ladder is complete, 2026-08-28.** All eight numbered rungs and the
+🎓 **The ladder is complete.** All eight numbered rungs and the
 spineboy graduation exam are cleared and hold under the current gate, **v2.4**, every clause PASS or SKIP:
 worst attributable slot drift **5.5550 px** against a 6.0 px bar — a **1.0801×**
 margin, the thinnest of the ladder's **G2** figures, and **G5**'s 1.0376× is thinner
@@ -688,24 +708,15 @@ still — and **0 of 124** frame-change disagreements. Recompiling the same spec
 different session reproduced every field of the measurement record **to the digit**.
 The rungs stay in place as regression gates.
 
-🗓️ **One rung's pass was withdrawn and restored on 2026-09-02, and both are dated
-facts.** `check`'s extent tolerance ([PR #254](https://github.com/firejune/rigc/pull/254))
-changed which box a set is measured in, and rung 7's stored candidate failed **G2**
-under it — one of its three slots draws in every set and is attributable in none,
-and no read-down ground survived the framing change. The gate then answered the two
-clause questions that exposed, as **v2.3**: a read-down names the framing of its
-evidence, and a slot whose attributability is **measured** to be capped below the bar
-reads down when everything observable about it is independently verified strict. That
-rung's third attempt clears on those grounds, on the candidate it already had.
-**Rungs 1–6 and 8 and the graduation exam were unaffected throughout**: each keeps its
-pass on the clause, and recompiling a stored candidate reproduces its record **to the
-digit within one gate**. Across an instrument change the digits do move, and the
-record says where — the graduation **G2** figure went 5.5491 → 5.5544 → **5.5550 px**
-over the #301 sampler repair and v2.4's adoption of the re-rendered reference basis,
-while **0 of 124** held throughout. Both verdicts, and the sweep of every candidate under the gate of the day, are in
-[docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md)'s *PR #254 instrument re-inspection* and *gate-v2.3
-re-inspection*; the standing figures quoted above are from its *gate-v2.4
-re-inspection*, which is the current sweep.
+**Rung 7 clears on a read-down.** One of its three slots draws in every set and is
+attributable in none; a read-down names the framing of its evidence, and a slot whose
+attributability is **measured** to be capped below the bar reads down when everything
+observable about it is independently verified strict. Every other rung and the
+graduation exam pass on the clause itself. Recompiling a stored candidate reproduces its
+record **to the digit within one gate**; across an instrument change the digits move,
+and [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) records
+where. The standing figures quoted above are from its *gate-v2.4 re-inspection*, which
+is the current sweep.
 
 ⚠️ **What that certifies, stated exactly.** That **the tool, the guide and the
 protocol reach the bar across a bounded series of honest attempts, each residual
@@ -717,8 +728,7 @@ ladder has not demonstrated that, and each row records which of the two it is.
 🧪 **A separate series measures that harder question, and it has not been kind.**
 From-zero attempts at spineboy — no inherited specs — have landed at **18.2, 18.8,
 19.57, 7.86, 9.33 and 18.98 px** worst drift against the 6.0 px bar, a spread with no
-monotone trend, and the two most recent — both **2026-09-03**, after the ladder's
-2026-08-28 completion — are recorded 🔴 **FAIL**. They move no rung and reopen nothing —
+monotone trend and every figure above the bar. They move no rung and reopen nothing —
 a from-zero run is a tooling-progress measurement rather than a re-climb, which is
 why the certification above is scoped to tool + guide + protocol. One of those
 attempts states the residual in its own words: *"in motion it is not at editor

package/cli.ts

@@ -31,8 +31,22 @@
  * Its paths resolve against the cuts.json file itself, so the table travels
  * with the project that owns the art rather than with this repository.
  */
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import {
+  appendFileSync,
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import {
   BallotError,
   buildBallot,
@@ -229,7 +243,7 @@ function repositoryUrl(): string {
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -3270,6 +3284,223 @@ function cmdIngest(flags: Record<string, string>, positional: string[]): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// skills install — put the shipped skills where an agent host looks (issue #831)
+// ---------------------------------------------------------------------------
+//
+// After `bun add -d spine-rigc` the skills sit at `node_modules/spine-rigc/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.
+//
+// ⭐ 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.
+//
+// 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
+// run. `--copy` writes the folder instead, for a host that does not follow a
+// linked skill folder.
+//
+// 🔒 **An entry that is already there and is not what this command would write is
+// refused by name, and then nothing at all is written.** The check runs over
+// every skill before the first write, so a refusal never leaves half an install
+// behind. The one entry that is NOT refused is the one this command would have
+// made — a link that already resolves to the same skill folder, however it is
+// spelled, or with `--copy` a folder whose files are byte for byte the package's
+// — and a run over only those says it had nothing to do. No lifecycle script
+// does this on install: a postinstall writing into a consumer's project root is
+// refused as design, and Bun does not run a dependency's lifecycle scripts
+// outside `trustedDependencies`, so half the installs would silently skip it.
+// ---------------------------------------------------------------------------
+
+/** The default `--dir`, resolved against the caller's working directory. */
+const DEFAULT_SKILLS_DIR = '.agents/skills';
+
+/** What `rigc skills` offers. One today; the list is what the refusal of any other word prints. */
+const SKILLS_SUBCOMMANDS = ['install'];
+
+/** An install refused before its first write — nothing to install, or an entry in the way. Exit 1. */
+class SkillsInstallError extends Error {}
+
+type SkillsInstallAction = 'linked' | 'copied' | 'already linked' | 'already copied';
+
+interface SkillsInstallEntry {
+  /** `<dir>/<name>`. */
+  target: string;
+  /** `<package>/skills/<name>`. */
+  source: string;
+  action: SkillsInstallAction;
+  /** The link text, relative to the directory it sits in, when the entry is a link. */
+  link: string;
+}
+
+/** 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 [];
+  return readdirSync(source)
+    .filter((name) => statSync(join(source, name)).isDirectory() && existsSync(join(source, name, 'SKILL.md')))
+    .sort();
+}
+
+/**
+ * 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
+ * computed between two paths spelled the same way, and on macOS the temp
+ * directory alone is reached as `/var/…` and is really `/private/var/…`.
+ */
+function realpathAhead(path: string): string {
+  const rest: string[] = [];
+  let at = resolve(path);
+  while (!existsSync(at)) {
+    const up = dirname(at);
+    if (up === at) break;
+    rest.unshift(basename(at));
+    at = up;
+  }
+  return join(realpathSync(at), ...rest);
+}
+
+/** Every file under `root`, relative and sorted, so two trees compare in one order. */
+function filesUnder(root: string, prefix = ''): string[] {
+  const out: string[] = [];
+  for (const name of readdirSync(join(root, prefix)).sort()) {
+    const rel = prefix === '' ? name : `${prefix}/${name}`;
+    if (lstatSync(join(root, rel)).isDirectory()) out.push(...filesUnder(root, rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+/** The first way `copy` differs from `original`, or null when every file is the same bytes. */
+function firstDifference(copy: string, original: string): string | null {
+  const theirs = filesUnder(copy);
+  const ours = filesUnder(original);
+  for (const rel of ours) {
+    if (!theirs.includes(rel)) return `${rel} is missing from it`;
+    if (!readFileSync(join(copy, rel)).equals(readFileSync(join(original, rel)))) return `${rel} differs`;
+  }
+  for (const rel of theirs) if (!ours.includes(rel)) return `${rel} is in it and not in the package`;
+  return null;
+}
+
+/**
+ * Install every shipped 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.
+ */
+function installSkills(source: string, dir: string, copy: boolean): SkillsInstallEntry[] {
+  const names = shippedSkills(source);
+  if (names.length === 0) {
+    throw new SkillsInstallError(
+      `no skill to install: ${source} ${existsSync(source) ? 'holds no <name>/SKILL.md' : 'is not there'}, and it is ` +
+        'the skills/ directory of the package this command ran from; nothing was written',
+    );
+  }
+  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 realDir = realpathAhead(dir);
+  const planned: SkillsInstallEntry[] = [];
+  const refused: string[] = [];
+  for (const name of names) {
+    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;
+    const stat = existsSync(target) || isLink(target) ? lstatSync(target) : null;
+    if (stat === null) {
+      // absent: this command writes it
+    } else if (stat.isSymbolicLink()) {
+      const text = readlinkSync(target);
+      const pointsAt = resolve(realDir, text);
+      const lands = existsSync(pointsAt) ? realpathSync(pointsAt) : null;
+      if (lands === realFrom && !copy) action = 'already linked';
+      else if (lands === realFrom) found = `a symlink to ${text}, the package's own folder, and --copy asks for a directory in its place`;
+      else found = `a symlink to ${text}, ${lands === null ? 'which resolves to nothing' : `which resolves to ${lands}`}`;
+    } else if (stat.isDirectory()) {
+      const difference = copy ? firstDifference(target, from) : null;
+      if (!copy) found = 'a directory';
+      else if (difference === null) action = 'already copied';
+      else found = `a directory that is not the package's copy (${difference})`;
+    } else {
+      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 });
+  }
+  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.map((line) => `  ${line}`).join('\n') +
+        '\nRemove the entries named above, or pass --dir to install somewhere else.',
+    );
+  }
+  mkdirSync(dir, { recursive: true });
+  for (const entry of planned) {
+    if (entry.action === 'linked') symlinkSync(entry.link, entry.target, 'dir');
+    else if (entry.action === 'copied') cpSync(entry.source, entry.target, { recursive: true, errorOnExist: true, force: false });
+  }
+  return planned;
+}
+
+/** A dangling link is not `existsSync`, and is still an entry in the way. */
+function isLink(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function cmdSkills(flags: Record<string, string>, positional: string[]): void {
+  const [sub, ...extra] = positional;
+  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}`,
+    );
+  }
+  if (!SKILLS_SUBCOMMANDS.includes(sub)) {
+    throw new UsageError(`unknown skills subcommand: ${sub} (rigc skills offers ${SKILLS_SUBCOMMANDS.join(', ')})`);
+  }
+  if (extra.length > 0) {
+    throw new UsageError(
+      `skills install takes no positional argument, and ${JSON.stringify(extra[0])} was given — the directory is --dir <path>`,
+    );
+  }
+  const takes = COMMANDS.find((c) => c.name === 'skills')?.flags ?? [];
+  const foreign = Object.keys(flags).filter((flag) => !takes.includes(flag));
+  if (foreign.length > 0) {
+    throw new UsageError(
+      `skills install takes ${takes.map((flag) => `--${flag}`).join(' and ')}; ` +
+        `${foreign.map((flag) => `--${flag}`).join(', ')} is not one of them`,
+    );
+  }
+  const copy = flags.copy !== undefined;
+  const dir = resolve(process.cwd(), flags.dir ?? DEFAULT_SKILLS_DIR);
+  const entries = installSkills(join(import.meta.dir, 'skills'), dir, copy);
+  for (const entry of entries) {
+    const ends = entry.action.endsWith('linked') ? `${entry.target} -> ${entry.link}  (${entry.source})` : `${entry.target} <- ${entry.source}`;
+    console.log(`  ${entry.action.padEnd(14)}  ${ends}`);
+  }
+  const wrote = entries.filter((entry) => entry.action === 'linked' || entry.action === 'copied').length;
+  const verb = copy ? 'copied' : 'linked';
+  console.log(
+    wrote === 0
+      ? `rigc skills install: nothing to do — all ${entries.length} skill(s) are already ${verb} into ${dir}`
+      : `rigc skills install: ${wrote} of ${entries.length} skill(s) ${verb} into ${dir}` +
+          (wrote < entries.length ? `, ${entries.length - wrote} already there` : ''),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // usage / per-command help
 // ---------------------------------------------------------------------------
@@ -3368,6 +3599,14 @@ const FLAG_MEANINGS: Record<string, string> = {
   ballot: `the ballot the --record'd vote answers (default \`${DEFAULT_BALLOT}\`); its embedded manifest is what the vote is checked against`,
   ledger: `the append-only JSONL the vote lands in (default \`${DEFAULT_LEDGER}\`)`,
   again: 'record a second vote on a ballot the ledger already has; without it, a repeat is refused rather than doubled',
+  dir:
+    `the directory to install into, resolved against your working directory (default \`${DEFAULT_SKILLS_DIR}\`, the ` +
+    'workspace directory Codex, Gemini CLI and Antigravity read skills from)',
+  copy:
+    'copy each skill folder instead of linking it, for a host that does not follow a linked skill folder. A copy ' +
+    'is not reached by an upgrade of the package, and one that is no longer the package\'s bytes is refused by name ' +
+    'on the next run — remove it and run again (default: a relative symlink, which an upgrade reaches with no ' +
+    'second run)',
   name: "the rig spec's own name, which the motion spec's archetype must match (default: the skeleton file's basename)",
   art: 'how the written spec reaches the art, which a skeleton does not encode: `loose` names an image per ' +
     "attachment, measured out of the rig spec's own images directory (--images writes it; without it, `build " +
@@ -3430,6 +3669,7 @@ const FLAG_VALUES: Record<string, string> = {
   name: '<n>',
   art: 'loose|none',
   stage: '<x,y,w,h>',
+  dir: '<path>',
 };
 
 interface CommandDoc {
@@ -3723,6 +3963,21 @@ const COMMANDS: CommandDoc[] = [
       },
     },
   },
+  {
+    name: 'skills',
+    usage: [`rigc skills install [--dir ${DEFAULT_SKILLS_DIR}] [--copy]   (every skill this package ships, 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',
+      `<workspace>/${DEFAULT_SKILLS_DIR}; Claude Code installs the plugin instead (README,`,
+      '"Install it into your agent").',
+    ],
+  },
 ];
 
 const KNOWN_COMMANDS = COMMANDS.map((c) => c.name);
@@ -3829,6 +4084,13 @@ const USAGE = [
   'answer rather than a missing one, and a result whose hashes are not the ballot\'s is',
   'refused by name instead of appended.',
   '',
+  'skills install puts the agent skills this package ships where an agent host looks',
+  'for them, since none of them 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`.',
+  '',
   'a cuts.json is { "<name>": { "rig": "...", "motion": "...", "out": "...",',
   '                             "manifest": "..." (optional) } }, with every path',
   'resolved relative to the cuts.json file itself.',
@@ -3870,6 +4132,7 @@ try {
   else if (command === 'pose') cmdPose(flags);
   else if (command === 'chainfit') cmdChainFit(flags);
   else if (command === 'vote') cmdVote(flags, lists.candidate ?? []);
+  else if (command === 'skills') cmdSkills(flags, positional);
 } catch (err) {
   if (err instanceof UsageError) {
     console.error(`rigc: ${err.message}\n\n${USAGE}`);
@@ -3940,5 +4203,13 @@ try {
     console.error(`rigc: ${err.message}`);
     process.exit(1);
   }
+  // An install refused before its first write (issue #831): the invocation was
+  // fine and an entry on disk was not what this command would write, so exit 1
+  // like a file that is not a PNG. The message names every such entry, what is
+  // there and what was required; the usage under it would bury that.
+  if (err instanceof SkillsInstallError) {
+    console.error(`rigc skills install: ${err.message}`);
+    process.exit(1);
+  }
   throw err;
 }