@alavida/agentpack 0.1.6 → 0.1.7

package/bin/intent.js

@@ -1,10 +1,35 @@
 #!/usr/bin/env node
-// Auto-generated by @tanstack/intent setup
-// Exposes the intent end-user CLI for consumers of this library.
-// Commit this file, then add to your package.json:
-//   "bin": { "intent": "./bin/intent.js" }
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const intentPackageRoot = join(packageRoot, 'node_modules', '@tanstack', 'intent');
+
 try {
-  await import('@tanstack/intent/intent-library')
+  const packageJsonPath = join(intentPackageRoot, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    const error = new Error('@tanstack/intent is not installed');
+    error.code = 'MODULE_NOT_FOUND';
+    throw error;
+  }
+
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+  const cliRelativePath = typeof packageJson.bin === 'string'
+    ? packageJson.bin
+    : packageJson.bin?.intent;
+
+  if (!cliRelativePath) {
+    throw new Error('@tanstack/intent does not expose an intent cli binary');
+  }
+
+  const result = spawnSync(process.execPath, [join(intentPackageRoot, cliRelativePath), ...process.argv.slice(2)], {
+    stdio: 'inherit',
+  });
+
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 0);
 } catch (e) {
   if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') {
     console.error('@tanstack/intent is not installed.')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alavida/agentpack",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Package-backed skills lifecycle CLI for agent skills and plugins",
   "type": "module",
   "workspaces": [
@@ -23,8 +23,8 @@
     "smoke:monorepo": "node scripts/smoke-monorepo.mjs",
     "docs:dev": "cd docs && mint dev",
     "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "changeset publish",
+    "version-packages": "node scripts/version-packages.mjs",
+    "release": "node scripts/release.mjs",
     "intent:validate": "npx @tanstack/intent validate",
     "build:dashboard": "node scripts/build-dashboard.mjs"
   },

package/src/commands/skills.js

@@ -304,6 +304,19 @@ export function skillsCommand() {
         return;
       }
 
+      if (result.kind === 'package') {
+        output.write(`Package: ${result.packageName}`);
+        if (result.packageVersion) output.write(`Version: ${result.packageVersion}`);
+        output.write(`Path: ${result.packagePath}`);
+        output.write('');
+        output.write('Exports:');
+        for (const entry of result.exports) {
+          output.write(`- ${entry.name}`);
+          output.write(`  path: ${entry.skillFile}`);
+        }
+        return;
+      }
+
       output.write(`Skill: ${result.name}`);
       if (result.description) output.write(`Description: ${result.description}`);
       if (result.packageName) output.write(`Package: ${result.packageName}`);
@@ -311,6 +324,7 @@ export function skillsCommand() {
       if (result.status) output.write(`Status: ${result.status}`);
       if (result.replacement) output.write(`Replacement: ${result.replacement}`);
       if (result.message) output.write(`Message: ${result.message}`);
+      if (result.wraps) output.write(`Wraps: ${result.wraps}`);
       output.write(`Path: ${result.skillFile}`);
 
       output.write('');
@@ -328,6 +342,12 @@ export function skillsCommand() {
       } else {
         for (const requirement of result.requires) output.write(`- ${requirement}`);
       }
+
+      if (result.overrides?.length) {
+        output.write('');
+        output.write('Overrides:');
+        for (const override of result.overrides) output.write(`- ${override}`);
+      }
     });
 
   cmd
@@ -387,16 +407,26 @@ export function skillsCommand() {
       const result = validateSkillsUseCase(target);
 
       if (globalOpts.json) {
-        output.json(
-          target
-            ? result.skills[0]
-            : result
-        );
+        output.json(target && result.count === 1 ? result.skills[0] : result);
         if (!result.valid) process.exitCode = EXIT_CODES.VALIDATION;
         return;
       }
 
       if (target) {
+        if (result.count > 1) {
+          output.write(`Validated Skills: ${result.count}`);
+          output.write(`Valid Skills: ${result.validCount}`);
+          output.write(`Invalid Skills: ${result.invalidCount}`);
+          for (const skill of result.skills) {
+            output.write('');
+            output.write(`- ${skill.name || skill.packageName || skill.packagePath}`);
+            output.write(`  status: ${skill.valid ? 'valid' : 'invalid'}`);
+            output.write(`  path: ${skill.skillFile}`);
+          }
+          if (!result.valid) process.exitCode = EXIT_CODES.VALIDATION;
+          return;
+        }
+
         const skill = result.skills[0];
         output.write(`Skill: ${skill.packageName || skill.packagePath}`);
         output.write(`Status: ${skill.valid ? 'valid' : 'invalid'}`);

package/src/domain/skills/skill-catalog.js

@@ -0,0 +1,116 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  buildCanonicalSkillRequirement,
+  normalizeDisplayPath,
+  readInstalledSkillExports,
+  readPackageMetadata,
+} from './skill-model.js';
+
+function isIgnoredEntry(name) {
+  return name === '.git' || name === 'node_modules' || name === '.agentpack';
+}
+
+function listSkillPackageDirs(repoRoot, { installed = false } = {}) {
+  const root = installed ? join(repoRoot, 'node_modules') : repoRoot;
+  if (!existsSync(root)) return [];
+
+  const stack = [root];
+  const results = [];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    let hasRootSkillFile = false;
+    let packageMetadata = null;
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!installed && isIgnoredEntry(entry.name)) continue;
+        stack.push(join(current, entry.name));
+        continue;
+      }
+
+      if (entry.name === 'SKILL.md') hasRootSkillFile = true;
+      if (entry.name !== 'package.json') continue;
+
+      try {
+        packageMetadata = readPackageMetadata(current);
+      } catch {
+        packageMetadata = null;
+      }
+    }
+
+    if (!packageMetadata?.packageName) continue;
+    if (packageMetadata.exportedSkills || hasRootSkillFile) {
+      results.push(current);
+    }
+  }
+
+  return results.sort();
+}
+
+function buildCatalogKey(packageName, exportedSkills, entry) {
+  if (!packageName) return null;
+  if (exportedSkills.length <= 1) return packageName;
+  return buildCanonicalSkillRequirement(packageName, entry.name);
+}
+
+export function readSkillPackage(repoRoot, packageDir, { origin = 'authored' } = {}) {
+  const packageMetadata = readPackageMetadata(packageDir);
+  if (!packageMetadata.packageName) return null;
+
+  const exportedSkills = readInstalledSkillExports(packageDir);
+  if (exportedSkills.length === 0) return null;
+
+  return {
+    origin,
+    packageDir,
+    packagePath: normalizeDisplayPath(repoRoot, packageDir),
+    packageName: packageMetadata.packageName,
+    packageVersion: packageMetadata.packageVersion,
+    packageMetadata,
+    exports: exportedSkills.map((entry) => ({
+      ...entry,
+      key: buildCatalogKey(packageMetadata.packageName, exportedSkills, entry),
+      packageName: packageMetadata.packageName,
+      packageVersion: packageMetadata.packageVersion,
+      packageDir,
+      packagePath: normalizeDisplayPath(repoRoot, packageDir),
+      skillDirPath: entry.skillDir,
+      skillFilePath: entry.skillFile,
+      skillPath: normalizeDisplayPath(repoRoot, entry.skillDir),
+      skillFile: normalizeDisplayPath(repoRoot, entry.skillFile),
+    })),
+  };
+}
+
+export function listAuthoredSkillPackages(repoRoot) {
+  return listSkillPackageDirs(repoRoot)
+    .map((packageDir) => {
+      try {
+        return readSkillPackage(repoRoot, packageDir);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function listInstalledSkillPackages(repoRoot) {
+  return listSkillPackageDirs(repoRoot, { installed: true })
+    .map((packageDir) => {
+      try {
+        return readSkillPackage(repoRoot, packageDir, { origin: 'installed' });
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}

package/src/domain/skills/skill-model.js

@@ -149,6 +149,12 @@ export function parseSkillFrontmatterFile(skillFilePath) {
     status: typeof fields.metadata?.status === 'string' ? fields.metadata.status : null,
     replacement: typeof fields.metadata?.replacement === 'string' ? fields.metadata.replacement : null,
     message: typeof fields.metadata?.message === 'string' ? fields.metadata.message : null,
+    wraps: typeof fields.metadata?.wraps === 'string'
+      ? fields.metadata.wraps
+      : (typeof fields.wraps === 'string' ? fields.wraps : null),
+    overrides: Array.isArray(fields.metadata?.overrides)
+      ? fields.metadata.overrides
+      : (Array.isArray(fields.overrides) ? fields.overrides : []),
   };
 }
 
@@ -210,10 +216,13 @@ export function readInstalledSkillExports(packageDir) {
         declaredName,
         name: metadata.name,
         description: metadata.description,
+        sources: metadata.sources,
         requires: metadata.requires,
         status: metadata.status,
         replacement: metadata.replacement,
         message: metadata.message,
+        wraps: metadata.wraps,
+        overrides: metadata.overrides,
         skillDir: dirname(skillFile),
         skillFile,
         relativeSkillFile,
@@ -233,10 +242,13 @@ export function readInstalledSkillExports(packageDir) {
     declaredName: metadata.name,
     name: metadata.name,
     description: metadata.description,
+    sources: metadata.sources,
     requires: metadata.requires,
     status: metadata.status,
     replacement: metadata.replacement,
     message: metadata.message,
+    wraps: metadata.wraps,
+    overrides: metadata.overrides,
     skillDir: packageDir,
     skillFile: rootSkillFile,
     relativeSkillFile: 'SKILL.md',

package/src/domain/skills/skill-target-resolution.js

@@ -0,0 +1,100 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { listAuthoredSkillPackages, listInstalledSkillPackages } from './skill-catalog.js';
+import { NotFoundError, ValidationError } from '../../utils/errors.js';
+
+function dedupePackages(authoredPackages, installedPackages) {
+  const seen = new Set(authoredPackages.map((pkg) => pkg.packageName));
+  return [
+    ...authoredPackages,
+    ...installedPackages.filter((pkg) => !seen.has(pkg.packageName)),
+  ];
+}
+
+export function loadSkillTargetContext(repoRoot, {
+  includeAuthored = true,
+  includeInstalled = true,
+} = {}) {
+  const authoredPackages = includeAuthored ? listAuthoredSkillPackages(repoRoot) : [];
+  const installedPackages = includeInstalled ? listInstalledSkillPackages(repoRoot) : [];
+
+  return {
+    authoredPackages,
+    installedPackages,
+    packages: dedupePackages(authoredPackages, installedPackages),
+  };
+}
+
+function buildPackageResolution(pkg, source) {
+  return {
+    kind: 'package',
+    source,
+    package: pkg,
+    exports: pkg.exports,
+  };
+}
+
+function buildExportResolution(pkg, skillExport, source) {
+  return {
+    kind: 'export',
+    source,
+    package: pkg,
+    export: skillExport,
+    exports: [skillExport],
+  };
+}
+
+export function resolveSkillTarget(repoRoot, target, options = {}) {
+  const context = loadSkillTargetContext(repoRoot, options);
+  const { packages } = context;
+
+  if (typeof target !== 'string' || target.length === 0) {
+    throw new NotFoundError('skill not found', {
+      code: 'skill_not_found',
+      suggestion: `Target: ${target}`,
+    });
+  }
+
+  const absoluteTarget = isAbsolute(target) ? target : resolve(repoRoot, target);
+
+  if (existsSync(absoluteTarget)) {
+    for (const pkg of packages) {
+      if (pkg.packageDir === absoluteTarget) {
+        return buildPackageResolution(pkg, 'package_path');
+      }
+
+      for (const skillExport of pkg.exports) {
+        if (skillExport.skillDirPath === absoluteTarget) {
+          return buildExportResolution(pkg, skillExport, 'skill_path');
+        }
+        if (skillExport.skillFilePath === absoluteTarget) {
+          return buildExportResolution(pkg, skillExport, 'skill_file');
+        }
+      }
+    }
+  }
+
+  const pkg = packages.find((entry) => entry.packageName === target);
+  if (pkg) {
+    return buildPackageResolution(pkg, 'package_name');
+  }
+
+  throw new NotFoundError('skill not found', {
+    code: 'skill_not_found',
+    suggestion: `Target: ${target}`,
+  });
+}
+
+export function resolveSingleSkillTarget(repoRoot, target, options = {}) {
+  const resolved = resolveSkillTarget(repoRoot, target, options);
+
+  if (resolved.kind === 'export') return resolved;
+  if (resolved.exports.length === 1) {
+    return buildExportResolution(resolved.package, resolved.exports[0], resolved.source);
+  }
+
+  throw new ValidationError('ambiguous skill target', {
+    code: 'ambiguous_skill_target',
+    suggestion: resolved.exports.map((entry) => entry.skillPath).join(', '),
+  });
+}

package/src/lib/skills.js

@@ -26,6 +26,8 @@ import {
   readInstalledSkillExports,
   readPackageMetadata,
 } from '../domain/skills/skill-model.js';
+import { listAuthoredSkillPackages } from '../domain/skills/skill-catalog.js';
+import { resolveSingleSkillTarget, resolveSkillTarget } from '../domain/skills/skill-target-resolution.js';
 import { inspectMaterializedSkills } from '../infrastructure/runtime/inspect-materialized-skills.js';
 import {
   buildStateRecordForPackageDir,
@@ -96,24 +98,15 @@ function resolveDevLinkedSkills(repoRoot, rootSkillDir) {
 }
 
 function resolveLocalPackagedSkillDir(repoRoot, target) {
-  const skillFile = resolveSkillFileTarget(repoRoot, target);
-  if (!skillFile) {
-    throw new AgentpackError(`SKILL.md not found for target: ${target}`, {
-      code: 'skill_not_found',
-      exitCode: EXIT_CODES.GENERAL,
-    });
-  }
-
-  const skillDir = dirname(skillFile);
-  const packageJsonPath = join(skillDir, 'package.json');
-  if (!existsSync(packageJsonPath)) {
-    throw new AgentpackError(`package.json not found: ${packageJsonPath}`, {
-      code: 'package_json_not_found',
-      exitCode: EXIT_CODES.GENERAL,
-    });
-  }
-
-  return { skillDir, skillFile, packageJsonPath };
+  const resolved = resolveSingleSkillTarget(repoRoot, target, { includeInstalled: false });
+  return {
+    skillDir: resolved.export.skillDirPath,
+    skillFile: resolved.export.skillFilePath,
+    packageDir: resolved.package.packageDir,
+    packageJsonPath: join(resolved.package.packageDir, 'package.json'),
+    packageName: resolved.package.packageName,
+    skillName: resolved.export.name,
+  };
 }
 
 function resolveSkillFileTarget(repoRoot, target) {
@@ -275,11 +268,11 @@ function reconcileDevSession(repoRoot) {
 }
 
 export function syncSkillDependencies(skillDir) {
-  const skillFile = join(skillDir, 'SKILL.md');
-  const metadata = parseSkillFrontmatterFile(skillFile);
+  const required = [...new Set(
+    readInstalledSkillExports(skillDir).flatMap((entry) => entry.requires || [])
+  )].sort((a, b) => a.localeCompare(b));
   const { packageJsonPath, packageJson } = readPackageJson(skillDir);
   const nextDependencies = { ...(packageJson.dependencies || {}) };
-  const required = [...new Set(metadata.requires || [])].sort((a, b) => a.localeCompare(b));
   const requiredSet = new Set(required);
   const added = [];
   const removed = [];
@@ -320,14 +313,14 @@ export function devSkill(target, {
 } = {}) {
   const repoRoot = findRepoRoot(cwd);
   try {
-    const { skillDir } = resolveLocalPackagedSkillDir(repoRoot, target);
+    const { skillDir, packageDir } = resolveLocalPackagedSkillDir(repoRoot, target);
     const { linkedSkills, unresolved } = resolveDevLinkedSkills(repoRoot, skillDir);
     const rootSkill = linkedSkills.find((entry) => entry.skillDir === skillDir);
     const synced = sync
-      ? syncSkillDependencies(skillDir)
+      ? syncSkillDependencies(packageDir)
       : {
-        skillDir,
-        packageJsonPath: join(skillDir, 'package.json'),
+        skillDir: packageDir,
+        packageJsonPath: join(packageDir, 'package.json'),
         added: [],
         removed: [],
         unchanged: true,
@@ -372,7 +365,20 @@ export function startSkillDev(target, {
   onRebuild = () => {},
 } = {}) {
   const outerRepoRoot = findRepoRoot(cwd);
-  const { skillDir } = resolveLocalPackagedSkillDir(outerRepoRoot, target);
+  let skillDir;
+  try {
+    ({ skillDir } = resolveLocalPackagedSkillDir(outerRepoRoot, target));
+  } catch (error) {
+    if (error instanceof AgentpackError && error.exitCode === EXIT_CODES.GENERAL) {
+      throw error;
+    }
+
+    throw new AgentpackError(error.message, {
+      code: error.code || 'skill_dev_failed',
+      exitCode: EXIT_CODES.GENERAL,
+      suggestion: error.suggestion,
+    });
+  }
   const repoRoot = findRepoRoot(skillDir);
   reconcileDevSession(repoRoot);
   let closed = false;
@@ -815,37 +821,40 @@ async function fetchRegistryLatestVersion(packageName, {
 
 export function inspectSkill(target, { cwd = process.cwd() } = {}) {
   const repoRoot = findRepoRoot(cwd);
+  const resolved = resolveSkillTarget(repoRoot, target);
 
-  let skillFile = resolveSkillFileTarget(repoRoot, target);
-
-  if (!skillFile && target.startsWith('@')) {
-    const packageDir = findPackageDirByName(repoRoot, target);
-    if (packageDir) {
-      skillFile = join(packageDir, 'SKILL.md');
-    }
-  }
-
-  if (!skillFile) {
-    throw new NotFoundError('skill not found', {
-      code: 'skill_not_found',
-      suggestion: `Target: ${target}`,
-    });
+  if (resolved.kind === 'package' && resolved.exports.length > 1) {
+    return {
+      kind: 'package',
+      packageName: resolved.package.packageName,
+      packageVersion: resolved.package.packageVersion,
+      packagePath: resolved.package.packagePath,
+      exports: resolved.exports.map((entry) => ({
+        name: entry.name,
+        declaredName: entry.declaredName,
+        skillFile: entry.skillFile,
+        skillPath: entry.skillPath,
+        requires: entry.requires,
+      })),
+    };
   }
 
-  const metadata = parseSkillFrontmatterFile(skillFile);
-  const packageMetadata = readPackageMetadata(dirname(skillFile));
+  const entry = resolved.kind === 'export' ? resolved.export : resolved.exports[0];
 
   return {
-    name: metadata.name,
-    description: metadata.description,
-    packageName: packageMetadata.packageName,
-    packageVersion: packageMetadata.packageVersion,
-    skillFile: normalizeDisplayPath(repoRoot, skillFile),
-    sources: metadata.sources,
-    requires: metadata.requires,
-    status: metadata.status,
-    replacement: metadata.replacement,
-    message: metadata.message,
+    kind: 'export',
+    name: entry.name,
+    description: entry.description,
+    packageName: resolved.package.packageName,
+    packageVersion: resolved.package.packageVersion,
+    skillFile: entry.skillFile,
+    sources: entry.sources,
+    requires: entry.requires,
+    status: entry.status,
+    replacement: entry.replacement,
+    message: entry.message,
+    wraps: entry.wraps,
+    overrides: entry.overrides,
   };
 }
 
@@ -960,55 +969,14 @@ export function inspectSkillDependencies(target, {
   };
 }
 
-function resolvePackagedSkillTarget(repoRoot, target) {
-  let skillFile = null;
-
-  if (target) {
-    skillFile = resolveSkillFileTarget(repoRoot, target);
-
-    if (!skillFile && target.startsWith('@')) {
-      const packageDir = findPackageDirByName(repoRoot, target);
-      if (packageDir) {
-        skillFile = join(packageDir, 'SKILL.md');
-      }
-    }
-
-    if (!skillFile) {
-      throw new NotFoundError('skill not found', {
-        code: 'skill_not_found',
-        suggestion: `Target: ${target}`,
-      });
-    }
-
-    const packageDir = dirname(skillFile);
-    const packageMetadata = readPackageMetadata(packageDir);
-    if (!packageMetadata.packageName) {
-      throw new ValidationError('validate target is not a packaged skill', {
-        code: 'invalid_validate_target',
-        suggestion: `Target: ${target}`,
-      });
-    }
-
-    return [packageDir];
-  }
-
-  return listPackagedSkillDirs(repoRoot);
+function isPublishedSkillFile(files, relativeSkillFile) {
+  if (!files) return true;
+  return files.some((entry) => entry === relativeSkillFile || relativeSkillFile.startsWith(`${entry}/`));
 }
 
-function validatePackagedSkillDir(repoRoot, packageDir) {
-  const skillFile = join(packageDir, 'SKILL.md');
-  const packageMetadata = readPackageMetadata(packageDir);
+function validatePackagedSkillExport(repoRoot, pkg, skillExport) {
+  const packageMetadata = readPackageMetadata(pkg.packageDir);
   const issues = [];
-  let skillMetadata = null;
-
-  try {
-    skillMetadata = parseSkillFrontmatterFile(skillFile);
-  } catch (error) {
-    issues.push({
-      code: error.code || 'invalid_skill_file',
-      message: error.message,
-    });
-  }
 
   if (!packageMetadata.packageName) {
     issues.push({
@@ -1024,10 +992,10 @@ function validatePackagedSkillDir(repoRoot, packageDir) {
     });
   }
 
-  if (packageMetadata.files && !packageMetadata.files.includes('SKILL.md')) {
+  if (!isPublishedSkillFile(packageMetadata.files, skillExport.relativeSkillFile)) {
     issues.push({
       code: 'skill_not_published',
-      message: 'package.json files does not include SKILL.md',
+      message: `package.json files does not include ${skillExport.relativeSkillFile}`,
     });
   }
 
@@ -1047,51 +1015,50 @@ function validatePackagedSkillDir(repoRoot, packageDir) {
     }
   }
 
-  if (skillMetadata) {
-    if (skillMetadata.status && !['deprecated', 'retired'].includes(skillMetadata.status)) {
+  if (skillExport.status && !['deprecated', 'retired'].includes(skillExport.status)) {
+    issues.push({
+      code: 'invalid_skill_status',
+      message: 'metadata.status must be "deprecated" or "retired"',
+    });
+  }
+
+  if (skillExport.replacement && !skillExport.replacement.startsWith('@')) {
+    issues.push({
+      code: 'invalid_replacement',
+      message: 'metadata.replacement must be a package name',
+    });
+  }
+
+  for (const sourcePath of skillExport.sources || []) {
+    if (!existsSync(join(repoRoot, sourcePath))) {
       issues.push({
-        code: 'invalid_skill_status',
-        message: 'metadata.status must be "deprecated" or "retired"',
+        code: 'missing_source',
+        message: 'declared source file does not exist',
+        path: sourcePath,
       });
     }
+  }
 
-    if (skillMetadata.replacement && !skillMetadata.replacement.startsWith('@')) {
+  for (const requirement of skillExport.requires || []) {
+    if (!packageMetadata.dependencies[requirement]) {
       issues.push({
-        code: 'invalid_replacement',
-        message: 'metadata.replacement must be a package name',
+        code: 'missing_dependency_declaration',
+        message: 'required skill is not declared in package dependencies',
+        dependency: requirement,
       });
     }
-
-    for (const sourcePath of skillMetadata.sources) {
-      if (!existsSync(join(repoRoot, sourcePath))) {
-        issues.push({
-          code: 'missing_source',
-          message: 'declared source file does not exist',
-          path: sourcePath,
-        });
-      }
-    }
-
-    for (const requirement of skillMetadata.requires) {
-      if (!packageMetadata.dependencies[requirement]) {
-        issues.push({
-          code: 'missing_dependency_declaration',
-          message: 'required skill is not declared in package dependencies',
-          dependency: requirement,
-        });
-      }
-    }
   }
 
   return {
     valid: issues.length === 0,
-    name: skillMetadata?.name || null,
+    key: skillExport.key,
+    name: skillExport.name || null,
     packageName: packageMetadata.packageName,
     packageVersion: packageMetadata.packageVersion,
-    skillFile: normalizeDisplayPath(repoRoot, skillFile),
-    packagePath: normalizeDisplayPath(repoRoot, packageDir),
-    status: skillMetadata?.status || null,
-    replacement: skillMetadata?.replacement || null,
+    skillFile: skillExport.skillFile,
+    packagePath: pkg.packagePath,
+    status: skillExport.status || null,
+    replacement: skillExport.replacement || null,
     nextSteps: buildValidateNextSteps(packageMetadata, issues.length === 0),
     issues,
   };
@@ -1099,15 +1066,25 @@ function validatePackagedSkillDir(repoRoot, packageDir) {
 
 export function validateSkills(target, { cwd = process.cwd() } = {}) {
   const repoRoot = findRepoRoot(cwd);
-  const packageDirs = resolvePackagedSkillTarget(repoRoot, target);
+  let targets = [];
 
-  for (const packageDir of packageDirs) {
+  if (target) {
+    const resolved = resolveSkillTarget(repoRoot, target, { includeInstalled: false });
+    targets = resolved.kind === 'export'
+      ? [{ package: resolved.package, export: resolved.export }]
+      : resolved.exports.map((entry) => ({ package: resolved.package, export: entry }));
+  } else {
+    targets = listAuthoredSkillPackages(repoRoot)
+      .flatMap((pkg) => pkg.exports.map((entry) => ({ package: pkg, export: entry })));
+  }
+
+  for (const packageDir of [...new Set(targets.map((entry) => entry.package.packageDir))]) {
     syncSkillDependencies(packageDir);
   }
 
-  const skills = packageDirs
-    .map((packageDir) => validatePackagedSkillDir(repoRoot, packageDir))
-    .sort((a, b) => (a.packageName || a.packagePath).localeCompare(b.packageName || b.packagePath));
+  const skills = targets
+    .map((entry) => validatePackagedSkillExport(repoRoot, entry.package, entry.export))
+    .sort((a, b) => (a.key || a.packageName || a.packagePath).localeCompare(b.key || b.packageName || b.packagePath));
 
   const validCount = skills.filter((skill) => skill.valid).length;
   const invalidCount = skills.length - validCount;
@@ -1115,18 +1092,32 @@ export function validateSkills(target, { cwd = process.cwd() } = {}) {
   if (validCount > 0) {
     const buildState = readBuildState(repoRoot);
 
-    for (const packageDir of packageDirs) {
-      const packageMetadata = readPackageMetadata(packageDir);
-      const result = skills.find((skill) => skill.packageName === packageMetadata.packageName);
+    if (!target) {
+      const authoredKeys = new Set(targets.map((entry) => entry.export.key));
+      for (const key of Object.keys(buildState.skills || {})) {
+        if (authoredKeys.has(key)) continue;
+        delete buildState.skills[key];
+      }
+    }
+
+    for (const targetEntry of targets) {
+      const result = skills.find((skill) => skill.key === targetEntry.export.key);
       if (!result?.valid) continue;
 
-      const { packageName, record } = buildStateRecordForPackageDir(repoRoot, packageDir, {
-        parseSkillFrontmatterFile,
-        readPackageMetadata,
-        normalizeDisplayPath,
-      });
-      if (!packageName) continue;
-      buildState.skills[packageName] = record;
+      const sources = {};
+      for (const sourcePath of targetEntry.export.sources || []) {
+        sources[sourcePath] = {
+          hash: hashFile(join(repoRoot, sourcePath)),
+        };
+      }
+
+      buildState.skills[targetEntry.export.key] = {
+        package_version: targetEntry.package.packageVersion,
+        skill_path: targetEntry.export.skillPath,
+        skill_file: targetEntry.export.skillFile,
+        sources,
+        requires: targetEntry.export.requires,
+      };
     }
 
     writeBuildState(repoRoot, buildState);
@@ -1188,28 +1179,22 @@ function listPackagedSkillDirs(repoRoot) {
 }
 
 function listAuthoredPackagedSkills(repoRoot) {
-  return listPackagedSkillDirs(repoRoot)
-    .map((packageDir) => {
-      const skillFile = join(packageDir, 'SKILL.md');
-      const metadata = parseSkillFrontmatterFile(skillFile);
-      const packageMetadata = readPackageMetadata(packageDir);
-
-      if (!packageMetadata.packageName || !packageMetadata.packageVersion) {
-        return null;
-      }
-
-      return {
-        name: metadata.name,
-        description: metadata.description,
-        packageName: packageMetadata.packageName,
-        packageVersion: packageMetadata.packageVersion,
-        skillPath: normalizeDisplayPath(repoRoot, packageDir),
-        skillFile: normalizeDisplayPath(repoRoot, skillFile),
-        sources: metadata.sources,
-        requires: metadata.requires,
-      };
-    })
-    .filter(Boolean)
+  return listAuthoredSkillPackages(repoRoot)
+    .flatMap((pkg) => pkg.exports.map((entry) => ({
+      key: entry.key,
+      name: entry.name,
+      description: entry.description,
+      packageName: entry.packageName,
+      packageVersion: entry.packageVersion,
+      skillPath: entry.skillPath,
+      skillFile: entry.skillFile,
+      sources: entry.sources,
+      requires: entry.requires,
+      wraps: entry.wraps,
+      overrides: entry.overrides,
+      declaredName: entry.declaredName,
+      packagePath: pkg.packagePath,
+    })))
     .sort((a, b) => a.packageName.localeCompare(b.packageName));
 }
 
@@ -1218,7 +1203,7 @@ export function generateSkillsCatalog({ cwd = process.cwd() } = {}) {
   const skills = {};
 
   for (const skill of listAuthoredPackagedSkills(repoRoot)) {
-    skills[skill.packageName] = {
+    skills[skill.key] = {
       name: skill.name,
       description: skill.description,
       path: skill.skillPath,
@@ -1227,6 +1212,8 @@ export function generateSkillsCatalog({ cwd = process.cwd() } = {}) {
       package_version: skill.packageVersion,
       sources: skill.sources,
       requires: skill.requires,
+      ...(skill.wraps ? { wraps: skill.wraps } : {}),
+      ...(skill.overrides?.length ? { overrides: skill.overrides } : {}),
     };
   }
 
@@ -1248,12 +1235,14 @@ export function generateBuildState({ cwd = process.cwd() } = {}) {
       };
     }
 
-    skills[skill.packageName] = {
+    skills[skill.key] = {
       package_version: skill.packageVersion,
       skill_path: skill.skillPath,
       skill_file: skill.skillFile,
       sources,
       requires: skill.requires,
+      ...(skill.wraps ? { wraps: skill.wraps } : {}),
+      ...(skill.overrides?.length ? { overrides: skill.overrides } : {}),
     };
   }