skillshelf 0.3.0 → 0.4.1

package/src/commands/agents.test.ts

@@ -0,0 +1,96 @@
+// `skl agents --json` end-to-end with ADR-0010 config: a persisted-but-empty
+// project must surface as a scope (no phantom deployments), a custom agent must
+// appear in the matrix, and a real deploy into a config-project must be inventoried.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as agentsRun } from "./agents.ts";
+import { run as useRun } from "./use.ts";
+import { loadLibrary } from "../core/library.ts";
+import type { AgentsReport } from "../core/agents.ts";
+import type { Config, Ctx } from "../types.ts";
+
+async function writeSkill(library: string, name: string) {
+  const dir = join(library, name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: ${name}\ndomains: [bio]\n---\n\nbody\n`);
+}
+
+describe("skl agents --json — config projects + agents (ADR-0010)", () => {
+  let tmp: string;
+  let library: string;
+
+  function makeCtx(config: Partial<Config>): { ctx: Ctx; json: unknown[] } {
+    const json: unknown[] = [];
+    const full: Config = {
+      libraryPath: library,
+      globalCoreTarget: join(tmp, ".no-global-core"),
+      roots: [],
+      agents: [],
+      projects: [],
+      configFile: null,
+      configFilePath: join(tmp, "config.json"),
+      source: "default",
+      ...config,
+    };
+    const ctx = {
+      config: full,
+      libraryPath: library,
+      roots: full.roots,
+      loadLibrary: () => loadLibrary(library),
+      log: () => {},
+      error: () => {},
+      json: (v: unknown) => json.push(v),
+    } as unknown as Ctx;
+    return { ctx, json };
+  }
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-agents-cmd-")));
+    library = join(tmp, "library");
+    await writeSkill(library, "alpha");
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("an empty config-project appears as a scope with no phantom deployments", async () => {
+    const empty = join(tmp, "scratch");
+    await mkdir(empty, { recursive: true });
+    const { ctx, json } = makeCtx({ projects: [empty] });
+    const code = await agentsRun(["--json"], ctx);
+    expect(code).toBe(0);
+    const report = json[0] as AgentsReport;
+    expect(report.scopes).toContain("scratch");
+    // empty project = NO fabricated cell. (The matrix may contain real machine
+    // global deployments; the invariant is that nothing is keyed to `scratch`.)
+    for (const byAgent of Object.values(report.deployments)) {
+      for (const dep of Object.values(byAgent)) {
+        expect(dep.p?.scratch).toBeUndefined();
+      }
+    }
+  });
+
+  test("a custom config-agent appears in the agents list", async () => {
+    const { ctx, json } = makeCtx({ agents: [{ id: "pi", name: "PI Agent", short: "PI" }] });
+    await agentsRun(["--json"], ctx);
+    const report = json[0] as AgentsReport;
+    expect(report.agents.map((a) => a.id)).toContain("pi");
+  });
+
+  test("a real deploy into a config-project is inventoried in the matrix", async () => {
+    const proj = join(tmp, "webapp");
+    await mkdir(proj, { recursive: true });
+    // deploy alpha into the config project for claude
+    const { ctx: useCtx } = makeCtx({ projects: [proj] });
+    await useRun(["alpha", "--agent", "claude", "--project", proj, "--json"], useCtx);
+
+    const { ctx, json } = makeCtx({ projects: [proj] });
+    await agentsRun(["--json"], ctx);
+    const report = json[0] as AgentsReport;
+    expect(report.scopes).toContain("webapp");
+    expect(report.deployments.alpha!.claude!.p!.webapp).toBe("clean");
+  });
+});

package/src/commands/agents.ts

@@ -6,10 +6,16 @@
 //   skl agents --json        full AgentsReport { agents, scopes, deployments }
 //   skl agents <name>        one skill's row across agents × scopes
 
-import type { Ctx } from "../types.ts";
+import { basename, join, sep } from "node:path";
+import type { AgentConfigEntry, Ctx } from "../types.ts";
 import { inventoryDeployments } from "../core/deployments.ts";
 import { knownAgentSurfacePaths } from "../core/surfaces.ts";
-import { computeAgentsReport, resolveReadTarget, type DeployState } from "../core/agents.ts";
+import {
+  computeAgentsReport,
+  knownAgentIds,
+  resolveReadTarget,
+  type DeployState,
+} from "../core/agents.ts";
 
 export const meta = {
   name: "agents",
@@ -28,7 +34,24 @@ const GLYPH: Record<DeployState, string> = {
 
 const LEGEND = "legend: ✓ clean · ⊙ source · ⚠ drift · □ copy · ✗ dead · · absent";
 
+/**
+ * Scope name for a persisted project dir = its basename — matching the engine's
+ * scope derivation (parseDeployTarget / scopeForSurface use the last path segment),
+ * so a config project reconciles with the FS-derived scopes in the matrix.
+ */
+function projectScopeName(projectPath: string): string {
+  return projectPath.split(sep).filter(Boolean).pop() || basename(projectPath) || projectPath;
+}
+
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  // ── Config write subverbs (ADR-0010 delta 4): `skl agents add|rm` mutate the
+  //    custom-agent registry in config.json. These are registry metadata only —
+  //    they never deploy; the matrix stays FS-derived. Checked BEFORE the read
+  //    path so `add`/`rm` are never mistaken for a skill name. (`add`/`rm` are
+  //    reserved subverbs; a skill literally named "add"/"rm" is not a concern.)
+  if (argv[0] === "add" || argv[0] === "rm") {
+    return runConfigSubverb(argv, ctx);
+  }
   try {
     const rt = resolveReadTarget(argv);
     if ("error" in rt) {
@@ -40,11 +63,35 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     const name = rt.rest.find((a) => !a.startsWith("--")) ?? null;
 
     const lib = await ctx.loadLibrary();
-    // Same surface union as `skl where` (+ any --project surfaces for this call) so
-    // the agent matrix sees the same reality and can verify an ad-hoc project deploy.
-    const surfaces = [...ctx.roots, ctx.config.globalCoreTarget, ...knownAgentSurfacePaths(), ...rt.extraSurfaces];
+    // Effective agent ids = built-in seeds + custom config agents (so a custom
+    // agent's project/global skills dirs are scanned for inventory).
+    const agentIds = new Set<string>(knownAgentIds());
+    for (const a of ctx.config.agents) {
+      if (a && typeof a.id === "string" && a.id.trim() !== "") agentIds.add(a.id);
+    }
+    // Config-project surfaces (ADR-0010 §5a): scan each persisted project dir for
+    // every effective agent so a deployed config-project is inventoried.
+    const projectSurfaces: string[] = [];
+    for (const proj of ctx.config.projects) {
+      for (const id of agentIds) projectSurfaces.push(join(proj, `.${id}`, "skills"));
+    }
+    // Same surface union as `skl where` (+ any --project surfaces for this call,
+    // + persisted config-project surfaces) so the agent matrix sees the same
+    // reality and can verify an ad-hoc OR persisted project deploy.
+    const surfaces = [
+      ...ctx.roots,
+      ctx.config.globalCoreTarget,
+      ...knownAgentSurfacePaths(),
+      ...projectSurfaces,
+      ...rt.extraSurfaces,
+    ];
     const report = await inventoryDeployments(surfaces, ctx.libraryPath, lib);
-    let agentsReport = computeAgentsReport(report);
+    // Empty persisted projects still appear as scope rows (basename = scope name);
+    // custom agents merge into the matrix. Deployments stay FS-derived.
+    let agentsReport = computeAgentsReport(report, undefined, {
+      agents: ctx.config.agents,
+      extraScopes: ctx.config.projects.map((p) => projectScopeName(p)),
+    });
 
     // --agent <id> focuses the whole report on that agent: prune the agents list
     // and the deployments map to just that agent (skills not deployed to it drop).
@@ -118,3 +165,79 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     return 1;
   }
 }
+
+/** Read a `--flag value` option out of argv (returns undefined if absent). */
+function flag(argv: string[], name: string): string | undefined {
+  const i = argv.indexOf(name);
+  if (i < 0) return undefined;
+  const v = argv[i + 1];
+  return v && !v.startsWith("--") ? v : undefined;
+}
+
+/**
+ * `skl agents add <id> --name <n> --global <dir> --proj-convention <c> [--icon k]
+ *  [--color #rgb]` and `skl agents rm <id>` — persist the custom-agent registry
+ * (ADR-0010 delta 4). With `--json` emits `{ agents }` / `{ agents, removed }`
+ * (the full custom-agent list) so the GUI can round-trip without a separate read.
+ */
+async function runConfigSubverb(argv: string[], ctx: Ctx): Promise<number> {
+  const verb = argv[0];
+  const json = argv.includes("--json");
+  const id = argv[1] && !argv[1].startsWith("--") ? argv[1].trim() : "";
+
+  if (!id) {
+    ctx.error(`skl agents ${verb}: requires an agent id`);
+    ctx.error("usage: skl agents add <id> --name <name> --global <dir> --proj-convention <conv> [--icon <key>] [--color <hex>]");
+    return 1;
+  }
+
+  if (verb === "rm") {
+    const { agents, removed } = await ctx.removeAgent(id);
+    if (json) {
+      ctx.json({ agents, removed });
+      return 0;
+    }
+    ctx.log(removed ? `Removed custom agent "${id}".` : `No custom agent "${id}" (nothing removed).`);
+    return 0;
+  }
+
+  // add
+  const name = flag(argv, "--name") ?? id;
+  const global = flag(argv, "--global");
+  const projConvention = flag(argv, "--proj-convention");
+  const icon = flag(argv, "--icon");
+  const color = flag(argv, "--color");
+  // `--hidden` persists a hide override (ADR-0010 delta 4 / RISK 8): mergeAgents
+  // drops `hidden:true` so the agent leaves the matrix everywhere. A hide entry
+  // for a SEED carries no paths, so --global/--proj-convention are only required
+  // for a real (visible) registration.
+  const hidden = argv.includes("--hidden");
+  // Global→project inheritance (ADR-0010): default TRUE (the ~/.x/skills
+  // convention). `--no-inherits-global` opts out (persists inheritsGlobal:false);
+  // `--inherits-global` is accepted for symmetry but is the default, so we only
+  // persist the flag when it diverges from the default to keep config minimal.
+  const inheritsGlobal = !argv.includes("--no-inherits-global");
+  if (!hidden && (!global || !projConvention)) {
+    ctx.error("skl agents add: --global and --proj-convention are required");
+    return 1;
+  }
+  const entry: AgentConfigEntry = {
+    id,
+    name,
+    short: name,
+    ...(global ? { global } : {}),
+    ...(projConvention ? { projConvention } : {}),
+    ...(icon ? { icon } : {}),
+    ...(color ? { color } : {}),
+    ...(hidden ? { hidden: true } : {}),
+    ...(inheritsGlobal ? {} : { inheritsGlobal: false }),
+  };
+  const agents = await ctx.addAgent(entry);
+  if (json) {
+    ctx.json({ agents, added: true });
+    return 0;
+  }
+  ctx.log(`Registered custom agent "${name}" (${id}). Custom agents (${agents.length}):`);
+  for (const a of agents) ctx.log(`  ${a.id}  ${a.global}`);
+  return 0;
+}

package/src/commands/import.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "./import.ts";
+import type { Ctx } from "../types.ts";
+
+const BODY = "---\nname: caveman\ndescription: a test skill\n---\n\nbody\n";
+
+interface Captured {
+  ctx: Ctx;
+  logs: string[];
+  errors: string[];
+  json: unknown[];
+}
+
+function makeCtx(libraryPath: string): Captured {
+  const logs: string[] = [];
+  const errors: string[] = [];
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    log: (...a: unknown[]) => logs.push(a.join(" ")),
+    error: (...a: unknown[]) => errors.push(a.join(" ")),
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, logs, errors, json };
+}
+
+describe("skl import — retired-aware collision", () => {
+  let tmp: string;
+  let library: string;
+  let candidate: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-import-")));
+    library = join(tmp, "library");
+    await mkdir(library, { recursive: true });
+    // A candidate skill dir on disk to import.
+    candidate = join(tmp, "ext", "caveman");
+    await mkdir(candidate, { recursive: true });
+    await writeFile(join(candidate, "SKILL.md"), BODY);
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("importing to a retired name refuses (exit 1, no write)", async () => {
+    // Retire "caveman": a tombstone, no active copy.
+    await mkdir(join(library, "_retired", "caveman"), { recursive: true });
+    await writeFile(join(library, "_retired", "caveman", "SKILL.md"), BODY);
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await run(["caveman", "--from", candidate, "--copy"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("skl unretire caveman");
+
+    // No active copy created; the candidate is untouched.
+    expect(existsSync(join(library, "caveman"))).toBe(false);
+    expect(existsSync(join(candidate, "SKILL.md"))).toBe(true);
+  });
+
+  test("importing a non-retired name still works (no regression)", async () => {
+    const { ctx } = makeCtx(library);
+    const code = await run(["caveman", "--from", candidate, "--copy", "--json"], ctx);
+    expect(code).toBe(0);
+    expect(existsSync(join(library, "caveman", "SKILL.md"))).toBe(true);
+  });
+});

package/src/commands/import.ts

@@ -34,6 +34,7 @@ import {
   isSymlink,
   realpathOrSelfAsync,
 } from "../lib/fs.ts";
+import { entryStatus } from "../core/library.ts";
 
 export const meta = {
   name: "import",
@@ -202,6 +203,18 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     // Flat, non-semantic layout (ADR-0001): always <library>/<name>/.
     const destDir = join(libraryPath, targetName);
 
+    // Retired-aware guard: refuse if the name exists ONLY as a retired tombstone
+    // (<library>/_retired/<name>). Importing beside it would strand a duplicate and
+    // break `skl unretire`; --force overwrites an ACTIVE copy, not a retired one, so
+    // this fires regardless. The user must unretire first (or import under --as).
+    const status = entryStatus(libraryPath, targetName);
+    if (status.retired && !status.active) {
+      ctx.error(
+        `skl import: a retired '${targetName}' exists — run \`skl unretire ${targetName}\` first (or import under another name with --as <slug>)`,
+      );
+      return 1;
+    }
+
     // Idempotency guard: refuse to clobber an existing library skill unless --force
     // (or the user re-aimed with --as). This protects a managed copy from a stray
     // re-import.

package/src/commands/link.test.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import { run } from "./link.ts";
 import type { Ctx } from "../types.ts";
 
-const BODY = "---\nname: cairn\ndescription: a test skill\n---\n\nbody\n";
+const BODY = "---\nname: claim-log\ndescription: a test skill\n---\n\nbody\n";
 
 async function makeSkillDir(parent: string, name: string, body = BODY): Promise<string> {
   const dir = join(parent, name);
@@ -54,94 +54,108 @@ describe("skl link --from (LINKED mode)", () => {
   });
 
   test("registers a dev-repo skill as a library symlink", async () => {
-    const src = await makeSkillDir(devRepo, "cairn");
+    const src = await makeSkillDir(devRepo, "claim-log");
     const { ctx, json } = makeCtx(library);
-    const code = await run(["cairn", "--from", src, "--json"], ctx);
+    const code = await run(["claim-log", "--from", src, "--json"], ctx);
 
     expect(code).toBe(0);
-    const libEntry = join(library, "cairn");
+    const libEntry = join(library, "claim-log");
     const st = await lstat(libEntry);
     expect(st.isSymbolicLink()).toBe(true);
     expect(await realpath(libEntry)).toBe(await realpath(src));
-    expect(json[0]).toMatchObject({ ok: true, name: "cairn", mode: "linked", discarded: false });
+    expect(json[0]).toMatchObject({ ok: true, name: "claim-log", mode: "linked", discarded: false });
   });
 
   test("derives the name from the dev-repo dir basename when omitted", async () => {
-    const src = await makeSkillDir(devRepo, "cairn");
+    const src = await makeSkillDir(devRepo, "claim-log");
     const { ctx } = makeCtx(library);
     const code = await run(["--from", src], ctx);
 
     expect(code).toBe(0);
-    const libEntry = join(library, "cairn");
+    const libEntry = join(library, "claim-log");
     expect((await lstat(libEntry)).isSymbolicLink()).toBe(true);
     expect(await realpath(libEntry)).toBe(await realpath(src));
   });
 
   test("is idempotent — re-running reports 'already'", async () => {
-    const src = await makeSkillDir(devRepo, "cairn");
+    const src = await makeSkillDir(devRepo, "claim-log");
     const { ctx } = makeCtx(library);
-    await run(["cairn", "--from", src], ctx);
+    await run(["claim-log", "--from", src], ctx);
 
     const { ctx: ctx2, json } = makeCtx(library);
-    const code = await run(["cairn", "--from", src, "--json"], ctx2);
+    const code = await run(["claim-log", "--from", src, "--json"], ctx2);
     expect(code).toBe(0);
     expect(json[0]).toMatchObject({ status: "already", mode: "linked" });
   });
 
   test("refuses to clobber an existing owned library copy without --force", async () => {
-    await makeSkillDir(library, "cairn"); // a real OWNED copy already in the library
-    const src = await makeSkillDir(devRepo, "cairn");
+    await makeSkillDir(library, "claim-log"); // a real OWNED copy already in the library
+    const src = await makeSkillDir(devRepo, "claim-log");
     const { ctx, errors } = makeCtx(library);
 
-    const code = await run(["cairn", "--from", src], ctx);
+    const code = await run(["claim-log", "--from", src], ctx);
     expect(code).toBe(1);
     expect(errors.join("\n")).toContain("already exists in the library");
     // unchanged: still a real dir, not a symlink
-    expect((await lstat(join(library, "cairn"))).isSymbolicLink()).toBe(false);
+    expect((await lstat(join(library, "claim-log"))).isSymbolicLink()).toBe(false);
+  });
+
+  test("refuses to shelve over a retired tombstone (points at unretire)", async () => {
+    // "claim-log" exists only as a retired tombstone — no active library entry.
+    await makeSkillDir(join(library, "_retired"), "claim-log");
+    const src = await makeSkillDir(devRepo, "claim-log");
+    const { ctx, errors } = makeCtx(library);
+
+    const code = await run(["claim-log", "--from", src], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("skl unretire claim-log");
+    // No active symlink created beside the tombstone.
+    expect(existsSync(join(library, "claim-log"))).toBe(false);
+    expect(existsSync(join(library, "_retired", "claim-log"))).toBe(true);
   });
 
   test("--force replaces an owned copy with the symlink and reports discarded", async () => {
-    await makeSkillDir(library, "cairn");
-    const src = await makeSkillDir(devRepo, "cairn");
+    await makeSkillDir(library, "claim-log");
+    const src = await makeSkillDir(devRepo, "claim-log");
     const { ctx, json } = makeCtx(library);
 
-    const code = await run(["cairn", "--from", src, "--force", "--json"], ctx);
+    const code = await run(["claim-log", "--from", src, "--force", "--json"], ctx);
     expect(code).toBe(0);
-    expect((await lstat(join(library, "cairn"))).isSymbolicLink()).toBe(true);
+    expect((await lstat(join(library, "claim-log"))).isSymbolicLink()).toBe(true);
     expect(json[0]).toMatchObject({ discarded: true, mode: "linked" });
   });
 
   test("drops a stale lockfile entry so update/outdated skip the now-LINKED skill", async () => {
     // An owned import existed (real copy + a github lock entry); now convert to LINKED.
-    await makeSkillDir(library, "cairn");
+    await makeSkillDir(library, "claim-log");
     await writeFile(
       join(library, "shelf.lock.json"),
       JSON.stringify({
         version: 1,
         entries: {
-          cairn: { name: "cairn", source: "github:owner/repo", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false },
+          "claim-log": { name: "claim-log", source: "github:owner/repo", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false },
         },
       }),
     );
-    const src = await makeSkillDir(devRepo, "cairn");
+    const src = await makeSkillDir(devRepo, "claim-log");
     const { ctx } = makeCtx(library);
 
-    const code = await run(["cairn", "--from", src, "--force"], ctx);
+    const code = await run(["claim-log", "--from", src, "--force"], ctx);
     expect(code).toBe(0);
     const lock = JSON.parse(await readFile(join(library, "shelf.lock.json"), "utf8"));
-    expect(lock.entries.cairn).toBeUndefined();
+    expect(lock.entries["claim-log"]).toBeUndefined();
   });
 
   test("rejects --at and --from together", async () => {
-    const src = await makeSkillDir(devRepo, "cairn");
+    const src = await makeSkillDir(devRepo, "claim-log");
     const { ctx, errors } = makeCtx(library);
-    const code = await run(["cairn", "--from", src, "--at", "/tmp/x"], ctx);
+    const code = await run(["claim-log", "--from", src, "--at", "/tmp/x"], ctx);
     expect(code).toBe(1);
     expect(errors.join("\n")).toContain("mutually exclusive");
   });
 
   test("refuses a --from source inside the library", async () => {
-    const inside = await makeSkillDir(library, "cairn");
+    const inside = await makeSkillDir(library, "claim-log");
     const { ctx, errors } = makeCtx(library);
     const code = await run(["other", "--from", inside], ctx);
     expect(code).toBe(1);

package/src/commands/link.ts

@@ -39,6 +39,7 @@ import {
   safeSymlink,
   realpathOrSelfAsync,
 } from "../lib/fs.ts";
+import { entryStatus } from "../core/library.ts";
 
 export const meta = {
   name: "link",
@@ -166,6 +167,16 @@ async function runFrom(flags: Flags, ctx: Ctx): Promise<number> {
       }
     }
 
+    // Retired-aware guard: refuse if the name exists ONLY as a retired tombstone
+    // (<library>/_retired/<name>). Shelving a symlink beside it would strand a duplicate
+    // and break `skl unretire`; --force replaces an ACTIVE entry, not a retired one, so
+    // this fires regardless. The user must unretire first.
+    const status = entryStatus(libraryPath, name);
+    if (status.retired && !status.active) {
+      ctx.error(`skl link: a retired '${name}' exists — run \`skl unretire ${name}\` first.`);
+      return 1;
+    }
+
     // An existing library entry won't be clobbered silently.
     const exists = existsSync(libDir) || isSymlink(libDir);
     if (exists && !flags.force) {

package/src/commands/ls.ts

@@ -2,7 +2,7 @@
 // bundle (tag query). Excludes retired by default; `--all` includes them.
 
 import { statSync } from "node:fs";
-import type { Ctx, Skill } from "../types.ts";
+import type { Ctx, Skill, Provenance } from "../types.ts";
 import { activeSkills, entryModeInfo } from "../core/library.ts";
 import { resolveBundle } from "../core/bundle.ts";
 import { inventoryDeployments } from "../core/deployments.ts";
@@ -94,8 +94,11 @@ function toJson(
       mode,
       linkTarget,
       // ADR-0008 §7.1 additions: a string source (UI maps "vendored"/"local"),
+      // a human origin label (the real upstream, NOT a hard-coded channel),
       // stat timestamps, and the count of clean deployment sites.
       source: s.source ? "vendored" : "local",
+      origin: originLabel(s.source),
+      channel: s.source ? s.source.channel : null,
       modifiedAt,
       createdAt,
       deployCount: deployCounts.get(s.name) ?? 0,
@@ -103,6 +106,20 @@ function toJson(
   });
 }
 
+/**
+ * Short, human display of a vendored skill's real upstream origin, e.g.
+ * "jimliu/baoyu-skills" from "github:jimliu/baoyu-skills@skills/baoyu-translate".
+ * Null for hand-written (local) skills. Replaces the UI's old hard-coded
+ * "dbskill" label so the table tells the truth about where a skill came from.
+ */
+function originLabel(prov: Provenance | null): string | null {
+  if (!prov) return null;
+  const stripped = prov.source.replace(/@.*$/, ""); // drop @subpath
+  const colon = stripped.indexOf(":");
+  const repo = colon >= 0 ? stripped.slice(colon + 1) : stripped; // drop channel:
+  return repo || prov.channel || "vendored";
+}
+
 /** Count clean (`linked`) deployment sites per skill across all surfaces. */
 async function deployCountsFor(ctx: Ctx, lib: Skill[]): Promise<Map<string, number>> {
   const counts = new Map<string, number>();