skillshop 0.0.0-stage → 2.0.0

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# Skillshop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skillshop is infrastructure for **building and consuming skill libraries**. It is not a bundled personal skill catalog.
+
+A skill is addressed by a portable component specifier:
+
+```text
+skill:clips
+skill:loopz
+skill:design-review
+```
+
+The library owns where its `SKILL.md` lives. Consumers only depend on the `skill:*` name.
+
+## The model
+
+A producer package keeps a source manifest:
+
+```json
+{
+  "schemaVersion": 1,
+  "exports": {
+    "skill:clips": "./.agents/skills/clips",
+    "skill:loopz": "./.agents/skills/loopz"
+  }
+}
+```
+
+`skillshop build` validates each directory and generates a package-facing `skillshop.manifest.mjs`. It also adds the standard `./skillshop` package export and, when `package.json#files` is present, ensures the exported skill directories are shipped.
+
+This makes a skill library behave like a component package: producers export named components; applications resolve or materialize only the components they choose.
+
+## Explicit export boundary
+
+`skillshop.library.json` is the **only** skill export definition. The `exports` map is an allowlist, not a directory scan. In particular, `.agents/skills/` is just a possible source/install location: a repository can contain any number of valid `SKILL.md` files there without publishing any of them.
+
+- `skillshop init` creates an empty `exports: {}` map; it does not discover or publish skills.
+- `skillshop build` requires that source manifest and generates entries only for explicitly named local exports and re-exports. Missing manifests fail validation; empty manifests publish zero skills.
+- `skillshop resolve` and `skillshop import` reject unlisted `skill:*` names, even when their files are present on disk.
+- `skillshop export` and `skillshop unexport` explicitly change that public surface. Removing an export does not delete the repository's local skill files.
+- Aggregators must also explicitly list every upstream skill they re-export; importing a dependency does not re-export its entire library.
+
+Skillshop only adds **declared local skill directories** to its managed `package.json#files` entries. Its export allowlist governs the Skillshop API, not arbitrary physical file access: if your own package `files` patterns include other private skills, npm may still publish those files. Keep such paths out of broad package globs if they must not ship.
+
+A library can also re-export another library's skill without copying its source:
+
+```json
+{
+  "schemaVersion": 1,
+  "exports": {
+    "skill:clips": {
+      "from": "@dfosco/clips",
+      "skill": "skill:clips"
+    }
+  }
+}
+```
+
+The upstream package must be a runtime dependency or a non-optional peer dependency so the generated manifest can safely load its standard `<package>/skillshop` export.
+
+## CLI
+
+Initialize a library:
+
+```bash
+skillshop init
+```
+
+Export skills:
+
+```bash
+skillshop export skill:clips ./.agents/skills/clips
+skillshop export skill:loopz ./.agents/skills/loopz
+skillshop export skill:clips --from @dfosco/clips
+skillshop list
+skillshop validate
+skillshop build
+```
+
+Consume a skill from an installed package or a local package directory:
+
+```bash
+skillshop resolve @dfosco/clips skill:clips
+skillshop import @dfosco/clips skill:clips --to .agents/skills/clips
+```
+
+`--force` replaces an existing import target. Without `--force`, the CLI does not overwrite an existing skill directory.
+
+**Imports are snapshots:** `importSkill` copies the complete skill directory to the destination. Imported files do not depend on the source package afterward and are never changed or deleted by a later `unexport`. To apply an updated source, the consumer must import it again explicitly.
+
+For applications that update only files owned by a skill while preserving local additions, the SDK also supports `merge: true`:
+
+```js
+const result = await importSkill({
+  library: '/path/to/a/skill-library',
+  specifier: 'skill:clips',
+  targetDir: '.agents/skills/clips',
+  merge: true,
+});
+// result.installed and result.updated indicate newly copied or changed files.
+```
+
+The merge mode overlays source files and leaves unrelated destination files untouched. It is opt-in; the normal import still refuses an existing destination unless `overwrite: true` is set.
+
+## SDK
+
+Skillshop exports the builder and consumer capabilities as normal application modules:
+
+```js
+import { exportSkill, reexportSkill, buildSkillLibrary } from 'skillshop/export';
+import { resolveSkill, importSkill } from 'skillshop/import';
+```
+
+Build a library programmatically:
+
+```js
+exportSkill({
+  root: process.cwd(),
+  specifier: 'skill:clips',
+  source: './.agents/skills/clips',
+});
+
+reexportSkill({
+  root: process.cwd(),
+  specifier: 'skill:loopz',
+  from: '@dfosco/clips',
+});
+
+buildSkillLibrary(process.cwd());
+```
+
+Resolve without copying, which is useful for applications such as Hypercanvas:
+
+```js
+const clips = await resolveSkill({
+  library: '@dfosco/clips',
+  specifier: 'skill:clips',
+});
+
+console.log(clips.manifestPath);
+```
+
+Or materialize the complete skill component:
+
+```js
+await importSkill({
+  library: '@dfosco/clips',
+  specifier: 'skill:loopz',
+  targetDir: '.agents/skills/loopz',
+});
+```
+
+## Package contract
+
+Published libraries expose one standard package subpath:
+
+```text
+<package>/skillshop
+```
+
+Skillshop generates that manifest. Consumers therefore do not need package-specific JS exports such as `clipsSkill` or `loopzSkill`.
+
+The producer package, a personal library, and an application are separate concerns:
+
+- **Skillshop** defines the protocol and tooling.
+- **Clips** can export `skill:clips` and `skill:loopz`.
+- **A personal library** can aggregate local skills and re-export `skill:*` components from packages such as Clips without vendoring them.
+- **Hypercanvas** can optionally resolve/import Clips workflow skills for Squads.

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "skillshop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "Build, export, resolve, and import portable agent skill libraries",
+  "type": "module",
+  "bin": {
+    "skillshop": "./src/cli.js",
+    "skillz": "./src/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./library": "./src/library.js",
+    "./export": "./src/export.js",
+    "./import": "./src/import.js",
+    "./specifier": "./src/specifier.js"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildSkillLibrary, initSkillLibrary, readSkillLibrary, validateSkillLibrary } from './library.js';
+import { exportSkill, reexportSkill, unexportSkill } from './export.js';
+import { importSkill, resolveSkill } from './import.js';
+
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+function help() {
+  console.log(`skillshop v${VERSION} — build and consume portable skill libraries
+
+Usage:
+  skillshop init
+  skillshop export skill:<name> <directory>
+  skillshop export skill:<name> --from <package> [--skill skill:<source-name>]
+  skillshop unexport skill:<name>
+  skillshop list
+  skillshop validate
+  skillshop build
+  skillshop resolve <library> skill:<name>
+  skillshop import <library> skill:<name> --to <directory> [--force]
+
+A library publishes skills by portable specifier, for example skill:clips.
+Consumers resolve the same specifier regardless of where the library stores SKILL.md.`);
+}
+
+function flag(args, name) {
+  const index = args.indexOf(name);
+  return index === -1 ? null : args[index + 1];
+}
+
+async function main(argv) {
+  const [command, ...args] = argv;
+  if (!command || command === '--help' || command === '-h' || command === 'help') return help();
+  if (command === '--version' || command === '-v') return console.log(`skillshop v${VERSION}`);
+
+  if (command === 'init') {
+    initSkillLibrary();
+    console.log(`Initialized ${path.resolve('skillshop.library.json')}`);
+    return;
+  }
+  if (command === 'export') {
+    if (args.length < 2) throw new Error('Usage: skillshop export skill:<name> <directory> | --from <package> [--skill skill:<source-name>]');
+    const from = flag(args, '--from');
+    const result = from
+      ? reexportSkill({ specifier: args[0], from, importedSpecifier: flag(args, '--skill') || args[0] })
+      : exportSkill({ specifier: args[0], source: args[1] });
+    console.log(result.kind === 'import'
+      ? `${result.specifier} -> ${result.from}#${result.importedSpecifier}`
+      : `${result.specifier} -> ${result.source}`);
+    return;
+  }
+  if (command === 'unexport') {
+    if (args.length !== 1) throw new Error('Usage: skillshop unexport skill:<name>');
+    console.log(unexportSkill({ specifier: args[0] }) ? `Removed ${args[0]}` : `${args[0]} was not exported`);
+    return;
+  }
+  if (command === 'list') {
+    const library = readSkillLibrary(process.cwd(), { required: true });
+    for (const [specifier, source] of Object.entries(library.exports)) {
+      console.log(typeof source === 'string' ? `${specifier} -> ${source}` : `${specifier} -> ${source.from}#${source.skill}`);
+    }
+    return;
+  }
+  if (command === 'validate') {
+    const result = validateSkillLibrary();
+    console.log(`Valid ${result.packageName}: ${result.skills.length} skill(s)`);
+    return;
+  }
+  if (command === 'build') {
+    const result = buildSkillLibrary();
+    console.log(`Built ${result.packageName}: ${result.skills.length} skill(s)`);
+    return;
+  }
+  if (command === 'resolve') {
+    if (args.length !== 2) throw new Error('Usage: skillshop resolve <library> skill:<name>');
+    console.log(JSON.stringify(await resolveSkill({ library: args[0], specifier: args[1] }), null, 2));
+    return;
+  }
+  if (command === 'import') {
+    if (args.length < 2) throw new Error('Usage: skillshop import <library> skill:<name> --to <directory> [--force]');
+    const targetDir = flag(args, '--to');
+    if (!targetDir) throw new Error('--to <directory> is required');
+    const result = await importSkill({ library: args[0], specifier: args[1], targetDir, overwrite: args.includes('--force') });
+    console.log(`${result.specifier} -> ${result.targetDir}`);
+    return;
+  }
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`skillshop: ${error.message}`);
+  process.exitCode = 1;
+});

package/src/export.js

@@ -0,0 +1,113 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  buildSkillLibrary,
+  initSkillLibrary,
+  readSkillLibrary,
+  resolveLocalSkill,
+  validateSkillLibrary,
+  writeSkillLibrary,
+} from './library.js';
+import { normalizeSkillSpecifier } from './specifier.js';
+
+function packageDependencies(root) {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(path.resolve(root), 'package.json'), 'utf8'),
+  );
+  const names = new Set(Object.keys(pkg.dependencies || {}));
+  for (const name of Object.keys(pkg.peerDependencies || {})) {
+    if (pkg.peerDependenciesMeta?.[name]?.optional === true) continue;
+    names.add(name);
+  }
+  return names;
+}
+
+function updateLibrary(root, mutate) {
+  initSkillLibrary(root);
+  const packageRoot = path.resolve(root);
+  const packagePath = path.join(packageRoot, 'package.json');
+  const manifestPath = path.join(packageRoot, 'skillshop.manifest.mjs');
+  const previousPackage = fs.readFileSync(packagePath);
+  const previousManifest = fs.existsSync(manifestPath)
+    ? fs.readFileSync(manifestPath)
+    : null;
+  const previous = readSkillLibrary(root, { required: true });
+  const next = { ...previous, exports: { ...previous.exports } };
+
+  mutate(next);
+  writeSkillLibrary(root, next);
+
+  try {
+    return buildSkillLibrary(root);
+  } catch (error) {
+    writeSkillLibrary(root, previous);
+    fs.writeFileSync(packagePath, previousPackage);
+    if (previousManifest === null) fs.rmSync(manifestPath, { force: true });
+    else fs.writeFileSync(manifestPath, previousManifest);
+    throw error;
+  }
+}
+
+export function exportSkill({
+  root = process.cwd(),
+  specifier,
+  source,
+}) {
+  const normalized = normalizeSkillSpecifier(specifier);
+  resolveLocalSkill(root, normalized, {
+    schemaVersion: 1,
+    exports: { [normalized]: source },
+  });
+
+  const result = updateLibrary(root, (library) => {
+    library.exports[normalized] = source;
+  });
+  return result.skills.find((skill) => skill.specifier === normalized);
+}
+
+export function reexportSkill({
+  root = process.cwd(),
+  specifier,
+  from,
+  importedSpecifier = specifier,
+}) {
+  const normalized = normalizeSkillSpecifier(specifier);
+  const imported = normalizeSkillSpecifier(importedSpecifier);
+  if (typeof from !== 'string' || !from.trim()) {
+    throw new Error('from package is required');
+  }
+  const packageName = from.trim();
+  if (!packageDependencies(root).has(packageName)) {
+    throw new Error(
+      `Re-export ${normalized} requires ${packageName} in dependencies or peerDependencies`,
+    );
+  }
+
+  const result = updateLibrary(root, (library) => {
+    library.exports[normalized] = {
+      from: packageName,
+      skill: imported,
+    };
+  });
+  return result.skills.find((skill) => skill.specifier === normalized);
+}
+
+export function unexportSkill({
+  root = process.cwd(),
+  specifier,
+}) {
+  const normalized = normalizeSkillSpecifier(specifier);
+  const library = readSkillLibrary(root, { required: true });
+  if (!Object.hasOwn(library.exports, normalized)) return false;
+
+  updateLibrary(root, (next) => {
+    delete next.exports[normalized];
+  });
+  return true;
+}
+
+export {
+  buildSkillLibrary,
+  initSkillLibrary,
+  validateSkillLibrary,
+};

package/src/import.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { normalizeSkillSpecifier, parseSkillSpecifier } from './specifier.js';
+import { SKILLSHOP_MANIFEST_FILE, SKILLSHOP_SCHEMA_VERSION } from './library.js';
+
+async function importManifestFile(file) {
+  // Content-based cache keys also invalidate in long-lived consumers when two
+  // export changes land within the filesystem timestamp resolution.
+  const digest = createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+  const url = `${pathToFileURL(file).href}?skillshop=${digest}`;
+  return (await import(url)).default;
+}
+
+function validatePublishedManifest(manifest, label) {
+  if (!manifest || manifest.schemaVersion !== SKILLSHOP_SCHEMA_VERSION || !manifest.skills || typeof manifest.skills !== 'object') {
+    throw new Error(`${label} is not a supported Skillshop library manifest`);
+  }
+  return manifest;
+}
+
+export async function loadSkillLibrary(library, { cwd = process.cwd() } = {}) {
+  if (library && typeof library === 'object') return validatePublishedManifest(library, 'library object');
+  if (typeof library !== 'string' || !library.trim()) throw new Error('library must be a package name, package directory, or manifest object');
+  const value = library.trim();
+  const local = path.resolve(cwd, value);
+  if (fs.existsSync(local) && fs.statSync(local).isDirectory()) {
+    const manifestFile = path.join(local, SKILLSHOP_MANIFEST_FILE);
+    if (!fs.existsSync(manifestFile)) throw new Error(`${value} has no ${SKILLSHOP_MANIFEST_FILE}; run skillshop build`);
+    return validatePublishedManifest(await importManifestFile(manifestFile), value);
+  }
+
+  const requireFromConsumer = createRequire(path.join(path.resolve(cwd), 'package.json'));
+  let resolved;
+  try {
+    resolved = requireFromConsumer.resolve(`${value}/skillshop`);
+  } catch (error) {
+    throw new Error(`Cannot resolve ${value}/skillshop from ${cwd}: ${error.message}`);
+  }
+  return validatePublishedManifest(await importManifestFile(resolved), value);
+}
+
+export async function resolveSkill({ library, specifier, cwd = process.cwd() }) {
+  const normalized = normalizeSkillSpecifier(specifier);
+  const manifest = await loadSkillLibrary(library, { cwd });
+  const href = manifest.skills[normalized];
+  if (typeof href !== 'string' || !href) throw new Error(`${normalized} is not exported by ${manifest.packageName || 'the library'}`);
+  const url = new URL(href);
+  if (url.protocol !== 'file:') throw new Error(`${normalized} does not resolve to a local packaged skill directory`);
+  const sourceDir = fileURLToPath(url);
+  const manifestPath = path.join(sourceDir, 'SKILL.md');
+  if (!fs.existsSync(manifestPath) || !fs.statSync(manifestPath).isFile()) {
+    throw new Error(`${normalized} is missing a regular SKILL.md file in the installed library`);
+  }
+  return Object.freeze({
+    ...parseSkillSpecifier(normalized),
+    packageName: manifest.packageName || null,
+    sourceDir,
+    manifestPath,
+  });
+}
+
+function listSkillFiles(sourceDir, relative = '') {
+  return fs.readdirSync(path.join(sourceDir, relative), { withFileTypes: true })
+    .flatMap((entry) => {
+      const nested = path.join(relative, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`Skill source contains an unsafe symlink: ${nested}`);
+      if (entry.isDirectory()) return listSkillFiles(sourceDir, nested);
+      if (!entry.isFile()) throw new Error(`Skill source contains an unsupported file: ${nested}`);
+      return [nested];
+    });
+}
+
+function assertSafeMergeTarget(target, relativeFile) {
+  let current = target;
+  for (const segment of relativeFile.split(path.sep)) {
+    current = path.join(current, segment);
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`Cannot merge through a symbolic link: ${current}`);
+    }
+  }
+}
+
+export async function importSkill({
+  library,
+  specifier,
+  targetDir,
+  cwd = process.cwd(),
+  overwrite = false,
+  merge = false,
+}) {
+  if (typeof targetDir !== 'string' || !targetDir.trim()) throw new Error('targetDir is required');
+  if (merge && overwrite) throw new Error('merge and overwrite cannot both be enabled');
+  const skill = await resolveSkill({ library, specifier, cwd });
+  const target = path.resolve(cwd, targetDir);
+  const exists = fs.existsSync(target);
+
+  if (exists && merge) {
+    if (!fs.lstatSync(target).isDirectory()) throw new Error(`Merge target is not a directory: ${target}`);
+    let addedFiles = 0;
+    let updatedFiles = 0;
+    for (const relativeFile of listSkillFiles(skill.sourceDir)) {
+      assertSafeMergeTarget(target, relativeFile);
+      const sourceFile = path.join(skill.sourceDir, relativeFile);
+      const destinationFile = path.join(target, relativeFile);
+      if (fs.existsSync(destinationFile)) {
+        if (!fs.lstatSync(destinationFile).isFile()) throw new Error(`Merge target is not a file: ${destinationFile}`);
+        if (fs.readFileSync(sourceFile).equals(fs.readFileSync(destinationFile))) continue;
+        fs.copyFileSync(sourceFile, destinationFile);
+        updatedFiles += 1;
+      } else {
+        fs.mkdirSync(path.dirname(destinationFile), { recursive: true });
+        fs.copyFileSync(sourceFile, destinationFile);
+        addedFiles += 1;
+      }
+    }
+    return { ...skill, targetDir: target, installed: addedFiles > 0, updated: updatedFiles > 0, addedFiles, updatedFiles };
+  }
+
+  if (exists && !overwrite) throw new Error(`Target already exists: ${target}`);
+  const temporary = `${target}.skillshop-tmp-${process.pid}`;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.rmSync(temporary, { recursive: true, force: true });
+  try {
+    fs.cpSync(skill.sourceDir, temporary, { recursive: true, force: true });
+    if (overwrite) fs.rmSync(target, { recursive: true, force: true });
+    fs.renameSync(temporary, target);
+  } finally {
+    fs.rmSync(temporary, { recursive: true, force: true });
+  }
+  return { ...skill, targetDir: target, installed: !exists, updated: exists };
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export * from './specifier.js';
+export * from './library.js';
+export * from './export.js';
+export * from './import.js';

package/src/library.js

@@ -0,0 +1,250 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { normalizeSkillSpecifier, parseSkillSpecifier } from './specifier.js';
+
+export const SKILLSHOP_LIBRARY_FILE = 'skillshop.library.json';
+export const SKILLSHOP_MANIFEST_FILE = 'skillshop.manifest.mjs';
+export const SKILLSHOP_SCHEMA_VERSION = 1;
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { throw new Error(`Cannot read ${file}: ${error.message}`); }
+}
+
+function packageFile(root) { return path.join(path.resolve(root), 'package.json'); }
+function libraryFile(root) { return path.join(path.resolve(root), SKILLSHOP_LIBRARY_FILE); }
+
+function normalizeLocalSource(source) {
+  if (typeof source !== 'string' || !source.trim()) throw new Error('skill source must be a nonempty relative path');
+  const raw = source.trim().replaceAll('\\', '/');
+  if (path.posix.isAbsolute(raw)) throw new Error('skill source must be relative to the library package');
+  const normalized = path.posix.normalize(raw.replace(/^\.\//, ''));
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../')) throw new Error('skill source must stay inside the library package');
+  if (/[*?\[\]{}()!]/.test(normalized)) {
+    throw new Error('skill source must not contain npm glob metacharacters');
+  }
+  const segments = normalized.split('/');
+  const npmExcludedDirectories = new Set(['node_modules', '.git', '.svn', 'CVS']);
+  if (segments.some((segment) => npmExcludedDirectories.has(segment))) {
+    throw new Error('skill source must not live under an npm-excluded directory');
+  }
+  return `./${normalized}`;
+}
+
+function normalizeTarget(target, exportedSpecifier) {
+  if (typeof target === 'string') return normalizeLocalSource(target);
+  if (!target || typeof target !== 'object' || Array.isArray(target)) throw new Error(`Invalid export target for ${exportedSpecifier}`);
+  if (typeof target.from !== 'string' || !target.from.trim()) throw new Error(`Imported export ${exportedSpecifier} needs a package in "from"`);
+  const importedSkill = normalizeSkillSpecifier(target.skill || exportedSpecifier);
+  return { from: target.from.trim(), skill: importedSkill };
+}
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function assertNoSymlinks(directory, specifier) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.name === '.npmignore' || entry.name === '.gitignore') {
+      throw new Error(`Skill ${specifier} must not contain nested npm/git ignore files that can exclude packaged assets`);
+    }
+    const entryPath = path.join(directory, entry.name);
+    const stat = fs.lstatSync(entryPath);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Skill ${specifier} must not contain symlinks because npm packages omit symbolic links`);
+    }
+    if (stat.isDirectory()) assertNoSymlinks(entryPath, specifier);
+  }
+}
+
+function assertNoParentIgnores(root, source, specifier) {
+  // Root ignore rules are overridden by package.json#files, but nested ignore
+  // rules can still omit SKILL.md even when its directory is explicitly packed.
+  for (let directory = path.dirname(source); directory !== root; directory = path.dirname(directory)) {
+    for (const name of ['.npmignore', '.gitignore']) {
+      if (fs.existsSync(path.join(directory, name))) {
+        throw new Error(`Skill ${specifier} has nested ignore rules in ${directory} that can exclude packaged assets`);
+      }
+    }
+  }
+}
+
+function legacyRootExport(packageRoot) {
+  const realRoot = fs.realpathSync(packageRoot);
+  const requireFromPackage = createRequire(path.join(realRoot, '__skillshop_resolve__.cjs'));
+  let resolved;
+  try {
+    resolved = requireFromPackage.resolve(realRoot);
+  } catch {
+    return null;
+  }
+  const realResolved = fs.realpathSync(resolved);
+  if (!inside(realRoot, realResolved)) {
+    throw new Error('package root entry resolves outside the package');
+  }
+  const relative = path.relative(realRoot, realResolved).split(path.sep).join('/');
+  return relative ? `./${relative}` : null;
+}
+
+export function resolveLocalSkill(root, specifier, library = readSkillLibrary(root, { required: true })) {
+  const packageRoot = fs.realpathSync(path.resolve(root));
+  const normalized = normalizeSkillSpecifier(specifier);
+  const target = library.exports[normalized];
+  if (!target) throw new Error(`Skill ${normalized} is not exported by this library`);
+  if (typeof target !== 'string') throw new Error(`Skill ${normalized} is re-exported from ${target.from}, not stored locally`);
+  const source = normalizeLocalSource(target);
+  const sourceDir = path.resolve(packageRoot, source);
+  if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) throw new Error(`Skill ${normalized} source directory does not exist: ${source}`);
+  const realSource = fs.realpathSync(sourceDir);
+  if (!inside(packageRoot, realSource)) throw new Error(`Skill ${normalized} source escapes the library package`);
+  if (path.normalize(realSource) !== path.normalize(sourceDir)) {
+    throw new Error(`Skill ${normalized} source must not use symlinks because npm packages omit symbolic links`);
+  }
+  assertNoParentIgnores(packageRoot, realSource, normalized);
+  assertNoSymlinks(realSource, normalized);
+  const manifestPath = path.join(realSource, 'SKILL.md');
+  if (!fs.existsSync(manifestPath) || !fs.statSync(manifestPath).isFile()) {
+    throw new Error(`Skill ${normalized} is missing a regular SKILL.md file`);
+  }
+  return Object.freeze({ ...parseSkillSpecifier(normalized), kind: 'local', source, sourceDir: realSource, manifestPath });
+}
+
+export function readSkillLibrary(root = process.cwd(), { required = false } = {}) {
+  const file = libraryFile(root);
+  if (!fs.existsSync(file)) {
+    if (required) throw new Error(`No ${SKILLSHOP_LIBRARY_FILE} found at ${path.resolve(root)}`);
+    return { schemaVersion: SKILLSHOP_SCHEMA_VERSION, exports: {} };
+  }
+  const raw = readJson(file);
+  if (raw?.schemaVersion !== SKILLSHOP_SCHEMA_VERSION || !raw.exports || Array.isArray(raw.exports) || typeof raw.exports !== 'object') throw new Error(`${file} is not a supported Skillshop library`);
+  const exports = {};
+  for (const [specifier, target] of Object.entries(raw.exports)) {
+    const normalized = normalizeSkillSpecifier(specifier);
+    if (normalized !== specifier) throw new Error(`Skill export must use canonical specifier ${normalized}`);
+    exports[normalized] = normalizeTarget(target, normalized);
+  }
+  return { schemaVersion: SKILLSHOP_SCHEMA_VERSION, exports };
+}
+
+export function writeSkillLibrary(root, library) {
+  const file = libraryFile(root);
+  const stable = {
+    schemaVersion: SKILLSHOP_SCHEMA_VERSION,
+    exports: Object.fromEntries(Object.entries(library.exports || {}).sort(([a], [b]) => a.localeCompare(b))),
+  };
+  fs.writeFileSync(file, `${JSON.stringify(stable, null, 2)}\n`);
+  return file;
+}
+
+export function initSkillLibrary(root = process.cwd()) {
+  const packageRoot = path.resolve(root);
+  if (!fs.existsSync(packageFile(packageRoot))) throw new Error('Skillshop libraries require a package.json');
+  const file = libraryFile(packageRoot);
+  if (!fs.existsSync(file)) writeSkillLibrary(packageRoot, { exports: {} });
+  return readSkillLibrary(packageRoot, { required: true });
+}
+
+function dependencyNames(pkg) {
+  const names = new Set(Object.keys(pkg.dependencies || {}));
+  for (const name of Object.keys(pkg.peerDependencies || {})) {
+    if (pkg.peerDependenciesMeta?.[name]?.optional === true) continue;
+    names.add(name);
+  }
+  return names;
+}
+
+function validateExports(packageRoot, pkg, library) {
+  const dependencies = dependencyNames(pkg);
+  return Object.entries(library.exports).map(([specifier, target]) => {
+    if (typeof target === 'string') return resolveLocalSkill(packageRoot, specifier, library);
+    if (!dependencies.has(target.from)) throw new Error(`Re-export ${specifier} requires ${target.from} in dependencies or peerDependencies`);
+    return Object.freeze({ ...parseSkillSpecifier(specifier), kind: 'import', from: target.from, importedSpecifier: target.skill });
+  });
+}
+
+function relativeUrlPath(source) {
+  return source.split('/').map((segment) => encodeURIComponent(segment)).join('/');
+}
+
+function manifestSource(packageName, library) {
+  const importedPackages = [...new Set(
+    Object.values(library.exports)
+      .filter((target) => typeof target === 'object')
+      .map((target) => target.from),
+  )].sort();
+  const aliases = new Map(importedPackages.map((name, index) => [name, `library${index}`]));
+  const imports = importedPackages.map((name) => `import ${aliases.get(name)} from ${JSON.stringify(`${name}/skillshop`)};`).join('\n');
+  const skills = Object.entries(library.exports).sort(([a], [b]) => a.localeCompare(b)).map(([specifier, target]) => {
+    if (typeof target === 'string') {
+      const directory = target.endsWith('/') ? target : `${target}/`;
+      return `  ${JSON.stringify(specifier)}: new URL(${JSON.stringify(relativeUrlPath(directory))}, import.meta.url).href,`;
+    }
+    return `  ${JSON.stringify(specifier)}: ${aliases.get(target.from)}.skills[${JSON.stringify(target.skill)}],`;
+  }).join('\n');
+  return `// Generated by Skillshop. Do not edit by hand.\n${imports}${imports ? '\n\n' : ''}const skills = Object.freeze({\n${skills}\n});\n\nexport default Object.freeze({\n  schemaVersion: ${SKILLSHOP_SCHEMA_VERSION},\n  packageName: ${JSON.stringify(packageName)},\n  skills,\n});\n`;
+}
+
+function mergePackageExports(pkg, packageRoot) {
+  const skillshopExport = `./${SKILLSHOP_MANIFEST_FILE}`;
+  if (pkg.exports == null) {
+    const rootExport = legacyRootExport(packageRoot);
+    return rootExport
+      ? { '.': rootExport, './skillshop': skillshopExport }
+      : { './skillshop': skillshopExport };
+  }
+  if (typeof pkg.exports !== 'object' || Array.isArray(pkg.exports)) {
+    return { '.': pkg.exports, './skillshop': skillshopExport };
+  }
+  const keys = Object.keys(pkg.exports);
+  const subpaths = keys.filter((key) => key.startsWith('.'));
+  if (subpaths.length && subpaths.length !== keys.length) {
+    throw new Error('package.json exports mixes subpaths and conditions and cannot be extended safely');
+  }
+  if (!subpaths.length) return { '.': pkg.exports, './skillshop': skillshopExport };
+  return { ...pkg.exports, './skillshop': skillshopExport };
+}
+
+function nextPackageManifest(packageRoot, pkg, skills) {
+  const next = structuredClone(pkg);
+  next.exports = mergePackageExports(next, packageRoot);
+  if (Array.isArray(next.files)) {
+    const previousManaged = new Set(Array.isArray(next.skillshop?.managedFiles) ? next.skillshop.managedFiles : []);
+    const userFiles = next.files.filter((file) => !previousManaged.has(file));
+    const desired = [
+      SKILLSHOP_MANIFEST_FILE,
+      ...skills.filter((skill) => skill.kind === 'local').map((skill) => skill.source.replace(/^\.\//, '').replace(/\/$/, '')),
+    ];
+    const managedFiles = desired.filter((file) => !userFiles.includes(file));
+    next.files = [...new Set([...userFiles, ...desired])];
+    next.skillshop = { ...(next.skillshop || {}), schemaVersion: SKILLSHOP_SCHEMA_VERSION, managedFiles };
+  }
+  return next;
+}
+
+export function validateSkillLibrary(root = process.cwd()) {
+  const packageRoot = path.resolve(root);
+  const pkgPath = packageFile(packageRoot);
+  if (!fs.existsSync(pkgPath)) throw new Error('Skillshop libraries require a package.json');
+  const pkg = readJson(pkgPath);
+  if (typeof pkg.name !== 'string' || !pkg.name.trim()) throw new Error('package.json must have a package name');
+  const library = readSkillLibrary(packageRoot, { required: true });
+  const skills = validateExports(packageRoot, pkg, library);
+  return { packageName: pkg.name, library, skills };
+}
+
+export function buildSkillLibrary(root = process.cwd()) {
+  const packageRoot = path.resolve(root);
+  const { packageName, library, skills } = validateSkillLibrary(packageRoot);
+  const manifestPath = path.join(packageRoot, SKILLSHOP_MANIFEST_FILE);
+  const pkgPath = packageFile(packageRoot);
+  const pkg = readJson(pkgPath);
+
+  const nextPkg = nextPackageManifest(packageRoot, pkg, skills);
+  const nextManifest = manifestSource(packageName, library);
+
+  fs.writeFileSync(manifestPath, nextManifest);
+  fs.writeFileSync(pkgPath, `${JSON.stringify(nextPkg, null, 2)}\n`);
+  return { packageName, manifestPath, skills };
+}

package/src/specifier.js

@@ -0,0 +1,16 @@
+const SKILL_SPECIFIER = /^skill:([a-z0-9][a-z0-9._-]*)$/;
+
+export function parseSkillSpecifier(value) {
+  if (typeof value !== 'string') throw new TypeError('skill specifier must be a string');
+  const match = value.trim().match(SKILL_SPECIFIER);
+  if (!match) throw new Error(`Invalid skill specifier: ${value}. Expected skill:<name>`);
+  return Object.freeze({ specifier: `skill:${match[1]}`, name: match[1] });
+}
+
+export function normalizeSkillSpecifier(value) {
+  return parseSkillSpecifier(value).specifier;
+}
+
+export function skillName(value) {
+  return parseSkillSpecifier(value).name;
+}