skills-package-manager 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,46 +1,682 @@
+import { cac } from "cac";
 import picocolors from "picocolors";
-import { access, cp as promises_cp, lstat, mkdir, mkdtemp, readFile, readdir, rm as promises_rm, stat as promises_stat, symlink, writeFile } from "node:fs/promises";
-import node_path, { join } from "node:path";
+import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat as promises_stat, symlink, writeFile } from "node:fs/promises";
+import node_path, { basename, join } from "node:path";
 import yaml from "yaml";
-import { createHash } from "node:crypto";
-import { tmpdir } from "node:os";
 import { execFile } from "node:child_process";
+import { homedir, tmpdir } from "node:os";
 import { promisify } from "node:util";
-import { cac } from "cac";
+import { createHash } from "node:crypto";
+import semver from "semver";
+import { createReadStream } from "node:fs";
+import { x } from "tar";
 import * as __rspack_external__clack_prompts_3cae1695 from "@clack/prompts";
+var package_namespaceObject = {
+    rE: "0.4.0"
+};
+const UNIVERSAL_AGENT_NAMES = [
+    'Amp',
+    'Antigravity',
+    'Cline',
+    'Codex',
+    'Cursor',
+    'Deep Agents',
+    'Firebender',
+    'Gemini CLI',
+    'GitHub Copilot',
+    'Kimi Code CLI',
+    'OpenCode',
+    'Warp'
+];
+const ADDITIONAL_AGENT_TARGETS = [
+    {
+        label: 'Augment',
+        path: '.augment/skills'
+    },
+    {
+        label: 'IBM Bob',
+        path: '.bob/skills'
+    },
+    {
+        label: 'Claude Code',
+        path: '.claude/skills'
+    },
+    {
+        label: 'OpenClaw',
+        path: 'skills'
+    },
+    {
+        label: 'CodeBuddy',
+        path: '.codebuddy/skills'
+    },
+    {
+        label: 'Command Code',
+        path: '.commandcode/skills'
+    },
+    {
+        label: 'Continue',
+        path: '.continue/skills'
+    },
+    {
+        label: 'Cortex Code',
+        path: '.cortex/skills'
+    },
+    {
+        label: 'Trae',
+        path: '.trae/skills'
+    }
+];
+async function promptSkillSelection(skills) {
+    if (0 === skills.length) throw new Error('No skills found in repository');
+    if (1 === skills.length) return skills;
+    const options = skills.map((skill)=>({
+            value: skill,
+            label: skill.name,
+            hint: skill.description ? skill.description.length > 60 ? `${skill.description.slice(0, 57)}...` : skill.description : void 0
+        }));
+    const selected = await __rspack_external__clack_prompts_3cae1695.multiselect({
+        message: 'Select skills to install',
+        options,
+        required: true
+    });
+    if (__rspack_external__clack_prompts_3cae1695.isCancel(selected)) {
+        __rspack_external__clack_prompts_3cae1695.cancel('Installation cancelled');
+        process.exit(0);
+    }
+    return selected;
+}
+async function promptInitManifestOptions(promptApi = __rspack_external__clack_prompts_3cae1695, exit = process.exit) {
+    const installDirInput = await promptApi.text({
+        message: 'Where should skills be installed?',
+        initialValue: '.agents/skills'
+    });
+    if (promptApi.isCancel(installDirInput)) {
+        promptApi.cancel('Initialization cancelled');
+        exit(0);
+    }
+    promptApi.note(UNIVERSAL_AGENT_NAMES.join('\n'), 'Universal (.agents/skills) — always included');
+    const selected = await promptApi.groupMultiselect({
+        message: 'Which agents do you want to install to?',
+        options: {
+            'Additional agents': ADDITIONAL_AGENT_TARGETS.map((agent)=>({
+                    value: agent.path,
+                    label: `${agent.label} (${agent.path})`
+                }))
+        },
+        required: false
+    });
+    if (promptApi.isCancel(selected)) {
+        promptApi.cancel('Initialization cancelled');
+        exit(0);
+    }
+    const installDir = String(installDirInput).trim() || '.agents/skills';
+    return {
+        installDir,
+        linkTargets: selected
+    };
+}
+var codes_ErrorCode = /*#__PURE__*/ function(ErrorCode) {
+    ErrorCode["FILE_NOT_FOUND"] = "ENOENT";
+    ErrorCode["PERMISSION_DENIED"] = "EACCES";
+    ErrorCode["FILE_EXISTS"] = "EEXIST";
+    ErrorCode["FS_ERROR"] = "EFS";
+    ErrorCode["GIT_CLONE_FAILED"] = "EGITCLONE";
+    ErrorCode["GIT_FETCH_FAILED"] = "EGITFETCH";
+    ErrorCode["GIT_CHECKOUT_FAILED"] = "EGITCHECKOUT";
+    ErrorCode["GIT_REF_NOT_FOUND"] = "EGITREF";
+    ErrorCode["GIT_NOT_INSTALLED"] = "EGITNOTFOUND";
+    ErrorCode["PARSE_ERROR"] = "EPARSE";
+    ErrorCode["JSON_PARSE_ERROR"] = "EJSONPARSE";
+    ErrorCode["YAML_PARSE_ERROR"] = "EYAMLPARSE";
+    ErrorCode["INVALID_SPECIFIER"] = "EINVALIDSPEC";
+    ErrorCode["MANIFEST_NOT_FOUND"] = "EMANIFEST";
+    ErrorCode["LOCKFILE_NOT_FOUND"] = "ELOCKFILE";
+    ErrorCode["LOCKFILE_OUTDATED"] = "ELOCKOUTDATED";
+    ErrorCode["MANIFEST_EXISTS"] = "EMANIFESTEXISTS";
+    ErrorCode["NETWORK_ERROR"] = "ENETWORK";
+    ErrorCode["REPO_NOT_FOUND"] = "EREPONOTFOUND";
+    ErrorCode["UNKNOWN_ERROR"] = "EUNKNOWN";
+    ErrorCode["NOT_IMPLEMENTED"] = "ENOTIMPL";
+    ErrorCode["VALIDATION_ERROR"] = "EVALIDATION";
+    ErrorCode["SKILL_NOT_FOUND"] = "ESKILLNOTFOUND";
+    ErrorCode["SKILL_EXISTS"] = "ESKILLEXISTS";
+    return ErrorCode;
+}({});
+class SpmError extends Error {
+    code;
+    cause;
+    context;
+    constructor(options){
+        super(options.message);
+        this.code = options.code;
+        this.cause = options.cause;
+        this.context = options.context ?? {};
+        this.name = 'SpmError';
+        if (Error.captureStackTrace) Error.captureStackTrace(this, SpmError);
+    }
+    toString() {
+        let result = `${this.code}: ${this.message}`;
+        if (this.cause) result += `\n  Caused by: ${this.cause.message}`;
+        return result;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            cause: this.cause ? {
+                name: this.cause.name,
+                message: this.cause.message
+            } : void 0,
+            stack: this.stack
+        };
+    }
+}
+class FileSystemError extends SpmError {
+    operation;
+    path;
+    constructor(options){
+        const message = options.message ?? `${options.operation} failed for ${options.path}`;
+        super({
+            code: options.code,
+            message,
+            cause: options.cause,
+            context: {
+                operation: options.operation,
+                path: options.path
+            }
+        });
+        this.operation = options.operation;
+        this.path = options.path;
+        this.name = 'FileSystemError';
+    }
+}
+class GitError extends SpmError {
+    operation;
+    repoUrl;
+    ref;
+    constructor(options){
+        const message = options.message ?? `git ${options.operation} failed${options.repoUrl ? ` for ${options.repoUrl}` : ''}`;
+        super({
+            code: options.code,
+            message,
+            cause: options.cause,
+            context: {
+                operation: options.operation,
+                repoUrl: options.repoUrl,
+                ref: options.ref
+            }
+        });
+        this.operation = options.operation;
+        this.repoUrl = options.repoUrl;
+        this.ref = options.ref;
+        this.name = 'GitError';
+    }
+}
+class ParseError extends SpmError {
+    filePath;
+    content;
+    constructor(options){
+        super({
+            code: options.code,
+            message: options.message,
+            cause: options.cause,
+            context: {
+                filePath: options.filePath,
+                contentSnippet: options.content?.slice(0, 200)
+            }
+        });
+        this.filePath = options.filePath;
+        this.content = options.content;
+        this.name = 'ParseError';
+    }
+}
+class ManifestError extends SpmError {
+    filePath;
+    constructor(options){
+        const defaultMessages = {
+            [codes_ErrorCode.MANIFEST_NOT_FOUND]: `Manifest not found: ${options.filePath}`,
+            [codes_ErrorCode.LOCKFILE_NOT_FOUND]: `Lockfile not found: ${options.filePath}`,
+            [codes_ErrorCode.LOCKFILE_OUTDATED]: `Lockfile is out of date: ${options.filePath}`,
+            [codes_ErrorCode.MANIFEST_EXISTS]: `Manifest already exists: ${options.filePath}`
+        };
+        const message = options.message ?? defaultMessages[options.code] ?? `Manifest error: ${options.filePath}`;
+        super({
+            code: options.code,
+            message,
+            cause: options.cause,
+            context: {
+                filePath: options.filePath
+            }
+        });
+        this.filePath = options.filePath;
+        this.name = 'ManifestError';
+    }
+}
+class SkillError extends SpmError {
+    skillName;
+    constructor(options){
+        const defaultMessages = {
+            [codes_ErrorCode.SKILL_NOT_FOUND]: `Skill not found: ${options.skillName}`,
+            [codes_ErrorCode.SKILL_EXISTS]: `Skill already exists: ${options.skillName}`,
+            [codes_ErrorCode.VALIDATION_ERROR]: `Skill validation failed: ${options.skillName}`
+        };
+        const message = options.message ?? defaultMessages[options.code] ?? `Skill error: ${options.skillName}`;
+        super({
+            code: options.code,
+            message,
+            cause: options.cause,
+            context: {
+                skillName: options.skillName
+            }
+        });
+        this.skillName = options.skillName;
+        this.name = 'SkillError';
+    }
+}
+class NetworkError extends SpmError {
+    url;
+    constructor(options){
+        super({
+            code: options.code,
+            message: options.message,
+            cause: options.cause,
+            context: {
+                url: options.url
+            }
+        });
+        this.url = options.url;
+        this.name = 'NetworkError';
+    }
+}
+function convertNodeError(error, context) {
+    switch(error.code){
+        case 'ENOENT':
+            return new FileSystemError({
+                code: codes_ErrorCode.FILE_NOT_FOUND,
+                operation: context.operation,
+                path: context.path,
+                cause: error
+            });
+        case 'EACCES':
+        case 'EPERM':
+            return new FileSystemError({
+                code: codes_ErrorCode.PERMISSION_DENIED,
+                operation: context.operation,
+                path: context.path,
+                cause: error
+            });
+        case 'EEXIST':
+            return new FileSystemError({
+                code: codes_ErrorCode.FILE_EXISTS,
+                operation: context.operation,
+                path: context.path,
+                cause: error
+            });
+        case 'ENOTDIR':
+            return new FileSystemError({
+                code: codes_ErrorCode.FS_ERROR,
+                operation: context.operation,
+                path: context.path,
+                message: `Not a directory: ${context.path}`,
+                cause: error
+            });
+        case 'EISDIR':
+            return new FileSystemError({
+                code: codes_ErrorCode.FS_ERROR,
+                operation: context.operation,
+                path: context.path,
+                message: `Is a directory: ${context.path}`,
+                cause: error
+            });
+        default:
+            return new FileSystemError({
+                code: codes_ErrorCode.FS_ERROR,
+                operation: context.operation,
+                path: context.path,
+                message: error.message,
+                cause: error
+            });
+    }
+}
+function formatErrorForDisplay(error) {
+    if (error instanceof SpmError) {
+        let output = `Error [${error.code}]: ${error.message}`;
+        if (error instanceof FileSystemError) {
+            if (error.code === codes_ErrorCode.FILE_NOT_FOUND) {
+                output += `\n\nThe file "${error.path}" was not found.`;
+                if (error.path.endsWith('skills.json')) output += `\nRun "spm init" to create a new skills.json file.`;
+            } else if (error.code === codes_ErrorCode.PERMISSION_DENIED) {
+                output += `\n\nPermission denied for "${error.path}".`;
+                output += `\nCheck that you have read/write access to this location.`;
+            }
+        } else if (error instanceof GitError) {
+            if (error.code === codes_ErrorCode.GIT_REF_NOT_FOUND) {
+                output += `\n\nThe reference "${error.ref}" could not be found in the repository.`;
+                output += `\nPlease check that the branch, tag, or commit hash is correct.`;
+            } else if (error.code === codes_ErrorCode.GIT_CLONE_FAILED) {
+                output += `\n\nFailed to clone the repository.`;
+                output += `\nPossible causes:`;
+                output += `\n  - The repository URL is incorrect`;
+                output += `\n  - The repository is private and requires authentication`;
+                output += `\n  - There is no internet connection`;
+            }
+        } else if (error instanceof ParseError) {
+            if (error.code === codes_ErrorCode.JSON_PARSE_ERROR || error.code === codes_ErrorCode.YAML_PARSE_ERROR) {
+                output += `\n\nFile: ${error.filePath}`;
+                output += `\nPlease check the file syntax and fix any formatting issues.`;
+            } else if (error.code === codes_ErrorCode.INVALID_SPECIFIER) {
+                output += `\n\nInvalid skill specifier format.`;
+                output += `\nExpected formats:`;
+                output += `\n  - owner/repo (GitHub shorthand)`;
+                output += `\n  - https://github.com/owner/repo.git`;
+                output += `\n  - link:./path/to/skill-dir`;
+                output += `\n  - file:./path/to/skill-package.tgz#path:/skills/my-skill`;
+                output += `\n  - npm:@scope/skill-package#path:/skills/my-skill`;
+            }
+        } else if (error instanceof ManifestError) {
+            if (error.code === codes_ErrorCode.LOCKFILE_OUTDATED) {
+                output += `\n\nThe lockfile is out of sync with skills.json.`;
+                output += `\nRun "spm install" to update the lockfile.`;
+            }
+        }
+        if (error.cause && !(error instanceof GitError || error instanceof FileSystemError)) output += `\n\nCaused by: ${error.cause.message}`;
+        return output;
+    }
+    if (error instanceof Error) return `Error: ${error.message}`;
+    return `Error: ${String(error)}`;
+}
+function isSpmError(error) {
+    return error instanceof SpmError;
+}
+function getExitCode(error) {
+    if (error instanceof SpmError) {
+        if (error.code.startsWith('E1')) return 101;
+        if (error.code.startsWith('E2')) return 102;
+        if (error.code.startsWith('E3')) return 103;
+        if (error.code.startsWith('E4')) return 104;
+        if (error.code.startsWith('E5')) return 105;
+        if (error.code.startsWith('E9')) return 109;
+    }
+    return 1;
+}
 async function readSkillsLock(rootDir) {
     const filePath = node_path.join(rootDir, 'skills-lock.yaml');
     try {
         const raw = await readFile(filePath, 'utf8');
-        return yaml.parse(raw);
+        try {
+            return yaml.parse(raw);
+        } catch (parseError) {
+            throw new ParseError({
+                code: codes_ErrorCode.YAML_PARSE_ERROR,
+                filePath,
+                content: raw,
+                message: `Failed to parse skills-lock.yaml: ${parseError.message}`,
+                cause: parseError
+            });
+        }
     } catch (error) {
         if ('ENOENT' === error.code) return null;
-        throw error;
+        if (error instanceof ParseError) throw error;
+        throw convertNodeError(error, {
+            operation: 'read',
+            path: filePath
+        });
     }
 }
 async function readSkillsManifest(rootDir) {
     const filePath = node_path.join(rootDir, 'skills.json');
     try {
         const raw = await readFile(filePath, 'utf8');
-        const json = JSON.parse(raw);
-        return {
-            installDir: json.installDir ?? '.agents/skills',
-            linkTargets: json.linkTargets ?? [],
-            skills: json.skills ?? {}
-        };
+        try {
+            const json = JSON.parse(raw);
+            return {
+                installDir: json.installDir ?? '.agents/skills',
+                linkTargets: json.linkTargets ?? [],
+                skills: json.skills ?? {}
+            };
+        } catch (parseError) {
+            throw new ParseError({
+                code: codes_ErrorCode.JSON_PARSE_ERROR,
+                filePath,
+                content: raw,
+                message: `Failed to parse skills.json: ${parseError.message}`,
+                cause: parseError
+            });
+        }
     } catch (error) {
         if ('ENOENT' === error.code) return null;
+        if (error instanceof ParseError) throw error;
+        throw convertNodeError(error, {
+            operation: 'read',
+            path: filePath
+        });
+    }
+}
+const resolvedNpmPackageCache = new Map();
+function normalizeRegistryUrl(url) {
+    return url.endsWith('/') ? url : `${url}/`;
+}
+function interpolateEnv(value) {
+    return value.replace(/\$\{([^}]+)\}/g, (_match, key)=>process.env[key] ?? '');
+}
+async function readNpmRc(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        const entries = new Map();
+        for (const rawLine of content.split(/\r?\n/)){
+            const line = rawLine.trim();
+            if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+            const separator = line.indexOf('=');
+            if (!(separator < 0)) entries.set(line.slice(0, separator).trim(), interpolateEnv(line.slice(separator + 1).trim()));
+        }
+        return entries;
+    } catch  {
+        return new Map();
+    }
+}
+function getCandidateDirs(cwd) {
+    const resolvedCwd = node_path.resolve(cwd);
+    if ('win32' === process.platform) {
+        const parsed = node_path.parse(resolvedCwd);
+        const relative = resolvedCwd.slice(parsed.root.length);
+        const parts = relative.split(node_path.sep).filter(Boolean);
+        return [
+            parsed.root,
+            ...parts.map((_part, index)=>node_path.join(parsed.root, ...parts.slice(0, index + 1)))
+        ];
+    }
+    const parts = resolvedCwd.split(node_path.sep).filter(Boolean);
+    return [
+        '/',
+        ...parts.map((_part, index)=>node_path.join('/', ...parts.slice(0, index + 1)))
+    ];
+}
+function buildRegistryAuthEntries(settings) {
+    const registryAuthConfigs = new Map();
+    for (const [key, value] of settings){
+        const match = key.match(/^(\/\/.+\/):(_authToken|_auth|username|_password)$/);
+        if (!match) continue;
+        const [, prefix, field] = match;
+        const config = registryAuthConfigs.get(prefix) ?? {};
+        registryAuthConfigs.set(prefix, {
+            ...config,
+            ['_authToken' === field ? 'authToken' : '_auth' === field ? 'auth' : 'username' === field ? 'username' : 'password']: value
+        });
+    }
+    return [
+        ...registryAuthConfigs.entries()
+    ].map(([prefix, config])=>{
+        if (config.authToken) return {
+            prefix,
+            authorization: `Bearer ${config.authToken}`
+        };
+        if (config.auth) return {
+            prefix,
+            authorization: `Basic ${config.auth}`
+        };
+        if (config.username && config.password) {
+            const decodedPassword = Buffer.from(config.password, 'base64').toString('utf8');
+            return {
+                prefix,
+                authorization: `Basic ${Buffer.from(`${config.username}:${decodedPassword}`).toString('base64')}`
+            };
+        }
+        return null;
+    }).filter((entry)=>null !== entry).sort((a, b)=>b.prefix.length - a.prefix.length);
+}
+async function loadNpmConfig(cwd) {
+    const configs = new Map();
+    for (const [key, value] of (await readNpmRc(node_path.join(homedir(), '.npmrc'))))configs.set(key, value);
+    for (const candidateDir of getCandidateDirs(cwd))for (const [key, value] of (await readNpmRc(node_path.join(candidateDir, '.npmrc'))))configs.set(key, value);
+    return {
+        settings: configs,
+        authEntries: buildRegistryAuthEntries(configs)
+    };
+}
+function resolveRegistryConfig(config, packageName) {
+    const scopeMatch = packageName.match(/^(@[^/]+)\//);
+    if (scopeMatch) {
+        const scopeRegistry = config.settings.get(`${scopeMatch[1]}:registry`);
+        if (scopeRegistry) return normalizeRegistryUrl(scopeRegistry);
+    }
+    return normalizeRegistryUrl(config.settings.get('registry') ?? 'https://registry.npmjs.org/');
+}
+function resolveAuthorizationHeader(config, requestUrl) {
+    const url = new URL(requestUrl);
+    const requestKey = `//${url.host}${url.pathname}`;
+    const matched = config.authEntries.find((entry)=>requestKey.startsWith(entry.prefix));
+    return matched?.authorization;
+}
+function createRequestHeaders(config, requestUrl) {
+    const authorization = resolveAuthorizationHeader(config, requestUrl);
+    if (!authorization) return;
+    return {
+        authorization
+    };
+}
+function parseRegistryPackageSpecifier(specifier) {
+    const scopedMatch = specifier.match(/^(@[^/]+\/[^@]+)(?:@(.+))?$/);
+    if (scopedMatch) return {
+        packageName: scopedMatch[1],
+        requestedVersion: scopedMatch[2] ?? null
+    };
+    const unscopedMatch = specifier.match(/^([^@/:][^@]*?)(?:@(.+))?$/);
+    if (unscopedMatch) return {
+        packageName: unscopedMatch[1],
+        requestedVersion: unscopedMatch[2] ?? null
+    };
+    throw new Error(`Unsupported npm specifier: ${specifier}`);
+}
+function resolveVersionFromMetadata(metadata, requestedVersion) {
+    const versions = metadata.versions ?? {};
+    const versionKeys = Object.keys(versions);
+    const requested = requestedVersion ?? 'latest';
+    const taggedVersion = metadata['dist-tags']?.[requested];
+    if (taggedVersion && versions[taggedVersion]) return taggedVersion;
+    if (semver.valid(requested) && versions[requested]) return requested;
+    const matched = semver.maxSatisfying(versionKeys, requested);
+    if (matched) return matched;
+    throw new Error(`Unable to resolve npm version "${requested}"`);
+}
+async function resolveNpmPackageUncached(cwd, specifier) {
+    const config = await loadNpmConfig(cwd);
+    const { packageName, requestedVersion } = parseRegistryPackageSpecifier(specifier);
+    const registry = resolveRegistryConfig(config, packageName);
+    const metadataUrl = new URL(encodeURIComponent(packageName), registry);
+    const response = await fetch(metadataUrl, {
+        headers: createRequestHeaders(config, metadataUrl.toString())
+    });
+    if (!response.ok) throw new Error(`Failed to fetch npm metadata for ${packageName}: ${response.status}`);
+    const metadata = await response.json();
+    const version = resolveVersionFromMetadata(metadata, requestedVersion);
+    const manifest = metadata.versions?.[version];
+    const tarballUrl = manifest?.dist?.tarball;
+    if (!manifest?.name || !manifest.version || !tarballUrl) throw new Error(`Invalid npm metadata for ${packageName}@${version}`);
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        tarballUrl,
+        integrity: manifest.dist?.integrity,
+        registry
+    };
+}
+async function resolveNpmPackage(cwd, specifier) {
+    const cacheKey = `${node_path.resolve(cwd)}\0${specifier}`;
+    const cached = resolvedNpmPackageCache.get(cacheKey);
+    if (cached) return cached;
+    const pending = resolveNpmPackageUncached(cwd, specifier);
+    resolvedNpmPackageCache.set(cacheKey, pending);
+    try {
+        return await pending;
+    } catch (error) {
+        resolvedNpmPackageCache.delete(cacheKey);
         throw error;
     }
 }
+function verifyIntegrity(buffer, integrity) {
+    for (const entry of integrity.split(/\s+/).filter(Boolean)){
+        const separatorIndex = entry.indexOf('-');
+        if (separatorIndex <= 0) continue;
+        const algorithm = entry.slice(0, separatorIndex);
+        const expectedDigest = entry.slice(separatorIndex + 1);
+        try {
+            const actualDigest = createHash(algorithm).update(buffer).digest('base64');
+            if (actualDigest === expectedDigest) return true;
+        } catch  {}
+    }
+    return false;
+}
+async function downloadNpmPackageTarball(cwd, tarballUrl, expectedIntegrity) {
+    const downloadRoot = await mkdtemp(node_path.join(tmpdir(), 'skills-pm-npm-download-'));
+    try {
+        const config = await loadNpmConfig(cwd);
+        const response = await fetch(tarballUrl, {
+            headers: createRequestHeaders(config, tarballUrl)
+        });
+        if (!response.ok) throw new Error(`Failed to download npm tarball: ${response.status}`);
+        const tarballBuffer = Buffer.from(await response.arrayBuffer());
+        if (expectedIntegrity && !verifyIntegrity(tarballBuffer, expectedIntegrity)) throw new Error(`Integrity check failed for npm tarball ${tarballUrl}`);
+        const tarballPath = node_path.join(downloadRoot, node_path.basename(new URL(tarballUrl).pathname) || 'package.tgz');
+        await writeFile(tarballPath, tarballBuffer);
+        return tarballPath;
+    } catch (error) {
+        await rm(downloadRoot, {
+            recursive: true,
+            force: true
+        }).catch(()=>{});
+        throw new Error(`Failed to download npm tarball ${tarballUrl}: ${error.message}`, {
+            cause: error
+        });
+    }
+}
+async function cleanupPackedNpmPackage(tarballPath) {
+    await rm(node_path.dirname(tarballPath), {
+        recursive: true,
+        force: true
+    }).catch(()=>{});
+}
+function normalizeLinkSource(sourcePart) {
+    const linkPath = sourcePart.slice(5).replace(/\\/g, '/').replace(/\/+$/, '');
+    return `link:${linkPath}`;
+}
 function parseSpecifier(specifier) {
     const firstHashIndex = specifier.indexOf('#');
     const secondHashIndex = firstHashIndex >= 0 ? specifier.indexOf('#', firstHashIndex + 1) : -1;
-    if (secondHashIndex >= 0) throw new Error('Invalid specifier: multiple # fragments are not supported');
+    if (secondHashIndex >= 0) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: 'Invalid specifier: multiple # fragments are not supported',
+        content: specifier
+    });
     const hashIndex = firstHashIndex;
     const sourcePart = hashIndex >= 0 ? specifier.slice(0, hashIndex) : specifier;
     const fragment = hashIndex >= 0 ? specifier.slice(hashIndex + 1) : '';
-    if (!sourcePart) throw new Error('Specifier source is required');
+    if (!sourcePart) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: 'Specifier source is required',
+        content: specifier
+    });
     if (!fragment) return {
         sourcePart,
         ref: null,
@@ -63,8 +699,37 @@ function parseSpecifier(specifier) {
     };
 }
 function normalizeSpecifier(specifier) {
-    const parsed = parseSpecifier(specifier);
-    const type = parsed.sourcePart.startsWith('file:') ? 'file' : parsed.sourcePart.startsWith('npm:') ? 'npm' : 'git';
+    if (specifier.startsWith('link:') && specifier.includes('#')) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: 'Invalid link specifier: link: must point directly to a skill directory',
+        content: specifier
+    });
+    let parsed;
+    try {
+        parsed = parseSpecifier(specifier);
+    } catch (error) {
+        if (error instanceof ParseError) throw error;
+        throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `Invalid specifier: ${error.message}`,
+            content: specifier,
+            cause: error
+        });
+    }
+    const type = parsed.sourcePart.startsWith('link:') ? 'link' : parsed.sourcePart.startsWith('file:') ? 'file' : parsed.sourcePart.startsWith('npm:') ? 'npm' : 'git';
+    if ('link' === type) {
+        const linkSource = normalizeLinkSource(parsed.sourcePart);
+        const linkPath = linkSource.slice(5);
+        const skillName = node_path.posix.basename(linkPath);
+        return {
+            type,
+            source: linkSource,
+            ref: null,
+            path: '/',
+            normalized: linkSource,
+            skillName
+        };
+    }
     const skillPath = parsed.path || '/';
     const skillName = node_path.posix.basename(skillPath);
     const normalized = parsed.ref ? `${parsed.sourcePart}#${parsed.ref}&path:${skillPath}` : parsed.path ? `${parsed.sourcePart}#path:${skillPath}` : parsed.sourcePart;
@@ -80,7 +745,50 @@ function normalizeSpecifier(specifier) {
 function sha256(content) {
     return `sha256-${createHash('sha256').update(content).digest('hex')}`;
 }
+function toPortablePath(filePath) {
+    return '/' === node_path.sep ? filePath : filePath.split(node_path.sep).join('/');
+}
+async function hashDirectoryEntry(hash, rootDir, currentDir) {
+    const entries = await readdir(currentDir, {
+        withFileTypes: true
+    });
+    entries.sort((a, b)=>a.name.localeCompare(b.name));
+    for (const entry of entries){
+        const absolutePath = node_path.join(currentDir, entry.name);
+        const relativePath = toPortablePath(node_path.relative(rootDir, absolutePath));
+        const stats = await lstat(absolutePath);
+        if (stats.isSymbolicLink()) {
+            hash.update(`symlink:${relativePath}\n`);
+            hash.update(await readlink(absolutePath));
+            hash.update('\n');
+            continue;
+        }
+        if (stats.isDirectory()) {
+            hash.update(`dir:${relativePath}\n`);
+            await hashDirectoryEntry(hash, rootDir, absolutePath);
+            continue;
+        }
+        hash.update(`file:${relativePath}\n`);
+        hash.update(await readFile(absolutePath));
+        hash.update('\n');
+    }
+}
+async function sha256Directory(rootDir) {
+    const hash = createHash('sha256');
+    await hashDirectoryEntry(hash, rootDir, rootDir);
+    return `sha256-${hash.digest('hex')}`;
+}
+async function sha256File(filePath, suffix = '') {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(filePath))hash.update(chunk);
+    if (suffix) hash.update(suffix);
+    return `sha256-${hash.digest('hex')}`;
+}
 const execFileAsync = promisify(execFile);
+function toPortableRelativePath(from, to) {
+    const relativePath = node_path.relative(from, to) || '.';
+    return '/' === node_path.sep ? relativePath : relativePath.split(node_path.sep).join('/');
+}
 async function resolveGitCommitByLsRemote(url, target) {
     try {
         const { stdout } = await execFileAsync('git', [
@@ -118,7 +826,7 @@ async function resolveGitCommitByClone(url, target) {
     } catch  {
         return null;
     } finally{
-        await promises_rm(checkoutRoot, {
+        await rm(checkoutRoot, {
             recursive: true,
             force: true
         }).catch(()=>{});
@@ -130,28 +838,61 @@ async function resolveGitCommit(url, ref) {
     if (commit) return commit;
     const clonedCommit = await resolveGitCommitByClone(url, target);
     if (clonedCommit) return clonedCommit;
-    throw new Error(`Unable to resolve git ref ${target} for ${url}`);
+    throw new GitError({
+        code: codes_ErrorCode.GIT_REF_NOT_FOUND,
+        operation: 'resolve-ref',
+        repoUrl: url,
+        ref: target,
+        message: `Unable to resolve git ref "${target}" for ${url}`
+    });
 }
-async function resolveLockEntry(cwd, specifier) {
-    const normalized = normalizeSpecifier(specifier);
-    if ('file' === normalized.type) {
+async function resolveLockEntry(cwd, specifier, skillName) {
+    let normalized;
+    try {
+        normalized = normalizeSpecifier(specifier);
+    } catch (error) {
+        if (error instanceof ParseError) throw error;
+        throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `Failed to parse specifier "${specifier}": ${error.message}`,
+            content: specifier,
+            cause: error
+        });
+    }
+    const finalSkillName = skillName || normalized.skillName;
+    if ('link' === normalized.type) {
         const sourceRoot = node_path.resolve(cwd, normalized.source.slice(5));
         return {
-            skillName: normalized.skillName,
+            skillName: finalSkillName,
+            entry: {
+                specifier: normalized.normalized,
+                resolution: {
+                    type: 'link',
+                    path: toPortableRelativePath(cwd, sourceRoot)
+                },
+                digest: await sha256Directory(sourceRoot)
+            }
+        };
+    }
+    if ('file' === normalized.type) {
+        const tarballPath = node_path.resolve(cwd, normalized.source.slice(5));
+        return {
+            skillName: finalSkillName,
             entry: {
                 specifier: normalized.normalized,
                 resolution: {
                     type: 'file',
-                    path: node_path.relative(cwd, sourceRoot) || '.'
+                    tarball: toPortableRelativePath(cwd, tarballPath),
+                    path: normalized.path
                 },
-                digest: sha256(`${sourceRoot}:${normalized.path}`)
+                digest: await sha256File(tarballPath, `:${normalized.path}`)
             }
         };
     }
     if ('git' === normalized.type) {
         const commit = await resolveGitCommit(normalized.source, normalized.ref);
         return {
-            skillName: normalized.skillName,
+            skillName: finalSkillName,
             entry: {
                 specifier: normalized.normalized,
                 resolution: {
@@ -164,14 +905,52 @@ async function resolveLockEntry(cwd, specifier) {
             }
         };
     }
-    throw new Error(`Unsupported specifier type in 0.1.0 core flow: ${normalized.type}`);
-}
-async function syncSkillsLock(cwd, manifest, existingLock) {
-    const nextSkills = {};
-    for (const specifier of Object.values(manifest.skills)){
-        const { skillName, entry } = await resolveLockEntry(cwd, specifier);
-        nextSkills[skillName] = entry;
+    if ('npm' === normalized.type) {
+        const packageSpecifier = normalized.source.slice(4);
+        const resolved = await resolveNpmPackage(cwd, packageSpecifier);
+        return {
+            skillName: finalSkillName,
+            entry: {
+                specifier: normalized.normalized,
+                resolution: {
+                    type: 'npm',
+                    packageName: resolved.name,
+                    version: resolved.version,
+                    path: normalized.path,
+                    tarball: resolved.tarballUrl,
+                    integrity: resolved.integrity,
+                    registry: resolved.registry
+                },
+                digest: sha256([
+                    resolved.name,
+                    resolved.version,
+                    resolved.tarballUrl,
+                    resolved.integrity ?? '',
+                    resolved.registry ?? '',
+                    normalized.path
+                ].join(':'))
+            }
+        };
     }
+    throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: `Unsupported specifier type in 0.1.0 core flow: ${normalized.type}`,
+        content: specifier
+    });
+}
+async function syncSkillsLock(cwd, manifest, _existingLock, options) {
+    const entries = await Promise.all(Object.entries(manifest.skills).map(async ([skillName, specifier])=>{
+        const { skillName: resolvedName, entry } = await resolveLockEntry(cwd, specifier, skillName);
+        options?.onProgress?.({
+            type: 'resolved',
+            skillName: resolvedName
+        });
+        return [
+            resolvedName,
+            entry
+        ];
+    }));
+    const nextSkills = Object.fromEntries(entries);
     return {
         lockfileVersion: '0.1',
         installDir: manifest.installDir ?? '.agents/skills',
@@ -181,7 +960,14 @@ async function syncSkillsLock(cwd, manifest, existingLock) {
 }
 async function writeSkillsLock(rootDir, lockfile) {
     const filePath = node_path.join(rootDir, 'skills-lock.yaml');
-    await writeFile(filePath, yaml.stringify(lockfile), 'utf8');
+    try {
+        await writeFile(filePath, yaml.stringify(lockfile), 'utf8');
+    } catch (error) {
+        throw convertNodeError(error, {
+            operation: 'write',
+            path: filePath
+        });
+    }
 }
 async function writeSkillsManifest(rootDir, manifest) {
     const filePath = node_path.join(rootDir, 'skills.json');
@@ -190,7 +976,14 @@ async function writeSkillsManifest(rootDir, manifest) {
         linkTargets: manifest.linkTargets ?? [],
         skills: manifest.skills
     };
-    await writeFile(filePath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+        await writeFile(filePath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    } catch (error) {
+        throw convertNodeError(error, {
+            operation: 'write',
+            path: filePath
+        });
+    }
 }
 const listSkills_execFileAsync = promisify(execFile);
 const SKIP_DIRS = new Set([
@@ -226,7 +1019,7 @@ async function parseSkillDir(dir, relativePath) {
     try {
         const content = await readFile(join(dir, 'SKILL.md'), 'utf8');
         const meta = parseSkillFrontmatter(content);
-        const dirName = dir.split('/').pop() ?? '';
+        const dirName = basename(dir);
         return {
             name: meta.name || dirName,
             description: meta.description,
@@ -268,189 +1061,138 @@ async function cloneAndDiscover(gitUrl, ref) {
             ref,
             gitUrl,
             tempDir
-        ] : [
-            'clone',
-            '--depth',
-            '1',
-            gitUrl,
-            tempDir
-        ];
-        await listSkills_execFileAsync('git', cloneArgs, {
-            env: {
-                ...process.env,
-                GIT_TERMINAL_PROMPT: '0'
-            },
-            timeout: 60000
-        });
-        const skills = await discoverSkillsInDir(tempDir);
-        return {
-            skills,
-            cleanup: async ()=>{
-                await promises_rm(tempDir, {
-                    recursive: true,
-                    force: true
-                }).catch(()=>{});
-            }
-        };
-    } catch (error) {
-        await promises_rm(tempDir, {
-            recursive: true,
-            force: true
-        }).catch(()=>{});
-        throw error;
-    }
-}
-async function discoverSkillsInDir(baseDir) {
-    const rootSkills = await scanForSkills(baseDir, '');
-    if (rootSkills.length > 0) {
-        rootSkills.sort((a, b)=>a.name.localeCompare(b.name));
-        return rootSkills;
-    }
-    const commonDirs = [
-        'skills',
-        '.agents/skills',
-        '.claude/skills',
-        '.github/skills'
-    ];
-    for (const dir of commonDirs){
-        const skills = await scanForSkills(baseDir, dir);
-        if (skills.length > 0) {
-            skills.sort((a, b)=>a.name.localeCompare(b.name));
-            return skills;
-        }
-    }
-    return [];
-}
-async function listRepoSkills(owner, repo, ref) {
-    const gitUrl = `https://github.com/${owner}/${repo}.git`;
-    const { skills, cleanup } = await cloneAndDiscover(gitUrl, ref);
-    await cleanup();
-    return skills;
-}
-function parseOwnerRepo(input) {
-    const match = input.match(/^([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+)$/);
-    if (!match) return null;
-    return {
-        owner: match[1],
-        repo: match[2]
-    };
-}
-function parseGitHubUrl(input) {
-    const match = input.match(/^https?:\/\/github\.com\/([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+?)(?:\.git)?\/?$/);
-    if (!match) return null;
-    return {
-        owner: match[1],
-        repo: match[2]
-    };
-}
-const UNIVERSAL_AGENT_NAMES = [
-    'Amp',
-    'Antigravity',
-    'Cline',
-    'Codex',
-    'Cursor',
-    'Deep Agents',
-    'Firebender',
-    'Gemini CLI',
-    'GitHub Copilot',
-    'Kimi Code CLI',
-    'OpenCode',
-    'Warp'
-];
-const ADDITIONAL_AGENT_TARGETS = [
-    {
-        label: 'Augment',
-        path: '.augment/skills'
-    },
-    {
-        label: 'IBM Bob',
-        path: '.bob/skills'
-    },
-    {
-        label: 'Claude Code',
-        path: '.claude/skills'
-    },
-    {
-        label: 'OpenClaw',
-        path: 'skills'
-    },
-    {
-        label: 'CodeBuddy',
-        path: '.codebuddy/skills'
-    },
-    {
-        label: 'Command Code',
-        path: '.commandcode/skills'
-    },
-    {
-        label: 'Continue',
-        path: '.continue/skills'
-    },
-    {
-        label: 'Cortex Code',
-        path: '.cortex/skills'
-    },
-    {
-        label: 'Trae',
-        path: '.trae/skills'
-    }
-];
-async function promptSkillSelection(skills) {
-    if (0 === skills.length) throw new Error('No skills found in repository');
-    if (1 === skills.length) return skills;
-    const options = skills.map((skill)=>({
-            value: skill,
-            label: skill.name,
-            hint: skill.description ? skill.description.length > 60 ? `${skill.description.slice(0, 57)}...` : skill.description : void 0
-        }));
-    const selected = await __rspack_external__clack_prompts_3cae1695.multiselect({
-        message: 'Select skills to install',
-        options,
-        required: true
-    });
-    if (__rspack_external__clack_prompts_3cae1695.isCancel(selected)) {
-        __rspack_external__clack_prompts_3cae1695.cancel('Installation cancelled');
-        process.exit(0);
+        ] : [
+            'clone',
+            '--depth',
+            '1',
+            gitUrl,
+            tempDir
+        ];
+        await listSkills_execFileAsync('git', cloneArgs, {
+            env: {
+                ...process.env,
+                GIT_TERMINAL_PROMPT: '0'
+            },
+            timeout: 60000
+        });
+        const skills = await discoverSkillsInDir(tempDir);
+        return {
+            skills,
+            cleanup: async ()=>{
+                await rm(tempDir, {
+                    recursive: true,
+                    force: true
+                }).catch(()=>{});
+            }
+        };
+    } catch (error) {
+        await rm(tempDir, {
+            recursive: true,
+            force: true
+        }).catch(()=>{});
+        throw error;
     }
-    return selected;
 }
-async function promptInitManifestOptions(promptApi = __rspack_external__clack_prompts_3cae1695, exit = process.exit) {
-    const installDirInput = await promptApi.text({
-        message: 'Where should skills be installed?',
-        initialValue: '.agents/skills'
-    });
-    if (promptApi.isCancel(installDirInput)) {
-        promptApi.cancel('Initialization cancelled');
-        exit(0);
+async function discoverSkillsInDir(baseDir) {
+    const rootSkills = await scanForSkills(baseDir, '');
+    if (rootSkills.length > 0) {
+        rootSkills.sort((a, b)=>a.name.localeCompare(b.name));
+        return rootSkills;
     }
-    promptApi.note(UNIVERSAL_AGENT_NAMES.join('\n'), 'Universal (.agents/skills) — always included');
-    const selected = await promptApi.groupMultiselect({
-        message: 'Which agents do you want to install to?',
-        options: {
-            'Additional agents': ADDITIONAL_AGENT_TARGETS.map((agent)=>({
-                    value: agent.path,
-                    label: `${agent.label} (${agent.path})`
-                }))
-        },
-        required: false
-    });
-    if (promptApi.isCancel(selected)) {
-        promptApi.cancel('Initialization cancelled');
-        exit(0);
+    const commonDirs = [
+        'skills',
+        '.agents/skills',
+        '.claude/skills',
+        '.github/skills'
+    ];
+    for (const dir of commonDirs){
+        const skills = await scanForSkills(baseDir, dir);
+        if (skills.length > 0) {
+            skills.sort((a, b)=>a.name.localeCompare(b.name));
+            return skills;
+        }
     }
-    const installDir = String(installDirInput).trim() || '.agents/skills';
+    return [];
+}
+async function listRepoSkills(owner, repo, ref) {
+    const gitUrl = `https://github.com/${owner}/${repo}.git`;
+    const { skills, cleanup } = await cloneAndDiscover(gitUrl, ref);
+    await cleanup();
+    return skills;
+}
+function parseOwnerRepo(input) {
+    const match = input.match(/^([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+)$/);
+    if (!match) return null;
     return {
-        installDir,
-        linkTargets: selected
+        owner: match[1],
+        repo: match[2]
+    };
+}
+function parseGitHubUrl(input) {
+    const match = input.match(/^https?:\/\/github\.com\/([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+?)(?:\.git)?\/?$/);
+    if (!match) return null;
+    return {
+        owner: match[1],
+        repo: match[2]
+    };
+}
+function parseForComparison(specifier) {
+    const parsed = parseSpecifier(specifier);
+    const isLink = parsed.sourcePart.startsWith('link:');
+    return {
+        sourcePart: isLink ? normalizeLinkSource(parsed.sourcePart) : parsed.sourcePart,
+        ref: isLink ? null : parsed.ref,
+        path: isLink ? '/' : parsed.path || '/'
     };
 }
+function isSpecifierCompatible(manifestSpecifier, lockSpecifier) {
+    const manifest = parseForComparison(manifestSpecifier);
+    const lock = parseForComparison(lockSpecifier);
+    if (manifest.sourcePart !== lock.sourcePart) return false;
+    if (manifest.path !== lock.path) return false;
+    if (null === manifest.ref) return true;
+    return manifest.ref === lock.ref;
+}
+function normalizeInstallDir(dir) {
+    return dir ?? '.agents/skills';
+}
+function normalizeLinkTargets(targets) {
+    return targets ?? [];
+}
+function arraysEqual(a, b) {
+    if (a.length !== b.length) return false;
+    return a.every((val, i)=>val === b[i]);
+}
+function isLockInSync(manifest, lock) {
+    if (!lock) return false;
+    if (normalizeInstallDir(manifest.installDir) !== normalizeInstallDir(lock.installDir)) return false;
+    if (!arraysEqual(normalizeLinkTargets(manifest.linkTargets), normalizeLinkTargets(lock.linkTargets))) return false;
+    const manifestSkills = Object.entries(manifest.skills);
+    const lockSkillNames = Object.keys(lock.skills);
+    if (manifestSkills.length !== lockSkillNames.length) return false;
+    for (const [name, specifier] of manifestSkills){
+        const lockEntry = lock.skills[name];
+        if (!lockEntry) return false;
+        if (!isSpecifierCompatible(specifier, lockEntry.specifier)) return false;
+    }
+    return true;
+}
 async function ensureDir(dirPath) {
     await mkdir(dirPath, {
         recursive: true
     });
 }
+async function replaceDir(from, to) {
+    await rm(to, {
+        recursive: true,
+        force: true
+    });
+    await cp(from, to, {
+        recursive: true
+    });
+}
 async function replaceSymlink(target, linkPath) {
-    await promises_rm(linkPath, {
+    await rm(linkPath, {
         recursive: true,
         force: true
     });
@@ -459,26 +1201,27 @@ async function replaceSymlink(target, linkPath) {
 async function writeJson(filePath, value) {
     await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
-async function linkSkill(rootDir, installDir, linkTarget, skillName) {
-    const absoluteTarget = node_path.join(rootDir, installDir, skillName);
-    const absoluteLink = node_path.join(rootDir, linkTarget, skillName);
-    await ensureDir(node_path.dirname(absoluteLink));
-    await replaceSymlink(absoluteTarget, absoluteLink);
-}
-async function readInstallState(rootDir) {
-    const filePath = node_path.join(rootDir, '.agents/skills/.skills-pm-install-state.json');
+const INSTALL_STATE_FILE = '.skills-pm-install-state.json';
+async function readInstallState(rootDir, installDir) {
+    const filePath = node_path.join(rootDir, installDir, INSTALL_STATE_FILE);
     try {
         return JSON.parse(await readFile(filePath, 'utf8'));
     } catch  {
         return null;
     }
 }
-async function writeInstallState(rootDir, value) {
-    const dirPath = node_path.join(rootDir, '.agents/skills');
+async function writeInstallState(rootDir, installDir, value) {
+    const dirPath = node_path.join(rootDir, installDir);
     await ensureDir(dirPath);
-    const filePath = node_path.join(dirPath, '.skills-pm-install-state.json');
+    const filePath = node_path.join(dirPath, INSTALL_STATE_FILE);
     await writeJson(filePath, value);
 }
+async function linkSkill(rootDir, installDir, linkTarget, skillName) {
+    const absoluteTarget = node_path.join(rootDir, installDir, skillName);
+    const absoluteLink = node_path.join(rootDir, linkTarget, skillName);
+    await ensureDir(node_path.dirname(absoluteLink));
+    await replaceSymlink(absoluteTarget, absoluteLink);
+}
 async function materializeLocalSkill(rootDir, skillName, sourceRoot, sourcePath, installDir) {
     const relativeSkillPath = sourcePath.replace(/^\//, '');
     const absoluteSkillPath = node_path.join(sourceRoot, relativeSkillPath);
@@ -492,10 +1235,7 @@ async function materializeLocalSkill(rootDir, skillName, sourceRoot, sourcePath,
     if (!skillDoc) throw new Error(`Invalid skill at ${absoluteSkillPath}: missing SKILL.md`);
     const targetDir = node_path.join(rootDir, installDir, skillName);
     await ensureDir(node_path.dirname(targetDir));
-    await promises_cp(absoluteSkillPath, targetDir, {
-        recursive: true,
-        force: true
-    });
+    await replaceDir(absoluteSkillPath, targetDir);
     await writeJson(node_path.join(targetDir, '.skills-pm.json'), {
         name: skillName,
         installedBy: 'skills-package-manager',
@@ -504,14 +1244,24 @@ async function materializeLocalSkill(rootDir, skillName, sourceRoot, sourcePath,
 }
 const materializeGitSkill_execFileAsync = promisify(execFile);
 async function checkoutCommit(checkoutRoot, commit) {
-    await materializeGitSkill_execFileAsync('git', [
-        'checkout',
-        commit
-    ], {
-        cwd: checkoutRoot
-    });
+    try {
+        await materializeGitSkill_execFileAsync('git', [
+            'checkout',
+            commit
+        ], {
+            cwd: checkoutRoot
+        });
+    } catch (error) {
+        throw new GitError({
+            code: codes_ErrorCode.GIT_CHECKOUT_FAILED,
+            operation: 'checkout',
+            ref: commit,
+            message: `Failed to checkout commit ${commit}`,
+            cause: error
+        });
+    }
 }
-async function fetchCommitFallback(checkoutRoot, commit) {
+async function fetchCommitFallback(checkoutRoot, commit, _repoUrl) {
     try {
         await materializeGitSkill_execFileAsync('git', [
             'fetch',
@@ -554,29 +1304,65 @@ async function fetchCommitFallback(checkoutRoot, commit) {
 async function materializeGitSkill(rootDir, skillName, repoUrl, commit, sourcePath, installDir) {
     const checkoutRoot = await mkdtemp(node_path.join(tmpdir(), 'skills-pm-git-checkout-'));
     try {
-        await materializeGitSkill_execFileAsync('git', [
-            'clone',
-            '--depth',
-            '1',
-            repoUrl,
-            checkoutRoot
-        ]);
+        try {
+            await materializeGitSkill_execFileAsync('git', [
+                'clone',
+                '--depth',
+                '1',
+                repoUrl,
+                checkoutRoot
+            ]);
+        } catch (error) {
+            throw new GitError({
+                code: codes_ErrorCode.GIT_CLONE_FAILED,
+                operation: 'clone',
+                repoUrl,
+                message: `Failed to clone repository ${repoUrl}`,
+                cause: error
+            });
+        }
         if (commit && 'HEAD' !== commit) try {
             await checkoutCommit(checkoutRoot, commit);
-        } catch  {
-            await fetchCommitFallback(checkoutRoot, commit);
-            await checkoutCommit(checkoutRoot, commit);
+        } catch (checkoutError) {
+            if (checkoutError instanceof GitError) try {
+                await fetchCommitFallback(checkoutRoot, commit, repoUrl);
+                await checkoutCommit(checkoutRoot, commit);
+            } catch  {
+                throw checkoutError;
+            }
+            else throw checkoutError;
         }
         const skillDocPath = node_path.join(checkoutRoot, sourcePath.replace(/^\//, ''), 'SKILL.md');
         await readFile(skillDocPath, 'utf8');
         await materializeLocalSkill(rootDir, skillName, checkoutRoot, sourcePath, installDir);
     } finally{
-        await promises_rm(checkoutRoot, {
+        await rm(checkoutRoot, {
             recursive: true,
             force: true
         });
     }
 }
+async function materializePackedSkill(rootDir, skillName, tarballPath, sourcePath, installDir) {
+    const extractRoot = await mkdtemp(node_path.join(tmpdir(), 'skills-pm-packed-skill-'));
+    try {
+        await mkdir(node_path.join(extractRoot, 'package'), {
+            recursive: true
+        });
+        await x({
+            file: tarballPath,
+            cwd: node_path.join(extractRoot, 'package'),
+            strip: 1,
+            preservePaths: false,
+            strict: true
+        });
+        await materializeLocalSkill(rootDir, skillName, node_path.join(extractRoot, 'package'), sourcePath, installDir);
+    } finally{
+        await rm(extractRoot, {
+            recursive: true,
+            force: true
+        }).catch(()=>{});
+    }
+}
 async function isManagedSkillDir(dirPath) {
     try {
         const marker = JSON.parse(await readFile(node_path.join(dirPath, '.skills-pm.json'), 'utf8'));
@@ -595,7 +1381,7 @@ async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillN
             const skillDir = node_path.join(absoluteInstallDir, entry);
             if (await isManagedSkillDir(skillDir)) {
                 if (!wanted.has(entry)) {
-                    await promises_rm(skillDir, {
+                    await rm(skillDir, {
                         recursive: true,
                         force: true
                     });
@@ -603,7 +1389,7 @@ async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillN
                         const linkPath = node_path.join(rootDir, linkTarget, entry);
                         try {
                             const stat = await lstat(linkPath);
-                            if (stat.isSymbolicLink() || stat.isDirectory() || stat.isFile()) await promises_rm(linkPath, {
+                            if (stat.isSymbolicLink() || stat.isDirectory() || stat.isFile()) await rm(linkPath, {
                                 recursive: true,
                                 force: true
                             });
@@ -617,66 +1403,129 @@ async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillN
 const installStageHooks = {
     beforeFetch: async (_rootDir, _manifest, _lockfile)=>{}
 };
-function extractSkillPath(specifier, skillName) {
-    const marker = '#path:';
-    const index = specifier.indexOf(marker);
-    if (index >= 0) return specifier.slice(index + marker.length);
-    return `/${skillName}`;
+async function areManagedSkillsInstalled(rootDir, installDir, skillNames) {
+    for (const skillName of skillNames)try {
+        await access(node_path.join(rootDir, installDir, skillName, 'SKILL.md'));
+    } catch  {
+        return false;
+    }
+    return true;
 }
-async function fetchSkillsFromLock(rootDir, manifest, lockfile) {
+async function fetchSkillsFromLock(rootDir, manifest, lockfile, options) {
     await installStageHooks.beforeFetch(rootDir, manifest, lockfile);
+    const installDir = manifest.installDir ?? '.agents/skills';
+    const linkTargets = manifest.linkTargets ?? [];
+    await pruneManagedSkills(rootDir, installDir, linkTargets, Object.keys(lockfile.skills));
     const lockDigest = sha256(JSON.stringify(lockfile));
-    const state = await readInstallState(rootDir);
-    if (state?.lockDigest === lockDigest) return {
+    const state = await readInstallState(rootDir, installDir);
+    if (state?.lockDigest === lockDigest && await areManagedSkillsInstalled(rootDir, installDir, Object.keys(lockfile.skills))) return {
         status: 'skipped',
         reason: 'up-to-date'
     };
-    const installDir = manifest.installDir ?? '.agents/skills';
-    const linkTargets = manifest.linkTargets ?? [];
-    await pruneManagedSkills(rootDir, installDir, linkTargets, Object.keys(lockfile.skills));
-    for (const [skillName, entry] of Object.entries(lockfile.skills)){
-        if ('file' === entry.resolution.type) {
-            await materializeLocalSkill(rootDir, skillName, node_path.resolve(rootDir, entry.resolution.path), extractSkillPath(entry.specifier, skillName), installDir);
-            continue;
-        }
-        if ('git' === entry.resolution.type) {
-            await materializeGitSkill(rootDir, skillName, entry.resolution.url, entry.resolution.commit, entry.resolution.path, installDir);
-            continue;
+    const downloadedTarballs = new Map();
+    try {
+        for (const [skillName, entry] of Object.entries(lockfile.skills)){
+            if ('link' === entry.resolution.type) {
+                await materializeLocalSkill(rootDir, skillName, node_path.resolve(rootDir, entry.resolution.path), '/', installDir);
+                options?.onProgress?.({
+                    type: 'added',
+                    skillName
+                });
+                continue;
+            }
+            if ('file' === entry.resolution.type) {
+                await materializePackedSkill(rootDir, skillName, node_path.resolve(rootDir, entry.resolution.tarball), entry.resolution.path, installDir);
+                options?.onProgress?.({
+                    type: 'added',
+                    skillName
+                });
+                continue;
+            }
+            if ('git' === entry.resolution.type) {
+                await materializeGitSkill(rootDir, skillName, entry.resolution.url, entry.resolution.commit, entry.resolution.path, installDir);
+                options?.onProgress?.({
+                    type: 'added',
+                    skillName
+                });
+                continue;
+            }
+            if ('npm' === entry.resolution.type) {
+                const cacheKey = `${entry.resolution.tarball}\0${entry.resolution.integrity ?? ''}`;
+                let tarballPathPromise = downloadedTarballs.get(cacheKey);
+                if (!tarballPathPromise) {
+                    tarballPathPromise = downloadNpmPackageTarball(rootDir, entry.resolution.tarball, entry.resolution.integrity);
+                    downloadedTarballs.set(cacheKey, tarballPathPromise);
+                }
+                const tarballPath = await tarballPathPromise;
+                await materializePackedSkill(rootDir, skillName, tarballPath, entry.resolution.path, installDir);
+                options?.onProgress?.({
+                    type: 'added',
+                    skillName
+                });
+                continue;
+            }
+            throw new Error(`Unsupported resolution type in 0.1.0 core flow: ${entry.resolution.type}`);
         }
-        throw new Error(`Unsupported resolution type in 0.1.0 core flow: ${entry.resolution.type}`);
+        await writeInstallState(rootDir, installDir, {
+            lockDigest,
+            installDir,
+            linkTargets,
+            installerVersion: '0.1.0',
+            installedAt: new Date().toISOString()
+        });
+    } finally{
+        const settledTarballs = await Promise.allSettled(downloadedTarballs.values());
+        const downloadedPaths = new Set(settledTarballs.filter((result)=>'fulfilled' === result.status).map((result)=>result.value));
+        await Promise.all([
+            ...downloadedPaths
+        ].map((tarballPath)=>cleanupPackedNpmPackage(tarballPath)));
     }
-    await writeInstallState(rootDir, {
-        lockDigest,
-        installDir,
-        linkTargets,
-        installerVersion: '0.1.0',
-        installedAt: new Date().toISOString()
-    });
     return {
         status: 'fetched',
         fetched: Object.keys(lockfile.skills)
     };
 }
-async function linkSkillsFromLock(rootDir, manifest, lockfile) {
+async function linkSkillsFromLock(rootDir, manifest, lockfile, options) {
     const installDir = manifest.installDir ?? '.agents/skills';
     const linkTargets = manifest.linkTargets ?? [];
-    for (const skillName of Object.keys(lockfile.skills))for (const linkTarget of linkTargets)await linkSkill(rootDir, installDir, linkTarget, skillName);
+    for (const skillName of Object.keys(lockfile.skills)){
+        for (const linkTarget of linkTargets)await linkSkill(rootDir, installDir, linkTarget, skillName);
+        options?.onProgress?.({
+            type: 'installed',
+            skillName
+        });
+    }
     return {
         status: 'linked',
         linked: Object.keys(lockfile.skills)
     };
 }
-async function installSkills(rootDir) {
+async function installSkills(rootDir, options) {
     const manifest = await readSkillsManifest(rootDir);
     if (!manifest) return {
         status: 'skipped',
         reason: 'manifest-missing'
     };
     const currentLock = await readSkillsLock(rootDir);
-    const lockfile = await syncSkillsLock(rootDir, manifest, currentLock);
-    await fetchSkillsFromLock(rootDir, manifest, lockfile);
-    await linkSkillsFromLock(rootDir, manifest, lockfile);
-    await writeSkillsLock(rootDir, lockfile);
+    let lockfile;
+    if (options?.frozenLockfile) {
+        if (!currentLock) throw new Error('Lockfile is required in frozen mode but none was found');
+        if (!isLockInSync(manifest, currentLock)) throw new Error('Lockfile is out of sync with manifest. Run install without --frozen-lockfile to update.');
+        lockfile = currentLock;
+        for (const skillName of Object.keys(lockfile.skills))options?.onProgress?.({
+            type: 'resolved',
+            skillName
+        });
+    } else lockfile = await syncSkillsLock(rootDir, manifest, currentLock, {
+        onProgress: options?.onProgress
+    });
+    await fetchSkillsFromLock(rootDir, manifest, lockfile, {
+        onProgress: options?.onProgress
+    });
+    await linkSkillsFromLock(rootDir, manifest, lockfile, {
+        onProgress: options?.onProgress
+    });
+    if (!options?.frozenLockfile) await writeSkillsLock(rootDir, lockfile);
     return {
         status: 'installed',
         installed: Object.keys(lockfile.skills)
@@ -686,14 +1535,29 @@ function buildGitHubSpecifier(owner, repo, skillPath) {
     return `https://github.com/${owner}/${repo}.git#path:${skillPath}`;
 }
 async function addSingleSkill(cwd, specifier) {
-    const normalized = normalizeSpecifier(specifier);
+    let normalized;
+    try {
+        normalized = normalizeSpecifier(specifier);
+    } catch (error) {
+        if (error instanceof ParseError) throw error;
+        throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `Invalid specifier: ${error.message}`,
+            content: specifier,
+            cause: error
+        });
+    }
     const existingManifest = await readSkillsManifest(cwd) ?? {
         installDir: '.agents/skills',
         linkTargets: [],
         skills: {}
     };
     const existing = existingManifest.skills[normalized.skillName];
-    if (existing && existing !== normalized.normalized) throw new Error(`Skill ${normalized.skillName} already exists with a different specifier`);
+    if (existing && existing !== normalized.normalized) throw new SkillError({
+        code: codes_ErrorCode.SKILL_EXISTS,
+        skillName: normalized.skillName,
+        message: `Skill ${normalized.skillName} already exists with a different specifier`
+    });
     existingManifest.skills[normalized.skillName] = normalized.normalized;
     await writeSkillsManifest(cwd, existingManifest);
     const existingLock = await readSkillsLock(cwd);
@@ -722,7 +1586,9 @@ async function addCommand(options) {
             const skillPath = found?.path ?? `/${skill}`;
             const gitSpecifier = buildGitHubSpecifier(owner, repo, skillPath);
             const result = await addSingleSkill(cwd, gitSpecifier);
+            spinner.start('Installing skills...');
             await installSkills(cwd);
+            spinner.stop('Installed skills');
             __rspack_external__clack_prompts_3cae1695.outro(`Added ${picocolors.cyan(result.skillName)}`);
             return result;
         }
@@ -731,7 +1597,11 @@ async function addCommand(options) {
         if (0 === skills.length) {
             spinner.stop(picocolors.red('No skills found'));
             __rspack_external__clack_prompts_3cae1695.outro(picocolors.red(`No valid skills found in ${source}`));
-            throw new Error(`No skills found in ${source}`);
+            throw new SkillError({
+                code: codes_ErrorCode.SKILL_NOT_FOUND,
+                skillName: source,
+                message: `No skills found in ${source}`
+            });
         }
         spinner.stop(`Found ${picocolors.green(String(skills.length))} skill${1 !== skills.length ? 's' : ''}`);
         const selected = await promptSkillSelection(skills);
@@ -742,22 +1612,38 @@ async function addCommand(options) {
             results.push(result);
             __rspack_external__clack_prompts_3cae1695.log.success(`Added ${picocolors.cyan(result.skillName)}`);
         }
+        spinner.start('Installing skills...');
         await installSkills(cwd);
+        spinner.stop('Installed skills');
         __rspack_external__clack_prompts_3cae1695.outro('Done');
         return 1 === results.length ? results[0] : results;
     }
     const result = await addSingleSkill(cwd, specifier);
+    const spinner = __rspack_external__clack_prompts_3cae1695.spinner();
+    spinner.start('Installing skills...');
     await installSkills(cwd);
+    spinner.stop('Installed skills');
     return result;
 }
 async function assertManifestMissing(cwd) {
     const filePath = node_path.join(cwd, 'skills.json');
     try {
         await access(filePath);
-        throw new Error('skills.json already exists');
+        throw new ManifestError({
+            code: codes_ErrorCode.MANIFEST_EXISTS,
+            filePath,
+            message: 'skills.json already exists'
+        });
     } catch (error) {
+        if (error instanceof ManifestError) throw error;
         if ('ENOENT' === error.code) return;
-        throw error;
+        throw new FileSystemError({
+            code: codes_ErrorCode.FS_ERROR,
+            operation: 'access',
+            path: filePath,
+            message: `Failed to check if manifest exists: ${error.message}`,
+            cause: error
+        });
     }
 }
 function createDefaultManifest() {
@@ -776,8 +1662,186 @@ async function initCommand(options, promptInit = promptInitManifestOptions) {
     await writeSkillsManifest(options.cwd, manifest);
     return manifest;
 }
+const phaseLabelMap = {
+    resolving: 'Resolving',
+    fetching: 'Fetching',
+    linking: 'Linking',
+    finalizing: 'Finalizing',
+    done: 'Done'
+};
+function clampCount(value, total) {
+    if (value < 0) return 0;
+    if (value > total) return total;
+    return value;
+}
+function calculatePercent(snapshot) {
+    if ('done' === snapshot.phase) return 100;
+    if (0 === snapshot.total) return 0;
+    const maxSteps = 3 * snapshot.total;
+    const completed = snapshot.resolved + snapshot.added + snapshot.installed;
+    return Math.floor(completed / maxSteps * 100);
+}
+function formatSummary(snapshot) {
+    const total = snapshot.total;
+    return `resolved ${snapshot.resolved}/${total}, added ${snapshot.added}/${total}, installed ${snapshot.installed}/${total}`;
+}
+function formatTTYLine(snapshot) {
+    const percent = calculatePercent(snapshot);
+    const progress = Math.round(percent / 100 * 20);
+    const filled = '='.repeat(progress);
+    const empty = '-'.repeat(Math.max(0, 20 - progress));
+    const phase = phaseLabelMap[snapshot.phase];
+    const summary = formatSummary(snapshot);
+    const skill = snapshot.currentSkill ? `, skill: ${snapshot.currentSkill}` : '';
+    return `[${filled}${empty}] ${percent}% ${phase} ${summary}${skill}`;
+}
+function createInstallProgressReporter(options = {}) {
+    const write = options.write ?? ((text)=>process.stderr.write(text));
+    const info = options.info ?? ((text)=>console.info(text));
+    const useTTY = options.isTTY ?? true === process.stderr.isTTY;
+    const snapshot = {
+        total: 0,
+        resolved: 0,
+        added: 0,
+        installed: 0,
+        phase: 'resolving'
+    };
+    let renderedTTY = false;
+    let lastLineLength = 0;
+    function renderTTY() {
+        const line = formatTTYLine(snapshot);
+        const clearPadding = lastLineLength > line.length ? ' '.repeat(lastLineLength - line.length) : '';
+        write(`\r${line}${clearPadding}`);
+        lastLineLength = line.length;
+        renderedTTY = true;
+    }
+    function logStage(phase) {
+        info(`spm install: ${phaseLabelMap[phase].toLowerCase()}...`);
+    }
+    function render() {
+        if (useTTY) return void renderTTY();
+    }
+    return {
+        start (total) {
+            snapshot.total = Math.max(0, total);
+            snapshot.resolved = 0;
+            snapshot.added = 0;
+            snapshot.installed = 0;
+            snapshot.phase = 'resolving';
+            snapshot.currentSkill = void 0;
+            if (useTTY) renderTTY();
+            else {
+                const noun = 1 === snapshot.total ? 'skill' : 'skills';
+                info(`spm install: starting (${snapshot.total} ${noun})`);
+                logStage('resolving');
+            }
+        },
+        setPhase (phase) {
+            snapshot.phase = phase;
+            snapshot.currentSkill = void 0;
+            render();
+            if (!useTTY && 'finalizing' !== phase) logStage(phase);
+        },
+        onProgress (event) {
+            snapshot.currentSkill = event.skillName;
+            switch(event.type){
+                case 'resolved':
+                    snapshot.resolved = clampCount(snapshot.resolved + 1, snapshot.total);
+                    break;
+                case 'added':
+                    snapshot.added = clampCount(snapshot.added + 1, snapshot.total);
+                    break;
+                case 'installed':
+                    snapshot.installed = clampCount(snapshot.installed + 1, snapshot.total);
+                    break;
+                default:
+            }
+            render();
+        },
+        complete () {
+            snapshot.phase = 'done';
+            snapshot.currentSkill = void 0;
+            const summary = formatSummary(snapshot);
+            if (useTTY) {
+                renderTTY();
+                write('\n');
+            }
+            info(`spm install: ${summary}`);
+        },
+        fail () {
+            if (useTTY && renderedTTY) write('\n');
+        }
+    };
+}
 async function installCommand(options) {
-    return installSkills(options.cwd);
+    const manifest = await readSkillsManifest(options.cwd);
+    if (!manifest) throw new ManifestError({
+        code: codes_ErrorCode.MANIFEST_NOT_FOUND,
+        filePath: `${options.cwd}/skills.json`,
+        message: 'No skills.json found in the current directory. Run "spm init" to create one.'
+    });
+    const currentLock = await readSkillsLock(options.cwd);
+    const totalSkills = Object.keys(manifest.skills).length;
+    const reporter = createInstallProgressReporter();
+    const onProgress = (event)=>reporter.onProgress(event);
+    let started = false;
+    try {
+        if (options.frozenLockfile) {
+            if (!currentLock) throw new ManifestError({
+                code: codes_ErrorCode.LOCKFILE_NOT_FOUND,
+                filePath: `${options.cwd}/skills-lock.yaml`,
+                message: 'Lockfile is required in frozen mode but none was found. Run "spm install" first.'
+            });
+            if (!isLockInSync(manifest, currentLock)) throw new ManifestError({
+                code: codes_ErrorCode.LOCKFILE_OUTDATED,
+                filePath: `${options.cwd}/skills-lock.yaml`,
+                message: 'Lockfile is out of sync with manifest. Run install without --frozen-lockfile to update.'
+            });
+            reporter.start(totalSkills);
+            started = true;
+            for (const skillName of Object.keys(currentLock.skills))onProgress({
+                type: 'resolved',
+                skillName
+            });
+            reporter.setPhase('fetching');
+            await fetchSkillsFromLock(options.cwd, manifest, currentLock, {
+                onProgress
+            });
+            reporter.setPhase('linking');
+            await linkSkillsFromLock(options.cwd, manifest, currentLock, {
+                onProgress
+            });
+            reporter.setPhase('finalizing');
+            reporter.complete();
+            return {
+                status: 'installed',
+                installed: Object.keys(currentLock.skills)
+            };
+        }
+        reporter.start(totalSkills);
+        started = true;
+        const lockfile = await syncSkillsLock(options.cwd, manifest, currentLock, {
+            onProgress
+        });
+        reporter.setPhase('fetching');
+        await fetchSkillsFromLock(options.cwd, manifest, lockfile, {
+            onProgress
+        });
+        reporter.setPhase('linking');
+        await linkSkillsFromLock(options.cwd, manifest, lockfile, {
+            onProgress
+        });
+        reporter.setPhase('finalizing');
+        await writeSkillsLock(options.cwd, lockfile);
+        reporter.complete();
+        return {
+            status: 'installed',
+            installed: Object.keys(lockfile.skills)
+        };
+    } catch (error) {
+        if (started) reporter.fail();
+        throw error;
+    }
 }
 function createEmptyResult() {
     return {
@@ -788,7 +1852,7 @@ function createEmptyResult() {
         failed: []
     };
 }
-function createBaseLock(cwd, currentLock) {
+function createBaseLock(_cwd, currentLock) {
     if (currentLock) return {
         ...currentLock,
         skills: {
@@ -804,27 +1868,44 @@ function createBaseLock(cwd, currentLock) {
 }
 async function updateCommand(options) {
     const manifest = await readSkillsManifest(options.cwd);
-    if (!manifest) return createEmptyResult();
+    if (!manifest) throw new ManifestError({
+        code: codes_ErrorCode.MANIFEST_NOT_FOUND,
+        filePath: `${options.cwd}/skills.json`,
+        message: 'No skills.json found in the current directory. Run "spm init" to create one.'
+    });
     const currentLock = await readSkillsLock(options.cwd);
     const targetSkills = options.skills ?? Object.keys(manifest.skills);
-    for (const skillName of targetSkills)if (!(skillName in manifest.skills)) throw new Error(`Unknown skill: ${skillName}`);
+    for (const skillName of targetSkills)if (!(skillName in manifest.skills)) throw new SkillError({
+        code: codes_ErrorCode.SKILL_NOT_FOUND,
+        skillName,
+        message: `Unknown skill: ${skillName}`
+    });
     const result = createEmptyResult();
     const candidateLock = createBaseLock(options.cwd, currentLock);
     candidateLock.installDir = manifest.installDir ?? '.agents/skills';
     candidateLock.linkTargets = manifest.linkTargets ?? [];
     for (const skillName of targetSkills){
         const specifier = manifest.skills[skillName];
-        if (specifier.startsWith('file:')) {
-            result.skipped.push({
-                name: skillName,
-                reason: 'file-specifier'
-            });
-            continue;
-        }
         try {
+            const normalized = normalizeSpecifier(specifier);
+            if ('link' === normalized.type) {
+                result.skipped.push({
+                    name: skillName,
+                    reason: 'link-specifier'
+                });
+                continue;
+            }
             const { entry } = await resolveLockEntry(options.cwd, specifier);
             const previous = currentLock?.skills[skillName];
-            if (previous?.resolution.type === 'git' && 'git' === entry.resolution.type && previous.resolution.commit === entry.resolution.commit) {
+            if (previous?.resolution.type === 'git' && 'git' === entry.resolution.type && previous.specifier === entry.specifier && previous.resolution.url === entry.resolution.url && previous.resolution.commit === entry.resolution.commit && previous.resolution.path === entry.resolution.path) {
+                result.unchanged.push(skillName);
+                continue;
+            }
+            if (previous?.resolution.type === 'npm' && 'npm' === entry.resolution.type && previous.specifier === entry.specifier && previous.resolution.packageName === entry.resolution.packageName && previous.resolution.version === entry.resolution.version && previous.resolution.path === entry.resolution.path && previous.resolution.tarball === entry.resolution.tarball && previous.resolution.integrity === entry.resolution.integrity && previous.resolution.registry === entry.resolution.registry) {
+                result.unchanged.push(skillName);
+                continue;
+            }
+            if (previous?.resolution.type === 'file' && 'file' === entry.resolution.type && previous.specifier === entry.specifier && previous.digest === entry.digest) {
                 result.unchanged.push(skillName);
                 continue;
             }
@@ -847,9 +1928,6 @@ async function updateCommand(options) {
     result.status = result.updated.length > 0 ? 'updated' : 'skipped';
     return result;
 }
-var package_namespaceObject = {
-    rE: "0.2.0"
-};
 function createHandlers(overrides) {
     return {
         addCommand: addCommand,
@@ -870,7 +1948,7 @@ async function runCli(argv, context = {}) {
     cli.help();
     cli.version(packageVersion);
     cli.showVersionOnExit = false;
-    cli.command('add [...positionals]').option('--skill <name>', 'Select a skill').action((positionals = [], options)=>{
+    cli.command('add [...positionals]').option('--skill <name>', 'Select a skill').action(async (positionals = [], options)=>{
         const specifier = positionals[0];
         if (!specifier) throw new Error('Missing required specifier');
         return handlers.addCommand({
@@ -879,16 +1957,17 @@ async function runCli(argv, context = {}) {
             skill: options.skill
         });
     });
-    cli.command('install [...args]').action(()=>handlers.installCommand({
-            cwd
+    cli.command('install [...args]').option('--frozen-lockfile', 'Fail if lockfile is out of sync').action(async (_args, options)=>handlers.installCommand({
+            cwd,
+            frozenLockfile: options.frozenLockfile
         }));
-    cli.command('update [...skills]').action((skills = [])=>handlers.updateCommand({
+    cli.command('update [...skills]').action(async (skills = [])=>handlers.updateCommand({
             cwd,
             skills: skills.length > 0 ? skills : void 0
         }));
     cli.command('init [...args]', '', {
         allowUnknownOptions: true
-    }).option('--yes [value]', 'Skip prompts and write defaults').action((args = [], options)=>{
+    }).option('--yes [value]', 'Skip prompts and write defaults').action(async (args = [], options)=>{
         if (args.length > 0) throw new Error('init does not accept positional arguments');
         for (const key of Object.keys(options))if ('--' !== key) {
             if ('yes' !== key) throw new Error(`Unknown flag for init: --${formatFlagName(key)}`);
@@ -907,6 +1986,14 @@ async function runCli(argv, context = {}) {
     if (argv.length <= 2) return void cli.outputHelp();
     if (globalOptions.help || globalOptions.h) return;
     if (!cli.matchedCommand) throw new Error(`Unknown command: ${argv[2]}`);
-    return cli.runMatchedCommand();
+    try {
+        return await cli.runMatchedCommand();
+    } catch (error) {
+        if (error instanceof SpmError) {
+            const enhancedError = new Error(formatErrorForDisplay(error));
+            throw enhancedError;
+        }
+        throw error;
+    }
 }
-export { addCommand, cloneAndDiscover, discoverSkillsInDir, fetchSkillsFromLock, initCommand, installCommand, installSkills, installStageHooks, linkSkillsFromLock, listRepoSkills, parseGitHubUrl, parseOwnerRepo, resolveLockEntry, runCli, updateCommand };
+export { FileSystemError, GitError, ManifestError, NetworkError, ParseError, SkillError, SpmError, addCommand, cloneAndDiscover, codes_ErrorCode as ErrorCode, convertNodeError, createInstallProgressReporter, discoverSkillsInDir, fetchSkillsFromLock, formatErrorForDisplay, getExitCode, initCommand, installCommand, installSkills, installStageHooks, isLockInSync, isSpmError, linkSkillsFromLock, listRepoSkills, normalizeSpecifier, parseGitHubUrl, parseOwnerRepo, parseSpecifier, readSkillsLock, readSkillsManifest, resolveLockEntry, runCli, updateCommand, writeSkillsLock, writeSkillsManifest };