@danieljvdm/dev-kit 0.3.3 → 0.5.0

package/README.md

@@ -20,7 +20,8 @@ Install the published Dev Kit package:
 bun add -d @danieljvdm/dev-kit
 ```
 
-Initialize the project, browse the approved catalog, and add skills:
+Initialize the project, browse available built-in, approved Git, and installed
+package skills, then add the ones you want:
 
 ```bash
 bun x dev-kit init
@@ -107,7 +108,7 @@ the root package itself.
 | `dev-kit remove <skill...>` | Deselect and uninstall skills safely. |
 | `dev-kit list [--all]` | List selected skills or browse the catalog. |
 | `dev-kit search <words...>` | Search names and descriptions. |
-| `dev-kit info <skill>` | Show description, source, and approved commit. |
+| `dev-kit info <skill>` | Show description and Git or installed-package provenance. |
 | `dev-kit status` | Check whether the project matches its selection. |
 | `dev-kit sync` | Apply the current manifest. |
 | `dev-kit plan` | Preview project changes without writing files. |
@@ -149,7 +150,8 @@ tool versions. A project-local process lock also prevents concurrent applies.
 
 ## Manifest
 
-`include` accepts individual skill names and skill families:
+`include` accepts static skill names, skill families, and explicit
+`<package>#<skill>` selectors:
 
 ```jsonc
 {
@@ -159,9 +161,13 @@ tool versions. A project-local process lock also prevents concurrent applies.
     "effect",
     "workers-best-practices",
     "wrangler",
-    "serve-sim"
+    "serve-sim",
+    "@tanstack/ai#ai-core"
   ],
   "exclude": ["animation-vocabulary"],
+  "setup": {
+    "claudeInstructions": { "enabled": true }
+  },
   "targets": {
     "agents": { "enabled": true, "mode": "copy" },
     "claude": { "enabled": true, "mode": "symlink" },
@@ -175,6 +181,8 @@ tool versions. A project-local process lock also prevents concurrent applies.
 - Prefer individual external skills such as `workers-best-practices` and
   `wrangler`, selected after scanning the project for relevant technologies.
 - `serve-sim` selects the approved Evan Bacon simulator skill directly.
+- `@tanstack/ai#ai-core` explicitly selects a skill discovered in that direct
+  project dependency; discovery alone never selects it.
 - An approved source ID is broad shorthand that selects every skill from that
   source. Use it only when the scan confirms that every member applies.
 
@@ -183,6 +191,25 @@ Dev Kit reserves `.repos/<source-id>` for project-local source checkouts. Run
 The patch is idempotent, preserves existing lines, and refuses symlinked
 `.gitignore` files.
 
+## Claude instructions
+
+Enable a portable Claude Code instruction bridge in the manifest:
+
+```jsonc
+{
+  "include": [],
+  "setup": {
+    "claudeInstructions": { "enabled": true }
+  }
+}
+```
+
+`dev-kit apply` requires a project-root `AGENTS.md`, then manages
+`CLAUDE.md` as the relative symlink `CLAUDE.md → AGENTS.md`. The link is
+recorded in the lockfile and local ownership state. Dev Kit refuses to replace
+an unowned `CLAUDE.md` and removes the link when the task is disabled only if
+the owned link is unchanged.
+
 ## Effect source checkout
 
 Enable a local checkout of the exact installed Effect release in the manifest:
@@ -248,10 +275,65 @@ troubleshooting the task directly.
 Package and tsconfig edits remain explicit until Dev Kit can safely own parts
 of shared JSONC files.
 
-## Approved external skills
+## Installed package skills
+
+Dev Kit generically discovers agent skills bundled by the project's installed
+JavaScript packages. It reads the project's direct dependencies, checks the
+package's Intent v1 discovery metadata (or Intent's repository-metadata
+fallback), then looks for the layout
+`node_modules/<package>/skills/<skill>/SKILL.md`.
+TanStack is one publisher of this layout; no TanStack package names or skill
+paths are hard-coded into Dev Kit.
+
+Discovery is browse-only. These commands show an installed package skill but do
+not select, copy, symlink, lock, or otherwise install it:
+
+```bash
+bun x dev-kit list --all
+bun x dev-kit search tanstack
+bun x dev-kit info @tanstack/ai#ai-core
+```
+
+Selection is explicit and package-qualified:
+
+```bash
+bun x dev-kit add @tanstack/ai#ai-core
+```
+
+That writes `@tanstack/ai#ai-core` to `dev-kit.jsonc` and, unless
+`--no-apply` is passed, installs it through the normal ownership-safe sync
+path. The qualifier prevents ambiguity when two dependencies publish the same
+skill name. Two selected skills that would both write the same destination are
+rejected before any output is changed.
+
+The initial compatibility boundary is intentionally small and deterministic:
 
-This repository is an opinionated catalog, not a mirror of every upstream skill
-tree. `skill-sources.jsonc` declares sources Dan has approved:
+- only packages named in the root project's `dependencies`,
+  `devDependencies`, `optionalDependencies`, or `peerDependencies` are
+  scanned;
+- package code is never imported or executed;
+- npm-style and pnpm/workspace symlinks under `node_modules` are supported;
+- Yarn Plug'n'Play and transitive dependency traversal are not scanned; and
+- immediate `skills/<name>/SKILL.md` roots are listed. Nested topic skills and
+  references remain part of that root and are copied with it.
+
+The last rule adapts Intent's routed, nested skill trees to the immediate folder
+and frontmatter-name invariants expected by Agent Skills targets. Dev Kit does
+not rewrite nested names or ask Intent to manage agent configuration.
+
+The project `dev-kit.lock.json` records the selected package name, installed
+version, skill name, and content digest. `apply --locked` therefore rejects
+package-version or skill-content drift. Dev Kit never downloads a missing
+package or substitutes a registry version.
+
+See TanStack's
+[Agent Skills documentation](https://tanstack.com/ai/latest/docs/getting-started/agent-skills)
+for a real package suite that uses this convention.
+
+## Approved external Git skills
+
+This repository remains an opinionated catalog for Git-hosted skills.
+`skill-sources.jsonc` contains only reviewed Git sources:
 
 ```jsonc
 {
@@ -276,49 +358,41 @@ bun run catalog:refresh
 bun run catalog:check
 ```
 
-Adding a source does not require editing JSONC:
+Adding a Git source does not require editing JSONC:
 
 ```bash
-# Opens a skill picker in a terminal
 dev-kit catalog add https://github.com/owner/repository
-
-# Explicit and automation-friendly
 dev-kit catalog add https://github.com/owner/repository \
   --skill one --skill two
 dev-kit catalog add https://github.com/owner/repository --all
 ```
 
-GitHub tree URLs are accepted, so a URL such as
-`https://github.com/owner/repository/tree/main/skills` supplies the repository,
-ref, and skills path together. `--all` expands to the skills discovered at that
+GitHub tree URLs are accepted. `--all` expands to the skills found at that
 exact snapshot; it never writes a wildcard that could silently approve a future
-upstream addition.
+upstream addition. Catalog refresh resolves refs to exact commits, validates
+names and paths, rejects symlinks and collisions, extracts descriptions, and
+updates `skill-sources.lock.json`.
 
-The current catalog includes approved snapshots from Emil Kowalski,
-Cloudflare, and Evan Bacon. Inspect them with `dev-kit catalog list` and
-`dev-kit catalog info <source>`.
+When a project selects one of these Git-backed skills, Dev Kit fetches the
+approved commit into the ignored `.dev-kit/cache` and installs it through the
+same ownership-safe sync path. Only a reviewed catalog refresh changes the
+approved Git content.
 
-The refresh resolves refs to exact commits, validates names and paths, rejects
-symlinks and collisions, extracts short descriptions, and updates
-`skill-sources.lock.json`. It does not copy upstream skill trees into this
-repository.
+## Oxlint and Oxfmt configurations
 
-When a consuming project selects an external skill, Dev Kit fetches that exact
-approved commit into the ignored `.dev-kit/cache`, applies declared compatibility
-transforms, and installs the result through the ownership-safe sync path. Normal
-installs never float to a newer upstream commit; only a reviewed catalog refresh
-changes what is approved.
-
-## Oxlint preset for Vite+
-
-Dev Kit exports a typed, composable set of high-signal Oxlint rules for Vite+
-projects:
+Dev Kit exports one typed Oxlint ruleset and one typed Oxfmt configuration for
+both standalone Oxc projects and Vite+ projects. A Vite+ project composes them
+in `vite.config.ts`:
 
 ```ts
 import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
+import { recommendedOxfmtConfig } from "@danieljvdm/dev-kit/oxfmt";
 import { defineConfig } from "vite-plus";
 
 export default defineConfig({
+  fmt: {
+    ...recommendedOxfmtConfig,
+  },
   lint: {
     extends: [recommendedOxlintConfig],
     rules: {
@@ -329,7 +403,38 @@ export default defineConfig({
 ```
 
 Use `lint.extends` rather than a shallow object spread so Vite+ composes the
-nested plugin and rule configuration correctly.
+nested plugin and rule configuration correctly. Oxfmt has no `extends`, so
+spread its configuration before project-local formatter options.
+
+Standalone projects import the same objects from their native config files:
+
+```ts
+// oxlint.config.ts
+import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
+import { defineConfig } from "oxlint";
+
+export default defineConfig({
+  extends: [recommendedOxlintConfig],
+});
+```
+
+```ts
+// oxfmt.config.ts
+import { recommendedOxfmtConfig } from "@danieljvdm/dev-kit/oxfmt";
+import { defineConfig } from "oxfmt";
+
+export default defineConfig({
+  ...recommendedOxfmtConfig,
+});
+```
+
+The Oxlint preset also registers the shared `effect` JavaScript plugin. Effect
+projects opt into its rules in path-specific overrides, for example
+`effect/no-effect-run`, `effect/no-unsafe-promise`, and
+`effect/no-untyped-throw`. The package exports the plugin directly from
+`@danieljvdm/dev-kit/oxlint-plugin-effect` for configurations that do not
+extend the recommended preset. Strict workflow, Atom, and boundary rules remain
+consumer-scoped because application and host boundaries differ by repository.
 
 ## Development
 

package/dev-kit.example.jsonc

@@ -2,6 +2,7 @@
   "$schema": "./schema/dev-kit.schema.json",
   "include": ["dev-kit", "effect"],
   "setup": {
+    "claudeInstructions": { "enabled": true },
     "effectSource": { "enabled": true },
     "effectTsgo": { "enabled": true }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "Declarative project development toolkit with portable agent skills.",
@@ -23,6 +23,14 @@
     "./oxlint": {
       "types": "./src/oxlint.ts",
       "default": "./src/oxlint.js"
+    },
+    "./oxfmt": {
+      "types": "./src/oxfmt.ts",
+      "default": "./src/oxfmt.js"
+    },
+    "./oxlint-plugin-effect": {
+      "types": "./src/oxlint-plugin-effect.d.ts",
+      "default": "./src/oxlint-plugin-effect.js"
     }
   },
   "files": [
@@ -64,14 +72,24 @@
     "@effect/tsgo": "0.24.3",
     "@effect/vitest": "4.0.0-beta.102",
     "@types/node": "25.9.1",
+    "oxfmt": "0.60.0",
+    "oxlint": "1.75.0",
     "typescript": "7.0.2",
     "vite-plus": "0.2.6",
     "vitest": "4.1.10"
   },
   "peerDependencies": {
+    "oxfmt": ">=0.60.0 <0.61.0",
+    "oxlint": ">=1.75.0 <2.0.0",
     "vite-plus": ">=0.2.6 <0.3.0"
   },
   "peerDependenciesMeta": {
+    "oxfmt": {
+      "optional": true
+    },
+    "oxlint": {
+      "optional": true
+    },
     "vite-plus": {
       "optional": true
     }

package/schema/dev-kit.schema.json

@@ -10,21 +10,21 @@
       "type": "string"
     },
     "include": {
-      "description": "Skill names or family names to sync. Prefer individually relevant external skills; an external source id selects every approved skill from that source.",
+      "description": "Static skill names, family names, or exact <package>#<skill> selectors to sync. Installed package skills are discovered for browsing but selected only when explicitly included.",
       "type": "array",
       "items": {
         "type": "string",
-        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        "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]+)*)$"
       },
       "uniqueItems": true,
       "minItems": 0
     },
     "exclude": {
-      "description": "Skill names or family names to remove from the selected set after expanding includes.",
+      "description": "Static skill names, family names, or exact <package>#<skill> selectors to remove after expanding includes.",
       "type": "array",
       "items": {
         "type": "string",
-        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        "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]+)*)$"
       },
       "uniqueItems": true,
       "default": []
@@ -34,6 +34,9 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "claudeInstructions": {
+          "$ref": "#/$defs/claudeInstructionsSetup"
+        },
         "effectSource": {
           "$ref": "#/$defs/effectSourceSetup"
         },
@@ -58,6 +61,17 @@
   },
   "required": ["include"],
   "$defs": {
+    "claudeInstructionsSetup": {
+      "description": "Manage CLAUDE.md as a relative symlink to the project-root AGENTS.md file.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    },
     "effectSourceSetup": {
       "type": "object",
       "additionalProperties": false,

package/skills/dev-kit/SKILL.md

@@ -67,6 +67,9 @@ skill as `dev-kit` when project agents should carry the toolkit procedure.
   "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
   "include": ["dev-kit", "effect"],
   "exclude": [],
+  "setup": {
+    "claudeInstructions": { "enabled": true }
+  },
   "targets": {
     "agents": { "enabled": true, "mode": "copy" },
     "claude": { "enabled": true, "mode": "symlink" },
@@ -80,6 +83,12 @@ use symlinks for additional harness discovery paths. Keep every target path
 project-relative and separate from the manifest, lock, state, and process-lock
 paths.
 
+Enable `setup.claudeInstructions` when Claude Code should consume the same
+project-root instructions as Codex. It manages `CLAUDE.md` as a relative
+symlink to an existing `AGENTS.md`. Preserve any conflicting `CLAUDE.md`; when
+disabled, dev-kit removes only an unchanged link recorded in local ownership
+state.
+
 ## Ownership and conflicts
 
 Dev-kit adopts an existing destination only when its digest exactly matches a
@@ -156,16 +165,19 @@ dependencies; `dev-kit apply` patches once and then converges.
 Use `dev-kit tsgo patch --dry-run` for focused diagnosis. Use `--force` only
 after the user accepts a potentially commit-incompatible TypeScript binary.
 
-## Oxlint preset for Vite+
+## Oxlint and Oxfmt configurations
 
-For Vite+ projects, compose the package's typed recommended Oxlint preset with
-project-specific lint configuration:
+Use Dev Kit's canonical Oxlint and Oxfmt objects in Vite+ projects:
 
 ```ts
 import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
+import { recommendedOxfmtConfig } from "@danieljvdm/dev-kit/oxfmt";
 import { defineConfig } from "vite-plus";
 
 export default defineConfig({
+  fmt: {
+    ...recommendedOxfmtConfig,
+  },
   lint: {
     extends: [recommendedOxlintConfig],
     rules: {
@@ -176,14 +188,25 @@ export default defineConfig({
 ```
 
 Use `lint.extends` instead of spreading the object so Vite+ composes nested
-rule maps correctly. Keep repository-specific path conventions and
-platform-specific accessibility rules in the consuming project.
+rule maps correctly. Oxfmt has no inheritance mechanism, so spread its object
+before project-local options. Standalone `oxlint.config.ts` uses the same
+`extends: [recommendedOxlintConfig]`; standalone `oxfmt.config.ts` spreads the
+same `recommendedOxfmtConfig`.
+
+The Oxlint preset registers Dev Kit's shared Effect plugin as `effect`, but
+does not enable its scope-sensitive rules globally. Effect projects should
+enable rules such as `effect/no-effect-run`, `effect/no-unsafe-promise`, and
+`effect/no-untyped-throw` only in Effect-owned code, with explicit exceptions
+for tests and host boundaries. The stricter `effect/no-async-workflow`,
+`effect/no-promise-atom-mode`, and `effect/no-sync-boundary-decode` rules also
+need consumer-owned scopes. Keep repository-specific paths and platform rules
+in the consuming project.
 
 ## Current boundary
 
-Manage skill outputs, the `setup.effectSource` checkout, and the explicit
-`setup.effectTsgo` task. Edit shared `package.json` and `tsconfig.json`
-contributions deliberately. The Oxlint preset is a composable package export,
-not a manifest-managed output. Treat named bundles, Oxfmt presets, and broader
-setup tasks as future manifest capabilities until the installed CLI exposes
-them.
+Manage skill outputs, the `setup.claudeInstructions` link, the
+`setup.effectSource` checkout, and the explicit `setup.effectTsgo` task. Edit
+shared `package.json` and `tsconfig.json`
+contributions deliberately. The Oxlint and Oxfmt configurations are composable
+package exports, not manifest-managed outputs. Treat broader setup tasks as
+future manifest capabilities until the installed CLI exposes them.

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]),
-    ),
+    ...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,6 @@
 export {
+  type ClaudeInstructionsSetup,
+  ClaudeInstructionsSetupSchema,
   type DevKitManifest,
   DevKitManifestSchema,
   type EffectSourceSetup,
@@ -58,15 +60,21 @@ export {
 } from "./sync.ts";
 export {
   AppliedStateSchema,
+  CatalogProvenanceSchema,
   DevKitLockSchema,
   EffectSourceLockSchema,
   EffectTsgoLockSchema,
+  ManagedInstructionOutputSchema,
+  ManagedOutputSchema,
   ManagedSkillOutputSchema,
   OwnershipReceiptSchema,
   type AppliedState,
+  type CatalogProvenance,
   type DevKitLock,
   type EffectSourceLock,
   type EffectTsgoLock,
+  type ManagedInstructionOutput,
+  type ManagedOutput,
   type ManagedSkillOutput,
   type OwnershipReceipt,
 } from "./project-state.ts";