@danieljvdm/dev-kit 0.3.3 → 0.5.0

package/src/skill-manager.ts

@@ -188,8 +188,14 @@ const selectedNames = (
   return selected;
 };
 
-const summary = (description: string, fallback: string): string => {
-  const text = description || fallback;
+const displayValue = (value: string): string =>
+  [...value].map((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 31 || (code >= 127 && code <= 159) ? " " : character;
+  }).join("").replace(/\s+/g, " ").trim();
+
+const summary = (description: string, defaultDescription: string): string => {
+  const text = displayValue(description || defaultDescription);
   const firstSentence = text.match(/^.*?[.!?](?:\s|$)/)?.[0]?.trim() ?? text;
   return firstSentence.length > 96 ? `${firstSentence.slice(0, 93).trimEnd()}…` : firstSentence;
 };
@@ -219,15 +225,16 @@ export const addSkills = Effect.fn("addManagedSkills")(function* (
   options: ManagerOptions,
 ) {
   const current = yield* readManifest(options, true);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
-  const known = new Set([...catalog.skills.map((skill) => skill.name), ...Object.keys(catalog.families)]);
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), current.projectDir);
+  const known = new Set([...catalog.skills.map((skill) => skill.selector), ...Object.keys(catalog.families)]);
   const unknown = names.filter((name) => !known.has(name));
   if (unknown.length > 0) {
     return yield* new SkillManagerError({
       message: `unknown skill${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}. Try \`dev-kit search ${unknown[0]}\`.`,
     });
   }
-  for (const source of catalog.lock?.sources ?? []) {
+  const sourceFamilies = catalog.lock?.sources ?? [];
+  for (const source of sourceFamilies) {
     if (!names.includes(source.id)) continue;
     yield* printStatus(
       "info",
@@ -255,7 +262,7 @@ export const removeSkills = Effect.fn("removeManagedSkills")(function* (
   options: ManagerOptions,
 ) {
   const current = yield* readManifest(options);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), current.projectDir);
   const before = selectedNames(
     current.manifest.include,
     current.manifest.exclude ?? [],
@@ -287,43 +294,63 @@ export const listSkills = Effect.fn("listManagedSkills")(function* (
 ) {
   const fs = yield* FileSystem.FileSystem;
   const paths = yield* resolvePaths(options);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), paths.projectDir);
   const manifest = (yield* fs.exists(paths.manifestPath))
     ? (yield* readManifest(options)).manifest
     : { include: [], exclude: [] };
   const selected = selectedNames(manifest.include, manifest.exclude ?? [], catalog.families);
   const query = options.query?.toLowerCase();
   const visible = catalog.skills.filter((skill) =>
-    (options.all || selected.has(skill.name)) &&
-    (!query || `${skill.name} ${skill.description} ${skill.source}`.toLowerCase().includes(query)),
+    (options.all || selected.has(skill.selector)) &&
+    (!query || `${skill.selector} ${skill.description} ${skill.source}`.toLowerCase().includes(query)),
+  );
+  const catalogSelectors = new Set(catalog.skills.map((skill) => skill.selector));
+  const unavailable = [...selected].filter((selector) =>
+    !catalogSelectors.has(selector) && (!query || selector.toLowerCase().includes(query))
   );
-  if (visible.length === 0) {
+  if (visible.length === 0 && unavailable.length === 0) {
     yield* printStatus("info", query ? "No matching skills" : "No skills selected");
     if (!query && !options.all) yield* printDetail("Browse with: dev-kit list --all");
     return;
   }
   for (const skill of visible) {
-    const marker = selected.has(skill.name) ? "✓" : " ";
+    const marker = selected.has(skill.selector) ? "✓" : " ";
     const origin = skill.bundled ? "built in" : skill.source;
-    const provenance = skill.bundled ? "" : ` [${skill.source}]`;
-    yield* printLine(`${marker} ${skill.name}${provenance}  ${summary(skill.description, origin)}`);
+    const provenance = skill.package
+      ? ` [installed ${displayValue(skill.package.version)}]`
+      : skill.bundled ? "" : ` [${skill.source}]`;
+    yield* printLine(`${marker} ${skill.selector}${provenance}  ${summary(skill.description, origin)}`);
+  }
+  for (const selector of unavailable) {
+    yield* printLine(`! ${selector} [unavailable]  install or repair the selected direct dependency`);
   }
   yield* printLine();
-  yield* printLine(`${selected.size} selected · ${catalog.skills.length} approved`);
+  yield* printLine(`${selected.size} selected · ${catalog.skills.length} available`);
 });
 
-export const showSkill = Effect.fn("showCatalogSkill")(function* (name: string) {
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
-  const skill = catalog.skills.find((candidate) => candidate.name === name);
+export const showSkill = Effect.fn("showCatalogSkill")(function* (
+  name: string,
+  options: ManagerOptions,
+) {
+  const paths = yield* resolvePaths(options);
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), paths.projectDir);
+  const skill = catalog.skills.find((candidate) => candidate.selector === name);
   if (!skill) return yield* new SkillManagerError({ message: `unknown skill: ${name}` });
-  yield* printLine(skill.name);
-  if (skill.description) yield* printLine(skill.description);
+  yield* printLine(skill.selector);
+  if (skill.description) yield* printLine(displayValue(skill.description));
+  if (skill.package) {
+    yield* printLine(`Source: installed package`);
+    yield* printLine(`Package: ${skill.package.name}`);
+    yield* printLine(`Version: ${displayValue(skill.package.version)}`);
+    return;
+  }
   yield* printLine(`Source: ${skill.bundled ? "dev-kit (built in)" : skill.source}`);
   if (!skill.bundled) {
     const source = catalog.lock?.sources.find((candidate) => candidate.id === skill.source);
     if (source) {
       yield* printLine(`Repository: ${source.repository}`);
       yield* printLine(`Approved commit: ${source.resolved}`);
+      return;
     }
   }
 });
@@ -345,22 +372,22 @@ export const chooseSkillsToAdd = Effect.fn("chooseSkillsToAdd")(function* (
     return yield* new SkillManagerError({ message: "pass one or more skill names, or run this command in a terminal" });
   }
   const current = yield* readManifest(options, true);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), current.projectDir);
   const selected = selectedNames(
     current.manifest.include,
     current.manifest.exclude ?? [],
     catalog.families,
   );
-  const available = catalog.skills.filter((skill) => !selected.has(skill.name));
+  const available = catalog.skills.filter((skill) => !selected.has(skill.selector));
   if (available.length === 0) {
-    yield* printStatus("success", "All approved skills are selected");
+    yield* printStatus("success", "All available skills are selected");
     return;
   }
   const names = yield* Prompt.multiSelect({
     message: "Choose skills to add",
     choices: available.map((skill) => ({
-      title: skill.name,
-      value: skill.name,
+      title: skill.selector,
+      value: skill.selector,
       description: summary(skill.description, skill.source),
     })),
     min: 1,
@@ -375,7 +402,7 @@ export const chooseSkillsToRemove = Effect.fn("chooseSkillsToRemove")(function*
     return yield* new SkillManagerError({ message: "pass one or more skill names, or run this command in a terminal" });
   }
   const current = yield* readManifest(options);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), current.projectDir);
   const selected = selectedNames(
     current.manifest.include,
     current.manifest.exclude ?? [],
@@ -387,11 +414,20 @@ export const chooseSkillsToRemove = Effect.fn("chooseSkillsToRemove")(function*
   }
   const names = yield* Prompt.multiSelect({
     message: "Choose skills to remove",
-    choices: catalog.skills.filter((skill) => selected.has(skill.name)).map((skill) => ({
-      title: skill.name,
-      value: skill.name,
-      description: summary(skill.description, skill.source),
-    })),
+    choices: [
+      ...catalog.skills.filter((skill) => selected.has(skill.selector)).map((skill) => ({
+        title: skill.selector,
+        value: skill.selector,
+        description: summary(skill.description, skill.source),
+      })),
+      ...[...selected]
+        .filter((selector) => !catalog.skills.some((skill) => skill.selector === selector))
+        .map((selector) => ({
+          title: selector,
+          value: selector,
+          description: "Selected but currently unavailable",
+        })),
+    ],
     min: 1,
   });
   yield* removeSkills(names, options);

package/src/skill-selector.ts

@@ -0,0 +1,43 @@
+import { isTypeScriptPackageName } from "./typescript-package-name.ts";
+
+/** An immediate Agent Skill directory name. */
+export const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+const PACKAGE_SKILL_SELECTOR_PATTERN = /^(?<package>[^#]+)#(?<skill>[^#]+)$/;
+
+type StaticSkillSelector = {
+  readonly type: "static";
+  readonly name: string;
+};
+
+type PackageSkillSelector = {
+  readonly type: "package";
+  readonly package: string;
+  readonly skill: string;
+};
+
+type SkillSelector = StaticSkillSelector | PackageSkillSelector;
+
+/**
+ * The JSON-schema-compatible pattern for static selectors and exact package
+ * selectors. Package names intentionally use the same rules as package-backed
+ * skill sources.
+ */
+export const SKILL_SELECTOR_PATTERN =
+  /^(?:[a-z0-9]+(?:-[a-z0-9]+)*|(?:[a-z0-9][a-z0-9._-]*|@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*)#[a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+export const isSkillName = (value: string): boolean => SKILL_NAME_PATTERN.test(value);
+
+/** Parse an exact, canonical manifest skill selector. */
+export const parseSkillSelector = (value: string): SkillSelector | undefined => {
+  if (isSkillName(value)) return { type: "static", name: value };
+
+  const match = PACKAGE_SKILL_SELECTOR_PATTERN.exec(value);
+  const packageName = match?.groups?.package;
+  const skill = match?.groups?.skill;
+  if (packageName === undefined || skill === undefined ||
+    !isTypeScriptPackageName(packageName) || !isSkillName(skill)) {
+    return undefined;
+  }
+  return { type: "package", package: packageName, skill };
+};

package/src/sync.ts

@@ -3,7 +3,12 @@ import { Cause, Effect, FileSystem, Path, Schema, Stream } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 
 import { DevKitManifestSchema, normalizeManifest } from "./manifest.ts";
-import { loadSkillCatalog, resolveSkillSources, type ResolvedSkillSource } from "./catalog.ts";
+import {
+  loadSkillCatalog,
+  resolveSkillSources,
+  type CatalogSkill,
+  type ResolvedSkillSource,
+} from "./catalog.ts";
 import { printDetail, printStatus, withSpinner } from "./cli-ui.ts";
 import {
   applyEffectSourcePlan,
@@ -21,11 +26,15 @@ import {
   observePath,
   type ObservedPath,
 } from "./path-digest.ts";
+import { resolvePackageSkillSelector } from "./package-skill-source.ts";
+import { parseSkillSelector } from "./skill-selector.ts";
 import {
   AppliedStateSchema,
   DevKitLockSchema,
   type AppliedState,
   type DevKitLock,
+  type ManagedInstructionOutput,
+  type ManagedOutput,
   type ManagedSkillOutput,
   type OwnershipReceipt,
 } from "./project-state.ts";
@@ -67,10 +76,17 @@ type DesiredSkillOutput =
       readonly linkTarget: string;
     });
 
+type DesiredInstructionOutput = ManagedInstructionOutput & {
+  readonly destination: string;
+  readonly linkTarget: string;
+};
+
+type DesiredOutput = DesiredSkillOutput | DesiredInstructionOutput;
+
 type SkillPlanAction =
   | {
       readonly action: "create" | "update";
-      readonly desired: DesiredSkillOutput;
+      readonly desired: DesiredOutput;
       readonly observed: ObservedPath;
     }
   | {
@@ -81,7 +97,7 @@ type SkillPlanAction =
     }
   | {
       readonly action: "unchanged";
-      readonly desired: DesiredSkillOutput;
+      readonly desired: DesiredOutput;
       readonly observed: ObservedPath;
       readonly adopted: boolean;
     }
@@ -263,7 +279,7 @@ const expandSelection = (
   for (const name of include) {
     if (skillFamilies[name]) {
       for (const skill of skillFamilies[name]) selected.add(skill);
-    } else if (availableSkills.includes(name)) {
+    } else if (availableSkills.includes(name) || parseSkillSelector(name)?.type === "package") {
       selected.add(name);
     } else {
       return Effect.fail(new UnknownSkillOrFamilyError({ name, known }));
@@ -315,7 +331,7 @@ const pathsOverlap = (left: string, right: string): boolean =>
 const validateReservedPaths = Effect.fn("validateReservedPaths")(function* (
   projectDir: string,
   reserved: ReadonlyArray<{ readonly label: string; readonly path: string }>,
-  outputs: ReadonlyArray<Pick<ManagedSkillOutput | OwnershipReceipt, "path">>,
+  outputs: ReadonlyArray<Pick<ManagedOutput | OwnershipReceipt, "path">>,
 ) {
   const outputPaths = new Set<string>();
   for (const output of outputs) {
@@ -342,19 +358,21 @@ const validateReservedPaths = Effect.fn("validateReservedPaths")(function* (
   }
 });
 
-const outputIdentity = (output: Pick<ManagedSkillOutput, "resourceId" | "path" | "mode" | "kind" | "digest" | "catalog">) =>
+const outputIdentity = (output: ManagedOutput) =>
   JSON.stringify({
     resourceId: output.resourceId,
     path: output.path,
     mode: output.mode,
     kind: output.kind,
     digest: output.digest,
-    catalog: output.catalog,
+    ...("skill" in output
+      ? { skill: output.skill, target: output.target, catalog: output.catalog }
+      : { sourcePath: output.sourcePath }),
   });
 
 const validateInventory = Effect.fn("validateManagedInventory")(function* (
   projectDir: string,
-  outputs: ReadonlyArray<ManagedSkillOutput | OwnershipReceipt>,
+  outputs: ReadonlyArray<ManagedOutput | OwnershipReceipt>,
   label: string,
 ) {
   const ids = new Set<string>();
@@ -384,7 +402,7 @@ const validateInventory = Effect.fn("validateManagedInventory")(function* (
 
 const validateCrossInventoryPaths = Effect.fn("validateCrossInventoryPaths")(function* (
   projectDir: string,
-  outputs: ReadonlyArray<Pick<ManagedSkillOutput | OwnershipReceipt, "path">>,
+  outputs: ReadonlyArray<Pick<ManagedOutput | OwnershipReceipt, "path">>,
 ) {
   const uniquePaths = new Set<string>();
   for (const output of outputs) {
@@ -406,16 +424,49 @@ const validateCrossInventoryPaths = Effect.fn("validateCrossInventoryPaths")(fun
 const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
   projectDir: string,
   sourceBySkill: ReadonlyMap<string, ResolvedSkillSource>,
-  skills: ReadonlyArray<string>,
+  skills: ReadonlyArray<CatalogSkill>,
+  setup: ReturnType<typeof normalizeManifest>["setup"],
   targets: ReturnType<typeof normalizeManifest>["targets"],
 ) {
   const path = yield* Path.Path;
-  const outputs: Array<DesiredSkillOutput> = [];
+  const outputs: Array<DesiredOutput> = [];
+  if (setup.claudeInstructions.enabled) {
+    const source = yield* resolveManagedPath(projectDir, "AGENTS.md");
+    const sourceObservation = yield* observePath(source.absolute);
+    if (sourceObservation.kind !== "file") {
+      return yield* new InvalidProjectStateError({
+        message: "Claude instructions source is not a regular file: AGENTS.md",
+      });
+    }
+    const managed = yield* resolveManagedPath(projectDir, "CLAUDE.md");
+    const linkTarget = path.relative(path.dirname(managed.absolute), source.absolute);
+    outputs.push({
+      resourceId: "setup:claude-instructions",
+      path: managed.relative,
+      sourcePath: source.relative,
+      mode: "symlink",
+      kind: "symlink",
+      digest: yield* digestSymlinkTarget(linkTarget),
+      destination: managed.absolute,
+      linkTarget,
+    });
+  }
   const agentsTarget = targets.agents;
+  const duplicateOutput = skills.find((skill, index) =>
+    skills.findIndex((candidate) => candidate.name === skill.name) !== index
+  );
+  if (duplicateOutput !== undefined) {
+    const selectors = skills
+      .filter((skill) => skill.name === duplicateOutput.name)
+      .map((skill) => skill.selector);
+    return yield* new InvalidProjectStateError({
+      message: `selected skills would both install as ${duplicateOutput.name}: ${selectors.join(", ")}`,
+    });
+  }
   for (const skill of skills) {
-    const resolvedSource = sourceBySkill.get(skill);
+    const resolvedSource = sourceBySkill.get(skill.selector);
     if (resolvedSource === undefined) {
-      return yield* new InvalidProjectStateError({ message: `skill source is unavailable: ${skill}` });
+      return yield* new InvalidProjectStateError({ message: `skill source is unavailable: ${skill.selector}` });
     }
     const source = resolvedSource.path;
     const sourceObservation = yield* observePath(source);
@@ -425,12 +476,12 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
     for (const targetName of ["agents", "claude", "opencode"] as const) {
       const target = targets[targetName];
       if (!target.enabled) continue;
-      const managed = yield* resolveManagedPath(projectDir, path.join(target.path, skill));
+      const managed = yield* resolveManagedPath(projectDir, path.join(target.path, skill.name));
       if (target.mode === "copy") {
         outputs.push({
-          resourceId: `skill:${skill}@${targetName}`,
+          resourceId: `skill:${skill.selector}@${targetName}`,
           path: managed.relative,
-          skill,
+          skill: skill.name,
           target: targetName,
           mode: "copy",
           kind: "directory",
@@ -443,14 +494,14 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       }
       const linkSource =
         targetName === "agents" || !agentsTarget.enabled
-          ? source
-          : (yield* resolveManagedPath(projectDir, path.join(agentsTarget.path, skill))).absolute;
+          ? resolvedSource.linkPath ?? source
+          : (yield* resolveManagedPath(projectDir, path.join(agentsTarget.path, skill.name))).absolute;
       const linkTarget = path.relative(path.dirname(managed.absolute), linkSource);
       const linkDigest = yield* digestSymlinkTarget(linkTarget);
       outputs.push({
-        resourceId: `skill:${skill}@${targetName}`,
+        resourceId: `skill:${skill.selector}@${targetName}`,
         path: managed.relative,
-        skill,
+        skill: skill.name,
         target: targetName,
         mode: "symlink",
         kind: "symlink",
@@ -471,7 +522,7 @@ const canonicalState = (state: AppliedState): string => `${JSON.stringify(state,
 
 const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
   projectDir: string,
-  desired: ReadonlyArray<DesiredSkillOutput>,
+  desired: ReadonlyArray<DesiredOutput>,
   currentLock: DevKitLock | undefined,
   currentState: AppliedState | undefined,
   nextLock: DevKitLock,
@@ -587,8 +638,8 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
         typescriptPackage: manifest.setup.effectTsgo.typescriptPackage,
       })
     : undefined;
-  const catalog = yield* loadSkillCatalog(packageRoot);
-  const availableSkills = catalog.skills.map((skill) => skill.name);
+  const catalog = yield* loadSkillCatalog(packageRoot, projectDir);
+  const availableSkills = catalog.skills.map((skill) => skill.selector);
   const skillFamilies = { ...SKILL_FAMILIES, ...catalog.families };
   for (const [family, familySkills] of Object.entries(skillFamilies)) {
     if (availableSkills.includes(family)) {
@@ -599,12 +650,35 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
       return yield* new InvalidSkillCatalogError({ family, message: `family references missing skills: ${missing.join(", ")}` });
     }
   }
-  const selectedSkills = yield* expandSelection(manifest.include, manifest.exclude, availableSkills, skillFamilies);
+  const selectedSelectors = yield* expandSelection(manifest.include, manifest.exclude, availableSkills, skillFamilies);
+  const catalogBySelector = new Map(catalog.skills.map((skill) => [skill.selector, skill]));
   const sourceBySkill = yield* withSpinner(
-    "Fetching selected skills",
-    resolveSkillSources(packageRoot, projectDir, selectedSkills, options.dryRun !== true),
+    "Resolving selected skills",
+    resolveSkillSources(
+      packageRoot,
+      projectDir,
+      catalog,
+      selectedSelectors,
+      options.dryRun !== true,
+    ),
+  );
+  const selectedSkills: Array<CatalogSkill> = [];
+  for (const selector of selectedSelectors) {
+    const catalogSkill = catalogBySelector.get(selector);
+    if (catalogSkill === undefined) {
+      return yield* new InvalidProjectStateError({
+        message: `selected skill is unavailable: ${selector}`,
+      });
+    }
+    selectedSkills.push(catalogSkill);
+  }
+  const desired = yield* buildDesiredOutputs(
+    projectDir,
+    sourceBySkill,
+    selectedSkills,
+    manifest.setup,
+    manifest.targets,
   );
-  const desired = yield* buildDesiredOutputs(projectDir, sourceBySkill, selectedSkills, manifest.targets);
   const nextLock: DevKitLock = {
     version: 1,
     toolVersion: DEV_KIT_VERSION,
@@ -631,16 +705,27 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
             },
           }),
     },
-    outputs: desired.map(({ resourceId, path: outputPath, skill, target, mode, kind, digest, catalog }) => ({
-      resourceId,
-      path: outputPath,
-      skill,
-      target,
-      mode,
-      kind,
-      digest,
-      ...(catalog ? { catalog } : {}),
-    })),
+    outputs: desired.map((output): ManagedOutput =>
+      "skill" in output
+        ? {
+            resourceId: output.resourceId,
+            path: output.path,
+            skill: output.skill,
+            target: output.target,
+            mode: output.mode,
+            kind: output.kind,
+            digest: output.digest,
+            ...(output.catalog ? { catalog: output.catalog } : {}),
+          }
+        : {
+            resourceId: output.resourceId,
+            path: output.path,
+            sourcePath: output.sourcePath,
+            mode: output.mode,
+            kind: output.kind,
+            digest: output.digest,
+          },
+    ),
   };
   const reservedPaths = [
     { label: "manifest", path: manifestManaged.relative },
@@ -692,7 +777,10 @@ const formatAction = (action: SkillPlanAction): string => {
   const verb = action.desired.mode === "copy" ? "copy" : "link";
   const adoption = action.action === "unchanged" && action.adopted ? " (adopt)" : "";
   const marker = action.action === "create" ? "+" : action.action === "update" ? "~" : "=";
-  return `${marker} ${verb} ${action.desired.skill} → ${action.desired.path}${adoption}`;
+  const source = "skill" in action.desired
+    ? action.desired.skill
+    : action.desired.sourcePath;
+  return `${marker} ${verb} ${source} → ${action.desired.path}${adoption}`;
 };
 
 const operationalChangeCount = (plan: SkillPlan): number =>
@@ -734,6 +822,47 @@ const observationsEqual = (left: ObservedPath, right: ObservedPath): boolean =>
   left.kind === right.kind &&
   (left.kind === "missing" || (right.kind !== "missing" && left.digest === right.digest));
 
+const findNestedSymbolicLink = Effect.fn("findNestedSkillSymbolicLink")(function* (
+  root: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const pending = [root];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === undefined) continue;
+    if ((yield* observeSymbolicLink(current)).kind === "symlink") return current;
+    const info = yield* fs.stat(current);
+    if (info.type !== "Directory") continue;
+    for (const entry of yield* fs.readDirectory(current)) {
+      pending.push(path.join(current, entry));
+    }
+  }
+  return undefined;
+});
+
+const verifyPackageSkillSources = Effect.fn("verifyPackageSkillSources")(function* (
+  plan: SkillPlan,
+) {
+  const verified = new Set<string>();
+  for (const action of plan.actions) {
+    if (action.action === "remove" || action.action === "conflict") continue;
+    if (!("skill" in action.desired)) continue;
+    const catalog = action.desired.catalog;
+    if (catalog === undefined || !("package" in catalog)) continue;
+    const selector = `${catalog.package}#${catalog.skill}`;
+    const key = `${selector}\0${catalog.version}\0${catalog.digest}`;
+    if (verified.has(key)) continue;
+    const resolved = yield* resolvePackageSkillSelector(plan.projectDir, selector);
+    const observation = yield* observePath(resolved.path);
+    if (resolved.path !== action.desired.source || resolved.version !== catalog.version ||
+      observation.kind !== "directory" || observation.digest !== catalog.digest) {
+      return yield* new ApplyRaceError({ path: action.desired.source });
+    }
+    verified.add(key);
+  }
+});
+
 const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function* (plan: SkillPlan) {
   const conflicts = plan.actions.filter((action) => action.action === "conflict");
   if (conflicts.length > 0) {
@@ -770,6 +899,12 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
     yield* fs.makeDirectory(path.dirname(staged), { recursive: true });
     if (action.desired.mode === "copy") {
       yield* fs.copy(action.desired.source, staged, { overwrite: true });
+      const symbolicLink = yield* findNestedSymbolicLink(staged);
+      if (symbolicLink !== undefined) {
+        return yield* new InvalidProjectStateError({
+          message: `staged skill contains a symlink: ${action.desired.path}`,
+        });
+      }
     } else {
       yield* fs.symlink(action.desired.linkTarget, staged);
     }
@@ -780,6 +915,8 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
     stagedByResource.set(action.desired.resourceId, staged);
   }
 
+  yield* verifyPackageSkillSources(plan);
+
   const stagedLock = path.join(tempDir, "next-lock.json");
   const stagedState = path.join(tempDir, "next-state.json");
   yield* fs.writeFileString(stagedLock, canonicalLock(plan.nextLock));