spine-rigc 1.0.2 → 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
@@ -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

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;
 }

package/docs/AUTHORING.md

@@ -186,6 +186,8 @@ 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 |
+| `--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
 protocol rate the reference frames use) and `--max <px>` (the long side of a
@@ -193,6 +195,26 @@ frame, default 256). Three commands take `--out`: a directory for `render`
 (default `render/`), the `.html` file for `preview` (default `preview.html`) and
 for `vote` (default `ballot.html`).
 
+`skills install` is the one 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
+project's own install — `bun rigc skills install` — so the links point into that
+project's `node_modules/spine-rigc/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
+(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:
+
+```text
+rigc skills install: <n> of the <m> skill(s) cannot be installed into <dir>, and nothing was written:
+  <dir>/rigc-motion is a plain file; a symlink to ../../node_modules/spine-rigc/skills/rigc-motion was required
+Remove the entries named above, or pass --dir to install somewhere else.
+```
+
+What is found is one of `a plain file`, `a directory`, `a symlink to <text>, which
+resolves to <path>` (or `to nothing`), and under `--copy` `a directory that is not
+the package's copy (<file> differs)`. A link to the package's own folder is not in
+the way however it is spelled, so an absolute link somebody else made is kept and
+reported `already linked`.
+
 Pick the profile deliberately, and know which one you got by saying nothing. The
 default is `spine`: "is this valid Spine 4.3 that any runtime plays correctly",
 which is the question a rig authored anywhere is asking. `--profile spine-html`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/skills/rigc/SKILL.md

@@ -34,8 +34,13 @@ whole interface, and this skill only says which of them to open.
 ```shell
 bunx spine-rigc --help       # run it without installing
 bun add -d spine-rigc        # or pin it in the project; the command is `rigc`
+bun rigc skills install      # then link these skills into .agents/skills
 ```
 
+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.
+
 ## The loop
 
 1. `rigc build --rig <spec> --motion <spec> --images <dir> --out <dir>` compiles,
@@ -61,17 +66,19 @@ AUTHORING §0.
 
 ## Which guide, for which need
 
-Read [AUTHORING.md](../../docs/AUTHORING.md) first, whatever the need: the two
+Read [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) first, whatever the need: the two
 spec files field by field, the emission rules, the loop, and the failure map. Then:
 
 | The request is… | Open | Skill |
 | --- | --- | --- |
-| a **skeleton** — how many bones, where each pivot sits, what hangs off what | [RIGGING.md](../../docs/RIGGING.md) | `rigging` |
-| a **movement** — an idle, a loop, from this pose to that one | [MOTION.md](../../docs/MOTION.md) | `motion` |
-| a **face** — a blink, a gaze, a head turn a few degrees off axis | [FACE.md](../../docs/FACE.md) | `face` |
-| a **skeleton.json somebody else authored** — read it, repair it, extend it | [INGEST.md](../../docs/INGEST.md) | `ingest` |
-| you are the **person operating** the agent rather than the agent | [PROMPTING.md](../../docs/PROMPTING.md) | — |
+| a **skeleton** — how many bones, where each pivot sits, what hangs off what | [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) | `rigc-rigging` |
+| a **movement** — an idle, a loop, from this pose to that one | [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) | `rigc-motion` |
+| a **face** — a blink, a gaze, a head turn a few degrees off axis | [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md) | `rigc-face` |
+| a **skeleton.json somebody else authored** — read it, repair it, extend it | [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) | `rigc-ingest` |
+| you are the **person operating** the agent rather than the agent | [PROMPTING.md](https://github.com/firejune/rigc/blob/main/docs/PROMPTING.md) | — |
 
-The same files are in the installed package at `node_modules/spine-rigc/docs/`;
-inside this plugin they are at `${CLAUDE_PLUGIN_ROOT}/docs/`. Formats, the CLI
-reference and the licence chain: [README.md](../../README.md).
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/`.
+Formats, the CLI reference and the licence chain:
+[README.md](https://github.com/firejune/rigc/blob/main/README.md), installed at `node_modules/spine-rigc/README.md`.

package/skills/{face → rigc-face}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: face
+name: rigc-face
 description: Author a face on plain Spine data with rigc — a blink, a gaze shift, a breathing portrait and a head turn a few degrees off axis, built from deform timelines and per-part parallax. Use when the request is a talking or living portrait, a standing character, an expression or a head turn, such as "rig this face", "make the portrait blink and look around" or "turn the head". Not for Live2D file conversion, cutting a face illustration into parts, or VTuber-style real-time face tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
@@ -9,7 +9,7 @@ compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
 
 Load this when the request is a **head rather than a body**: a drawn face that
 breathes, blinks, moves its eyes and turns a few degrees off axis. Every rule below
-is owned by [FACE.md](../../docs/FACE.md); this file says when to open it and what
+is owned by [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md); this file says when to open it and what
 it will not do for you.
 
 ## Non-negotiables
@@ -40,17 +40,21 @@ differential audit and the three limits it does not lift.
 
 ## Read, in this order
 
-1. [AUTHORING.md](../../docs/AUTHORING.md) — the `deform` timeline field by field
+1. [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) — the `deform` timeline field by field
    and what rigc refuses in it (§4), the failure map (§5–§6), the editor's
    conventions (§10).
-2. [MOTION.md](../../docs/MOTION.md) — timing, easing and the offset table (§3),
+2. [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) — timing, easing and the offset table (§3),
    candidates and the ballot (§4–§5). A blink and a gaze are ordinary motion work.
-3. [FACE.md](../../docs/FACE.md) — the face's own geometry: the closed form every
+3. [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md) — the face's own geometry: the closed form every
    number in a turn comes from (§1), the hierarchy underneath (§3), what
    foreshortens (§5), and the deform audit gap (§9).
-4. Then [RIGGING.md](../../docs/RIGGING.md) for the hierarchy as a general rule
-   rather than this closed form, and [INGEST.md](../../docs/INGEST.md) if the head
+4. Then [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) for the hierarchy as a general rule
+   rather than this closed form, and [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) if the head
    arrived as a compiled skeleton.
 
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/`.
+
 The install line and the build → validate → render → check loop are in the `rigc`
 skill.

package/skills/{ingest → rigc-ingest}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ingest
+name: rigc-ingest
 description: Work with a Spine skeleton.json somebody else authored — exported from the Spine editor or another tool — using rigc. Read and validate it, understand a complaint rigc raised about it, decompile it into rigc specs with `rigc ingest`, normalise, re-pivot or rename it, and extend it with an animation it does not have. Use when the input is an existing skeleton.json with its .atlas and page images rather than loose part PNGs. Not for Live2D file conversion or runtime tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
@@ -10,7 +10,7 @@ compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
 Load this when what you were handed is **already a skeleton**: a `skeleton.json`
 with its `.atlas` and page images, and a request to understand it, answer a
 complaint about it, re-express it, or extend it. Every rule below is owned by
-[INGEST.md](../../docs/INGEST.md); this file says when to open it and what it will
+[INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md); this file says when to open it and what it will
 not do for you.
 
 ## Non-negotiables
@@ -61,14 +61,18 @@ thing to reach for; transcription by hand is what you fall back on for a constru
 
 ## Read, in this order
 
-1. [INGEST.md](../../docs/INGEST.md) — what every command will and will not do with
+1. [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) — what every command will and will not do with
    a foreign file (§0), `ingest` and transcription (§2), what each validator
    complaint means on an export (§3), and the re-pivot, rename and extend
    recipes (§4).
-2. [AUTHORING.md](../../docs/AUTHORING.md) — the two spec files the transcription
+2. [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) — the two spec files the transcription
    targets (§3–§4), the failure map (§5–§6), and the coordinate contract (§11.2).
-3. Then [RIGGING.md](../../docs/RIGGING.md) for why the re-pivot edit has the shape
-   it has, and [MOTION.md](../../docs/MOTION.md) for the animation you are adding.
+3. Then [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) for why the re-pivot edit has the shape
+   it has, and [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) for the animation you are adding.
+
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/`.
 
 The install line and the build → validate → render → check loop are in the `rigc`
 skill.

package/skills/{motion → rigc-motion}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: motion
+name: rigc-motion
 description: Author a Spine animation with rigc from key poses — an idle, a loop, a move from one picture to another — with timing and spacing, ease in and out, anticipation, arcs, overlap, follow-through, squash and stretch, and candidate variants a person can choose between. Use when the request is a movement on an existing or planned rig, in the animator's words too: "animate this rig", "make it breathe", "go from pose A to pose B", "make it feel heavier", "the cape should follow through". Not for Live2D, separating an image into parts, or real-time tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
@@ -10,7 +10,7 @@ compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
 Load this when the request is a **movement rather than a skeleton**: a sentence of
 intent, between zero and N pictures of what the movement passes through, and a
 Spine animation somebody would choose coming back. Every rule below is owned by
-[MOTION.md](../../docs/MOTION.md); this file says when to open it and what it will
+[MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md); this file says when to open it and what it will
 not do for you.
 
 ## Non-negotiables
@@ -31,17 +31,21 @@ thing that judges a movement is a person's eye through `rigc vote` — MOTION §
 
 ## Read, in this order
 
-1. [AUTHORING.md](../../docs/AUTHORING.md) — the motion spec field by field (§4),
+1. [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) — the motion spec field by field (§4),
    the failure map (§5–§6), reading reference frames (§8) and checking against
    them (§9), what the editor does when nobody tells it otherwise (§10), and
    reading a pose out of a picture (§11–§12).
-2. [MOTION.md](../../docs/MOTION.md) — the normal form every motion request
+2. [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) — the normal form every motion request
    reduces to (§0), timing, easing and the per-bone offset table (§3), and how to
    spread candidates so a ballot informs (§4–§5).
-3. Then [RIGGING.md](../../docs/RIGGING.md) if the skeleton itself is what you have
-   to decide; [FACE.md](../../docs/FACE.md) if the movement is a blink, a gaze or a
-   head turn; [INGEST.md](../../docs/INGEST.md) if the rig arrived as a compiled
+3. Then [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) if the skeleton itself is what you have
+   to decide; [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md) if the movement is a blink, a gaze or a
+   head turn; [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) if the rig arrived as a compiled
    skeleton rather than loose parts.
 
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/`.
+
 The install line and the build → validate → render → check loop are in the `rigc`
 skill.

package/skills/{rigging → rigc-rigging}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: rigging
+name: rigc-rigging
 description: Decide a Spine rig's hierarchy with rigc — how many bones, where each pivot sits, what hangs off what, offsets, chains and what a chain can reach, siblings versus chains, constraints as structure — and which of those decisions the reference frames can check. Use when the request is a skeleton from loose part PNGs, such as "rig these parts", "make a Spine skeleton" or "where do the joints go", before any motion is authored. Not for Live2D, cutting an illustration into parts, or VTuber-style tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
@@ -9,7 +9,7 @@ compatibility: Requires Bun 1.2 or later and the npm package spine-rigc.
 
 Load this when the request is a **skeleton rather than a movement**: loose part
 PNGs in, a bone hierarchy out. Every rule below is owned by
-[RIGGING.md](../../docs/RIGGING.md); this file says when to open it and what it
+[RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md); this file says when to open it and what it
 will not do for you.
 
 ## Non-negotiables
@@ -30,16 +30,20 @@ are named in RIGGING §11 — neither as a pass bar.
 
 ## Read, in this order
 
-1. [AUTHORING.md](../../docs/AUTHORING.md) — the rig spec field by field (§3),
+1. [AUTHORING.md](https://github.com/firejune/rigc/blob/main/docs/AUTHORING.md) — the rig spec field by field (§3),
    the failure map (§5–§6), reading a pose out of a picture (§8.1, §11, §12),
    and the editor's own conventions (§10).
-2. [RIGGING.md](../../docs/RIGGING.md) — the structure itself: what identifies a
+2. [RIGGING.md](https://github.com/firejune/rigc/blob/main/docs/RIGGING.md) — the structure itself: what identifies a
    pivot and what moving one costs (§2–§3), gauges (§4), what a chain can reach
    (§6), and the instruments that see structure (§11).
-3. Then [MOTION.md](../../docs/MOTION.md) once the skeleton exists;
-   [FACE.md](../../docs/FACE.md) if the figure is a head;
-   [INGEST.md](../../docs/INGEST.md) if the skeleton was handed to you already
+3. Then [MOTION.md](https://github.com/firejune/rigc/blob/main/docs/MOTION.md) once the skeleton exists;
+   [FACE.md](https://github.com/firejune/rigc/blob/main/docs/FACE.md) if the figure is a head;
+   [INGEST.md](https://github.com/firejune/rigc/blob/main/docs/INGEST.md) if the skeleton was handed to you already
    compiled.
 
+Every guide linked here is in the installed package at `node_modules/spine-rigc/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/`.
+
 The install line and the build → validate → render → check loop are in the `rigc`
 skill.