@alavida/agentpack 0.1.5 → 0.1.7

package/src/lib/skills.js

@@ -19,11 +19,16 @@ import {
   removeSkillLinksByNames,
 } from '../infrastructure/runtime/materialize-skills.js';
 import {
+  buildCanonicalSkillRequirement,
   normalizeDisplayPath,
   normalizeRepoPath,
   parseSkillFrontmatterFile,
+  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,
   compareRecordedSources,
@@ -31,6 +36,10 @@ import {
   readBuildState,
   writeBuildState,
 } from '../domain/skills/skill-provenance.js';
+import { readUserConfig } from '../infrastructure/fs/user-config-repository.js';
+import { readUserCredentials } from '../infrastructure/fs/user-credentials-repository.js';
+import { getUserNpmrcPath, readUserNpmrc } from '../infrastructure/fs/user-npmrc-repository.js';
+import { resolveRegistryConfig } from '../domain/auth/registry-resolution.js';
 import { startSkillDevWorkbench } from '../application/skills/start-skill-dev-workbench.js';
 import { AgentpackError, EXIT_CODES, NetworkError, NotFoundError, ValidationError } from '../utils/errors.js';
 
@@ -89,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) {
@@ -268,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 = [];
@@ -313,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,
@@ -365,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;
@@ -638,24 +651,75 @@ function readRepoNpmRegistryConfig(repoRoot, scope = null) {
     : {};
   const scopes = scope ? [scope] : MANAGED_PACKAGE_SCOPES;
   const matchedScope = scopes.find((candidate) => config[`${candidate}:registry`]) || scope || scopes[0] || null;
+  const registry = matchedScope ? (config[`${matchedScope}:registry`] || null) : null;
+  const authKey = registry ? `//${new URL(registry).host}/:_authToken` : null;
 
   return {
     npmrcPath: existsSync(npmrcPath) ? npmrcPath : null,
     scope: matchedScope,
-    registry: matchedScope ? (config[`${matchedScope}:registry`] || null) : null,
-    authToken: config['//npm.pkg.github.com/:_authToken'] || null,
+    registry,
+    authToken: authKey ? (config[authKey] || null) : null,
     alwaysAuth: String(config['always-auth'] || '').toLowerCase() === 'true',
   };
 }
 
+function readEffectiveRegistryConfig(repoRoot, scope = null, env = process.env) {
+  const userConfig = readUserConfig({ env });
+  const userNpmrc = readUserNpmrc({ env });
+  const repoConfig = readRepoNpmRegistryConfig(repoRoot, scope);
+  const userScope = MANAGED_PACKAGE_SCOPES.find((candidate) => userNpmrc[`${candidate}:registry`]) || null;
+  const resolvedScope = scope
+    || (repoConfig.registry ? repoConfig.scope : null)
+    || userScope
+    || userConfig.scope
+    || repoConfig.scope
+    || MANAGED_PACKAGE_SCOPES[0]
+    || null;
+  const resolved = resolveRegistryConfig({
+    scope: resolvedScope,
+    defaults: {
+      registry: userConfig.registry,
+      verificationPackage: userConfig.verificationPackage,
+    },
+    userNpmrc,
+    repoNpmrc: repoConfig.registry ? {
+      [`${repoConfig.scope}:registry`]: repoConfig.registry,
+      ...(repoConfig.authToken ? { [`//${new URL(repoConfig.registry).host}/:_authToken`]: repoConfig.authToken } : {}),
+    } : {},
+  });
+
+  let npmrcPath = null;
+  if (resolved.source === 'repo') {
+    npmrcPath = repoConfig.npmrcPath;
+  } else if (resolved.source === 'user') {
+    npmrcPath = getUserNpmrcPath({ env });
+  }
+
+  const alwaysAuth = resolved.source === 'repo'
+    ? repoConfig.alwaysAuth
+    : String(userNpmrc['always-auth'] || '').toLowerCase() === 'true';
+
+  return {
+    scope: resolved.scope,
+    npmrcPath,
+    registry: resolved.registry,
+    authToken: resolved.authToken,
+    alwaysAuth,
+    source: resolved.source,
+    configured: resolved.source !== 'default' && Boolean(resolved.registry),
+  };
+}
+
 export function inspectRegistryConfig({
   cwd = process.cwd(),
   scope = null,
+  env = process.env,
 } = {}) {
   const repoRoot = findRepoRoot(cwd);
-  const { npmrcPath, scope: resolvedScope, registry, authToken, alwaysAuth } = readRepoNpmRegistryConfig(
+  const { npmrcPath, scope: resolvedScope, registry, authToken, alwaysAuth, source, configured } = readEffectiveRegistryConfig(
     repoRoot,
-    scope
+    scope,
+    env
   );
 
   let auth = {
@@ -688,10 +752,11 @@ export function inspectRegistryConfig({
     scope: resolvedScope,
     repoRoot,
     npmrcPath: npmrcPath ? normalizeDisplayPath(repoRoot, npmrcPath) : null,
-    configured: Boolean(registry),
-    registry,
+    configured,
+    registry: configured ? registry : null,
     auth,
     alwaysAuth,
+    source,
   };
 }
 
@@ -704,6 +769,22 @@ function resolveRegistryAuthToken(rawValue) {
   return rawValue;
 }
 
+function buildNpmRegistryEnv(repoRoot, env = process.env) {
+  const effective = readEffectiveRegistryConfig(repoRoot, null, env);
+  const authToken = effective.authToken || null;
+  const envMatch = authToken?.match(/^\$\{([^}]+)\}$/) || null;
+  if (!envMatch) return env;
+  if (env[envMatch[1]]) return env;
+
+  const credentials = readUserCredentials({ env });
+  if (!credentials?.token) return env;
+
+  return {
+    ...env,
+    [envMatch[1]]: credentials.token,
+  };
+}
+
 async function fetchRegistryLatestVersion(packageName, {
   registry,
   authToken,
@@ -740,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,
   };
 }
 
@@ -885,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({
@@ -949,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}`,
     });
   }
 
@@ -972,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,
   };
@@ -1024,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;
@@ -1040,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);
@@ -1113,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));
 }
 
@@ -1143,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,
@@ -1152,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 } : {}),
     };
   }
 
@@ -1173,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 } : {}),
     };
   }
 
@@ -1265,6 +1329,36 @@ function listInstalledPackageDirs(nodeModulesDir) {
   return packageDirs;
 }
 
+function findInstalledPackageDir(nodeModulesDir, packageName) {
+  if (!packageName) return null;
+  const packageDir = join(nodeModulesDir, ...packageName.split('/'));
+  return existsSync(packageDir) ? packageDir : null;
+}
+
+function resolveInstalledPackageClosure(repoRoot, directTargetMap) {
+  const nodeModulesDir = join(repoRoot, 'node_modules');
+  const queue = [...directTargetMap.keys()];
+  const seen = new Set();
+  const packageDirs = [];
+
+  while (queue.length > 0) {
+    const packageName = queue.shift();
+    if (seen.has(packageName)) continue;
+    seen.add(packageName);
+
+    const packageDir = findInstalledPackageDir(nodeModulesDir, packageName);
+    if (!packageDir) continue;
+
+    packageDirs.push(packageDir);
+    const packageMetadata = readPackageMetadata(packageDir);
+    for (const dependencyName of Object.keys(packageMetadata.dependencies || {})) {
+      queue.push(dependencyName);
+    }
+  }
+
+  return packageDirs.sort();
+}
+
 function collectLocalInstallTargets(initialTarget) {
   const resolvedTarget = resolve(initialTarget);
   const queue = [resolvedTarget];
@@ -1342,14 +1436,16 @@ export function installSkills(targets, { cwd = process.cwd() } = {}) {
 
   execFileSync('npm', ['install', '--no-save', ...uniqueInstallTargets], {
     cwd: repoRoot,
+    env: buildNpmRegistryEnv(repoRoot, process.env),
     encoding: 'utf-8',
     stdio: ['pipe', 'pipe', 'pipe'],
   });
 
+  const resolvedPackageDirs = resolveInstalledPackageClosure(repoRoot, directTargetMap);
   return rebuildInstallState(repoRoot, directTargetMap, {
-    listInstalledPackageDirs,
-    parseSkillFrontmatterFile,
+    packageDirs: resolvedPackageDirs,
     readPackageMetadata,
+    readInstalledSkillExports,
     normalizeRelativePath,
   });
 }
@@ -1360,11 +1456,14 @@ export function inspectSkillsEnv({ cwd = process.cwd() } = {}) {
   const installs = Object.entries(state.installs || {})
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([packageName, install]) => ({
-      ...readInstalledSkillLifecycle(repoRoot, install.source_package_path),
+      ...(install.skills?.length > 0
+        ? readInstalledSkillLifecycleFromRecord(install)
+        : readInstalledSkillLifecycle(repoRoot, install.source_package_path)),
       packageName,
       direct: install.direct,
       packageVersion: install.package_version,
       sourcePackagePath: install.source_package_path,
+      skills: install.skills || [],
       materializations: install.materializations || [],
     }));
 
@@ -1403,10 +1502,66 @@ function readInstalledSkillLifecycle(repoRoot, sourcePackagePath) {
   };
 }
 
+function readInstalledSkillLifecycleFromRecord(install) {
+  const primarySkill = (install.skills || []).find((entry) => entry.runtime_name === entry.name)
+    || (install.skills || [])[0]
+    || null;
+
+  if (!primarySkill) {
+    return {
+      requires: [],
+      status: null,
+      replacement: null,
+      message: null,
+    };
+  }
+
+  return {
+    requires: primarySkill.requires || [],
+    status: primarySkill.status || null,
+    replacement: primarySkill.replacement || null,
+    message: primarySkill.message || null,
+  };
+}
+
 function buildInstallCommand(packageName) {
   return `agentpack skills install ${packageName}`;
 }
 
+function buildInstalledRequirementSet(installs) {
+  const installed = new Set();
+
+  for (const install of installs) {
+    if (install.packageName) installed.add(install.packageName);
+    for (const skill of install.skills || []) {
+      const requirement = buildCanonicalSkillRequirement(install.packageName, skill.name);
+      if (requirement) installed.add(requirement);
+    }
+  }
+
+  return installed;
+}
+
+function buildInstalledRequirementRecords(installs) {
+  return installs.map((install) => {
+    const requires = new Set();
+
+    for (const skill of install.skills || []) {
+      for (const requirement of skill.requires || []) {
+        requires.add(requirement);
+      }
+    }
+
+    return {
+      packageName: install.packageName,
+      name: null,
+      skillFile: install.sourcePackagePath ? `${install.sourcePackagePath}/SKILL.md` : null,
+      direct: install.direct,
+      requires: [...requires].sort((a, b) => a.localeCompare(b)),
+    };
+  });
+}
+
 function listLocalWorkbenchSkillRecords(repoRoot) {
   const records = [];
 
@@ -1492,14 +1647,8 @@ export function inspectMissingSkillDependencies({
 } = {}) {
   const repoRoot = findRepoRoot(cwd);
   const env = inspectSkillsEnv({ cwd });
-  const installed = new Set(env.installs.map((install) => install.packageName));
-  const installedRecords = env.installs.map((install) => ({
-    packageName: install.packageName,
-    name: null,
-    skillFile: install.sourcePackagePath ? `${install.sourcePackagePath}/SKILL.md` : null,
-    direct: install.direct,
-    requires: install.requires,
-  }));
+  const installed = buildInstalledRequirementSet(env.installs);
+  const installedRecords = buildInstalledRequirementRecords(env.installs);
   const localWorkbenchRecords = listLocalWorkbenchSkillRecords(repoRoot);
 
   let records = [...installedRecords, ...localWorkbenchRecords];
@@ -1600,9 +1749,11 @@ export async function listOutdatedSkills({
 
 export async function inspectSkillsStatus({ cwd = process.cwd() } = {}) {
   const env = inspectSkillsEnv({ cwd });
+  const state = readInstallState(env.repoRoot);
   const registry = inspectRegistryConfig({ cwd });
   const outdatedResult = await listOutdatedSkills({ cwd });
   const missingResult = inspectMissingSkillDependencies({ cwd });
+  const runtimeInspection = inspectMaterializedSkills(env.repoRoot, state);
 
   const installedCount = env.installs.length;
   const directCount = env.installs.filter((install) => install.direct).length;
@@ -1619,13 +1770,23 @@ export async function inspectSkillsStatus({ cwd = process.cwd() } = {}) {
   const deprecatedCount = deprecated.length;
   const incomplete = missingResult.skills;
   const incompleteCount = missingResult.count;
+  const runtimeDrift = runtimeInspection.runtimeDrift;
+  const runtimeDriftCount = runtimeInspection.runtimeDriftCount;
+  const orphanedMaterializations = runtimeInspection.orphanedMaterializations;
+  const orphanedMaterializationCount = runtimeInspection.orphanedMaterializationCount;
 
   let health = 'healthy';
   if (!registry.configured) {
     health = installedCount > 0 || outdatedCount > 0 ? 'attention-needed' : 'needs-config';
-  } else if (outdatedCount > 0 || deprecatedCount > 0 || incompleteCount > 0) {
+  } else if (
+    outdatedCount > 0
+    || deprecatedCount > 0
+    || incompleteCount > 0
+    || runtimeDriftCount > 0
+    || orphanedMaterializationCount > 0
+  ) {
     health = 'attention-needed';
-  } else if (incompleteCount > 0) {
+  } else if (incompleteCount > 0 || runtimeDriftCount > 0 || orphanedMaterializationCount > 0) {
     health = 'attention-needed';
   }
 
@@ -1637,10 +1798,14 @@ export async function inspectSkillsStatus({ cwd = process.cwd() } = {}) {
     outdatedCount,
     deprecatedCount,
     incompleteCount,
+    runtimeDriftCount,
+    orphanedMaterializationCount,
     registry,
     outdated: outdatedResult.skills,
     deprecated,
     incomplete,
+    runtimeDrift,
+    orphanedMaterializations,
     installs: env.installs,
     health,
   };
@@ -1662,15 +1827,17 @@ export function uninstallSkills(target, { cwd = process.cwd() } = {}) {
   if (nextInstallTargets.length > 0) {
     execFileSync('npm', ['install', '--no-save', ...nextInstallTargets], {
       cwd: repoRoot,
+      env: buildNpmRegistryEnv(repoRoot, process.env),
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
     });
   }
 
+  const resolvedPackageDirs = resolveInstalledPackageClosure(repoRoot, nextDirectTargetMap);
   const nextState = rebuildInstallState(repoRoot, nextDirectTargetMap, {
-    listInstalledPackageDirs,
-    parseSkillFrontmatterFile,
+    packageDirs: resolvedPackageDirs,
     readPackageMetadata,
+    readInstalledSkillExports,
     normalizeRelativePath,
   });
   const remainingTargets = new Set(