@danieljvdm/dev-kit 0.4.0 → 0.6.0

package/skills/effect-atom-data-fetching/references/tanstack-start.md

@@ -0,0 +1,69 @@
+# TanStack Start integration
+
+TanStack Start code is isomorphic by default, including route loaders. Treat every module used by a route as server-capable unless an explicit boundary says otherwise.
+
+## Choose an SSR strategy
+
+Use one of these models deliberately:
+
+### Client-only atom data
+
+- Put one `RegistryProvider` in the app/root component so client navigations share a registry.
+- Render atom consumers that touch browser-only APIs inside `ClientOnly` from `@tanstack/react-router`.
+- Accept that the fallback is the server-rendered state and fetching begins on the client.
+- Keep the client runtime and API service as module singletons.
+
+```tsx
+import { RegistryProvider } from "@effect/atom-react";
+import { ClientOnly } from "@tanstack/react-router";
+
+export function AppShell() {
+  return (
+    <RegistryProvider defaultIdleTTL={30_000}>
+      <ClientOnly fallback={<DashboardSkeleton />}>
+        <Dashboard />
+      </ClientOnly>
+    </RegistryProvider>
+  );
+}
+```
+
+### SSR plus hydration
+
+- Create the registry and any request-specific runtime/layers per request; never share user/auth state through a process-global registry or memo map.
+- Give decoded query atoms deterministic `serializationKey` values.
+- Mount/run the required serializable atoms on the server, dehydrate only the intended values, and pass them through the document safely.
+- Create the client registry once, then hydrate matching atom identities before descendants consume them. Use `HydrationBoundary` where the installed React adapter supports it.
+- Verify that server and client construct the same API service, family arguments, and serialization keys.
+
+Prefer framework loaders/server functions when they already own SSR data. Do not build a second atom SSR cache merely to mirror loader data; seed atoms from the loader or keep atom fetching client-only.
+
+## Focus is browser-only
+
+`Atom.windowFocusSignal` reads `window` and `document.visibilityState` when mounted. Do not mount it during SSR. Put focus-enabled consumers behind `ClientOnly`, or inject a no-op server signal and the browser signal on the client.
+
+```ts
+const project = projectAtom(projectId).pipe(
+  Atom.swr({
+    staleTime: "30 seconds",
+    revalidateOnFocus: true,
+    focusSignal: Atom.windowFocusSignal,
+  }),
+);
+```
+
+`revalidateOnFocus: true` respects `staleTime`; `"always"` forces a request on every focus signal.
+
+## In-memory limits
+
+Effect Atom's registry cache is in memory and scoped to that registry:
+
+- a new tab, hard reload, server process, or newly created provider starts another cache;
+- idle TTL evicts only unused atoms and is not a maximum-entry or byte-size bound;
+- `keepAlive` and infinite TTL can grow memory with unbounded family keys;
+- browser memory is not durable or shared across users/devices;
+- hydration transfers a snapshot, not a persistent distributed cache.
+
+For large or unbounded parameter spaces, use finite TTLs and avoid `keepAlive`. Put durable/shared caching at the HTTP, server, CDN, or database layer.
+
+Primary TanStack references: [execution model](https://tanstack.com/start/latest/docs/framework/react/guide/execution-model) and [`ClientOnly`](https://tanstack.com/router/latest/docs/api/router/clientOnlyComponent).

package/skills/effect-atom-data-fetching/references/testing.md

@@ -0,0 +1,63 @@
+# Deterministic lifecycle testing
+
+Test cache policy below React first with `AtomRegistry.make()`. Add a React integration test only for provider placement, hook behavior, a browser-only SSR boundary, or hydration.
+
+Use fake timers, a request counter, controllable Effects, and explicit mounts:
+
+```ts
+const registry = AtomRegistry.make({ defaultIdleTTL: 1_000 });
+const unmount = registry.mount(queryAtom);
+const first = registry.get(queryAtom);
+
+// Advance the Effect scheduler/microtasks as required by the installed version.
+// Assert with AsyncResult predicates and request counts.
+
+unmount();
+```
+
+Avoid wall-clock sleeps. Flush Effect work with the repository's established `Effect.yieldNow`/test-clock pattern and advance the test runner's fake timers.
+
+Prefer the installed test APIs over invented helpers or matchers. The upstream Effect tests use `assert(AsyncResult.isSuccess(result))`, `Effect.runPromise(Effect.yieldNow)`, `vitest.advanceTimersByTimeAsync(...)`, and the cleanup returned by `registry.mount(atom)`.
+
+## Required scenarios
+
+### Remount reuse
+
+1. Mount and resolve the query; assert request count `1`.
+2. Unmount, advance less than idle TTL, remount the same atom identity.
+3. Assert the cached success is immediately available and no request occurs while still fresh.
+
+### Stale refresh
+
+1. Resolve once through an SWR wrapper.
+2. Advance past `staleTime` but not idle TTL.
+3. Remount or emit the injected focus signal.
+4. Assert the previous success stays available with `waiting: true`, then a second success arrives and request count becomes `2`.
+5. Also prove a fresh mount/focus does not request.
+
+### TTL eviction
+
+1. Resolve and unmount.
+2. Advance to just before TTL; assert reuse.
+3. Advance to/after TTL and flush disposal; remount.
+4. Assert `Initial`/waiting behavior and a new request.
+
+### Polling cleanup
+
+1. Mount the `Atom.withRefresh` wrapper and resolve once.
+2. Advance one interval; assert one forced refresh.
+3. Unmount and advance several intervals.
+4. Assert the counter does not change. This catches leaked timers or accidental `keepAlive`.
+
+### Mutation invalidation
+
+1. Mount list and detail queries with explicit keys.
+2. Run a successful mutation with matching keys; assert only the intended queries refresh.
+3. Run a failed mutation; assert no invalidation.
+4. Assert cleanup removes invalidation handlers after query disposal.
+
+### Aggregate stability
+
+Mount a route atom that uses `AsyncResult.all`, resolve every input, unmount, and remount inside the retention window. Assert the aggregate never returns to `Initial`. Then let one input expire and prove the aggregate reset is caused by that input, not the retained queries.
+
+For runtime/layer tests, seed `runtime.layer` through `RegistryProvider initialValues` with a deterministic test layer. This replaces network services without changing the production atom graph.

package/src/bin/dev-kit.ts

@@ -57,7 +57,7 @@ const addCommand = CliCommand.make(
     skills.length === 0
       ? chooseSkillsToAdd({ apply: !noApply, manifestPath: manifest, projectDir })
       : addSkills(skills, { apply: !noApply, manifestPath: manifest, projectDir }),
-).pipe(CliCommand.withDescription("Select and install one or more approved skills."));
+).pipe(CliCommand.withDescription("Select and install one or more available skills."));
 
 const removeCommand = CliCommand.make(
   "remove",
@@ -89,13 +89,13 @@ const searchCommand = CliCommand.make(
   { query: Argument.string("query").pipe(Argument.variadic({ min: 1 })), ...projectFlags },
   ({ query, manifest, projectDir }) =>
     listSkills({ all: true, query: query.join(" "), manifestPath: manifest, projectDir }),
-).pipe(CliCommand.withDescription("Search approved skill names and descriptions."));
+).pipe(CliCommand.withDescription("Search available skill names and descriptions."));
 
 const infoCommand = CliCommand.make(
   "info",
-  { skill: Argument.string("skill") },
-  ({ skill }) => showSkill(skill),
-).pipe(CliCommand.withDescription("Show provenance and details for an approved skill."));
+  { skill: Argument.string("skill"), ...projectFlags },
+  ({ skill, manifest, projectDir }) => showSkill(skill, { manifestPath: manifest, projectDir }),
+).pipe(CliCommand.withDescription("Show provenance and details for an available skill."));
 
 const planCommand = CliCommand.make(
   "plan",

package/src/catalog.ts

@@ -2,7 +2,11 @@ import { parse as parseJsonc, type ParseError } from "jsonc-parser";
 import { Effect, FileSystem, Path, Schema, Stream } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 
-import { observePath } from "./path-digest.ts";
+import { observePath, type Digest } from "./path-digest.ts";
+import {
+  discoverPackageSkills,
+  resolvePackageSkillSelector,
+} from "./package-skill-source.ts";
 import {
   SkillSourcesLockSchema,
   type LockedSkillSource,
@@ -11,9 +15,14 @@ import {
 
 export type CatalogSkill = {
   readonly name: string;
+  readonly selector: string;
   readonly description: string;
   readonly source: string;
   readonly bundled: boolean;
+  readonly package?: {
+    readonly name: string;
+    readonly version: string;
+  };
 };
 
 export type SkillCatalog = {
@@ -24,11 +33,19 @@ export type SkillCatalog = {
 
 export type ResolvedSkillSource = {
   readonly path: string;
-  readonly catalog?: {
-    readonly source: string;
-    readonly repository: string;
-    readonly resolved: string;
-  };
+  readonly linkPath?: string;
+  readonly catalog?:
+    | {
+        readonly source: string;
+        readonly repository: string;
+        readonly resolved: string;
+      }
+    | {
+        readonly package: string;
+        readonly version: string;
+        readonly skill: string;
+        readonly digest: Digest;
+      };
 };
 
 class CatalogError extends Schema.TaggedErrorClass<CatalogError>()("CatalogError", {
@@ -87,6 +104,7 @@ const readDescription = Effect.fn("readSkillDescription")(function* (skillPath:
 
 export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
   packageRoot: string,
+  projectDir: string,
 ) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -98,6 +116,7 @@ export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
       if ((yield* fs.exists(path.join(skillPath, "SKILL.md")))) {
         skills.push({
           name,
+          selector: name,
           description: yield* readDescription(skillPath),
           source: "built-in",
           bundled: true,
@@ -110,28 +129,49 @@ export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
     for (const name of source.skills) {
       skills.push({
         name,
+        selector: name,
         description: source.descriptions?.[name] ?? "",
         source: source.id,
         bundled: false,
       });
     }
   }
+  const discovery = yield* discoverPackageSkills(projectDir);
+  for (const candidate of discovery.candidates) {
+    skills.push({
+      name: candidate.name,
+      selector: candidate.selector,
+      description: candidate.description,
+      source: candidate.package,
+      bundled: false,
+      package: { name: candidate.package, version: candidate.version },
+    });
+  }
   const duplicates = skills.filter(
-    (skill, index) => skills.findIndex((candidate) => candidate.name === skill.name) !== index,
+    (skill, index) => skills.findIndex((candidate) => candidate.selector === skill.selector) !== index,
   );
   if (duplicates.length > 0) {
     return yield* new CatalogError({
-      message: `duplicate catalog skill: ${duplicates[0]?.name ?? "unknown"}`,
+      message: `duplicate catalog skill selector: ${duplicates[0]?.selector ?? "unknown"}`,
+    });
+  }
+  const externalFamilies = (lock?.sources ?? []).map((source) =>
+    [source.id, source.skills] as const
+  );
+  const duplicateFamily = externalFamilies.find(
+    ([id], index) => externalFamilies.findIndex(([candidate]) => candidate === id) !== index,
+  );
+  if (duplicateFamily !== undefined) {
+    return yield* new CatalogError({
+      message: `duplicate catalog family: ${duplicateFamily[0]}`,
     });
   }
   const families: Readonly<Record<string, ReadonlyArray<string>>> = {
-    effect: ["effect-ts"],
-    ...Object.fromEntries(
-      (lock?.sources ?? []).map((source) => [source.id, source.skills]),
-    ),
+    effect: ["effect-ts", "effect-atom-data-fetching"],
+    ...Object.fromEntries(externalFamilies),
   };
   return {
-    skills: skills.sort((left, right) => left.name.localeCompare(right.name)),
+    skills: skills.sort((left, right) => left.selector.localeCompare(right.selector)),
     families,
     ...(lock ? { lock } : {}),
   } satisfies SkillCatalog;
@@ -224,15 +264,15 @@ const materializeSource = Effect.fn("materializeCatalogSource")(function* (
 export const resolveSkillSources = Effect.fn("resolveSkillSources")(function* (
   packageRoot: string,
   projectDir: string,
+  catalog: SkillCatalog,
   selected: ReadonlyArray<string>,
   cache = true,
 ) {
   const path = yield* Path.Path;
-  const catalog = yield* loadSkillCatalog(packageRoot);
   const sources = new Map<string, ResolvedSkillSource>();
   for (const skill of catalog.skills.filter((skill) => skill.bundled)) {
-    if (selected.includes(skill.name)) {
-      sources.set(skill.name, { path: path.join(packageRoot, "skills", skill.name) });
+    if (selected.includes(skill.selector)) {
+      sources.set(skill.selector, { path: path.join(packageRoot, "skills", skill.name) });
     }
   }
   for (const source of catalog.lock?.sources ?? []) {
@@ -242,5 +282,22 @@ export const resolveSkillSources = Effect.fn("resolveSkillSources")(function* (
       sources.set(name, sourcePath);
     }
   }
+  for (const selector of selected.filter((value) => value.includes("#"))) {
+    const resolved = yield* resolvePackageSkillSelector(projectDir, selector);
+    const observation = yield* observePath(resolved.path);
+    if (observation.kind !== "directory") {
+      return yield* new CatalogError({ message: `package skill is missing: ${selector}` });
+    }
+    sources.set(selector, {
+      path: resolved.path,
+      linkPath: resolved.linkPath,
+      catalog: {
+        package: resolved.package,
+        version: resolved.version,
+        skill: resolved.name,
+        digest: observation.digest,
+      },
+    });
+  }
   return sources;
 });

package/src/index.ts

@@ -1,4 +1,8 @@
 export {
+  type AgentInstructionsSetup,
+  AgentInstructionsSetupSchema,
+  type ClaudeInstructionsSetup,
+  ClaudeInstructionsSetupSchema,
   type DevKitManifest,
   DevKitManifestSchema,
   type EffectSourceSetup,
@@ -58,15 +62,25 @@ export {
 } from "./sync.ts";
 export {
   AppliedStateSchema,
+  CatalogProvenanceSchema,
   DevKitLockSchema,
   EffectSourceLockSchema,
   EffectTsgoLockSchema,
+  ManagedAgentInstructionsOutputSchema,
+  ManagedClaudeInstructionsOutputSchema,
+  ManagedInstructionOutputSchema,
+  ManagedOutputSchema,
   ManagedSkillOutputSchema,
   OwnershipReceiptSchema,
   type AppliedState,
+  type CatalogProvenance,
   type DevKitLock,
   type EffectSourceLock,
   type EffectTsgoLock,
+  type ManagedAgentInstructionsOutput,
+  type ManagedClaudeInstructionsOutput,
+  type ManagedInstructionOutput,
+  type ManagedOutput,
   type ManagedSkillOutput,
   type OwnershipReceipt,
 } from "./project-state.ts";

package/src/manifest.ts

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 
+import { SKILL_SELECTOR_PATTERN } from "./skill-selector.ts";
 import { TYPESCRIPT_PACKAGE_NAME_PATTERN } from "./typescript-package-name.ts";
 
 export type HarnessTarget = "agents" | "claude" | "opencode";
@@ -36,12 +37,26 @@ export const EffectSourceSetupSchema = Schema.Struct({
 
 export type EffectSourceSetup = typeof EffectSourceSetupSchema.Type;
 
+export const AgentInstructionsSetupSchema = Schema.Struct({
+  enabled: Schema.optional(Schema.Boolean),
+});
+
+export type AgentInstructionsSetup = typeof AgentInstructionsSetupSchema.Type;
+
+export const ClaudeInstructionsSetupSchema = Schema.Struct({
+  enabled: Schema.optional(Schema.Boolean),
+});
+
+export type ClaudeInstructionsSetup = typeof ClaudeInstructionsSetupSchema.Type;
+
 export const DevKitManifestSchema = Schema.Struct({
   $schema: Schema.optional(Schema.String),
-  include: Schema.Array(Schema.String),
-  exclude: Schema.optional(Schema.Array(Schema.String)),
+  include: Schema.Array(Schema.String.check(Schema.isPattern(SKILL_SELECTOR_PATTERN))),
+  exclude: Schema.optional(Schema.Array(Schema.String.check(Schema.isPattern(SKILL_SELECTOR_PATTERN)))),
   setup: Schema.optional(
     Schema.Struct({
+      agentInstructions: Schema.optional(AgentInstructionsSetupSchema),
+      claudeInstructions: Schema.optional(ClaudeInstructionsSetupSchema),
       effectSource: Schema.optional(EffectSourceSetupSchema),
       effectTsgo: Schema.optional(EffectTsgoSetupSchema),
     }),
@@ -67,6 +82,12 @@ export type NormalizedManifest = {
   readonly include: ReadonlyArray<string>;
   readonly exclude: ReadonlyArray<string>;
   readonly setup: {
+    readonly agentInstructions: {
+      readonly enabled: boolean;
+    };
+    readonly claudeInstructions: {
+      readonly enabled: boolean;
+    };
     readonly effectSource: {
       readonly enabled: boolean;
       readonly packageName: string;
@@ -114,6 +135,12 @@ export const normalizeManifest = (manifest: DevKitManifest): NormalizedManifest
     exclude: manifest.exclude ?? [],
     include: manifest.include,
     setup: {
+      agentInstructions: {
+        enabled: manifest.setup?.agentInstructions?.enabled ?? false,
+      },
+      claudeInstructions: {
+        enabled: manifest.setup?.claudeInstructions?.enabled ?? false,
+      },
       effectSource: {
         enabled: manifest.setup?.effectSource?.enabled ?? false,
         packageName: manifest.setup?.effectSource?.packageName ?? "effect",

package/src/package-skill-source.ts

@@ -0,0 +1,250 @@
+import { Effect, FileSystem, Path, Result, Schema } from "effect";
+
+import { observeSymbolicLink } from "./node-symbolic-link.ts";
+import { readDirectDependencyNames } from "./project-package.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 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));
+  }
+});
+
+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,
+  );
+});