@skild/core 0.2.9 → 0.4.1

package/dist/index.d.ts

@@ -144,6 +144,29 @@ declare function normalizeAlias(input: unknown): string | null;
 declare function isValidAlias(input: string): boolean;
 declare function assertValidAlias(input: string): void;
 
+declare function materializeSourceToDir(input: {
+    source: string;
+    targetDir: string;
+    materializedDir?: string | null;
+}): Promise<{
+    sourceType: SourceType;
+    materializedFrom: string;
+}>;
+declare function materializeSourceToTemp(source: string): Promise<{
+    dir: string;
+    cleanup: () => void;
+    sourceType: SourceType;
+}>;
+
+declare function toDegitPath(url: string): string;
+/**
+ * Derive a child source spec from a base source and a relative path.
+ *
+ * - GitHub URLs are converted to degit shorthand so the result is a valid install source.
+ * - Keeps `#ref` when present.
+ */
+declare function deriveChildSource(baseSource: string, relPath: string): string;
+
 declare const DEFAULT_REGISTRY_URL = "https://registry.skild.sh";
 interface RegistrySpecifier {
     canonicalName: string;
@@ -183,6 +206,12 @@ declare function downloadAndExtractTarball(resolved: RegistryResolvedVersion, te
 interface InstallInput {
     source: string;
     nameOverride?: string;
+    /**
+     * Optional local directory containing the already-fetched source content.
+     * When provided, Skild will copy from this directory but still record `source`
+     * and `sourceType` based on the original `source` string (useful for multi-skill installs).
+     */
+    materializedDir?: string;
 }
 declare function installSkill(input: InstallInput, options?: InstallOptions): Promise<InstallRecord>;
 declare function installRegistrySkill(input: {
@@ -215,4 +244,4 @@ declare function uninstallSkill(name: string, options?: InstallOptions & {
 }): void;
 declare function updateSkill(name?: string, options?: UpdateOptions): Promise<InstallRecord[]>;
 
-export { DEFAULT_REGISTRY_URL, type DependencySourceType, type GlobalConfig, type InstallOptions, type InstallRecord, type InstallScope, type InstalledDependency, type ListOptions, type Lockfile, PLATFORMS, type Platform, type RegistryAuth, SkildError, type SkillFrontmatter, type SkillValidationIssue, type SkillValidationResult, type UpdateOptions, assertValidAlias, canonicalNameToInstallDirName, clearRegistryAuth, downloadAndExtractTarball, fetchWithTimeout, getSkillInfo, getSkillInstallDir, getSkillsDir, initSkill, installRegistrySkill, installSkill, isValidAlias, listAllSkills, listSkills, loadOrCreateGlobalConfig, loadRegistryAuth, normalizeAlias, parseRegistrySpecifier, resolveRegistryAlias, resolveRegistryUrl, resolveRegistryVersion, saveRegistryAuth, searchRegistrySkills, splitCanonicalName, uninstallSkill, updateSkill, validateSkill, validateSkillDir };
+export { DEFAULT_REGISTRY_URL, type DependencySourceType, type GlobalConfig, type InstallOptions, type InstallRecord, type InstallScope, type InstalledDependency, type ListOptions, type Lockfile, PLATFORMS, type Platform, type RegistryAuth, SkildError, type SkillFrontmatter, type SkillValidationIssue, type SkillValidationResult, type UpdateOptions, assertValidAlias, canonicalNameToInstallDirName, clearRegistryAuth, deriveChildSource, downloadAndExtractTarball, fetchWithTimeout, getSkillInfo, getSkillInstallDir, getSkillsDir, initSkill, installRegistrySkill, installSkill, isValidAlias, listAllSkills, listSkills, loadOrCreateGlobalConfig, loadRegistryAuth, materializeSourceToDir, materializeSourceToTemp, normalizeAlias, parseRegistrySpecifier, resolveRegistryAlias, resolveRegistryUrl, resolveRegistryVersion, saveRegistryAuth, searchRegistrySkills, splitCanonicalName, toDegitPath, uninstallSkill, updateSkill, validateSkill, validateSkillDir };

package/dist/index.js

@@ -289,10 +289,215 @@ function assertValidAlias(input) {
   }
 }
 
-// src/registry.ts
+// src/materialize.ts
+import fs6 from "fs";
+import os2 from "os";
+import path7 from "path";
+import degit from "degit";
+
+// src/source.ts
+import path6 from "path";
+
+// src/fs.ts
 import fs5 from "fs";
 import path5 from "path";
 import crypto from "crypto";
+function pathExists(filePath) {
+  return fs5.existsSync(filePath);
+}
+function isDirectory(filePath) {
+  try {
+    return fs5.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function isDirEmpty(dir) {
+  try {
+    const entries = fs5.readdirSync(dir);
+    return entries.length === 0;
+  } catch {
+    return true;
+  }
+}
+function copyDir(src, dest) {
+  fs5.cpSync(src, dest, { recursive: true });
+}
+function removeDir(dir) {
+  if (fs5.existsSync(dir)) fs5.rmSync(dir, { recursive: true, force: true });
+}
+function sanitizeForPathSegment(value) {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function createTempDir(parentDir, prefix) {
+  ensureDir(parentDir);
+  const safePrefix = sanitizeForPathSegment(prefix || "tmp");
+  const template = path5.join(parentDir, `.skild-${safePrefix}-`);
+  return fs5.mkdtempSync(template);
+}
+function replaceDirAtomic(sourceDir, destDir) {
+  const backupDir = fs5.existsSync(destDir) ? `${destDir}.bak-${Date.now()}` : null;
+  try {
+    if (backupDir) fs5.renameSync(destDir, backupDir);
+    fs5.renameSync(sourceDir, destDir);
+    if (backupDir) removeDir(backupDir);
+  } catch (error) {
+    try {
+      if (!fs5.existsSync(destDir) && backupDir && fs5.existsSync(backupDir)) {
+        fs5.renameSync(backupDir, destDir);
+      }
+    } catch {
+    }
+    try {
+      if (fs5.existsSync(sourceDir)) removeDir(sourceDir);
+    } catch {
+    }
+    throw error;
+  }
+}
+function listFilesRecursive(rootDir) {
+  const results = [];
+  const stack = [rootDir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = fs5.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === ".skild") continue;
+      if (entry.name === ".git") continue;
+      const full = path5.join(current, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile()) results.push(full);
+    }
+  }
+  results.sort();
+  return results;
+}
+function hashDirectoryContent(rootDir) {
+  const files = listFilesRecursive(rootDir);
+  const h = crypto.createHash("sha256");
+  for (const filePath of files) {
+    const rel = path5.relative(rootDir, filePath);
+    h.update(rel);
+    h.update("\0");
+    h.update(fs5.readFileSync(filePath));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+
+// src/source.ts
+function resolveLocalPath(source) {
+  const resolved = path6.resolve(source);
+  return pathExists(resolved) ? resolved : null;
+}
+function classifySource(source) {
+  const local = resolveLocalPath(source);
+  if (local) return "local";
+  if (/^https?:\/\//i.test(source) || source.includes("github.com")) return "github-url";
+  if (/^[^/]+\/[^/]+/.test(source)) return "degit-shorthand";
+  throw new SkildError(
+    "INVALID_SOURCE",
+    `Unsupported source "${source}". Use a Git URL (e.g. https://github.com/owner/repo/tree/<branch>/<subdir>) or degit shorthand (e.g. owner/repo[/subdir][#ref]) or a local directory.`
+  );
+}
+function extractSkillName(source) {
+  const local = resolveLocalPath(source);
+  if (local) return path6.basename(local) || "unknown-skill";
+  const cleaned = source.replace(/[#?].*$/, "");
+  const treeMatch = cleaned.match(/\/tree\/[^/]+\/(.+?)(?:\/)?$/);
+  if (treeMatch) return treeMatch[1].split("/").pop() || "unknown-skill";
+  const repoMatch = cleaned.match(/github\.com\/[^/]+\/([^/]+)/);
+  if (repoMatch) return repoMatch[1].replace(/\.git$/, "");
+  const parts = cleaned.split("/").filter(Boolean);
+  if (parts.length >= 2) return parts[parts.length - 1] || "unknown-skill";
+  return cleaned || "unknown-skill";
+}
+function toDegitPath(url) {
+  const treeMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)\/(.+?)(?:\/)?$/);
+  if (treeMatch) {
+    const [, owner, repo, branch, subpath] = treeMatch;
+    return `${owner}/${repo}/${subpath}#${branch}`;
+  }
+  const treeRootMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)(?:\/)?$/);
+  if (treeRootMatch) {
+    const [, owner, repo, branch] = treeRootMatch;
+    return `${owner}/${repo}#${branch}`;
+  }
+  const repoMatch = url.match(/github\.com\/([^/]+\/[^/]+)/);
+  if (repoMatch) return repoMatch[1].replace(/\.git$/, "");
+  return url;
+}
+function normalizeRelPath(relPath) {
+  return relPath.split(path6.sep).join("/").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function deriveChildSource(baseSource, relPath) {
+  const baseType = classifySource(baseSource);
+  const baseSpec = baseType === "github-url" ? toDegitPath(baseSource) : baseSource;
+  const [pathPart, ref] = baseSpec.split("#", 2);
+  const clean = normalizeRelPath(relPath);
+  const joined = clean ? `${pathPart.replace(/\/+$/, "")}/${clean}` : pathPart;
+  return ref ? `${joined}#${ref}` : joined;
+}
+
+// src/materialize.ts
+function ensureInstallableDir(sourcePath) {
+  if (!isDirectory(sourcePath)) {
+    throw new SkildError("NOT_A_DIRECTORY", `Source path is not a directory: ${sourcePath}`, { sourcePath });
+  }
+}
+async function cloneRemote(degitSrc, targetPath) {
+  const emitter = degit(degitSrc, { force: true, verbose: false });
+  await emitter.clone(targetPath);
+}
+async function materializeSourceToDir(input) {
+  const sourceType = classifySource(input.source);
+  const targetDir = path7.resolve(input.targetDir);
+  fs6.mkdirSync(targetDir, { recursive: true });
+  const overridden = input.materializedDir?.trim() ? path7.resolve(input.materializedDir.trim()) : null;
+  if (overridden) {
+    ensureInstallableDir(overridden);
+    copyDir(overridden, targetDir);
+    return { sourceType, materializedFrom: overridden };
+  }
+  const localPath = resolveLocalPath(input.source);
+  if (localPath) {
+    ensureInstallableDir(localPath);
+    copyDir(localPath, targetDir);
+    return { sourceType: "local", materializedFrom: localPath };
+  }
+  const degitPath = toDegitPath(input.source);
+  await cloneRemote(degitPath, targetDir);
+  return { sourceType, materializedFrom: degitPath };
+}
+async function materializeSourceToTemp(source) {
+  const sourceType = classifySource(source);
+  const tempParent = path7.join(os2.tmpdir(), "skild-materialize");
+  const tempRoot = createTempDir(tempParent, extractSkillName(source));
+  const dir = path7.join(tempRoot, "staging");
+  fs6.mkdirSync(dir, { recursive: true });
+  try {
+    await materializeSourceToDir({ source, targetDir: dir });
+    if (isDirEmpty(dir)) {
+      throw new SkildError(
+        "EMPTY_INSTALL_DIR",
+        `Installed directory is empty for source: ${source}
+Source likely does not point to a valid subdirectory.
+Try: https://github.com/<owner>/<repo>/tree/<branch>/skills/<skill-name>
+Example: https://github.com/anthropics/skills/tree/main/skills/pdf`,
+        { source }
+      );
+    }
+    return { dir, sourceType, cleanup: () => removeDir(tempRoot) };
+  } catch (e) {
+    removeDir(tempRoot);
+    throw e;
+  }
+}
+
+// src/registry.ts
+import fs7 from "fs";
+import path8 from "path";
+import crypto2 from "crypto";
 import * as tar from "tar";
 import semver from "semver";
 var DEFAULT_REGISTRY_URL = "https://registry.skild.sh";
@@ -369,7 +574,7 @@ async function resolveRegistryVersion(registryUrl, spec) {
   return { canonicalName: spec.canonicalName, version: json.version, integrity: json.integrity, tarballUrl, publishedAt: json.publishedAt };
 }
 function sha256Hex(buffer) {
-  const h = crypto.createHash("sha256");
+  const h = crypto2.createHash("sha256");
   h.update(buffer);
   return h.digest("hex");
 }
@@ -422,9 +627,9 @@ async function downloadAndExtractTarball(resolved, tempRoot, stagingDir) {
       `Integrity mismatch for ${resolved.canonicalName}@${resolved.version}. Expected ${resolved.integrity}, got ${computed}.`
     );
   }
-  const tarballPath = path5.join(tempRoot, "skill.tgz");
-  fs5.mkdirSync(stagingDir, { recursive: true });
-  fs5.writeFileSync(tarballPath, buf);
+  const tarballPath = path8.join(tempRoot, "skill.tgz");
+  fs7.mkdirSync(stagingDir, { recursive: true });
+  fs7.writeFileSync(tarballPath, buf);
   try {
     await tar.x({ file: tarballPath, cwd: stagingDir, gzip: true });
   } catch (error) {
@@ -433,139 +638,8 @@ async function downloadAndExtractTarball(resolved, tempRoot, stagingDir) {
 }
 
 // src/lifecycle.ts
-import path8 from "path";
-import fs7 from "fs";
-import degit from "degit";
-
-// src/source.ts
-import path7 from "path";
-
-// src/fs.ts
-import fs6 from "fs";
-import path6 from "path";
-import crypto2 from "crypto";
-function pathExists(filePath) {
-  return fs6.existsSync(filePath);
-}
-function isDirectory(filePath) {
-  try {
-    return fs6.statSync(filePath).isDirectory();
-  } catch {
-    return false;
-  }
-}
-function isDirEmpty(dir) {
-  try {
-    const entries = fs6.readdirSync(dir);
-    return entries.length === 0;
-  } catch {
-    return true;
-  }
-}
-function copyDir(src, dest) {
-  fs6.cpSync(src, dest, { recursive: true });
-}
-function removeDir(dir) {
-  if (fs6.existsSync(dir)) fs6.rmSync(dir, { recursive: true, force: true });
-}
-function sanitizeForPathSegment(value) {
-  return value.replace(/[^a-zA-Z0-9._-]/g, "_");
-}
-function createTempDir(parentDir, prefix) {
-  ensureDir(parentDir);
-  const safePrefix = sanitizeForPathSegment(prefix || "tmp");
-  const template = path6.join(parentDir, `.skild-${safePrefix}-`);
-  return fs6.mkdtempSync(template);
-}
-function replaceDirAtomic(sourceDir, destDir) {
-  const backupDir = fs6.existsSync(destDir) ? `${destDir}.bak-${Date.now()}` : null;
-  try {
-    if (backupDir) fs6.renameSync(destDir, backupDir);
-    fs6.renameSync(sourceDir, destDir);
-    if (backupDir) removeDir(backupDir);
-  } catch (error) {
-    try {
-      if (!fs6.existsSync(destDir) && backupDir && fs6.existsSync(backupDir)) {
-        fs6.renameSync(backupDir, destDir);
-      }
-    } catch {
-    }
-    try {
-      if (fs6.existsSync(sourceDir)) removeDir(sourceDir);
-    } catch {
-    }
-    throw error;
-  }
-}
-function listFilesRecursive(rootDir) {
-  const results = [];
-  const stack = [rootDir];
-  while (stack.length) {
-    const current = stack.pop();
-    const entries = fs6.readdirSync(current, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.name === ".skild") continue;
-      if (entry.name === ".git") continue;
-      const full = path6.join(current, entry.name);
-      if (entry.isDirectory()) stack.push(full);
-      else if (entry.isFile()) results.push(full);
-    }
-  }
-  results.sort();
-  return results;
-}
-function hashDirectoryContent(rootDir) {
-  const files = listFilesRecursive(rootDir);
-  const h = crypto2.createHash("sha256");
-  for (const filePath of files) {
-    const rel = path6.relative(rootDir, filePath);
-    h.update(rel);
-    h.update("\0");
-    h.update(fs6.readFileSync(filePath));
-    h.update("\0");
-  }
-  return h.digest("hex");
-}
-
-// src/source.ts
-function resolveLocalPath(source) {
-  const resolved = path7.resolve(source);
-  return pathExists(resolved) ? resolved : null;
-}
-function classifySource(source) {
-  const local = resolveLocalPath(source);
-  if (local) return "local";
-  if (/^https?:\/\//i.test(source) || source.includes("github.com")) return "github-url";
-  if (/^[^/]+\/[^/]+/.test(source)) return "degit-shorthand";
-  throw new SkildError(
-    "INVALID_SOURCE",
-    `Unsupported source "${source}". Use a Git URL (e.g. https://github.com/owner/repo/tree/<branch>/<subdir>) or degit shorthand (e.g. owner/repo[/subdir][#ref]) or a local directory.`
-  );
-}
-function extractSkillName(source) {
-  const local = resolveLocalPath(source);
-  if (local) return path7.basename(local) || "unknown-skill";
-  const cleaned = source.replace(/[#?].*$/, "");
-  const treeMatch = cleaned.match(/\/tree\/[^/]+\/(.+?)(?:\/)?$/);
-  if (treeMatch) return treeMatch[1].split("/").pop() || "unknown-skill";
-  const repoMatch = cleaned.match(/github\.com\/[^/]+\/([^/]+)/);
-  if (repoMatch) return repoMatch[1].replace(/\.git$/, "");
-  const parts = cleaned.split("/").filter(Boolean);
-  if (parts.length >= 2) return parts[parts.length - 1] || "unknown-skill";
-  return cleaned || "unknown-skill";
-}
-function toDegitPath(url) {
-  const treeMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)\/(.+?)(?:\/)?$/);
-  if (treeMatch) {
-    const [, owner, repo, branch, subpath] = treeMatch;
-    return `${owner}/${repo}/${subpath}#${branch}`;
-  }
-  const repoMatch = url.match(/github\.com\/([^/]+\/[^/]+)/);
-  if (repoMatch) return repoMatch[1].replace(/\.git$/, "");
-  return url;
-}
-
-// src/lifecycle.ts
+import path9 from "path";
+import fs8 from "fs";
 function normalizeDependencies(raw) {
   if (raw === void 0 || raw === null) return [];
   if (!Array.isArray(raw)) {
@@ -591,9 +665,9 @@ function isRelativeDependency(dep) {
   return dep.startsWith("./") || dep.startsWith("../");
 }
 function resolveInlineDependency(raw, baseDir, rootDir) {
-  const resolved = path8.resolve(baseDir, raw);
-  const relToRoot = path8.relative(rootDir, resolved);
-  if (relToRoot.startsWith("..") || path8.isAbsolute(relToRoot)) {
+  const resolved = path9.resolve(baseDir, raw);
+  const relToRoot = path9.relative(rootDir, resolved);
+  if (relToRoot.startsWith("..") || path9.isAbsolute(relToRoot)) {
     throw new SkildError("INVALID_DEPENDENCY", `Inline dependency path escapes the skill root: ${raw}`);
   }
   if (!isDirectory(resolved)) {
@@ -603,11 +677,11 @@ function resolveInlineDependency(raw, baseDir, rootDir) {
   if (!validation.ok) {
     throw new SkildError("INVALID_DEPENDENCY", `Inline dependency is not a valid skill: ${raw}`, { issues: validation.issues });
   }
-  const normalizedInlinePath = relToRoot.split(path8.sep).join("/");
+  const normalizedInlinePath = relToRoot.split(path9.sep).join("/");
   return {
     sourceType: "inline",
     source: raw,
-    name: path8.basename(resolved) || raw,
+    name: path9.basename(resolved) || raw,
     inlinePath: normalizedInlinePath,
     inlineDir: resolved
   };
@@ -677,15 +751,6 @@ function dedupeInstalledDependencies(entries) {
   }
   return out;
 }
-async function cloneRemote(degitSrc, targetPath) {
-  const emitter = degit(degitSrc, { force: true, verbose: false });
-  await emitter.clone(targetPath);
-}
-function ensureInstallableLocalDir(sourcePath) {
-  if (!isDirectory(sourcePath)) {
-    throw new SkildError("NOT_A_DIRECTORY", `Source path is not a directory: ${sourcePath}`, { sourcePath });
-  }
-}
 function assertNonEmptyInstall(stagingDir, source) {
   if (isDirEmpty(stagingDir)) {
     throw new SkildError(
@@ -713,23 +778,16 @@ async function installSkillBase(input, options = {}) {
   ensureDir(skillsDir);
   const skillName = input.nameOverride || extractSkillName(source);
   const installDir = getSkillInstallDir(platform, scope, skillName);
-  if (fs7.existsSync(installDir) && !options.force) {
+  if (fs8.existsSync(installDir) && !options.force) {
     throw new SkildError("ALREADY_INSTALLED", `Skill "${skillName}" is already installed at ${installDir}. Use --force, or uninstall first.`, {
       skillName,
       installDir
     });
   }
   const tempRoot = createTempDir(skillsDir, skillName);
-  const stagingDir = path8.join(tempRoot, "staging");
+  const stagingDir = path9.join(tempRoot, "staging");
   try {
-    const localPath = resolveLocalPath(source);
-    if (localPath) {
-      ensureInstallableLocalDir(localPath);
-      copyDir(localPath, stagingDir);
-    } else {
-      const degitPath = toDegitPath(source);
-      await cloneRemote(degitPath, stagingDir);
-    }
+    await materializeSourceToDir({ source, targetDir: stagingDir, materializedDir: input.materializedDir });
     assertNonEmptyInstall(stagingDir, source);
     replaceDirAtomic(stagingDir, installDir);
     const contentHash = hashDirectoryContent(installDir);
@@ -744,7 +802,7 @@ async function installSkillBase(input, options = {}) {
       installedAt: (/* @__PURE__ */ new Date()).toISOString(),
       installDir,
       contentHash,
-      hasSkillMd: fs7.existsSync(path8.join(installDir, "SKILL.md")),
+      hasSkillMd: fs8.existsSync(path9.join(installDir, "SKILL.md")),
       skill: {
         frontmatter: validation.frontmatter,
         validation
@@ -777,14 +835,14 @@ async function installRegistrySkillBase(input, options = {}, resolved) {
   ensureDir(skillsDir);
   const installName = input.nameOverride || canonicalNameToInstallDirName(canonicalName);
   const installDir = getSkillInstallDir(platform, scope, installName);
-  if (fs7.existsSync(installDir) && !options.force) {
+  if (fs8.existsSync(installDir) && !options.force) {
     throw new SkildError("ALREADY_INSTALLED", `Skill "${canonicalName}" is already installed at ${installDir}. Use --force, or uninstall first.`, {
       skillName: canonicalName,
       installDir
     });
   }
   const tempRoot = createTempDir(skillsDir, installName);
-  const stagingDir = path8.join(tempRoot, "staging");
+  const stagingDir = path9.join(tempRoot, "staging");
   try {
     const resolvedVersion = resolved || await resolveRegistryVersion(registryUrl, spec);
     await downloadAndExtractTarball(resolvedVersion, tempRoot, stagingDir);
@@ -805,7 +863,7 @@ async function installRegistrySkillBase(input, options = {}, resolved) {
       installedAt: (/* @__PURE__ */ new Date()).toISOString(),
       installDir,
       contentHash,
-      hasSkillMd: fs7.existsSync(path8.join(installDir, "SKILL.md")),
+      hasSkillMd: fs8.existsSync(path9.join(installDir, "SKILL.md")),
       skill: { validation, frontmatter: validation.frontmatter }
     };
     writeInstallRecord(installDir, record);
@@ -854,7 +912,7 @@ async function ensureExternalDependencyInstalled(dep, ctx, dependerName) {
     const resolved = await resolveRegistryVersion(registryUrl, spec);
     const installName2 = canonicalNameToInstallDirName(spec.canonicalName);
     const installDir2 = getSkillInstallDir(ctx.platform, ctx.scope, installName2);
-    if (fs7.existsSync(installDir2) && !ctx.force) {
+    if (fs8.existsSync(installDir2) && !ctx.force) {
       const existing = readInstallRecord(installDir2);
       if (!existing) {
         throw new SkildError(
@@ -896,7 +954,7 @@ async function ensureExternalDependencyInstalled(dep, ctx, dependerName) {
   }
   const installName = extractSkillName(dep.source);
   const installDir = getSkillInstallDir(ctx.platform, ctx.scope, installName);
-  if (fs7.existsSync(installDir) && !ctx.force) {
+  if (fs8.existsSync(installDir) && !ctx.force) {
     const existing = readInstallRecord(installDir);
     if (!existing) {
       throw new SkildError(
@@ -1019,11 +1077,11 @@ async function installRegistrySkill(input, options = {}) {
 function listSkills(options = {}) {
   const { platform, scope } = resolvePlatformAndScope(options);
   const skillsDir = getSkillsDir(platform, scope);
-  if (!fs7.existsSync(skillsDir)) return [];
-  const entries = fs7.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith("."));
+  if (!fs8.existsSync(skillsDir)) return [];
+  const entries = fs8.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith("."));
   return entries.map((e) => {
-    const dir = path8.join(skillsDir, e.name);
-    const hasSkillMd = fs7.existsSync(path8.join(dir, "SKILL.md"));
+    const dir = path9.join(skillsDir, e.name);
+    const hasSkillMd = fs8.existsSync(path9.join(dir, "SKILL.md"));
     const record = readInstallRecord(dir);
     return { name: e.name, installDir: dir, hasSkillMd, record };
   }).sort((a, b) => a.name.localeCompare(b.name));
@@ -1041,7 +1099,7 @@ function listAllSkills(options = {}) {
 function getSkillInfo(name, options = {}) {
   const { platform, scope } = resolvePlatformAndScope(options);
   const installDir = getSkillInstallDir(platform, scope, name);
-  if (!fs7.existsSync(installDir)) {
+  if (!fs8.existsSync(installDir)) {
     throw new SkildError("SKILL_NOT_FOUND", `Skill "${name}" not found in ${getSkillsDir(platform, scope)}`, { name, platform, scope });
   }
   const record = readInstallRecord(installDir);
@@ -1065,7 +1123,7 @@ function uninstallSkillInternal(name, options, visited) {
   if (visited.has(key)) return;
   visited.add(key);
   const installDir = getSkillInstallDir(platform, scope, name);
-  if (!fs7.existsSync(installDir)) {
+  if (!fs8.existsSync(installDir)) {
     throw new SkildError("SKILL_NOT_FOUND", `Skill "${name}" not found in ${getSkillsDir(platform, scope)}`, { name, platform, scope });
   }
   const record = readInstallRecord(installDir);
@@ -1114,6 +1172,7 @@ export {
   assertValidAlias,
   canonicalNameToInstallDirName,
   clearRegistryAuth,
+  deriveChildSource,
   downloadAndExtractTarball,
   fetchWithTimeout,
   getSkillInfo,
@@ -1127,6 +1186,8 @@ export {
   listSkills,
   loadOrCreateGlobalConfig,
   loadRegistryAuth,
+  materializeSourceToDir,
+  materializeSourceToTemp,
   normalizeAlias,
   parseRegistrySpecifier,
   resolveRegistryAlias,
@@ -1135,6 +1196,7 @@ export {
   saveRegistryAuth,
   searchRegistrySkills,
   splitCanonicalName,
+  toDegitPath,
   uninstallSkill,
   updateSkill,
   validateSkill,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skild/core",
-  "version": "0.2.9",
+  "version": "0.4.1",
   "description": "Skild core library (headless) for installing, validating, and managing Agent Skills locally.",
   "type": "module",
   "main": "./dist/index.js",