@danieljvdm/dev-kit 0.4.0 → 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.
 
-This repository is an opinionated catalog, not a mirror of every upstream skill
-tree. `skill-sources.jsonc` declares sources Dan has approved:
+The initial compatibility boundary is intentionally small and deterministic:
+
+- 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,38 +358,25 @@ 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.
-
-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>`.
-
-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.
-
-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.
+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`.
+
+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.
 
 ## Oxlint and Oxfmt configurations
 

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.4.0",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "Declarative project development toolkit with portable agent skills.",

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
@@ -195,8 +204,9 @@ 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`
+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";

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,19 @@ export const EffectSourceSetupSchema = Schema.Struct({
 
 export type EffectSourceSetup = typeof EffectSourceSetupSchema.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({
+      claudeInstructions: Schema.optional(ClaudeInstructionsSetupSchema),
       effectSource: Schema.optional(EffectSourceSetupSchema),
       effectTsgo: Schema.optional(EffectTsgoSetupSchema),
     }),
@@ -67,6 +75,9 @@ export type NormalizedManifest = {
   readonly include: ReadonlyArray<string>;
   readonly exclude: ReadonlyArray<string>;
   readonly setup: {
+    readonly claudeInstructions: {
+      readonly enabled: boolean;
+    };
     readonly effectSource: {
       readonly enabled: boolean;
       readonly packageName: string;
@@ -114,6 +125,9 @@ export const normalizeManifest = (manifest: DevKitManifest): NormalizedManifest
     exclude: manifest.exclude ?? [],
     include: manifest.include,
     setup: {
+      claudeInstructions: {
+        enabled: manifest.setup?.claudeInstructions?.enabled ?? false,
+      },
       effectSource: {
         enabled: manifest.setup?.effectSource?.enabled ?? false,
         packageName: manifest.setup?.effectSource?.packageName ?? "effect",