Q34: built-in skill updates reach existing orgs and their bindings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/main/services/agent-skill-tools.ts

@@ -10,7 +10,7 @@ export function listSkillsTool(deps: AgentToolDeps, ctx: AgentToolContext): stri
     select sd.id, sd.name, sd.slug, sr.manifest_json
     from skill_definitions sd
     left join skill_revisions sr on sr.id = (
-      select id from skill_revisions where skill_id = sd.id order by published_at desc, id desc limit 1
+      select id from skill_revisions where skill_id = sd.id order by published_at desc, rowid desc limit 1
     )
     where sd.org_id = ? and sd.status = 'active'
     order by sd.slug asc
@@ -69,7 +69,7 @@ export function grantSkillTool(deps: AgentToolDeps, ctx: AgentToolContext, args:
   const skillService = new SkillService(deps.db, "");
   if (mode === "grant") {
     const revision = deps.db.prepare(
-      "select id from skill_revisions where skill_id = ? order by published_at desc, id desc limit 1",
+      "select id from skill_revisions where skill_id = ? order by published_at desc, rowid desc limit 1",
     ).get(skill.id) as { id: string } | undefined;
     if (!revision) return `ERROR: The "${skillSlug}" skill has no published revision.`;
     skillService.bind({ orgId: ctx.orgId, agentId: target.id, skillId: skill.id, revisionId: revision.id });
@@ -94,7 +94,7 @@ export function bindSkillSlugs(deps: AgentToolDeps, orgId: string, agentId: stri
       select sd.id as skill_id, sd.name, sr.id as revision_id
       from skill_definitions sd
       join skill_revisions sr on sr.id = (
-        select id from skill_revisions where skill_id = sd.id order by published_at desc, id desc limit 1
+        select id from skill_revisions where skill_id = sd.id order by published_at desc, rowid desc limit 1
       )
       where sd.org_id = ? and sd.slug = ? and sd.status = 'active'
     `).get(orgId, slug) as { skill_id: string; name: string; revision_id: string } | undefined;

src/main/services/builtin-skills.ts

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { RISK_LEVEL } from "../../shared/domain";
 import { loadSkillManifest, type SkillManifest } from "./skill-manifest";
@@ -17,7 +17,7 @@ import type { SkillService } from "./skill-service";
  * Staging normalizes both into one library layout the import machinery
  * understands — `<libraryRoot>/<slug>/SKILL.md` — a real copy on disk, never a
  * reference back into the bundle. Import then publishes every staged skill the
- * org does not carry yet into the immutable artifact store.
+ * org does not carry yet, or whose files changed, into the immutable artifact store.
  */
 
 export interface StagedBuiltinSkill {
@@ -28,6 +28,8 @@ export interface StagedBuiltinSkill {
 
 export interface BuiltinSkillSyncReport {
   imported: number;
+  /** Existing skills that got a new revision because the bundle changed them. */
+  upgraded: number;
   skipped: number;
   /** Active skills retired because the bundle no longer carries their slug. */
   retired: number;
@@ -73,17 +75,18 @@ export function stageBuiltinSkillsLibrary(sourceRoot: string, libraryRoot: strin
 
 /**
  * Makes the org catalogue mirror the bundle: publishes every staged skill
- * the org does not carry yet, then retires active skills whose slug the
- * bundle no longer ships (legacy ~/.agents imports, removed skills).
- * Existing bindings pin revisions directly and keep working; retired skills
- * simply leave list_skills and stop being grantable.
+ * the org does not carry yet, upgrades skills whose files changed (moving
+ * bindings onto the new revision), then retires active skills whose slug
+ * the bundle no longer ships. Retired skills leave list_skills and stop
+ * being grantable.
  */
 export function importStagedSkills(skills: SkillService, orgId: string, staged: StagedBuiltinSkill[]): BuiltinSkillSyncReport {
-  const report: BuiltinSkillSyncReport = { imported: 0, skipped: 0, retired: 0, failures: [] };
+  const report: BuiltinSkillSyncReport = { imported: 0, upgraded: 0, skipped: 0, retired: 0, failures: [] };
   for (const unit of staged) {
     try {
       if (skills.hasSkill(orgId, unit.slug)) {
-        report.skipped += 1;
+        if (skills.upgradeIfChanged(orgId, unit.directory, unit.manifest, unit.slug)) report.upgraded += 1;
+        else report.skipped += 1;
         continue;
       }
       skills.importManifest(orgId, unit.directory, unit.manifest, unit.slug);
@@ -99,7 +102,8 @@ export function importStagedSkills(skills: SkillService, orgId: string, staged:
 function stageDirectorySkill(sourceDir: string, dirName: string, libraryRoot: string, seen: Set<string>): StagedBuiltinSkill {
   const slug = uniqueSlug(slugify(dirName), seen, sourceDir);
   const target = join(libraryRoot, slug);
-  mkdirSync(target, { recursive: true });
+  // Clear first so files the bundle dropped do not linger in the library.
+  rmSync(target, { recursive: true, force: true });
   cpSync(sourceDir, target, { recursive: true });
   const manifest = existsSync(join(target, "skill.manifest.json"))
     ? loadSkillManifest(target)
@@ -119,6 +123,7 @@ function stageCategorySkills(categoryDir: string, libraryRoot: string, seen: Set
     const stem = entry.name.replace(/\.md$/i, "");
     const slug = uniqueSlug(slugify(stem), seen, join(categoryDir, entry.name));
     const target = join(libraryRoot, slug);
+    rmSync(target, { recursive: true, force: true });
     mkdirSync(target, { recursive: true });
     writeFileSync(join(target, "SKILL.md"), body, "utf8");
     staged.push({

src/main/services/skill-service.ts

@@ -83,6 +83,39 @@ export class SkillService {
     return retired;
   }
 
+  /** Publishes a new revision when the files changed and moves bindings on the latest revision onto it. */
+  upgradeIfChanged(orgId: string, directoryPath: string, manifest: SkillManifest, slug: string): boolean {
+    const latest = this.db.prepare(`
+      select sr.id, sr.immutable_checksum from skill_definitions sd
+      join skill_revisions sr on sr.skill_id = sd.id
+      where sd.org_id = ? and sd.slug = ?
+      order by sr.published_at desc, sr.rowid desc limit 1
+    `).get(orgId, slug) as { id: string; immutable_checksum: string } | undefined;
+    if (!latest) throw new Error(`Skill "${slug}" has no revision to upgrade.`);
+    const checksum = recursiveSkillChecksum(directoryPath);
+    if (latest.immutable_checksum === checksum) return false;
+    const revisions = this.db.prepare(`
+      select sr.version_semver from skill_revisions sr join skill_definitions sd on sd.id = sr.skill_id
+      where sd.org_id = ? and sd.slug = ?
+    `).all(orgId, slug) as Array<{ version_semver: string }>;
+    // Same declared version, new content: tag the build so revisions stay distinct.
+    const versionTaken = revisions.some((row) => row.version_semver === manifest.version);
+    const published = versionTaken ? { ...manifest, version: `${manifest.version}+rev${revisions.length + 1}` } : manifest;
+    const revisionId = this.importManifest(orgId, directoryPath, published, slug);
+    const moved = this.db.prepare("update skill_bindings set pinned_revision_id = ? where org_id = ? and pinned_revision_id = ?")
+      .run(revisionId, orgId, latest.id);
+    this.audit.record({
+      orgId,
+      entityType: "skill_revision",
+      entityId: revisionId,
+      actorType: "system",
+      actorId: null,
+      action: "upgraded",
+      payload: { slug, fromRevisionId: latest.id, version: published.version, bindingsMoved: Number(moved.changes) },
+    });
+    return true;
+  }
+
   importManifest(orgId: string, directoryPath: string, manifest: SkillManifest, explicitSlug?: string): string {
     const slug = explicitSlug ?? slugify(manifest.name);
     if (!slug) throw new Error("Skill name could not be derived.");
@@ -216,7 +249,7 @@ export class SkillService {
         sa.object_key
       from skill_definitions sd
       join skill_revisions sr on sr.id = (
-        select id from skill_revisions where skill_id = sd.id order by published_at desc, id desc limit 1
+        select id from skill_revisions where skill_id = sd.id order by published_at desc, rowid desc limit 1
       )
       join skill_artifacts sa on sa.revision_id = sr.id and sa.artifact_type in ('entrypoint', 'markdown')
       where sd.org_id = ? and sd.status = 'active' and sd.slug in (${candidates.map(() => "?").join(", ")})