@danieljvdm/dev-kit 0.4.0 → 0.5.0

package/src/package-skill-source.ts

@@ -0,0 +1,272 @@
+import { Effect, FileSystem, Path, Result, Schema } from "effect";
+
+import { observeSymbolicLink } from "./node-symbolic-link.ts";
+import { isSkillName, parseSkillSelector } from "./skill-selector.ts";
+import { isTypeScriptPackageName } from "./typescript-package-name.ts";
+
+export class PackageSkillSourceError extends Schema.TaggedErrorClass<PackageSkillSourceError>()(
+  "PackageSkillSourceError",
+  { message: Schema.String },
+) {}
+
+export type PackageSkillDiagnostic = {
+  readonly package: string;
+  readonly message: string;
+};
+
+export type DiscoveredPackageSkill = {
+  readonly selector: string;
+  readonly name: string;
+  readonly description: string;
+  readonly package: string;
+  readonly version: string;
+  readonly path: string;
+  readonly linkPath: string;
+};
+
+const ProjectPackageSchema = Schema.fromJsonString(Schema.Struct({
+  dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  optionalDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  peerDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+}));
+
+const PackageMetadataSchema = Schema.fromJsonString(Schema.Struct({
+  name: Schema.String,
+  version: Schema.String,
+  intent: Schema.optional(Schema.Unknown),
+  repository: Schema.optional(Schema.Unknown),
+}));
+
+const nonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
+const hasIntentDiscoveryMetadata = (metadata: typeof PackageMetadataSchema.Type): boolean => {
+  const intent = metadata.intent;
+  if (typeof intent === "object" && intent !== null &&
+    "version" in intent && intent.version === 1 &&
+    "repo" in intent && nonEmptyString(intent.repo) &&
+    "docs" in intent && nonEmptyString(intent.docs)) {
+    return true;
+  }
+  const repository = metadata.repository;
+  return nonEmptyString(repository) ||
+    (typeof repository === "object" && repository !== null &&
+      "url" in repository && nonEmptyString(repository.url));
+};
+
+const isSafePackageVersion = (value: string): boolean =>
+  value.length > 0 && value.trim() === value && ![...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 32 || (code >= 127 && code <= 159);
+  });
+
+const isContained = (path: Path.Path, root: string, candidate: string): boolean => {
+  const relative = path.relative(root, candidate);
+  return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+
+const frontmatterScalar = (document: string, key: string): string | undefined => {
+  const body = document.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+  if (body === undefined) return undefined;
+  const lines = body.split(/\r?\n/);
+  const index = lines.findIndex((line) => line.startsWith(`${key}:`));
+  if (index < 0) return undefined;
+  const raw = lines[index]?.slice(key.length + 1).trim() ?? "";
+  const block = raw.match(/^([|>])(?:[1-9][+-]?|[+-][1-9]?)?$/)?.[1];
+  if (block !== undefined) {
+    const values: Array<string> = [];
+    for (const line of lines.slice(index + 1)) {
+      if (line.length > 0 && !/^\s/.test(line)) break;
+      values.push(line.trim());
+    }
+    const value = block === "|" ? values.join("\n").trim() : values.join(" ").trim();
+    return value.length > 0 ? value : undefined;
+  }
+  const quoted = raw.match(/^(['"])([\s\S]*?)\1(?:\s+#.*)?$/)?.[2];
+  const value = (quoted ?? raw.replace(/\s+#.*$/, "")).trim();
+  return value.length > 0 ? value : undefined;
+};
+
+const skillName = (document: string): string | undefined =>
+  frontmatterScalar(document, "name");
+
+const skillDescription = (document: string): string | undefined =>
+  frontmatterScalar(document, "description");
+
+const rejectNestedSymlinks = Effect.fn("rejectPackageSkillSymlinks")(function* (skillRoot: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const pending = [skillRoot];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === undefined) continue;
+    if ((yield* observeSymbolicLink(current)).kind === "symlink") {
+      return yield* new PackageSkillSourceError({ message: `package skill contains a symlink: ${current}` });
+    }
+    const info = yield* fs.stat(current).pipe(
+      Effect.mapError(() => new PackageSkillSourceError({ message: `could not inspect package skill: ${current}` })),
+    );
+    if (info.type !== "Directory") continue;
+    for (const entry of yield* fs.readDirectory(current).pipe(
+      Effect.mapError(() => new PackageSkillSourceError({ message: `could not read package skill: ${current}` })),
+    )) pending.push(path.join(current, entry));
+  }
+});
+
+const readDirectDependencyNames = Effect.fn("readDirectPackageSkillDependencyNames")(function* (projectDir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const manifestPath = path.join(projectDir, "package.json");
+  const manifest = yield* fs.readFileString(manifestPath).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(ProjectPackageSchema)),
+    Effect.mapError(() => new PackageSkillSourceError({ message: `invalid project package.json: ${manifestPath}` })),
+  );
+  return [...new Set([
+    ...Object.keys(manifest.dependencies ?? {}),
+    ...Object.keys(manifest.devDependencies ?? {}),
+    ...Object.keys(manifest.optionalDependencies ?? {}),
+    ...Object.keys(manifest.peerDependencies ?? {}),
+  ])].sort();
+});
+
+type InstalledPackageSkills = {
+  readonly package: string;
+  readonly version: string;
+  readonly packageLink: string;
+  readonly skillsRoot: string;
+  readonly names: ReadonlyArray<string>;
+};
+
+const loadInstalledPackageSkills = Effect.fn("loadInstalledPackageSkills")(function* (
+  projectDir: string,
+  packageName: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const packageLink = path.join(projectDir, "node_modules", ...packageName.split("/"));
+  const packageRoot = yield* fs.realPath(packageLink).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill package is not installed: ${packageName}` })),
+  );
+  const packageInfo = yield* fs.stat(packageRoot).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `could not inspect package skill package: ${packageName}` })),
+  );
+  if (packageInfo.type !== "Directory") return yield* new PackageSkillSourceError({ message: `package skill package is not a directory: ${packageName}` });
+  const metadata = yield* fs.readFileString(path.join(packageRoot, "package.json")).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(PackageMetadataSchema)),
+    Effect.mapError(() => new PackageSkillSourceError({ message: `invalid package.json for package skill package: ${packageName}` })),
+  );
+  if (metadata.name !== packageName) return yield* new PackageSkillSourceError({ message: `package.json name does not match package skill package: ${packageName}` });
+  if (!isSafePackageVersion(metadata.version)) return yield* new PackageSkillSourceError({ message: `package.json has an invalid version for package skill package: ${packageName}` });
+  if (!hasIntentDiscoveryMetadata(metadata)) return yield* new PackageSkillSourceError({ message: `package does not declare Intent-compatible discovery metadata: ${packageName}` });
+  const skillsPath = "skills";
+  const skillsLink = path.join(packageLink, skillsPath);
+  if ((yield* observeSymbolicLink(skillsLink)).kind === "symlink") return yield* new PackageSkillSourceError({ message: `package skills path is a symlink: ${packageName}/${skillsPath}` });
+  const skillsRoot = yield* fs.realPath(skillsLink).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill package has no skills directory: ${packageName}` })),
+  );
+  if (!isContained(path, packageRoot, skillsRoot)) return yield* new PackageSkillSourceError({ message: `package skills path resolves outside package root: ${packageName}/${skillsPath}` });
+  const skillsInfo = yield* fs.stat(skillsRoot);
+  if (skillsInfo.type !== "Directory") return yield* new PackageSkillSourceError({ message: `package skills path is not a directory: ${packageName}/${skillsPath}` });
+  const names = (yield* fs.readDirectory(skillsRoot).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({
+      message: `package skill package has no readable skills directory: ${packageName}`,
+    })),
+  )).filter(isSkillName).sort();
+  return {
+    package: packageName,
+    version: metadata.version,
+    packageLink,
+    skillsRoot,
+    names,
+  } satisfies InstalledPackageSkills;
+});
+
+const inspectPackageSkill = Effect.fn("inspectInstalledPackageSkill")(function* (
+  installed: InstalledPackageSkills,
+  name: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  if (!isSkillName(name)) {
+    return yield* new PackageSkillSourceError({ message: `invalid package skill name: ${name}` });
+  }
+  const selector = `${installed.package}#${name}`;
+  const linkPath = path.join(installed.packageLink, "skills", name);
+  if ((yield* observeSymbolicLink(linkPath)).kind === "symlink") {
+    return yield* new PackageSkillSourceError({ message: `package skill contains a symlink: ${selector}` });
+  }
+  const skillRoot = yield* fs.realPath(linkPath).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill does not exist: ${selector}` })),
+  );
+  if (!isContained(path, installed.skillsRoot, skillRoot) ||
+    (yield* fs.stat(skillRoot)).type !== "Directory") {
+    return yield* new PackageSkillSourceError({ message: `package skill is not a contained directory: ${selector}` });
+  }
+  yield* rejectNestedSymlinks(skillRoot);
+  const document = yield* fs.readFileString(path.join(skillRoot, "SKILL.md")).pipe(
+    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill is missing SKILL.md: ${selector}` })),
+  );
+  if (skillName(document) !== name) {
+    return yield* new PackageSkillSourceError({
+      message: `package skill SKILL.md name must match directory: ${selector}`,
+    });
+  }
+  const description = skillDescription(document);
+  if (description === undefined) {
+    return yield* new PackageSkillSourceError({
+      message: `package skill SKILL.md must declare a description: ${selector}`,
+    });
+  }
+  return {
+    selector,
+    name,
+    description,
+    package: installed.package,
+    version: installed.version,
+    path: skillRoot,
+    linkPath,
+  } satisfies DiscoveredPackageSkill;
+});
+
+/** Read direct project dependencies only; malformed packages are returned as diagnostics, never executed. */
+export const discoverPackageSkills = Effect.fn("discoverInstalledPackageSkills")(function* (projectDir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const candidates: Array<DiscoveredPackageSkill> = [];
+  const diagnostics: Array<PackageSkillDiagnostic> = [];
+  if (!(yield* fs.exists(path.join(projectDir, "package.json")))) {
+    return { candidates, diagnostics };
+  }
+  for (const packageName of yield* readDirectDependencyNames(projectDir)) {
+    if (!isTypeScriptPackageName(packageName)) {
+      diagnostics.push({ package: packageName, message: `invalid direct dependency package name: ${packageName}` });
+      continue;
+    }
+    const skillsLink = path.join(projectDir, "node_modules", ...packageName.split("/"), "skills");
+    if (!(yield* fs.exists(skillsLink))) continue;
+    const installed = yield* Effect.result(loadInstalledPackageSkills(projectDir, packageName));
+    if (Result.isFailure(installed)) {
+      diagnostics.push({ package: packageName, message: installed.failure.message });
+      continue;
+    }
+    for (const name of installed.success.names) {
+      const inspected = yield* Effect.result(inspectPackageSkill(installed.success, name));
+      if (Result.isSuccess(inspected)) candidates.push(inspected.success);
+      else diagnostics.push({ package: packageName, message: inspected.failure.message });
+    }
+  }
+  return { candidates: candidates.sort((left, right) => left.selector.localeCompare(right.selector)), diagnostics };
+});
+
+/** Resolve one explicitly selected package skill. Unlike browsing, every malformed or missing part is an error. */
+export const resolvePackageSkillSelector = Effect.fn("resolvePackageSkillSelector")(function* (projectDir: string, selector: string) {
+  const parsed = parseSkillSelector(selector);
+  if (parsed?.type !== "package") return yield* new PackageSkillSourceError({ message: `invalid package skill selector: ${selector}` });
+  const directDependencies = yield* readDirectDependencyNames(projectDir);
+  if (!directDependencies.includes(parsed.package)) return yield* new PackageSkillSourceError({ message: `package skill package is not a direct dependency: ${parsed.package}` });
+  return yield* inspectPackageSkill(
+    yield* loadInstalledPackageSkills(projectDir, parsed.package),
+    parsed.skill,
+  );
+});

package/src/project-state.ts

@@ -2,6 +2,21 @@ import { Schema } from "effect";
 
 import { DigestSchema } from "./path-digest.ts";
 
+export const CatalogProvenanceSchema = Schema.Union([
+  Schema.Struct({
+    source: Schema.String,
+    repository: Schema.String,
+    resolved: Schema.String,
+  }),
+  Schema.Struct({
+    package: Schema.String,
+    version: Schema.String,
+    skill: Schema.String,
+    digest: DigestSchema,
+  }),
+]);
+export type CatalogProvenance = typeof CatalogProvenanceSchema.Type;
+
 export const ManagedSkillOutputSchema = Schema.Struct({
   resourceId: Schema.String,
   path: Schema.String,
@@ -10,16 +25,26 @@ export const ManagedSkillOutputSchema = Schema.Struct({
   mode: Schema.Literals(["copy", "symlink"]),
   kind: Schema.Literals(["directory", "symlink"]),
   digest: DigestSchema,
-  catalog: Schema.optional(
-    Schema.Struct({
-      source: Schema.String,
-      repository: Schema.String,
-      resolved: Schema.String,
-    }),
-  ),
+  catalog: Schema.optional(CatalogProvenanceSchema),
 });
 export type ManagedSkillOutput = typeof ManagedSkillOutputSchema.Type;
 
+export const ManagedInstructionOutputSchema = Schema.Struct({
+  resourceId: Schema.Literal("setup:claude-instructions"),
+  path: Schema.String,
+  sourcePath: Schema.String,
+  mode: Schema.Literal("symlink"),
+  kind: Schema.Literal("symlink"),
+  digest: DigestSchema,
+});
+export type ManagedInstructionOutput = typeof ManagedInstructionOutputSchema.Type;
+
+export const ManagedOutputSchema = Schema.Union([
+  ManagedSkillOutputSchema,
+  ManagedInstructionOutputSchema,
+]);
+export type ManagedOutput = typeof ManagedOutputSchema.Type;
+
 export const EffectTsgoLockSchema = Schema.Struct({
   effectTsgoVersion: Schema.String,
   typescriptPackage: Schema.String,
@@ -46,7 +71,7 @@ export const DevKitLockSchema = Schema.Struct({
       effectTsgo: Schema.optional(EffectTsgoLockSchema),
     }),
   ),
-  outputs: Schema.Array(ManagedSkillOutputSchema),
+  outputs: Schema.Array(ManagedOutputSchema),
 });
 export type DevKitLock = typeof DevKitLockSchema.Type;
 

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