reskill 1.1.0 → 1.2.0

package/dist/index.js

@@ -3,6 +3,7 @@ import * as __WEBPACK_EXTERNAL_MODULE_node_os__ from "node:os";
 import * as __WEBPACK_EXTERNAL_MODULE_node_path__ from "node:path";
 import * as __WEBPACK_EXTERNAL_MODULE_node_child_process__ from "node:child_process";
 import * as __WEBPACK_EXTERNAL_MODULE_node_util__ from "node:util";
+import * as __WEBPACK_EXTERNAL_MODULE_node_stream_promises__ from "node:stream/promises";
 import * as __WEBPACK_EXTERNAL_MODULE_semver__ from "semver";
 import * as __WEBPACK_EXTERNAL_MODULE_chalk__ from "chalk";
 var __webpack_modules__ = {
@@ -10,19 +11,33 @@ var __webpack_modules__ = {
         module.exports = __WEBPACK_EXTERNAL_MODULE_node_fs__;
     }
 };
+/************************************************************************/ // The module cache
 var __webpack_module_cache__ = {};
+// The require function
 function __webpack_require__(moduleId) {
+    // Check if module is in cache
     var cachedModule = __webpack_module_cache__[moduleId];
     if (void 0 !== cachedModule) return cachedModule.exports;
+    // Create a new module (and put it into the cache)
     var module = __webpack_module_cache__[moduleId] = {
         exports: {}
     };
+    // Execute the module function
     __webpack_modules__[moduleId](module, module.exports, __webpack_require__);
+    // Return the exports of the module
     return module.exports;
 }
+/************************************************************************/ // EXTERNAL MODULE: external "node:fs"
 var external_node_fs_ = __webpack_require__("node:fs");
-const agent_registry_home = (0, __WEBPACK_EXTERNAL_MODULE_node_os__.homedir)();
-const agents = {
+/**
+ * Agent Registry - Multi-Agent configuration definitions
+ *
+ * Supports global and project-level installation for 17 coding agents
+ * Reference: https://github.com/vercel-labs/add-skill
+ */ const agent_registry_home = (0, __WEBPACK_EXTERNAL_MODULE_node_os__.homedir)();
+/**
+ * All supported Agents configuration
+ */ const agents = {
     amp: {
         name: 'amp',
         displayName: 'Amp',
@@ -143,52 +158,81 @@ const agents = {
         detectInstalled: async ()=>(0, external_node_fs_.existsSync)((0, __WEBPACK_EXTERNAL_MODULE_node_path__.join)(agent_registry_home, '.neovate'))
     }
 };
-function getAllAgentTypes() {
+/**
+ * Get all Agent type list
+ */ function getAllAgentTypes() {
     return Object.keys(agents);
 }
-async function detectInstalledAgents() {
+/**
+ * Detect installed Agents
+ */ async function detectInstalledAgents() {
     const installed = [];
     for (const [type, config] of Object.entries(agents))if (await config.detectInstalled()) installed.push(type);
     return installed;
 }
-function getAgentConfig(type) {
+/**
+ * Get Agent configuration
+ */ function getAgentConfig(type) {
     return agents[type];
 }
-function isValidAgentType(type) {
+/**
+ * Validate if Agent type is valid
+ */ function isValidAgentType(type) {
     return type in agents;
 }
-function getAgentSkillsDir(type, options = {}) {
+/**
+ * Get Agent's project-level skills directory
+ */ function getAgentSkillsDir(type, options = {}) {
     const config = agents[type];
     if (options.global) return config.globalSkillsDir;
     const cwd = options.cwd || process.cwd();
     return (0, __WEBPACK_EXTERNAL_MODULE_node_path__.join)(cwd, config.skillsDir);
 }
-function exists(filePath) {
+/**
+ * File system utilities
+ */ /**
+ * Check if a file or directory exists
+ */ function exists(filePath) {
     return external_node_fs_.existsSync(filePath);
 }
-function readJson(filePath) {
+/**
+ * Read JSON file
+ */ function readJson(filePath) {
     const content = external_node_fs_.readFileSync(filePath, 'utf-8');
     return JSON.parse(content);
 }
-function writeJson(filePath, data, indent = 2) {
+/**
+ * Write JSON file
+ */ function writeJson(filePath, data, indent = 2) {
     const dir = __WEBPACK_EXTERNAL_MODULE_node_path__.dirname(filePath);
     if (!exists(dir)) external_node_fs_.mkdirSync(dir, {
         recursive: true
     });
     external_node_fs_.writeFileSync(filePath, `${JSON.stringify(data, null, indent)}\n`, 'utf-8');
 }
-function ensureDir(dirPath) {
+/**
+ * Create directory recursively
+ */ function ensureDir(dirPath) {
     if (!exists(dirPath)) external_node_fs_.mkdirSync(dirPath, {
         recursive: true
     });
 }
-function remove(targetPath) {
+/**
+ * Remove file or directory
+ */ function remove(targetPath) {
     if (exists(targetPath)) external_node_fs_.rmSync(targetPath, {
         recursive: true,
         force: true
     });
 }
-function copyDir(src, dest, options) {
+/**
+ * Copy directory recursively
+ *
+ * @param src - Source directory
+ * @param dest - Destination directory
+ * @param options.exclude - Array of filenames to exclude
+ * @param options.excludePrefix - Prefix for files to exclude (e.g., '_' to exclude _private.md)
+ */ function copyDir(src, dest, options) {
     const exclude = options?.exclude || [];
     const excludePrefix = options?.excludePrefix || '_';
     ensureDir(dest);
@@ -196,6 +240,7 @@ function copyDir(src, dest, options) {
         withFileTypes: true
     });
     for (const entry of entries){
+        // Skip files in exclude list or starting with excludePrefix
         if (exclude.includes(entry.name) || entry.name.startsWith(excludePrefix)) continue;
         const srcPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(src, entry.name);
         const destPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(dest, entry.name);
@@ -203,72 +248,134 @@ function copyDir(src, dest, options) {
         else external_node_fs_.copyFileSync(srcPath, destPath);
     }
 }
-function listDir(dirPath) {
+/**
+ * List directory contents
+ */ function listDir(dirPath) {
     if (!exists(dirPath)) return [];
     return external_node_fs_.readdirSync(dirPath);
 }
-function isDirectory(targetPath) {
+/**
+ * Check if path is a directory
+ */ function isDirectory(targetPath) {
     if (!exists(targetPath)) return false;
     return external_node_fs_.statSync(targetPath).isDirectory();
 }
-function isSymlink(targetPath) {
+/**
+ * Check if path is a symbolic link
+ */ function isSymlink(targetPath) {
     if (!exists(targetPath)) return false;
     return external_node_fs_.lstatSync(targetPath).isSymbolicLink();
 }
-function getRealPath(linkPath) {
+/**
+ * Get real path of symbolic link
+ */ function getRealPath(linkPath) {
     return external_node_fs_.realpathSync(linkPath);
 }
-function getSkillsJsonPath(projectRoot) {
+/**
+ * Get skills.json path for current project
+ */ function getSkillsJsonPath(projectRoot) {
     const root = projectRoot || process.cwd();
     return __WEBPACK_EXTERNAL_MODULE_node_path__.join(root, 'skills.json');
 }
-function getSkillsLockPath(projectRoot) {
+/**
+ * Get skills.lock path for current project
+ */ function getSkillsLockPath(projectRoot) {
     const root = projectRoot || process.cwd();
     return __WEBPACK_EXTERNAL_MODULE_node_path__.join(root, 'skills.lock');
 }
-function getCacheDir() {
+/**
+ * Get global cache directory
+ */ function getCacheDir() {
     const home = process.env.HOME || process.env.USERPROFILE || '';
     return process.env.RESKILL_CACHE_DIR || __WEBPACK_EXTERNAL_MODULE_node_path__.join(home, '.reskill-cache');
 }
-function getHomeDir() {
+/**
+ * Get home directory
+ */ function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || '';
 }
-function getGlobalSkillsDir() {
+/**
+ * Get global skills installation directory (~/.claude/skills)
+ * @deprecated Use getAgentGlobalSkillsDir from agent-registry instead
+ */ function getGlobalSkillsDir() {
     const home = getHomeDir();
     return __WEBPACK_EXTERNAL_MODULE_node_path__.join(home, '.claude', 'skills');
 }
-const AGENTS_DIR = '.agents';
+// ============================================================================
+// Multi-Agent path utilities
+// ============================================================================
+/**
+ * Canonical skills directory name
+ */ const AGENTS_DIR = '.agents';
 const SKILLS_SUBDIR = 'skills';
-function getCanonicalSkillsDir(options = {}) {
+/**
+ * Get canonical skills directory path
+ *
+ * Canonical location: .agents/skills/ (project level) or ~/.agents/skills/ (global)
+ * This is the storage location for skill source files, each agent directory points here via symlinks
+ */ function getCanonicalSkillsDir(options = {}) {
     const { global: isGlobal = false, cwd } = options;
     const baseDir = isGlobal ? getHomeDir() : cwd || process.cwd();
     return __WEBPACK_EXTERNAL_MODULE_node_path__.join(baseDir, AGENTS_DIR, SKILLS_SUBDIR);
 }
-function getCanonicalSkillPath(skillName, options = {}) {
+/**
+ * Get canonical skill path
+ */ function getCanonicalSkillPath(skillName, options = {}) {
     return __WEBPACK_EXTERNAL_MODULE_node_path__.join(getCanonicalSkillsDir(options), skillName);
 }
-function shortenPath(fullPath, cwd) {
+/**
+ * Shorten path display (replace home directory with ~)
+ */ function shortenPath(fullPath, cwd) {
     const home = getHomeDir();
     const currentDir = cwd || process.cwd();
     if (fullPath.startsWith(home)) return fullPath.replace(home, '~');
     if (fullPath.startsWith(currentDir)) return `.${fullPath.slice(currentDir.length)}`;
     return fullPath;
 }
-function isPathSafe(basePath, targetPath) {
+/**
+ * Validate path safety (prevent path traversal attacks)
+ */ function isPathSafe(basePath, targetPath) {
     const normalizedBase = __WEBPACK_EXTERNAL_MODULE_node_path__.normalize(__WEBPACK_EXTERNAL_MODULE_node_path__.resolve(basePath));
     const normalizedTarget = __WEBPACK_EXTERNAL_MODULE_node_path__.normalize(__WEBPACK_EXTERNAL_MODULE_node_path__.resolve(targetPath));
     return normalizedTarget.startsWith(normalizedBase + __WEBPACK_EXTERNAL_MODULE_node_path__.sep) || normalizedTarget === normalizedBase;
 }
-function sanitizeName(name) {
+/**
+ * Sanitize filename (prevent path traversal attacks)
+ */ function sanitizeName(name) {
+    // Remove path separators and special characters
     let sanitized = name.replace(/[/\\:\0]/g, '');
+    // Remove leading and trailing dots and spaces
     sanitized = sanitized.replace(/^[.\s]+|[.\s]+$/g, '');
+    // Remove leading dots
     sanitized = sanitized.replace(/^\.+/, '');
     if (!sanitized || 0 === sanitized.length) sanitized = 'unnamed-skill';
     if (sanitized.length > 255) sanitized = sanitized.substring(0, 255);
     return sanitized;
 }
 const git_execAsync = (0, __WEBPACK_EXTERNAL_MODULE_node_util__.promisify)(__WEBPACK_EXTERNAL_MODULE_node_child_process__.exec);
-class GitCloneError extends Error {
+/**
+ * Git utilities
+ */ /**
+ * SSH command with auto-accept for new host keys
+ * Uses StrictHostKeyChecking=accept-new which:
+ * - Automatically accepts keys for hosts not in known_hosts
+ * - Still rejects connections if a known host's key has changed (security)
+ */ const GIT_SSH_COMMAND = 'ssh -o StrictHostKeyChecking=accept-new -o BatchMode=yes';
+/**
+ * Get environment variables for git commands that access remote repositories
+ * Configures SSH to auto-accept new host keys and disables interactive prompts
+ */ function getGitEnv() {
+    return {
+        ...process.env,
+        GIT_SSH_COMMAND,
+        // Disable interactive prompts for HTTPS as well
+        GIT_TERMINAL_PROMPT: '0'
+    };
+}
+/**
+ * Custom error class for Git clone failures
+ * Provides helpful tips for private repository authentication
+ */ class GitCloneError extends Error {
     repoUrl;
     originalError;
     isAuthError;
@@ -283,6 +390,7 @@ class GitCloneError extends Error {
                 message += '\n  - Check ~/.ssh/id_rsa or ~/.ssh/id_ed25519';
                 message += '\n  - Ensure SSH key is added to your Git hosting service';
             } else {
+                // HTTPS or unknown
                 message += "\n  - Run 'git config --global credential.helper store'";
                 message += '\n  - Or use a personal access token in the URL';
             }
@@ -294,12 +402,16 @@ class GitCloneError extends Error {
         this.isAuthError = isAuthError;
         this.urlType = urlType;
     }
-    static detectUrlType(url) {
+    /**
+   * Detect URL type from repository URL
+   */ static detectUrlType(url) {
         if (url.startsWith('git@') || url.startsWith('ssh://')) return 'ssh';
         if (url.startsWith('http://') || url.startsWith('https://')) return 'https';
         return 'unknown';
     }
-    static isAuthenticationError(message) {
+    /**
+   * Check if an error message indicates an authentication problem
+   */ static isAuthenticationError(message) {
         const authPatterns = [
             /permission denied/i,
             /could not read from remote/i,
@@ -314,14 +426,19 @@ class GitCloneError extends Error {
         return authPatterns.some((pattern)=>pattern.test(message));
     }
 }
-async function git(args, cwd) {
+/**
+ * Execute git command asynchronously
+ */ async function git(args, cwd) {
     const { stdout } = await git_execAsync(`git ${args.join(' ')}`, {
         cwd,
-        encoding: 'utf-8'
+        encoding: 'utf-8',
+        env: getGitEnv()
     });
     return stdout.trim();
 }
-async function getRemoteTags(repoUrl) {
+/**
+ * Get remote tags for a repository
+ */ async function getRemoteTags(repoUrl) {
     try {
         const output = await git([
             'ls-remote',
@@ -335,6 +452,7 @@ async function getRemoteTags(repoUrl) {
         for (const line of lines){
             const [commit, ref] = line.split('\t');
             if (commit && ref) {
+                // Extract tag name from refs/tags/v1.0.0
                 const tagName = ref.replace('refs/tags/', '');
                 tags.push({
                     name: tagName,
@@ -347,9 +465,12 @@ async function getRemoteTags(repoUrl) {
         return [];
     }
 }
-async function getLatestTag(repoUrl) {
+/**
+ * Get latest tag from repository
+ */ async function getLatestTag(repoUrl) {
     const tags = await getRemoteTags(repoUrl);
     if (0 === tags.length) return null;
+    // Sort by semver (simple version sort)
     const sortedTags = tags.sort((a, b)=>{
         const aVer = a.name.replace(/^v/, '');
         const bVer = b.name.replace(/^v/, '');
@@ -357,7 +478,11 @@ async function getLatestTag(repoUrl) {
     });
     return sortedTags[0];
 }
-async function clone(repoUrl, destPath, options) {
+/**
+ * Clone a repository with shallow clone
+ *
+ * @throws {GitCloneError} When clone fails, with helpful tips for authentication issues
+ */ async function clone(repoUrl, destPath, options) {
     const args = [
         'clone'
     ];
@@ -370,13 +495,17 @@ async function clone(repoUrl, destPath, options) {
         throw new GitCloneError(repoUrl, error);
     }
 }
-async function getCurrentCommit(cwd) {
+/**
+ * Get current commit hash
+ */ async function getCurrentCommit(cwd) {
     return git([
         'rev-parse',
         'HEAD'
     ], cwd);
 }
-async function getDefaultBranch(repoUrl) {
+/**
+ * Get default branch name
+ */ async function getDefaultBranch(repoUrl) {
     try {
         const output = await git([
             'ls-remote',
@@ -390,7 +519,9 @@ async function getDefaultBranch(repoUrl) {
         return 'main';
     }
 }
-function compareVersions(a, b) {
+/**
+ * Simple version comparison (for sorting)
+ */ function compareVersions(a, b) {
     const aParts = a.split('.').map((p)=>parseInt(p, 10) || 0);
     const bParts = b.split('.').map((p)=>parseInt(p, 10) || 0);
     const maxLength = Math.max(aParts.length, bParts.length);
@@ -402,24 +533,40 @@ function compareVersions(a, b) {
     }
     return 0;
 }
-function buildRepoUrl(registry, ownerRepo) {
-    const registryUrls = {
-        github: 'https://github.com',
-        gitlab: 'https://gitlab.com'
-    };
-    const baseUrl = registryUrls[registry] || `https://${registry}`;
-    return `${baseUrl}/${ownerRepo}`;
-}
-function isGitUrl(source) {
+/**
+ * Check if a source string is a complete Git URL (SSH, HTTPS, or git://)
+ *
+ * Supported formats:
+ * - SSH: git@github.com:user/repo.git
+ * - HTTPS: https://github.com/user/repo.git
+ * - Git protocol: git://github.com/user/repo.git
+ * - URLs ending with .git
+ */ function isGitUrl(source) {
     return source.startsWith('git@') || source.startsWith('git://') || source.startsWith('http://') || source.startsWith('https://') || source.endsWith('.git');
 }
-function parseGitUrl(url) {
+/**
+ * Parse a Git URL and extract host, owner, and repo information
+ *
+ * Supports:
+ * - SSH: git@github.com:user/repo.git
+ * - HTTPS: https://github.com/user/repo.git
+ * - Git protocol: git://github.com/user/repo.git
+ *
+ * Note: GitHub/GitLab web URLs (with /tree/, /blob/, etc.) are handled
+ * at a higher level in GitResolver.parseGitUrlRef() before calling this function.
+ *
+ * @param url The Git URL to parse
+ * @returns Parsed URL information or null if parsing fails
+ */ function parseGitUrl(url) {
+    // Remove trailing .git if present
     const cleanUrl = url.replace(/\.git$/, '');
+    // SSH format: git@github.com:user/repo
     const sshMatch = cleanUrl.match(/^git@([^:]+):(.+)$/);
     if (sshMatch) {
         const [, host, path] = sshMatch;
         const parts = path.split('/');
         if (parts.length >= 2) {
+            // Handle nested paths like org/sub/repo
             const owner = parts.slice(0, -1).join('/');
             const repo = parts[parts.length - 1];
             return {
@@ -431,6 +578,7 @@ function parseGitUrl(url) {
             };
         }
     }
+    // HTTPS/Git protocol format: https://github.com/user/repo or git://github.com/user/repo
     const httpMatch = cleanUrl.match(/^(https?|git):\/\/([^/]+)\/(.+)$/);
     if (httpMatch) {
         const [, protocol, host, path] = httpMatch;
@@ -449,50 +597,286 @@ function parseGitUrl(url) {
     }
     return null;
 }
-const installer_AGENTS_DIR = '.agents';
+/**
+ * HTTP utilities for downloading and extracting skill archives
+ */ /**
+ * Custom error class for HTTP download failures
+ */ class HttpDownloadError extends Error {
+    url;
+    statusCode;
+    originalError;
+    constructor(url, message, statusCode, originalError){
+        super(message);
+        this.name = 'HttpDownloadError';
+        this.url = url;
+        this.statusCode = statusCode;
+        this.originalError = originalError;
+    }
+}
+/**
+ * Download a file from HTTP/HTTPS URL
+ *
+ * @param url - URL to download from
+ * @param destPath - Destination file path
+ * @param options - Download options
+ */ async function downloadFile(url, destPath, options = {}) {
+    const { timeout = 60000, headers = {} } = options;
+    // Ensure destination directory exists
+    ensureDir(__WEBPACK_EXTERNAL_MODULE_node_path__.dirname(destPath));
+    try {
+        // Use native fetch for HTTP/HTTPS
+        const controller = new AbortController();
+        const timeoutId = setTimeout(()=>controller.abort(), timeout);
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                'User-Agent': 'reskill/1.0',
+                ...headers
+            }
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) throw new HttpDownloadError(url, `HTTP ${response.status}: ${response.statusText}`, response.status);
+        // Stream response to file
+        const fileStream = external_node_fs_.createWriteStream(destPath);
+        const body = response.body;
+        if (!body) throw new HttpDownloadError(url, 'Response body is empty');
+        // Convert Web ReadableStream to Node.js Readable
+        const { Readable } = await import("node:stream");
+        const nodeStream = Readable.fromWeb(body);
+        await (0, __WEBPACK_EXTERNAL_MODULE_node_stream_promises__.pipeline)(nodeStream, fileStream);
+    } catch (error) {
+        // Clean up partial download
+        if (external_node_fs_.existsSync(destPath)) external_node_fs_.unlinkSync(destPath);
+        if (error instanceof HttpDownloadError) throw error;
+        const err = error;
+        if ('AbortError' === err.name) throw new HttpDownloadError(url, `Download timeout after ${timeout}ms`);
+        throw new HttpDownloadError(url, `Download failed: ${err.message}`, void 0, err);
+    }
+}
+/**
+ * Extract an archive to a directory
+ *
+ * @param archivePath - Path to the archive file
+ * @param destDir - Destination directory
+ * @param format - Archive format (auto-detected from extension if not provided)
+ */ async function extractArchive(archivePath, destDir, format) {
+    // Auto-detect format from extension
+    const detectedFormat = format || detectArchiveFormat(archivePath);
+    if (!detectedFormat) throw new Error(`Unable to detect archive format for: ${archivePath}`);
+    // Ensure destination directory exists
+    ensureDir(destDir);
+    switch(detectedFormat){
+        case 'tar.gz':
+        case 'tgz':
+        case 'tar':
+            await extractTar(archivePath, destDir, 'tar.gz' === detectedFormat || 'tgz' === detectedFormat);
+            break;
+        case 'zip':
+            await extractZip(archivePath, destDir);
+            break;
+        default:
+            throw new Error(`Unsupported archive format: ${detectedFormat}`);
+    }
+}
+/**
+ * Extract tar archive using native tar command
+ */ async function extractTar(archivePath, destDir, gzipped) {
+    const { exec } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execAsync = promisify(exec);
+    const flags = gzipped ? '-xzf' : '-xf';
+    try {
+        // Extract to a temp directory first to handle single-folder archives
+        const tempExtractDir = `${destDir}.extract-temp`;
+        ensureDir(tempExtractDir);
+        await execAsync(`tar ${flags} "${archivePath}" -C "${tempExtractDir}"`, {
+            encoding: 'utf-8'
+        });
+        // Check if archive contains a single root directory
+        const extractedItems = external_node_fs_.readdirSync(tempExtractDir);
+        if (1 === extractedItems.length) {
+            const singleItem = __WEBPACK_EXTERNAL_MODULE_node_path__.join(tempExtractDir, extractedItems[0]);
+            if (external_node_fs_.statSync(singleItem).isDirectory()) {
+                // Move contents of single directory to destination
+                const contents = external_node_fs_.readdirSync(singleItem);
+                for (const item of contents){
+                    const src = __WEBPACK_EXTERNAL_MODULE_node_path__.join(singleItem, item);
+                    const dest = __WEBPACK_EXTERNAL_MODULE_node_path__.join(destDir, item);
+                    external_node_fs_.renameSync(src, dest);
+                }
+                remove(tempExtractDir);
+                return;
+            }
+        }
+        // Move all items to destination
+        for (const item of extractedItems){
+            const src = __WEBPACK_EXTERNAL_MODULE_node_path__.join(tempExtractDir, item);
+            const dest = __WEBPACK_EXTERNAL_MODULE_node_path__.join(destDir, item);
+            external_node_fs_.renameSync(src, dest);
+        }
+        remove(tempExtractDir);
+    } catch (error) {
+        throw new Error(`Failed to extract tar archive: ${error.message}`);
+    }
+}
+/**
+ * Extract zip archive using native unzip command or Node.js
+ */ async function extractZip(archivePath, destDir) {
+    const { exec } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execAsync = promisify(exec);
+    try {
+        // Extract to a temp directory first
+        const tempExtractDir = `${destDir}.extract-temp`;
+        ensureDir(tempExtractDir);
+        // Try using unzip command (available on most systems)
+        await execAsync(`unzip -q "${archivePath}" -d "${tempExtractDir}"`, {
+            encoding: 'utf-8'
+        });
+        // Check if archive contains a single root directory
+        const extractedItems = external_node_fs_.readdirSync(tempExtractDir);
+        if (1 === extractedItems.length) {
+            const singleItem = __WEBPACK_EXTERNAL_MODULE_node_path__.join(tempExtractDir, extractedItems[0]);
+            if (external_node_fs_.statSync(singleItem).isDirectory()) {
+                // Move contents of single directory to destination
+                const contents = external_node_fs_.readdirSync(singleItem);
+                for (const item of contents){
+                    const src = __WEBPACK_EXTERNAL_MODULE_node_path__.join(singleItem, item);
+                    const dest = __WEBPACK_EXTERNAL_MODULE_node_path__.join(destDir, item);
+                    external_node_fs_.renameSync(src, dest);
+                }
+                remove(tempExtractDir);
+                return;
+            }
+        }
+        // Move all items to destination
+        for (const item of extractedItems){
+            const src = __WEBPACK_EXTERNAL_MODULE_node_path__.join(tempExtractDir, item);
+            const dest = __WEBPACK_EXTERNAL_MODULE_node_path__.join(destDir, item);
+            external_node_fs_.renameSync(src, dest);
+        }
+        remove(tempExtractDir);
+    } catch (error) {
+        throw new Error(`Failed to extract zip archive: ${error.message}`);
+    }
+}
+/**
+ * Detect archive format from file path
+ */ function detectArchiveFormat(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith('.tar.gz')) return 'tar.gz';
+    if (lower.endsWith('.tgz')) return 'tgz';
+    if (lower.endsWith('.zip')) return 'zip';
+    if (lower.endsWith('.tar')) return 'tar';
+}
+/**
+ * Download and extract an archive in one operation
+ *
+ * @param url - URL to download from
+ * @param destDir - Destination directory for extracted contents
+ * @param options - Download options
+ * @returns Path to extracted contents
+ */ async function downloadAndExtract(url, destDir, options = {}) {
+    // Determine archive filename from URL
+    const urlObj = new URL(url);
+    const filename = __WEBPACK_EXTERNAL_MODULE_node_path__.basename(urlObj.pathname);
+    // Detect format from original filename before adding .download suffix
+    const format = detectArchiveFormat(filename);
+    if (!format) throw new Error(`Unable to detect archive format from URL: ${url}`);
+    const tempArchive = __WEBPACK_EXTERNAL_MODULE_node_path__.join(destDir, `../${filename}.download`);
+    try {
+        // Download archive
+        await downloadFile(url, tempArchive, options);
+        // Extract archive with explicit format
+        await extractArchive(tempArchive, destDir, format);
+        return destDir;
+    } finally{
+        // Clean up temp archive
+        if (external_node_fs_.existsSync(tempArchive)) external_node_fs_.unlinkSync(tempArchive);
+    }
+}
+/**
+ * Installer - Multi-Agent installer
+ *
+ * Supports two installation modes:
+ * - symlink: Canonical location (.agents/skills/) + symlinks to each agent directory
+ * - copy: Direct copy to each agent directory
+ *
+ * Reference: https://github.com/vercel-labs/add-skill/blob/main/src/installer.ts
+ */ const installer_AGENTS_DIR = '.agents';
 const installer_SKILLS_SUBDIR = 'skills';
-const DEFAULT_EXCLUDE_FILES = [
+/**
+ * Default files to exclude when copying skills
+ * These files are typically used for repository metadata and should not be copied to agent directories
+ */ const DEFAULT_EXCLUDE_FILES = [
     'README.md',
     'metadata.json',
     '.reskill-commit'
 ];
-const EXCLUDE_PREFIX = '_';
-function installer_sanitizeName(name) {
+/**
+ * Prefix for files that should be excluded (internal/private files)
+ */ const EXCLUDE_PREFIX = '_';
+/**
+ * Sanitize filename to prevent path traversal attacks
+ */ function installer_sanitizeName(name) {
+    // Remove path separators and special characters
     let sanitized = name.replace(/[/\\:\0]/g, '');
+    // Remove leading and trailing dots and spaces
     sanitized = sanitized.replace(/^[.\s]+|[.\s]+$/g, '');
+    // Remove leading dots
     sanitized = sanitized.replace(/^\.+/, '');
     if (!sanitized || 0 === sanitized.length) sanitized = 'unnamed-skill';
     if (sanitized.length > 255) sanitized = sanitized.substring(0, 255);
     return sanitized;
 }
-function installer_isPathSafe(basePath, targetPath) {
+/**
+ * Validate path safety
+ */ function installer_isPathSafe(basePath, targetPath) {
     const normalizedBase = __WEBPACK_EXTERNAL_MODULE_node_path__.normalize(__WEBPACK_EXTERNAL_MODULE_node_path__.resolve(basePath));
     const normalizedTarget = __WEBPACK_EXTERNAL_MODULE_node_path__.normalize(__WEBPACK_EXTERNAL_MODULE_node_path__.resolve(targetPath));
     return normalizedTarget.startsWith(normalizedBase + __WEBPACK_EXTERNAL_MODULE_node_path__.sep) || normalizedTarget === normalizedBase;
 }
-function installer_getCanonicalSkillsDir(isGlobal, cwd, installDir) {
+/**
+ * Get canonical skills directory path
+ *
+ * @param isGlobal - Whether installing globally
+ * @param cwd - Current working directory
+ * @param installDir - Custom installation directory (relative to cwd), overrides default
+ */ function installer_getCanonicalSkillsDir(isGlobal, cwd, installDir) {
     const baseDir = isGlobal ? (0, __WEBPACK_EXTERNAL_MODULE_node_os__.homedir)() : cwd || process.cwd();
+    // Use custom installDir if provided, otherwise use default
     if (installDir && !isGlobal) return __WEBPACK_EXTERNAL_MODULE_node_path__.join(baseDir, installDir);
     return __WEBPACK_EXTERNAL_MODULE_node_path__.join(baseDir, installer_AGENTS_DIR, installer_SKILLS_SUBDIR);
 }
-function installer_ensureDir(dirPath) {
+/**
+ * Ensure directory exists
+ */ function installer_ensureDir(dirPath) {
     if (!external_node_fs_.existsSync(dirPath)) external_node_fs_.mkdirSync(dirPath, {
         recursive: true
     });
 }
-function installer_remove(targetPath) {
+/**
+ * Remove file or directory
+ */ function installer_remove(targetPath) {
     if (external_node_fs_.existsSync(targetPath)) external_node_fs_.rmSync(targetPath, {
         recursive: true,
         force: true
     });
 }
-function copyDirectory(src, dest, options) {
+/**
+ * Copy directory with file exclusion
+ *
+ * By default excludes:
+ * - Files in DEFAULT_EXCLUDE_FILES (README.md, metadata.json, .reskill-commit)
+ * - Files starting with EXCLUDE_PREFIX ('_')
+ */ function copyDirectory(src, dest, options) {
     const exclude = new Set(options?.exclude || DEFAULT_EXCLUDE_FILES);
     installer_ensureDir(dest);
     const entries = external_node_fs_.readdirSync(src, {
         withFileTypes: true
     });
     for (const entry of entries){
+        // Skip files starting with EXCLUDE_PREFIX and files in exclude list
         if (exclude.has(entry.name) || entry.name.startsWith(EXCLUDE_PREFIX)) continue;
         const srcPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(src, entry.name);
         const destPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(dest, entry.name);
@@ -500,8 +884,13 @@ function copyDirectory(src, dest, options) {
         else external_node_fs_.copyFileSync(srcPath, destPath);
     }
 }
-async function installer_createSymlink(target, linkPath) {
+/**
+ * Create symbolic link
+ *
+ * @returns true if successful, false if needs to fallback to copy
+ */ async function installer_createSymlink(target, linkPath) {
     try {
+        // Check existing link
         try {
             const stats = external_node_fs_.lstatSync(linkPath);
             if (stats.isSymbolicLink()) {
@@ -512,17 +901,24 @@ async function installer_createSymlink(target, linkPath) {
                 recursive: true
             });
         } catch (err) {
+            // ELOOP = circular symlink, ENOENT = does not exist
             if (err && 'object' == typeof err && 'code' in err) {
                 if ('ELOOP' === err.code) try {
                     external_node_fs_.rmSync(linkPath, {
                         force: true
                     });
-                } catch  {}
+                } catch  {
+                // If unable to delete, symlink creation will fail and trigger copy fallback
+                }
             }
+        // For ENOENT or other errors, continue trying to create symlink
         }
+        // Ensure parent directory exists
         const linkDir = __WEBPACK_EXTERNAL_MODULE_node_path__.dirname(linkPath);
         installer_ensureDir(linkDir);
+        // Calculate relative path
         const relativePath = __WEBPACK_EXTERNAL_MODULE_node_path__.relative(linkDir, target);
+        // Windows uses junction, other systems use default
         const symlinkType = 'win32' === (0, __WEBPACK_EXTERNAL_MODULE_node_os__.platform)() ? 'junction' : void 0;
         external_node_fs_.symlinkSync(relativePath, linkPath, symlinkType);
         return true;
@@ -530,7 +926,9 @@ async function installer_createSymlink(target, linkPath) {
         return false;
     }
 }
-class Installer {
+/**
+ * Installer class - Multi-Agent installer
+ */ class Installer {
     cwd;
     isGlobal;
     installDir;
@@ -539,25 +937,39 @@ class Installer {
         this.isGlobal = options.global || false;
         this.installDir = options.installDir;
     }
-    getCanonicalPath(skillName) {
+    /**
+   * Get canonical installation path
+   */ getCanonicalPath(skillName) {
         const sanitized = installer_sanitizeName(skillName);
         const canonicalBase = installer_getCanonicalSkillsDir(this.isGlobal, this.cwd, this.installDir);
         return __WEBPACK_EXTERNAL_MODULE_node_path__.join(canonicalBase, sanitized);
     }
-    getAgentSkillPath(skillName, agentType) {
+    /**
+   * Get agent's skill installation path
+   */ getAgentSkillPath(skillName, agentType) {
         const agent = getAgentConfig(agentType);
         const sanitized = installer_sanitizeName(skillName);
         const agentBase = this.isGlobal ? agent.globalSkillsDir : __WEBPACK_EXTERNAL_MODULE_node_path__.join(this.cwd, agent.skillsDir);
         return __WEBPACK_EXTERNAL_MODULE_node_path__.join(agentBase, sanitized);
     }
-    async installForAgent(sourcePath, skillName, agentType, options = {}) {
+    /**
+   * Install skill to specified agent
+   *
+   * @param sourcePath - Skill source directory path
+   * @param skillName - Skill name
+   * @param agentType - Target agent type
+   * @param options - Installation options
+   */ async installForAgent(sourcePath, skillName, agentType, options = {}) {
         const agent = getAgentConfig(agentType);
         const installMode = options.mode || 'symlink';
         const sanitized = installer_sanitizeName(skillName);
+        // Canonical location
         const canonicalBase = installer_getCanonicalSkillsDir(this.isGlobal, this.cwd, this.installDir);
         const canonicalDir = __WEBPACK_EXTERNAL_MODULE_node_path__.join(canonicalBase, sanitized);
+        // Agent specific location
         const agentBase = this.isGlobal ? agent.globalSkillsDir : __WEBPACK_EXTERNAL_MODULE_node_path__.join(this.cwd, agent.skillsDir);
         const agentDir = __WEBPACK_EXTERNAL_MODULE_node_path__.join(agentBase, sanitized);
+        // Validate path safety
         if (!installer_isPathSafe(canonicalBase, canonicalDir)) return {
             success: false,
             path: agentDir,
@@ -571,6 +983,7 @@ class Installer {
             error: 'Invalid skill name: potential path traversal detected'
         };
         try {
+            // Copy mode: directly copy to agent location
             if ('copy' === installMode) {
                 installer_ensureDir(agentDir);
                 installer_remove(agentDir);
@@ -581,14 +994,18 @@ class Installer {
                     mode: 'copy'
                 };
             }
+            // Symlink mode: copy to canonical location, then create symlink
             installer_ensureDir(canonicalDir);
             installer_remove(canonicalDir);
             copyDirectory(sourcePath, canonicalDir);
             const symlinkCreated = await installer_createSymlink(canonicalDir, agentDir);
             if (!symlinkCreated) {
+                // Symlink failed, fallback to copy
                 try {
                     installer_remove(agentDir);
-                } catch  {}
+                } catch  {
+                // Ignore cleanup errors
+                }
                 installer_ensureDir(agentDir);
                 copyDirectory(sourcePath, agentDir);
                 return {
@@ -614,7 +1031,9 @@ class Installer {
             };
         }
     }
-    async installToAgents(sourcePath, skillName, targetAgents, options = {}) {
+    /**
+   * Install skill to multiple agents
+   */ async installToAgents(sourcePath, skillName, targetAgents, options = {}) {
         const results = new Map();
         for (const agent of targetAgents){
             const result = await this.installForAgent(sourcePath, skillName, agent, options);
@@ -622,24 +1041,33 @@ class Installer {
         }
         return results;
     }
-    isInstalled(skillName, agentType) {
+    /**
+   * Check if skill is installed to specified agent
+   */ isInstalled(skillName, agentType) {
         const skillPath = this.getAgentSkillPath(skillName, agentType);
         return external_node_fs_.existsSync(skillPath);
     }
-    uninstallFromAgent(skillName, agentType) {
+    /**
+   * Uninstall skill from specified agent
+   */ uninstallFromAgent(skillName, agentType) {
         const skillPath = this.getAgentSkillPath(skillName, agentType);
         if (!external_node_fs_.existsSync(skillPath)) return false;
         installer_remove(skillPath);
         return true;
     }
-    uninstallFromAgents(skillName, targetAgents) {
+    /**
+   * Uninstall skill from multiple agents
+   */ uninstallFromAgents(skillName, targetAgents) {
         const results = new Map();
         for (const agent of targetAgents)results.set(agent, this.uninstallFromAgent(skillName, agent));
+        // Also delete canonical location
         const canonicalPath = this.getCanonicalPath(skillName);
         if (external_node_fs_.existsSync(canonicalPath)) installer_remove(canonicalPath);
         return results;
     }
-    listInstalledSkills(agentType) {
+    /**
+   * Get all skills installed to specified agent
+   */ listInstalledSkills(agentType) {
         const agent = getAgentConfig(agentType);
         const skillsDir = this.isGlobal ? agent.globalSkillsDir : __WEBPACK_EXTERNAL_MODULE_node_path__.join(this.cwd, agent.skillsDir);
         if (!external_node_fs_.existsSync(skillsDir)) return [];
@@ -648,49 +1076,95 @@ class Installer {
         }).filter((entry)=>entry.isDirectory() || entry.isSymbolicLink()).map((entry)=>entry.name);
     }
 }
-class CacheManager {
+/**
+ * CacheManager - Manage global skill cache
+ *
+ * Cache directory structure:
+ * ~/.reskill-cache/
+ * ├── github/                          # Shorthand format registry
+ * │   └── user/
+ * │       └── skill/
+ * │           ├── v1.0.0/
+ * │           └── v1.1.0/
+ * ├── github.com/                      # Git URL format, using host as directory
+ * │   └── user/
+ * │       └── private-skill/
+ * │           └── v1.0.0/
+ * └── gitlab.company.com/              # Private GitLab instance
+ *     └── team/
+ *         └── skill/
+ *             └── v2.0.0/
+ *
+ * For Git URL format (SSH/HTTPS):
+ * - git@github.com:user/repo.git -> github.com/user/repo/version
+ * - https://gitlab.company.com/team/skill.git -> gitlab.company.com/team/skill/version
+ */ class CacheManager {
     cacheDir;
     constructor(cacheDir){
         this.cacheDir = cacheDir || getCacheDir();
     }
-    getCacheDir() {
+    /**
+   * Get cache directory
+   */ getCacheDir() {
         return this.cacheDir;
     }
-    getSkillCachePath(parsed, version) {
+    /**
+   * Get skill path in cache
+   *
+   * For different reference formats, cache paths are:
+   * - github:user/repo@v1.0.0 -> ~/.reskill-cache/github/user/repo/v1.0.0
+   * - git@github.com:user/repo.git@v1.0.0 -> ~/.reskill-cache/github.com/user/repo/v1.0.0
+   * - https://gitlab.company.com/team/skill.git@v2.0.0 -> ~/.reskill-cache/gitlab.company.com/team/skill/v2.0.0
+   */ getSkillCachePath(parsed, version) {
         return __WEBPACK_EXTERNAL_MODULE_node_path__.join(this.cacheDir, parsed.registry, parsed.owner, parsed.repo, version);
     }
-    getCachePath(parsed, version) {
+    /**
+   * Get cache path (alias for getSkillCachePath)
+   */ getCachePath(parsed, version) {
         return this.getSkillCachePath(parsed, version);
     }
-    isCached(parsed, version) {
+    /**
+   * Check if skill is cached
+   */ isCached(parsed, version) {
         const cachePath = this.getSkillCachePath(parsed, version);
         return exists(cachePath) && isDirectory(cachePath);
     }
-    async get(parsed, version) {
+    /**
+   * Get cached skill
+   */ async get(parsed, version) {
         const cachePath = this.getSkillCachePath(parsed, version);
         if (!this.isCached(parsed, version)) return null;
+        // Read cached commit info
         const commitFile = __WEBPACK_EXTERNAL_MODULE_node_path__.join(cachePath, '.reskill-commit');
         let commit = '';
         try {
             const fs = await import("node:fs");
             if (exists(commitFile)) commit = fs.readFileSync(commitFile, 'utf-8').trim();
-        } catch  {}
+        } catch  {
+        // Ignore read errors
+        }
         return {
             path: cachePath,
             commit
         };
     }
-    async cache(repoUrl, parsed, ref, version) {
+    /**
+   * Cache skill from Git repository
+   */ async cache(repoUrl, parsed, ref, version) {
         const cachePath = this.getSkillCachePath(parsed, version);
+        // If exists, delete first
         if (exists(cachePath)) remove(cachePath);
         ensureDir(__WEBPACK_EXTERNAL_MODULE_node_path__.dirname(cachePath));
+        // Clone repository
         const tempPath = `${cachePath}.tmp`;
         remove(tempPath);
         await clone(repoUrl, tempPath, {
             depth: 1,
             branch: ref
         });
+        // Get commit hash
         const commit = await getCurrentCommit(tempPath);
+        // If has subPath, only keep subdirectory
         if (parsed.subPath) {
             const subDir = __WEBPACK_EXTERNAL_MODULE_node_path__.join(tempPath, parsed.subPath);
             if (!exists(subDir)) {
@@ -707,35 +1181,80 @@ class CacheManager {
                 '.git'
             ]
         });
-        const fs = await import("node:fs");
-        fs.writeFileSync(__WEBPACK_EXTERNAL_MODULE_node_path__.join(cachePath, '.reskill-commit'), commit);
+        // Save commit info
+        external_node_fs_.writeFileSync(__WEBPACK_EXTERNAL_MODULE_node_path__.join(cachePath, '.reskill-commit'), commit);
+        // Clean up temp directory
         remove(tempPath);
         return {
             path: cachePath,
             commit
         };
     }
-    async copyTo(parsed, version, destPath) {
+    /**
+   * Cache skill from HTTP/OSS URL
+   *
+   * Downloads and extracts an archive from the given URL.
+   * Supports tar.gz, tgz, zip, and tar formats.
+   *
+   * @param url - HTTP/HTTPS URL to download from
+   * @param parsed - Parsed skill reference
+   * @param version - Version string for cache path
+   * @returns Cache path and a hash of the download URL as commit identifier
+   */ async cacheFromHttp(url, parsed, version) {
+        const cachePath = this.getSkillCachePath(parsed, version);
+        // If exists, delete first
+        if (exists(cachePath)) remove(cachePath);
+        ensureDir(__WEBPACK_EXTERNAL_MODULE_node_path__.dirname(cachePath));
+        // Download and extract to cache path
+        await downloadAndExtract(url, cachePath);
+        // Generate a commit-like identifier from URL and version
+        // This serves as a pseudo-commit for HTTP sources
+        const crypto = await import("node:crypto");
+        const commit = crypto.createHash('sha256').update(`${url}@${version}`).digest('hex').slice(0, 40);
+        // Save commit info
+        external_node_fs_.writeFileSync(__WEBPACK_EXTERNAL_MODULE_node_path__.join(cachePath, '.reskill-commit'), commit);
+        // Also save the source URL for reference
+        external_node_fs_.writeFileSync(__WEBPACK_EXTERNAL_MODULE_node_path__.join(cachePath, '.reskill-source'), url);
+        return {
+            path: cachePath,
+            commit
+        };
+    }
+    /**
+   * Copy from cache to target directory
+   *
+   * Uses the same exclude rules as Installer to ensure consistency:
+   * - DEFAULT_EXCLUDE_FILES (README.md, metadata.json, .reskill-commit)
+   */ async copyTo(parsed, version, destPath) {
         const cached = await this.get(parsed, version);
         if (!cached) throw new Error(`Skill ${parsed.raw} version ${version} not found in cache`);
+        // If target exists, delete first
         if (exists(destPath)) remove(destPath);
+        // Use same exclude rules as Installer for consistency
         copyDir(cached.path, destPath, {
             exclude: DEFAULT_EXCLUDE_FILES
         });
     }
-    clearSkill(parsed, version) {
+    /**
+   * Clear cache for specific skill
+   */ clearSkill(parsed, version) {
         if (version) {
             const cachePath = this.getSkillCachePath(parsed, version);
             remove(cachePath);
         } else {
+            // Clear all versions
             const skillDir = __WEBPACK_EXTERNAL_MODULE_node_path__.join(this.cacheDir, parsed.registry, parsed.owner, parsed.repo);
             remove(skillDir);
         }
     }
-    clearAll() {
+    /**
+   * Clear all cache
+   */ clearAll() {
         remove(this.cacheDir);
     }
-    getStats() {
+    /**
+   * Get cache statistics
+   */ getStats() {
         if (!exists(this.cacheDir)) return {
             totalSkills: 0,
             registries: []
@@ -756,11 +1275,20 @@ class CacheManager {
             registries
         };
     }
-    async getRemoteCommit(repoUrl, ref) {
+    /**
+   * Get the remote commit hash for a specific ref without cloning
+   *
+   * Uses `git ls-remote` to fetch the commit hash efficiently.
+   *
+   * @param repoUrl - Repository URL
+   * @param ref - Git reference (branch, tag, or commit)
+   * @returns Commit hash string
+   */ async getRemoteCommit(repoUrl, ref) {
         const { exec } = await import("node:child_process");
         const { promisify } = await import("node:util");
         const execAsync = promisify(exec);
         try {
+            // Try to get commit for the ref
             const { stdout } = await execAsync(`git ls-remote ${repoUrl} ${ref}`, {
                 encoding: 'utf-8'
             });
@@ -768,6 +1296,7 @@ class CacheManager {
                 const [commit] = stdout.trim().split('\t');
                 return commit;
             }
+            // If ref is not found directly, try refs/heads/ and refs/tags/
             const { stdout: allRefs } = await execAsync(`git ls-remote ${repoUrl}`, {
                 encoding: 'utf-8'
             });
@@ -776,28 +1305,62 @@ class CacheManager {
                 const [commit, refPath] = line.split('\t');
                 if (refPath === `refs/heads/${ref}` || refPath === `refs/tags/${ref}` || refPath === ref) return commit;
             }
+            // If still not found, return empty string (will trigger update)
             return '';
         } catch  {
+            // On error, return empty string to trigger update
             return '';
         }
     }
 }
-const DEFAULT_SKILLS_JSON = {
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Default skills.json configuration template
+ */ const DEFAULT_SKILLS_JSON = {
     skills: {},
+    registries: {
+        github: 'https://github.com'
+    },
     defaults: {
         installDir: '.skills'
     }
 };
-const DEFAULT_VALUES = {
+/**
+ * Default values for SkillsDefaults fields
+ */ const DEFAULT_VALUES = {
     installDir: '.skills',
     targetAgents: [],
     installMode: 'symlink'
 };
-const DEFAULT_REGISTRIES = {
+/**
+ * Well-known registry URLs
+ */ const DEFAULT_REGISTRIES = {
     github: 'https://github.com',
     gitlab: 'https://gitlab.com'
 };
-class ConfigLoader {
+// ============================================================================
+// ConfigLoader Class
+// ============================================================================
+/**
+ * ConfigLoader - Load and manage skills.json configuration
+ *
+ * Handles reading, writing, and managing the project's skills.json file.
+ * Provides methods for:
+ * - Loading/saving configuration
+ * - Managing skill dependencies
+ * - Managing default settings (registry, installDir, targetAgents, installMode)
+ *
+ * @example
+ * ```ts
+ * const config = new ConfigLoader();
+ * if (config.exists()) {
+ *   const defaults = config.getDefaults();
+ *   console.log(defaults.targetAgents);
+ * }
+ * ```
+ */ class ConfigLoader {
     projectRoot;
     configPath;
     config = null;
@@ -805,20 +1368,38 @@ class ConfigLoader {
         this.projectRoot = projectRoot ?? process.cwd();
         this.configPath = getSkillsJsonPath(this.projectRoot);
     }
-    getProjectRoot() {
+    // ==========================================================================
+    // Path Accessors
+    // ==========================================================================
+    /**
+   * Get project root directory
+   */ getProjectRoot() {
         return this.projectRoot;
     }
-    getConfigPath() {
+    /**
+   * Get configuration file path
+   */ getConfigPath() {
         return this.configPath;
     }
-    getInstallDir() {
+    /**
+   * Get installation directory (resolved absolute path)
+   */ getInstallDir() {
         const { installDir } = this.getDefaults();
         return __WEBPACK_EXTERNAL_MODULE_node_path__.join(this.projectRoot, installDir);
     }
-    exists() {
+    // ==========================================================================
+    // File Operations
+    // ==========================================================================
+    /**
+   * Check if configuration file exists
+   */ exists() {
         return exists(this.configPath);
     }
-    load() {
+    /**
+   * Load configuration from file
+   *
+   * @throws Error if file doesn't exist or is invalid JSON
+   */ load() {
         if (this.config) return this.config;
         if (!this.exists()) throw new Error(`skills.json not found in ${this.projectRoot}. Run 'reskill init' first.`);
         try {
@@ -828,26 +1409,46 @@ class ConfigLoader {
             throw new Error(`Failed to parse skills.json: ${error.message}`);
         }
     }
-    reload() {
+    /**
+   * Reload configuration from file (ignores cache)
+   */ reload() {
         this.config = null;
         return this.load();
     }
-    save(config) {
+    /**
+   * Save configuration to file
+   *
+   * @param config - Configuration to save (uses cached config if not provided)
+   * @throws Error if no configuration to save
+   */ save(config) {
         const toSave = config ?? this.config;
         if (!toSave) throw new Error('No config to save');
         writeJson(this.configPath, toSave);
         this.config = toSave;
     }
-    ensureExists() {
+    /**
+   * Ensure skills.json exists, create with defaults if not
+   *
+   * @returns true if file was created, false if it already existed
+   */ ensureExists() {
         if (this.exists()) return false;
         this.create();
         return true;
     }
-    create(options) {
+    /**
+   * Create new configuration file with defaults
+   *
+   * @param options - Optional overrides for default configuration
+   */ create(options) {
         const config = {
             ...DEFAULT_SKILLS_JSON,
             ...options,
             skills: options?.skills ?? {},
+            // Deep copy registries to avoid mutating the default object
+            registries: {
+                ...DEFAULT_SKILLS_JSON.registries,
+                ...options?.registries
+            },
             defaults: {
                 ...DEFAULT_SKILLS_JSON.defaults,
                 ...options?.defaults
@@ -856,7 +1457,15 @@ class ConfigLoader {
         this.save(config);
         return config;
     }
-    getDefaults() {
+    // ==========================================================================
+    // Defaults Management
+    // ==========================================================================
+    /**
+   * Get default configuration values
+   *
+   * Returns a complete defaults object with all fields populated.
+   * Uses stored values if available, falls back to defaults.
+   */ getDefaults() {
         const config = this.getConfigOrDefault();
         const storedDefaults = config.defaults ?? {};
         return {
@@ -865,7 +1474,13 @@ class ConfigLoader {
             installMode: storedDefaults.installMode ?? DEFAULT_VALUES.installMode
         };
     }
-    updateDefaults(updates) {
+    /**
+   * Update default configuration values
+   *
+   * Merges the provided updates with existing defaults and saves to file.
+   *
+   * @param updates - Partial defaults to merge
+   */ updateDefaults(updates) {
         this.ensureConfigLoaded();
         if (this.config) {
             this.config.defaults = {
@@ -875,20 +1490,176 @@ class ConfigLoader {
             this.save();
         }
     }
-    getRegistryUrl(registryName) {
+    // ==========================================================================
+    // Registry Management
+    // ==========================================================================
+    /**
+   * Get registry URL by name
+   *
+   * Resolution order:
+   * 1. Custom registries defined in skills.json
+   * 2. Well-known registries (github, gitlab)
+   * 3. Assumes it's a custom domain (https://{registryName})
+   */ getRegistryUrl(registryName) {
         const config = this.getConfigOrDefault();
+        // Check custom registries
         if (config.registries?.[registryName]) return config.registries[registryName];
+        // Check well-known registries
         if (DEFAULT_REGISTRIES[registryName]) return DEFAULT_REGISTRIES[registryName];
+        // Assume it's a custom domain
         return `https://${registryName}`;
     }
-    addSkill(name, ref) {
+    /**
+   * Find registry name for a given URL
+   *
+   * Reverse lookup: finds which registry (if any) matches the URL.
+   * Custom registries are checked first, then well-known registries.
+   *
+   * @param url - The URL to match (e.g., "https://gitlab.company.com/team/tool")
+   * @returns The registry name if found, or undefined
+   */ findRegistryForUrl(url) {
+        const config = this.getConfigOrDefault();
+        // Normalize URL - remove trailing slash
+        const normalizedUrl = url.replace(/\/$/, '');
+        // Check custom registries first (higher priority)
+        if (config.registries) for (const [name, registryUrl] of Object.entries(config.registries)){
+            const normalizedRegistryUrl = registryUrl.replace(/\/$/, '');
+            if (normalizedUrl.startsWith(normalizedRegistryUrl)) return name;
+        }
+        // Check well-known registries
+        for (const [name, registryUrl] of Object.entries(DEFAULT_REGISTRIES)){
+            const normalizedRegistryUrl = registryUrl.replace(/\/$/, '');
+            if (normalizedUrl.startsWith(normalizedRegistryUrl)) return name;
+        }
+    }
+    /**
+   * Normalize a skill reference to use registry shorthand if possible
+   *
+   * Converts full URLs to registry format when they match a configured registry.
+   * E.g., "https://gitlab.company.com/team/tool@v1.0.0" → "internal:team/tool@v1.0.0"
+   *       (if "internal": "https://gitlab.company.com" is configured)
+   *
+   * @param ref - The skill reference to normalize
+   * @returns Normalized reference using registry shorthand, or original if no match
+   */ normalizeSkillRef(ref) {
+        // Check if it's an SSH URL (git@...) - must check first as it contains ':'
+        if (ref.startsWith('git@')) return this.normalizeGitSshUrl(ref);
+        // Check if it's an HTTPS URL
+        if (ref.startsWith('https://') || ref.startsWith('http://')) return this.normalizeHttpsUrl(ref);
+        // Check if it's already in registry format (contains : but not a URL)
+        // At this point we've excluded git@ and http(s):// URLs
+        ref.includes(':');
+        return ref;
+    }
+    /**
+   * Normalize an HTTPS URL to registry format
+   */ normalizeHttpsUrl(ref) {
+        // Extract version part if present
+        let url = ref;
+        let version = '';
+        // Handle .git suffix with version
+        const gitVersionMatch = ref.match(/^(.+\.git)(@.+)$/);
+        if (gitVersionMatch) {
+            url = gitVersionMatch[1];
+            version = gitVersionMatch[2];
+        } else {
+            // Handle URL without .git suffix
+            const versionMatch = ref.match(/^(.+?)(@[^@]+)$/);
+            if (versionMatch && !versionMatch[1].includes('@')) {
+                url = versionMatch[1];
+                version = versionMatch[2];
+            }
+        }
+        // Find matching registry
+        const registryName = this.findRegistryForUrl(url);
+        if (!registryName) return ref;
+        const registryUrl = this.getRegistryUrl(registryName).replace(/\/$/, '');
+        // Extract the path after registry URL
+        let path = url.replace(registryUrl, '').replace(/^\//, '');
+        // Remove .git suffix if present
+        path = path.replace(/\.git$/, '');
+        if (!path) return ref;
+        return `${registryName}:${path}${version}`;
+    }
+    /**
+   * Normalize a Git SSH URL to registry format
+   */ normalizeGitSshUrl(ref) {
+        // Parse: git@host:owner/repo.git[@version] or git@host:owner/repo[@version]
+        // The .git suffix and @version are both optional
+        // Use greedy match for repoPath (.+) to ensure .git is captured as part of the path,
+        // then explicitly remove it. This avoids issues with non-greedy matching and optional groups.
+        const match = ref.match(/^git@([^:]+):(.+?)(@[^@]+)?$/);
+        if (!match) return ref;
+        const [, host, rawRepoPath, version = ''] = match;
+        // Remove .git suffix if present
+        const repoPath = rawRepoPath.replace(/\.git$/, '');
+        const testUrl = `https://${host}`;
+        // Find matching registry
+        const registryName = this.findRegistryForUrl(testUrl);
+        if (!registryName) return ref;
+        return `${registryName}:${repoPath}${version}`;
+    }
+    // ==========================================================================
+    // Skills Management
+    // ==========================================================================
+    /**
+   * Add skill to configuration
+   *
+   * Also auto-adds the registry to the registries field if it's a well-known registry.
+   */ addSkill(name, ref) {
         this.ensureConfigLoaded();
         if (this.config) {
             this.config.skills[name] = ref;
+            // Auto-add registry if it's a well-known registry
+            const registryName = this.extractRegistryFromRef(ref);
+            if (registryName && DEFAULT_REGISTRIES[registryName]) this.addRegistry(registryName, DEFAULT_REGISTRIES[registryName]);
             this.save();
         }
     }
-    removeSkill(name) {
+    /**
+   * Add registry to configuration
+   *
+   * Only adds if the registry doesn't already exist.
+   * Note: This method requires config to be loaded first via load() or create().
+   * If config is not loaded, this method is a no-op (silent return) since it's
+   * typically called as a side effect of addSkill() which handles config loading.
+   *
+   * @param name - Registry name (e.g., 'github', 'gitlab', 'internal')
+   * @param url - Registry URL (e.g., 'https://github.com')
+   */ addRegistry(name, url) {
+        if (!this.config) // Config not loaded - this is expected when called before load()/create()
+        // Callers like addSkill() ensure config is loaded before calling this
+        return;
+        if (!this.config.registries) this.config.registries = {};
+        // Don't overwrite existing registries
+        if (!this.config.registries[name]) this.config.registries[name] = url;
+    }
+    /**
+   * Extract registry name from a skill reference
+   *
+   * @example
+   * extractRegistryFromRef('github:user/repo@v1.0.0') // 'github'
+   * extractRegistryFromRef('gitlab:user/repo') // 'gitlab'
+   * extractRegistryFromRef('https://github.com/user/repo') // undefined
+   */ extractRegistryFromRef(ref) {
+        // Check for registry format: registry:path[@version]
+        const match = ref.match(/^([a-zA-Z][a-zA-Z0-9-]*):(.+)$/);
+        if (match) {
+            const registryName = match[1];
+            // Exclude URL protocols (http, https, git, ssh)
+            if (![
+                'http',
+                'https',
+                'git',
+                'ssh'
+            ].includes(registryName.toLowerCase())) return registryName;
+        }
+    }
+    /**
+   * Remove skill from configuration
+   *
+   * @returns true if skill was removed, false if it didn't exist
+   */ removeSkill(name) {
         this.ensureConfigLoaded();
         if (this.config?.skills[name]) {
             delete this.config.skills[name];
@@ -897,7 +1668,9 @@ class ConfigLoader {
         }
         return false;
     }
-    getSkills() {
+    /**
+   * Get all skills as a shallow copy
+   */ getSkills() {
         if (!this.config) {
             if (!this.exists()) return {};
             this.load();
@@ -906,41 +1679,116 @@ class ConfigLoader {
             ...this.config?.skills
         };
     }
-    hasSkill(name) {
+    /**
+   * Check if skill exists in configuration
+   */ hasSkill(name) {
         const skills = this.getSkills();
         return name in skills;
     }
-    getSkillRef(name) {
+    /**
+   * Get skill reference by name
+   */ getSkillRef(name) {
         const skills = this.getSkills();
         return skills[name];
     }
-    getConfigOrDefault() {
+    // ==========================================================================
+    // Private Helpers
+    // ==========================================================================
+    /**
+   * Get loaded config or default (does not throw)
+   */ getConfigOrDefault() {
         if (this.config) return this.config;
         if (this.exists()) return this.load();
         return DEFAULT_SKILLS_JSON;
     }
-    ensureConfigLoaded() {
+    /**
+   * Ensure config is loaded into memory
+   */ ensureConfigLoaded() {
         if (!this.config) this.load();
     }
 }
-class GitResolver {
-    defaultRegistry = 'github';
-    parseRef(ref) {
+/**
+ * GitResolver - Parse skill references and versions
+ *
+ * Reference formats:
+ *   Full: <registry>:<owner>/<repo>@<version>
+ *   Short: <owner>/<repo>@<version>
+ *   Git URL: git@github.com:user/repo.git[@version]
+ *   HTTPS: https://github.com/user/repo.git[@version]
+ *
+ * Version formats:
+ *   - @v1.0.0       Exact version
+ *   - @latest       Latest tag
+ *   - @^2.0.0       Semver range
+ *   - @branch:dev   Branch
+ *   - @commit:abc   Commit hash
+ *   - (none)        Default branch
+ */ class GitResolver {
+    defaultRegistry;
+    customRegistries;
+    registryResolver;
+    /**
+   * Create a GitResolver instance
+   *
+   * @param defaultRegistry - Default registry name (defaults to 'github')
+   * @param registries - Custom registry configuration (name -> URL mapping)
+   * @param registryResolver - Optional custom registry resolver function
+   */ constructor(defaultRegistry = 'github', registries, registryResolver){
+        this.defaultRegistry = defaultRegistry;
+        this.customRegistries = registries ?? {};
+        this.registryResolver = registryResolver;
+    }
+    /**
+   * Get registry URL by name
+   *
+   * Resolution order:
+   * 1. Custom registry resolver function (if provided)
+   * 2. Custom registries from configuration
+   * 3. Well-known registries (github, gitlab)
+   * 4. Assumes it's a custom domain (https://{registryName})
+   */ getRegistryUrl(registryName) {
+        // Use custom resolver if provided
+        if (this.registryResolver) return this.registryResolver(registryName);
+        // Check custom registries from configuration
+        if (this.customRegistries[registryName]) return this.customRegistries[registryName];
+        // Check well-known registries
+        if (DEFAULT_REGISTRIES[registryName]) return DEFAULT_REGISTRIES[registryName];
+        // Assume it's a custom domain
+        return `https://${registryName}`;
+    }
+    /**
+   * Parse skill reference string
+   *
+   * Supported formats:
+   * - Short: owner/repo[@version]
+   * - Full: registry:owner/repo[@version]
+   * - SSH URL: git@github.com:user/repo.git[@version]
+   * - HTTPS URL: https://github.com/user/repo.git[@version]
+   * - Monorepo: git@github.com:org/repo.git/subpath[@version]
+   */ parseRef(ref) {
         const raw = ref;
+        // First check if it's a Git URL (SSH, HTTPS, git://)
+        // For Git URLs, need special handling for version separator
+        // Format: git@host:user/repo.git[@version] or git@host:user/repo.git/subpath[@version]
         if (isGitUrl(ref)) return this.parseGitUrlRef(ref);
+        // Standard format parsing for non-Git URLs
         let remaining = ref;
         let registry = this.defaultRegistry;
         let version;
+        // Check for registry prefix (github:, gitlab:, custom.com:)
         const registryMatch = remaining.match(/^([a-zA-Z0-9.-]+):(.+)$/);
         if (registryMatch) {
             registry = registryMatch[1];
             remaining = registryMatch[2];
         }
+        // Separate version part
         const atIndex = remaining.lastIndexOf('@');
         if (atIndex > 0) {
             version = remaining.slice(atIndex + 1);
             remaining = remaining.slice(0, atIndex);
         }
+        // Parse owner/repo and possible subPath
+        // E.g.: user/repo or org/monorepo/skills/pdf
         const parts = remaining.split('/');
         if (parts.length < 2) throw new Error(`Invalid skill reference: ${ref}. Expected format: owner/repo[@version]`);
         const owner = parts[0];
@@ -955,16 +1803,30 @@ class GitResolver {
             raw
         };
     }
-    parseGitUrlRef(ref) {
+    /**
+   * Parse Git URL format reference
+   *
+   * Supported formats:
+   * - git@github.com:user/repo.git
+   * - git@github.com:user/repo.git@v1.0.0
+   * - git@github.com:user/repo.git/subpath@v1.0.0
+   * - https://github.com/user/repo.git
+   * - https://github.com/user/repo.git@v1.0.0
+   * - https://github.com/user/repo/tree/branch/path (GitHub web URL)
+   */ parseGitUrlRef(ref) {
         const raw = ref;
         let gitUrl = ref;
         let version;
         let subPath;
+        // Check for GitHub/GitLab web URL format: https://github.com/user/repo/tree/branch/path
         const webUrlMatch = ref.match(/^(https?:\/\/[^/]+)\/([^/]+)\/([^/]+)\/(tree|blob|raw)\/([^/]+)(?:\/(.+))?$/);
         if (webUrlMatch) {
             const [, baseUrl, owner, repo, , branch, path] = webUrlMatch;
+            // Build standard Git URL
             gitUrl = `${baseUrl}/${owner}/${repo}.git`;
+            // Extract branch as version
             version = `branch:${branch}`;
+            // Extract subpath
             subPath = path;
             return {
                 registry: new URL(baseUrl).hostname,
@@ -976,25 +1838,33 @@ class GitResolver {
                 gitUrl
             };
         }
+        // For URLs ending with .git, first check for /subpath@version or @version
+        // Format: url.git/subpath@version or url.git@version
         const gitSuffixIndex = ref.indexOf('.git');
         if (-1 !== gitSuffixIndex) {
             const afterGit = ref.slice(gitSuffixIndex + 4);
             if (afterGit) {
+                // Check version (@version)
                 const atIndex = afterGit.lastIndexOf('@');
                 if (-1 !== atIndex) {
                     version = afterGit.slice(atIndex + 1);
                     const pathPart = afterGit.slice(0, atIndex);
                     if (pathPart.startsWith('/')) subPath = pathPart.slice(1);
                 } else if (afterGit.startsWith('/')) subPath = afterGit.slice(1);
+                // Extract clean Git URL (without subpath and version)
                 gitUrl = ref.slice(0, gitSuffixIndex + 4);
             }
         } else {
+            // URL without .git suffix, try to separate version
             const atIndex = ref.lastIndexOf('@');
+            // For SSH URL, @ at the beginning is normal (git@...), need to skip
             if (atIndex > 4) {
+                // Make sure it's not the @ in git@host
                 version = ref.slice(atIndex + 1);
                 gitUrl = ref.slice(0, atIndex);
             }
         }
+        // Parse Git URL to get host, owner, repo
         const parsed = parseGitUrl(gitUrl);
         if (!parsed) throw new Error(`Invalid Git URL: ${ref}. Expected format: git@host:owner/repo.git or https://host/owner/repo.git`);
         return {
@@ -1007,53 +1877,73 @@ class GitResolver {
             gitUrl
         };
     }
-    parseVersion(versionSpec) {
+    /**
+   * Parse version specification
+   */ parseVersion(versionSpec) {
         if (!versionSpec) return {
             type: 'branch',
             value: 'main',
             raw: ''
         };
         const raw = versionSpec;
+        // latest
         if ('latest' === versionSpec) return {
             type: 'latest',
             value: 'latest',
             raw
         };
+        // branch:xxx
         if (versionSpec.startsWith('branch:')) return {
             type: 'branch',
             value: versionSpec.slice(7),
             raw
         };
+        // commit:xxx
         if (versionSpec.startsWith('commit:')) return {
             type: 'commit',
             value: versionSpec.slice(7),
             raw
         };
+        // semver range (^, ~, >, <, etc.)
         if (/^[\^~><]/.test(versionSpec)) return {
             type: 'range',
             value: versionSpec,
             raw
         };
+        // exact version (v1.0.0 or 1.0.0)
         return {
             type: 'exact',
             value: versionSpec,
             raw
         };
     }
-    buildRepoUrl(parsed) {
+    /**
+   * Build repository URL
+   *
+   * If parsed contains gitUrl, return it directly;
+   * Otherwise build HTTPS URL from registry and owner/repo
+   */ buildRepoUrl(parsed) {
+        // If has complete Git URL, return directly
         if (parsed.gitUrl) return parsed.gitUrl;
-        return buildRepoUrl(parsed.registry, `${parsed.owner}/${parsed.repo}`);
+        // Use our registry resolver to get the base URL
+        const baseUrl = this.getRegistryUrl(parsed.registry);
+        return `${baseUrl}/${parsed.owner}/${parsed.repo}`;
     }
-    async resolveVersion(repoUrl, versionSpec) {
+    /**
+   * Resolve version and get specific ref (tag name or commit)
+   */ async resolveVersion(repoUrl, versionSpec) {
         switch(versionSpec.type){
             case 'exact':
+                // Use specified tag directly
                 return {
                     ref: versionSpec.value
                 };
             case 'latest':
                 {
+                    // Get latest tag
                     const latestTag = await getLatestTag(repoUrl);
                     if (!latestTag) {
+                        // No tag, use default branch
                         const defaultBranch = await getDefaultBranch(repoUrl);
                         return {
                             ref: defaultBranch
@@ -1066,12 +1956,14 @@ class GitResolver {
                 }
             case 'range':
                 {
+                    // Get all tags, find latest version satisfying semver range
                     const tags = await getRemoteTags(repoUrl);
                     const matchingTags = tags.filter((tag)=>{
                         const version = tag.name.replace(/^v/, '');
                         return __WEBPACK_EXTERNAL_MODULE_semver__.satisfies(version, versionSpec.value);
                     });
                     if (0 === matchingTags.length) throw new Error(`No version found matching ${versionSpec.raw} for ${repoUrl}`);
+                    // Sort by version, get latest
                     matchingTags.sort((a, b)=>{
                         const aVer = a.name.replace(/^v/, '');
                         const bVer = b.name.replace(/^v/, '');
@@ -1095,7 +1987,9 @@ class GitResolver {
                 throw new Error(`Unknown version type: ${versionSpec.type}`);
         }
     }
-    async resolve(ref) {
+    /**
+   * Full resolution: from reference string to clone-ready information
+   */ async resolve(ref) {
         const parsed = this.parseRef(ref);
         const repoUrl = this.buildRepoUrl(parsed);
         const versionSpec = this.parseVersion(parsed.version);
@@ -1108,8 +2002,204 @@ class GitResolver {
         };
     }
 }
-const LOCKFILE_VERSION = 1;
-class LockManager {
+/**
+ * HttpResolver - Parse HTTP/OSS URLs and resolve skill references
+ *
+ * Supported URL formats:
+ *   - https://bucket.oss-cn-hangzhou.aliyuncs.com/path/to/skill.tar.gz
+ *   - https://bucket.s3.amazonaws.com/skills/skill-v1.0.0.tar.gz
+ *   - https://example.com/skills/my-skill.zip
+ *   - http://localhost:8080/skills/test-skill.tar.gz
+ *
+ * The resolver extracts:
+ *   - Skill name from filename (removes version suffix and archive extension)
+ *   - Version from filename pattern (e.g., skill-v1.0.0.tar.gz -> v1.0.0)
+ *   - Archive format for extraction
+ */ class HttpResolver {
+    /**
+   * Check if a reference is an HTTP/OSS URL
+   *
+   * Returns true for:
+   * - http:// or https:// URLs
+   * - Explicit oss:// or s3:// protocol URLs
+   */ static isHttpUrl(ref) {
+        // Remove version suffix for checking (e.g., url@v1.0.0)
+        const urlPart = ref.split('@')[0];
+        return urlPart.startsWith('http://') || urlPart.startsWith('https://') || urlPart.startsWith('oss://') || urlPart.startsWith('s3://');
+    }
+    /**
+   * Parse an HTTP/OSS URL reference
+   *
+   * Supported formats:
+   * - https://host/path/to/skill-v1.0.0.tar.gz
+   * - https://host/path/to/skill.tar.gz@v1.0.0
+   * - oss://bucket/path/to/skill.tar.gz
+   */ parseUrl(ref) {
+        let url = ref;
+        let explicitVersion;
+        // Extract explicit version suffix (@v1.0.0)
+        const atIndex = ref.lastIndexOf('@');
+        if (atIndex > 0 && !ref.slice(atIndex).includes('/')) {
+            explicitVersion = ref.slice(atIndex + 1);
+            url = ref.slice(0, atIndex);
+        }
+        // Normalize protocol
+        url = this.normalizeUrl(url);
+        // Parse URL components
+        const urlObj = new URL(url);
+        const host = urlObj.host;
+        const urlPath = urlObj.pathname;
+        const filename = __WEBPACK_EXTERNAL_MODULE_node_path__.basename(urlPath);
+        // Detect archive format
+        const format = this.detectArchiveFormat(filename);
+        // Extract skill name and version from filename
+        const { name, version: filenameVersion } = this.parseFilename(filename);
+        const skillName = name;
+        const version = explicitVersion || filenameVersion;
+        return {
+            url,
+            host,
+            path: urlPath,
+            filename,
+            format,
+            skillName,
+            version
+        };
+    }
+    /**
+   * Parse HTTP URL to ParsedSkillRef format (for compatibility with existing system)
+   */ parseRef(ref) {
+        const parsed = this.parseUrl(ref);
+        // Use host as registry, 'http' as owner (convention for HTTP sources)
+        return {
+            registry: 'http',
+            owner: parsed.host,
+            repo: parsed.skillName,
+            version: parsed.version,
+            raw: ref
+        };
+    }
+    /**
+   * Parse version specification (same as GitResolver for consistency)
+   */ parseVersion(versionSpec) {
+        if (!versionSpec) return {
+            type: 'exact',
+            value: 'latest',
+            raw: ''
+        };
+        const raw = versionSpec;
+        // latest
+        if ('latest' === versionSpec) return {
+            type: 'latest',
+            value: 'latest',
+            raw
+        };
+        // exact version (v1.0.0 or 1.0.0)
+        return {
+            type: 'exact',
+            value: versionSpec,
+            raw
+        };
+    }
+    /**
+   * Resolve version for HTTP sources
+   * Since HTTP sources are static, we just return the parsed version
+   */ async resolveVersion(_url, versionSpec) {
+        // For HTTP sources, version is embedded in URL or specified explicitly
+        // No remote version resolution like Git
+        return {
+            ref: versionSpec.value
+        };
+    }
+    /**
+   * Build the download URL
+   * For HTTP sources, the URL is already complete
+   */ buildRepoUrl(parsed) {
+        // For HTTP sources, raw contains the full URL
+        const urlPart = parsed.raw.split('@')[0];
+        return this.normalizeUrl(urlPart);
+    }
+    /**
+   * Full resolution: from reference string to download-ready information
+   */ async resolve(ref) {
+        const httpInfo = this.parseUrl(ref);
+        const parsed = this.parseRef(ref);
+        const repoUrl = httpInfo.url;
+        const versionSpec = this.parseVersion(parsed.version);
+        const resolved = await this.resolveVersion(repoUrl, versionSpec);
+        return {
+            parsed,
+            repoUrl,
+            ref: resolved.ref,
+            commit: resolved.commit,
+            httpInfo
+        };
+    }
+    /**
+   * Normalize URL protocol
+   * Converts oss:// and s3:// to https://
+   */ normalizeUrl(url) {
+        // Convert oss:// to https:// (Aliyun OSS)
+        if (url.startsWith('oss://')) {
+            // oss://bucket-name/path -> https://bucket-name.oss.aliyuncs.com/path
+            const parts = url.slice(6).split('/');
+            const bucket = parts[0];
+            const rest = parts.slice(1).join('/');
+            return `https://${bucket}.oss.aliyuncs.com/${rest}`;
+        }
+        // Convert s3:// to https:// (AWS S3)
+        if (url.startsWith('s3://')) {
+            // s3://bucket-name/path -> https://bucket-name.s3.amazonaws.com/path
+            const parts = url.slice(5).split('/');
+            const bucket = parts[0];
+            const rest = parts.slice(1).join('/');
+            return `https://${bucket}.s3.amazonaws.com/${rest}`;
+        }
+        return url;
+    }
+    /**
+   * Detect archive format from filename
+   */ detectArchiveFormat(filename) {
+        const lower = filename.toLowerCase();
+        if (lower.endsWith('.tar.gz')) return 'tar.gz';
+        if (lower.endsWith('.tgz')) return 'tgz';
+        if (lower.endsWith('.zip')) return 'zip';
+        if (lower.endsWith('.tar')) return 'tar';
+    }
+    /**
+   * Parse filename to extract skill name and version
+   *
+   * Examples:
+   * - my-skill-v1.0.0.tar.gz -> { name: 'my-skill', version: 'v1.0.0' }
+   * - skill.tar.gz -> { name: 'skill', version: undefined }
+   * - test-skill-1.2.3.zip -> { name: 'test-skill', version: '1.2.3' }
+   */ parseFilename(filename) {
+        // Remove archive extension
+        const baseName = filename.replace(/\.tar\.gz$/i, '').replace(/\.tgz$/i, '').replace(/\.zip$/i, '').replace(/\.tar$/i, '');
+        // Try to extract version pattern
+        // Patterns: -v1.0.0, -1.0.0, _v1.0.0, _1.0.0
+        const versionMatch = baseName.match(/[-_](v?\d+\.\d+\.\d+(?:-[\w.]+)?)$/i);
+        if (versionMatch) {
+            const version = versionMatch[1];
+            const name = baseName.slice(0, -versionMatch[0].length);
+            return {
+                name,
+                version
+            };
+        }
+        return {
+            name: baseName
+        };
+    }
+}
+/**
+ * Current lockfile version
+ */ const LOCKFILE_VERSION = 1;
+/**
+ * LockManager - Manage skills.lock file
+ *
+ * Used for locking exact versions to ensure team consistency
+ */ class LockManager {
     projectRoot;
     lockPath;
     lockData = null;
@@ -1117,15 +2207,22 @@ class LockManager {
         this.projectRoot = projectRoot || process.cwd();
         this.lockPath = getSkillsLockPath(this.projectRoot);
     }
-    getLockPath() {
+    /**
+   * Get lock file path
+   */ getLockPath() {
         return this.lockPath;
     }
-    exists() {
+    /**
+   * Check if lock file exists
+   */ exists() {
         return exists(this.lockPath);
     }
-    load() {
+    /**
+   * Load lock file
+   */ load() {
         if (this.lockData) return this.lockData;
         if (!this.exists()) {
+            // If not exists, create empty lock
             this.lockData = {
                 lockfileVersion: LOCKFILE_VERSION,
                 skills: {}
@@ -1139,26 +2236,36 @@ class LockManager {
             throw new Error(`Failed to parse skills.lock: ${error.message}`);
         }
     }
-    reload() {
+    /**
+   * Reload lock file
+   */ reload() {
         this.lockData = null;
         return this.load();
     }
-    save(lockToSave) {
+    /**
+   * Save lock file
+   */ save(lockToSave) {
         const toSave = lockToSave || this.lockData;
         if (!toSave) throw new Error('No lock to save');
         writeJson(this.lockPath, toSave);
         this.lockData = toSave;
     }
-    get(name) {
+    /**
+   * Get locked skill
+   */ get(name) {
         const lock = this.load();
         return lock.skills[name];
     }
-    set(name, skill) {
+    /**
+   * Set locked skill
+   */ set(name, skill) {
         const lock = this.load();
         lock.skills[name] = skill;
         this.save();
     }
-    remove(name) {
+    /**
+   * Remove locked skill
+   */ remove(name) {
         const lock = this.load();
         if (lock.skills[name]) {
             delete lock.skills[name];
@@ -1167,7 +2274,9 @@ class LockManager {
         }
         return false;
     }
-    lockSkill(name, options) {
+    /**
+   * Lock a skill
+   */ lockSkill(name, options) {
         const lockedSkill = {
             source: options.source,
             version: options.version,
@@ -1179,29 +2288,39 @@ class LockManager {
         this.set(name, lockedSkill);
         return lockedSkill;
     }
-    getAll() {
+    /**
+   * Get all locked skills
+   */ getAll() {
         const lock = this.load();
         return {
             ...lock.skills
         };
     }
-    has(name) {
+    /**
+   * Check if skill is locked
+   */ has(name) {
         const lock = this.load();
         return name in lock.skills;
     }
-    isVersionMatch(name, version) {
+    /**
+   * Check if locked version matches current version
+   */ isVersionMatch(name, version) {
         const locked = this.get(name);
         if (!locked) return false;
         return locked.version === version;
     }
-    clear() {
+    /**
+   * Clear all locks
+   */ clear() {
         this.lockData = {
             lockfileVersion: LOCKFILE_VERSION,
             skills: {}
         };
         this.save();
     }
-    delete() {
+    /**
+   * Delete lock file
+   */ delete() {
         if (this.exists()) {
             const fs = __webpack_require__("node:fs");
             fs.unlinkSync(this.lockPath);
@@ -1209,32 +2328,53 @@ class LockManager {
         this.lockData = null;
     }
 }
-const logger_logger = {
-    info (message) {
+/**
+ * Logger utility for CLI output
+ */ const logger_logger = {
+    /**
+   * Info message (blue)
+   */ info (message) {
         console.log(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].blue('ℹ'), message);
     },
-    success (message) {
+    /**
+   * Success message (green)
+   */ success (message) {
         console.log(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green('✅'), message);
     },
-    warn (message) {
+    /**
+   * Warning message (yellow)
+   */ warn (message) {
         console.log(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].yellow('⚠️'), message);
     },
-    error (message) {
+    /**
+   * Error message (red)
+   */ error (message) {
         console.error(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].red('❌'), message);
     },
-    debug (message) {
+    /**
+   * Debug message (gray, only in verbose mode)
+   */ debug (message) {
         if (process.env.DEBUG || process.env.VERBOSE) console.log(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].gray('🔍'), __WEBPACK_EXTERNAL_MODULE_chalk__["default"].gray(message));
     },
-    package (message) {
+    /**
+   * Package/skill message (package emoji)
+   */ package (message) {
         console.log(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan('📦'), message);
     },
-    log (message) {
+    /**
+   * Plain message without icon
+   */ log (message) {
         console.log(message);
     },
-    newline () {
+    /**
+   * Newline
+   */ newline () {
         console.log();
     },
-    table (headers, rows) {
+    /**
+   * Table-like output
+   */ table (headers, rows) {
+        // Calculate column widths
         const widths = headers.map((h, i)=>{
             const colValues = [
                 h,
@@ -1242,17 +2382,31 @@ const logger_logger = {
             ];
             return Math.max(...colValues.map((v)=>v.length));
         });
+        // Print header
         const headerRow = headers.map((h, i)=>h.padEnd(widths[i])).join('  ');
         console.log(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].bold(headerRow));
+        // Print separator (removed)
+        // console.log(widths.map(w => '-'.repeat(w)).join('  '));
+        // Print rows
         for (const row of rows){
             const rowStr = row.map((cell, i)=>(cell || '').padEnd(widths[i])).join('  ');
             console.log(rowStr);
         }
     }
 };
-class SkillManager {
+/**
+ * SkillManager - Core Skill management class
+ *
+ * Integrates GitResolver, CacheManager, ConfigLoader, LockManager
+ * Provides complete skill installation, update, and uninstall functionality
+ *
+ * Installation directories:
+ * - Project mode (default): .skills/ or directory configured in skills.json
+ * - Global mode (-g): ~/.claude/skills/
+ */ class SkillManager {
     projectRoot;
     resolver;
+    httpResolver;
     cache;
     config;
     lockManager;
@@ -1263,42 +2417,86 @@ class SkillManager {
         this.config = new ConfigLoader(this.projectRoot);
         this.lockManager = new LockManager(this.projectRoot);
         this.cache = new CacheManager();
-        this.resolver = new GitResolver();
+        // Pass registry resolver from ConfigLoader to GitResolver
+        this.resolver = new GitResolver('github', void 0, (registryName)=>this.config.getRegistryUrl(registryName));
+        this.httpResolver = new HttpResolver();
     }
-    isGlobalMode() {
+    /**
+   * Check if in global mode
+   */ isGlobalMode() {
         return this.isGlobal;
     }
-    getProjectRoot() {
+    /**
+   * Get project root directory
+   */ getProjectRoot() {
         return this.projectRoot;
     }
-    getInstallDir() {
+    /**
+   * Get legacy installation directory (for backward compatibility)
+   *
+   * - Global mode: ~/.claude/skills/
+   * - Project mode: .skills/ or directory configured in skills.json
+   */ getInstallDir() {
         if (this.isGlobal) return getGlobalSkillsDir();
         return this.config.getInstallDir();
     }
-    getCanonicalSkillsDir() {
+    /**
+   * Get canonical skills directory
+   *
+   * This is the primary storage location used by installToAgents().
+   * - Project mode: .agents/skills/
+   * - Global mode: ~/.agents/skills/
+   */ getCanonicalSkillsDir() {
         const home = process.env.HOME || process.env.USERPROFILE || '';
         const baseDir = this.isGlobal ? home : this.projectRoot;
         return __WEBPACK_EXTERNAL_MODULE_node_path__.join(baseDir, '.agents', 'skills');
     }
-    getSkillPath(name) {
+    /**
+   * Get skill installation path
+   *
+   * Checks canonical location first, then falls back to configured installDir.
+   */ getSkillPath(name) {
+        // Check canonical location first (.agents/skills/)
         const canonicalPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(this.getCanonicalSkillsDir(), name);
         if (exists(canonicalPath)) return canonicalPath;
+        // Check configured installation directory (.skills/ or custom)
         const installDir = this.getInstallDir();
         const installPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(installDir, name);
         if (exists(installPath)) return installPath;
+        // Default to configured installation directory for new installations
+        // if it's not the default .skills, otherwise use canonical location.
+        // This respects "installDir" in skills.json.
         const defaults = this.config.getDefaults();
         if ('.skills' !== defaults.installDir && !this.isGlobal) return installPath;
+        // Default to canonical location for new installations
         return canonicalPath;
     }
-    async install(ref, options = {}) {
+    /**
+   * Detect if a reference is an HTTP/OSS URL
+   */ isHttpSource(ref) {
+        return HttpResolver.isHttpUrl(ref);
+    }
+    /**
+   * Install skill
+   */ async install(ref, options = {}) {
+        // Detect source type and delegate to appropriate installer
+        if (this.isHttpSource(ref)) return this.installFromHttp(ref, options);
+        return this.installFromGit(ref, options);
+    }
+    /**
+   * Install skill from Git repository
+   */ async installFromGit(ref, options = {}) {
         const { force = false, save = true } = options;
+        // Parse reference
         const resolved = await this.resolver.resolve(ref);
         const { parsed, repoUrl } = resolved;
-        const gitRef = resolved.ref;
+        const gitRef = resolved.ref; // Git reference (tag, branch, commit)
         const skillName = parsed.subPath ? __WEBPACK_EXTERNAL_MODULE_node_path__.basename(parsed.subPath) : parsed.repo;
         const skillPath = this.getSkillPath(skillName);
+        // Check if already installed
         if (exists(skillPath) && !force) {
             const locked = this.lockManager.get(skillName);
+            // Compare ref if available, fallback to version for backward compatibility
             const lockedRef = locked?.ref || locked?.version;
             if (locked && lockedRef === gitRef) {
                 logger_logger.info(`${skillName}@${gitRef} is already installed`);
@@ -1312,21 +2510,27 @@ class SkillManager {
             }
         }
         logger_logger["package"](`Installing ${skillName}@${gitRef}...`);
+        // Check cache
         let cacheResult = await this.cache.get(parsed, gitRef);
         if (cacheResult) logger_logger.debug(`Using cached ${skillName}@${gitRef}`);
         else {
             logger_logger.debug(`Caching ${skillName}@${gitRef} from ${repoUrl}`);
             cacheResult = await this.cache.cache(repoUrl, parsed, gitRef, gitRef);
         }
+        // Copy to installation directory
         ensureDir(this.getInstallDir());
         if (exists(skillPath)) remove(skillPath);
         await this.cache.copyTo(parsed, gitRef, skillPath);
-        let semanticVersion = gitRef;
+        // Read semantic version from skill.json
+        let semanticVersion = gitRef; // fallback to gitRef if no skill.json
         const skillJsonPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(skillPath, 'skill.json');
         if (exists(skillJsonPath)) try {
             const skillJson = readJson(skillJsonPath);
             if (skillJson.version) semanticVersion = skillJson.version;
-        } catch  {}
+        } catch  {
+        // Ignore parse errors, use gitRef as fallback
+        }
+        // Update lock file (project mode only)
         if (!this.isGlobal) this.lockManager.lockSkill(skillName, {
             source: `${parsed.registry}:${parsed.owner}/${parsed.repo}${parsed.subPath ? `/${parsed.subPath}` : ''}`,
             version: semanticVersion,
@@ -1334,9 +2538,12 @@ class SkillManager {
             resolved: repoUrl,
             commit: cacheResult.commit
         });
+        // Update skills.json (project mode only)
         if (!this.isGlobal && save) {
             this.config.ensureExists();
-            this.config.addSkill(skillName, ref);
+            // Normalize the reference to use registry shorthand if possible
+            const normalizedRef = this.config.normalizeSkillRef(ref);
+            this.config.addSkill(skillName, normalizedRef);
         }
         const displayVersion = semanticVersion !== gitRef ? `${semanticVersion} (${gitRef})` : gitRef;
         const locationHint = this.isGlobal ? '(global)' : '';
@@ -1345,7 +2552,75 @@ class SkillManager {
         if (!installed) throw new Error(`Failed to get installed skill info for ${skillName}`);
         return installed;
     }
-    async installAll(options = {}) {
+    /**
+   * Install skill from HTTP/OSS URL
+   */ async installFromHttp(ref, options = {}) {
+        const { force = false, save = true } = options;
+        // Parse HTTP reference
+        const resolved = await this.httpResolver.resolve(ref);
+        const { parsed, repoUrl, httpInfo } = resolved;
+        const version = resolved.ref || 'latest';
+        const skillName = httpInfo.skillName;
+        const skillPath = this.getSkillPath(skillName);
+        // Check if already installed
+        if (exists(skillPath) && !force) {
+            const locked = this.lockManager.get(skillName);
+            const lockedRef = locked?.ref || locked?.version;
+            if (locked && lockedRef === version) {
+                logger_logger.info(`${skillName}@${version} is already installed`);
+                const installed = this.getInstalledSkill(skillName);
+                if (installed) return installed;
+            }
+            if (!force) {
+                logger_logger.warn(`${skillName} is already installed. Use --force to reinstall.`);
+                const installed = this.getInstalledSkill(skillName);
+                if (installed) return installed;
+            }
+        }
+        logger_logger["package"](`Installing ${skillName}@${version} from ${httpInfo.host}...`);
+        // Check cache
+        let cacheResult = await this.cache.get(parsed, version);
+        if (cacheResult) logger_logger.debug(`Using cached ${skillName}@${version}`);
+        else {
+            logger_logger.debug(`Downloading ${skillName}@${version} from ${repoUrl}`);
+            cacheResult = await this.cache.cacheFromHttp(repoUrl, parsed, version);
+        }
+        // Copy to installation directory
+        ensureDir(this.getInstallDir());
+        if (exists(skillPath)) remove(skillPath);
+        await this.cache.copyTo(parsed, version, skillPath);
+        // Read semantic version from skill.json
+        let semanticVersion = version;
+        const skillJsonPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(skillPath, 'skill.json');
+        if (exists(skillJsonPath)) try {
+            const skillJson = readJson(skillJsonPath);
+            if (skillJson.version) semanticVersion = skillJson.version;
+        } catch  {
+        // Ignore parse errors
+        }
+        // Update lock file (project mode only)
+        if (!this.isGlobal) this.lockManager.lockSkill(skillName, {
+            source: `http:${httpInfo.host}/${skillName}`,
+            version: semanticVersion,
+            ref: version,
+            resolved: repoUrl,
+            commit: cacheResult.commit
+        });
+        // Update skills.json (project mode only)
+        if (!this.isGlobal && save) {
+            this.config.ensureExists();
+            this.config.addSkill(skillName, ref);
+        }
+        const displayVersion = semanticVersion !== version ? `${semanticVersion} (${version})` : version;
+        const locationHint = this.isGlobal ? '(global)' : '';
+        logger_logger.success(`Installed ${skillName}@${displayVersion} to ${skillPath} ${locationHint}`.trim());
+        const installed = this.getInstalledSkill(skillName);
+        if (!installed) throw new Error(`Failed to get installed skill info for ${skillName}`);
+        return installed;
+    }
+    /**
+   * Install all skills from skills.json
+   */ async installAll(options = {}) {
         const skills = this.config.getSkills();
         const installed = [];
         for (const [name, ref] of Object.entries(skills))try {
@@ -1359,38 +2634,59 @@ class SkillManager {
         }
         return installed;
     }
-    uninstall(name) {
+    /**
+   * Uninstall skill
+   */ uninstall(name) {
         const skillPath = this.getSkillPath(name);
         if (!exists(skillPath)) {
             const location = this.isGlobal ? '(global)' : '';
             logger_logger.warn(`Skill ${name} is not installed ${location}`.trim());
             return false;
         }
+        // Remove installation directory
         remove(skillPath);
+        // Remove from lock file (project mode only)
         if (!this.isGlobal) this.lockManager.remove(name);
+        // Remove from skills.json (project mode only)
         if (!this.isGlobal && this.config.exists()) this.config.removeSkill(name);
         const locationHint = this.isGlobal ? '(global)' : '';
         logger_logger.success(`Uninstalled ${name} ${locationHint}`.trim());
         return true;
     }
-    checkNeedsUpdate(name, remoteCommit) {
+    /**
+   * Check if a skill needs to be updated by comparing local and remote commits
+   *
+   * @param name - Skill name
+   * @param remoteCommit - Remote commit hash to compare against
+   * @returns true if update is needed, false if already up to date
+   */ checkNeedsUpdate(name, remoteCommit) {
         const locked = this.lockManager.get(name);
+        // No lock info or no commit hash means we need to update
         if (!locked?.commit) return true;
+        // Compare commits
         return locked.commit !== remoteCommit;
     }
-    async update(name) {
+    /**
+   * Update skill
+   */ async update(name) {
         const updated = [];
         if (name) {
+            // Update single skill
             const ref = this.config.getSkillRef(name);
             if (!ref) {
                 logger_logger.error(`Skill ${name} not found in skills.json`);
                 return [];
             }
-            const resolved = await this.resolver.resolve(ref);
-            const remoteCommit = await this.cache.getRemoteCommit(resolved.repoUrl, resolved.ref);
-            if (!this.checkNeedsUpdate(name, remoteCommit)) {
-                logger_logger.info(`${name} is already up to date`);
-                return [];
+            // Check if update is needed (skip check for HTTP sources - always re-download)
+            if (this.isHttpSource(ref)) // For HTTP sources, log that we're re-downloading
+            logger_logger.info(`${name} is from HTTP source, re-downloading...`);
+            else {
+                const resolved = await this.resolver.resolve(ref);
+                const remoteCommit = await this.cache.getRemoteCommit(resolved.repoUrl, resolved.ref);
+                if (!this.checkNeedsUpdate(name, remoteCommit)) {
+                    logger_logger.info(`${name} is already up to date`);
+                    return [];
+                }
             }
             const skill = await this.install(ref, {
                 force: true,
@@ -1398,13 +2694,18 @@ class SkillManager {
             });
             updated.push(skill);
         } else {
+            // Update all
             const skills = this.config.getSkills();
             for (const [skillName, ref] of Object.entries(skills))try {
-                const resolved = await this.resolver.resolve(ref);
-                const remoteCommit = await this.cache.getRemoteCommit(resolved.repoUrl, resolved.ref);
-                if (!this.checkNeedsUpdate(skillName, remoteCommit)) {
-                    logger_logger.info(`${skillName} is already up to date`);
-                    continue;
+                // Check if update is needed (skip check for HTTP sources)
+                if (this.isHttpSource(ref)) logger_logger.info(`${skillName} is from HTTP source, re-downloading...`);
+                else {
+                    const resolved = await this.resolver.resolve(ref);
+                    const remoteCommit = await this.cache.getRemoteCommit(resolved.repoUrl, resolved.ref);
+                    if (!this.checkNeedsUpdate(skillName, remoteCommit)) {
+                        logger_logger.info(`${skillName} is already up to date`);
+                        continue;
+                    }
                 }
                 const skill = await this.install(ref, {
                     force: true,
@@ -1417,9 +2718,14 @@ class SkillManager {
         }
         return updated;
     }
-    list() {
+    /**
+   * List installed skills
+   *
+   * Checks both canonical (.agents/skills/) and legacy (.skills/) locations.
+   */ list() {
         const skills = [];
         const seenNames = new Set();
+        // Check canonical location first (.agents/skills/)
         const canonicalDir = this.getCanonicalSkillsDir();
         if (exists(canonicalDir)) for (const name of listDir(canonicalDir)){
             const skillPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(canonicalDir, name);
@@ -1430,15 +2736,20 @@ class SkillManager {
                 seenNames.add(name);
             }
         }
+        // Check legacy location (.skills/)
         const legacyDir = this.getInstallDir();
         if (exists(legacyDir) && legacyDir !== canonicalDir) for (const name of listDir(legacyDir)){
+            // Skip if already found in canonical location
             if (seenNames.has(name)) continue;
             const skillPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(legacyDir, name);
             if (!isDirectory(skillPath)) continue;
+            // Skip symlinks pointing to canonical location (avoid duplicates)
             if (isSymlink(skillPath)) try {
                 const realPath = getRealPath(skillPath);
                 if (realPath.includes(__WEBPACK_EXTERNAL_MODULE_node_path__.join('.agents', 'skills'))) continue;
-            } catch  {}
+            } catch  {
+            // If we can't resolve the symlink, include it anyway
+            }
             const skill = this.getInstalledSkillFromPath(name, skillPath);
             if (skill) {
                 skills.push(skill);
@@ -1447,7 +2758,9 @@ class SkillManager {
         }
         return skills;
     }
-    getInstalledSkillFromPath(name, skillPath) {
+    /**
+   * Get installed skill information from a specific path
+   */ getInstalledSkillFromPath(name, skillPath) {
         if (!exists(skillPath)) return null;
         const isLinked = isSymlink(skillPath);
         const locked = this.lockManager.get(name);
@@ -1455,7 +2768,9 @@ class SkillManager {
         const skillJsonPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(skillPath, 'skill.json');
         if (exists(skillJsonPath)) try {
             metadata = readJson(skillJsonPath);
-        } catch  {}
+        } catch  {
+        // Ignore parse errors
+        }
         return {
             name,
             path: skillPath,
@@ -1465,35 +2780,59 @@ class SkillManager {
             isLinked
         };
     }
-    getInstalledSkill(name) {
+    /**
+   * Get installed skill information
+   *
+   * Checks canonical location first, then legacy location.
+   */ getInstalledSkill(name) {
+        // Check canonical location first (.agents/skills/)
         const canonicalPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(this.getCanonicalSkillsDir(), name);
         if (exists(canonicalPath)) return this.getInstalledSkillFromPath(name, canonicalPath);
+        // Check legacy location (.skills/)
         const legacyPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(this.getInstallDir(), name);
         if (exists(legacyPath)) return this.getInstalledSkillFromPath(name, legacyPath);
         return null;
     }
-    getInfo(name) {
+    /**
+   * Get skill details
+   */ getInfo(name) {
         return {
             installed: this.getInstalledSkill(name),
             locked: this.lockManager.get(name),
             config: this.config.getSkillRef(name)
         };
     }
-    async checkOutdated() {
+    /**
+   * Check for outdated skills
+   */ async checkOutdated() {
         const results = [];
         const skills = this.config.getSkills();
         for (const [name, ref] of Object.entries(skills))try {
             const locked = this.lockManager.get(name);
+            // Use ref for comparison (git tag/branch/commit), fallback to version for backward compatibility
             const currentRef = locked?.ref || locked?.version || 'unknown';
             const currentVersion = locked?.version || 'unknown';
+            // HTTP sources don't support version checking
+            if (this.isHttpSource(ref)) {
+                results.push({
+                    name,
+                    current: currentVersion,
+                    latest: 'n/a (HTTP source)',
+                    updateAvailable: false
+                });
+                continue;
+            }
+            // Parse latest version
             const parsed = this.resolver.parseRef(ref);
             const repoUrl = this.resolver.buildRepoUrl(parsed);
+            // Force get latest
             const latestResolved = await this.resolver.resolveVersion(repoUrl, {
                 type: 'latest',
                 value: 'latest',
                 raw: 'latest'
             });
             const latest = latestResolved.ref;
+            // Compare using git refs, not semantic versions
             const updateAvailable = currentRef !== latest && 'unknown' !== currentRef;
             results.push({
                 name,
@@ -1512,35 +2851,60 @@ class SkillManager {
         }
         return results;
     }
-    async installToAgents(ref, targetAgents, options = {}) {
+    // ============================================================================
+    // Multi-Agent installation methods
+    // ============================================================================
+    /**
+   * Install skill to multiple agents
+   *
+   * @param ref - Skill reference (e.g., github:user/repo@v1.0.0 or HTTP URL)
+   * @param targetAgents - Target agents list
+   * @param options - Installation options
+   */ async installToAgents(ref, targetAgents, options = {}) {
+        // Detect source type and delegate to appropriate installer
+        if (this.isHttpSource(ref)) return this.installToAgentsFromHttp(ref, targetAgents, options);
+        return this.installToAgentsFromGit(ref, targetAgents, options);
+    }
+    /**
+   * Install skill from Git to multiple agents
+   */ async installToAgentsFromGit(ref, targetAgents, options = {}) {
         const { save = true, mode = 'symlink' } = options;
+        // Parse reference
         const resolved = await this.resolver.resolve(ref);
         const { parsed, repoUrl } = resolved;
-        const gitRef = resolved.ref;
+        const gitRef = resolved.ref; // Git reference (tag, branch, commit)
         const skillName = parsed.subPath ? __WEBPACK_EXTERNAL_MODULE_node_path__.basename(parsed.subPath) : parsed.repo;
         logger_logger["package"](`Installing ${skillName}@${gitRef} to ${targetAgents.length} agent(s)...`);
+        // Check cache
         let cacheResult = await this.cache.get(parsed, gitRef);
         if (cacheResult) logger_logger.debug(`Using cached ${skillName}@${gitRef}`);
         else {
             logger_logger.debug(`Caching ${skillName}@${gitRef} from ${repoUrl}`);
             cacheResult = await this.cache.cache(repoUrl, parsed, gitRef, gitRef);
         }
+        // Get cache path as source
         const sourcePath = this.cache.getCachePath(parsed, gitRef);
-        let semanticVersion = gitRef;
+        // Read semantic version from skill.json
+        let semanticVersion = gitRef; // fallback to gitRef if no skill.json
         const skillJsonPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(sourcePath, 'skill.json');
         if (exists(skillJsonPath)) try {
             const skillJson = readJson(skillJsonPath);
             if (skillJson.version) semanticVersion = skillJson.version;
-        } catch  {}
+        } catch  {
+        // Ignore parse errors, use gitRef as fallback
+        }
+        // Create Installer with custom installDir from config
         const defaults = this.config.getDefaults();
         const installer = new Installer({
             cwd: this.projectRoot,
             global: this.isGlobal,
             installDir: defaults.installDir
         });
+        // Install to all target agents
         const results = await installer.installToAgents(sourcePath, skillName, targetAgents, {
             mode: mode
         });
+        // Update lock file (project mode only)
         if (!this.isGlobal) this.lockManager.lockSkill(skillName, {
             source: `${parsed.registry}:${parsed.owner}/${parsed.repo}${parsed.subPath ? `/${parsed.subPath}` : ''}`,
             version: semanticVersion,
@@ -1548,15 +2912,20 @@ class SkillManager {
             resolved: repoUrl,
             commit: cacheResult.commit
         });
+        // Update skills.json (project mode only)
         if (!this.isGlobal && save) {
             this.config.ensureExists();
-            this.config.addSkill(skillName, ref);
+            // Normalize the reference to use registry shorthand if possible
+            const normalizedRef = this.config.normalizeSkillRef(ref);
+            this.config.addSkill(skillName, normalizedRef);
         }
+        // Count results
         const successCount = Array.from(results.values()).filter((r)=>r.success).length;
         const failCount = results.size - successCount;
         const displayVersion = semanticVersion !== gitRef ? `${semanticVersion} (${gitRef})` : gitRef;
         if (0 === failCount) logger_logger.success(`Installed ${skillName}@${displayVersion} to ${successCount} agent(s)`);
         else logger_logger.warn(`Installed ${skillName}@${displayVersion} to ${successCount} agent(s), ${failCount} failed`);
+        // Build the InstalledSkill to return
         const skill = {
             name: skillName,
             path: sourcePath,
@@ -1568,17 +2937,100 @@ class SkillManager {
             results
         };
     }
-    async getDefaultTargetAgents() {
+    /**
+   * Install skill from HTTP/OSS to multiple agents
+   */ async installToAgentsFromHttp(ref, targetAgents, options = {}) {
+        const { save = true, mode = 'symlink' } = options;
+        // Parse HTTP reference
+        const resolved = await this.httpResolver.resolve(ref);
+        const { parsed, repoUrl, httpInfo } = resolved;
+        const version = resolved.ref || 'latest';
+        const skillName = httpInfo.skillName;
+        logger_logger["package"](`Installing ${skillName}@${version} from ${httpInfo.host} to ${targetAgents.length} agent(s)...`);
+        // Check cache
+        let cacheResult = await this.cache.get(parsed, version);
+        if (cacheResult) logger_logger.debug(`Using cached ${skillName}@${version}`);
+        else {
+            logger_logger.debug(`Downloading ${skillName}@${version} from ${repoUrl}`);
+            cacheResult = await this.cache.cacheFromHttp(repoUrl, parsed, version);
+        }
+        // Get cache path as source
+        const sourcePath = this.cache.getCachePath(parsed, version);
+        // Read semantic version from skill.json
+        let semanticVersion = version;
+        const skillJsonPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(sourcePath, 'skill.json');
+        if (exists(skillJsonPath)) try {
+            const skillJson = readJson(skillJsonPath);
+            if (skillJson.version) semanticVersion = skillJson.version;
+        } catch  {
+        // Ignore parse errors
+        }
+        // Create Installer with custom installDir from config
+        const defaults = this.config.getDefaults();
+        const installer = new Installer({
+            cwd: this.projectRoot,
+            global: this.isGlobal,
+            installDir: defaults.installDir
+        });
+        // Install to all target agents
+        const results = await installer.installToAgents(sourcePath, skillName, targetAgents, {
+            mode: mode
+        });
+        // Update lock file (project mode only)
+        if (!this.isGlobal) this.lockManager.lockSkill(skillName, {
+            source: `http:${httpInfo.host}/${skillName}`,
+            version: semanticVersion,
+            ref: version,
+            resolved: repoUrl,
+            commit: cacheResult.commit
+        });
+        // Update skills.json (project mode only)
+        if (!this.isGlobal && save) {
+            this.config.ensureExists();
+            this.config.addSkill(skillName, ref);
+        }
+        // Count results
+        const successCount = Array.from(results.values()).filter((r)=>r.success).length;
+        const failCount = results.size - successCount;
+        const displayVersion = semanticVersion !== version ? `${semanticVersion} (${version})` : version;
+        if (0 === failCount) logger_logger.success(`Installed ${skillName}@${displayVersion} to ${successCount} agent(s)`);
+        else logger_logger.warn(`Installed ${skillName}@${displayVersion} to ${successCount} agent(s), ${failCount} failed`);
+        // Build the InstalledSkill to return
+        const skill = {
+            name: skillName,
+            path: sourcePath,
+            version: semanticVersion,
+            source: `http:${httpInfo.host}/${skillName}`
+        };
+        return {
+            skill,
+            results
+        };
+    }
+    /**
+   * Get default target agents
+   *
+   * Priority:
+   * 1. defaults.targetAgents in skills.json
+   * 2. Auto-detect installed agents
+   * 3. Return empty array
+   */ async getDefaultTargetAgents() {
+        // Read from configuration
         const defaults = this.config.getDefaults();
         if (defaults.targetAgents && defaults.targetAgents.length > 0) return defaults.targetAgents.filter(isValidAgentType);
+        // Auto-detect
         return detectInstalledAgents();
     }
-    getDefaultInstallMode() {
+    /**
+   * Get default installation mode
+   */ getDefaultInstallMode() {
         const defaults = this.config.getDefaults();
         if ('copy' === defaults.installMode || 'symlink' === defaults.installMode) return defaults.installMode;
         return 'symlink';
     }
-    validateAgentTypes(agentNames) {
+    /**
+   * Validate agent type list
+   */ validateAgentTypes(agentNames) {
         const valid = [];
         const invalid = [];
         for (const name of agentNames)if (isValidAgentType(name)) valid.push(name);
@@ -1588,10 +3040,14 @@ class SkillManager {
             invalid
         };
     }
-    getAllAgentTypes() {
+    /**
+   * Get all available agent types
+   */ getAllAgentTypes() {
         return Object.keys(agents);
     }
-    uninstallFromAgents(name, targetAgents) {
+    /**
+   * Uninstall skill from specified agents
+   */ uninstallFromAgents(name, targetAgents) {
         const defaults = this.config.getDefaults();
         const installer = new Installer({
             cwd: this.projectRoot,
@@ -1599,21 +3055,38 @@ class SkillManager {
             installDir: defaults.installDir
         });
         const results = installer.uninstallFromAgents(name, targetAgents);
+        // Remove from lock file (project mode only)
         if (!this.isGlobal) this.lockManager.remove(name);
+        // Remove from skills.json (project mode only)
         if (!this.isGlobal && this.config.exists()) this.config.removeSkill(name);
         const successCount = Array.from(results.values()).filter((r)=>r).length;
         logger_logger.success(`Uninstalled ${name} from ${successCount} agent(s)`);
         return results;
     }
 }
-class SkillValidationError extends Error {
+/**
+ * Skill Parser - SKILL.md parser
+ *
+ * Following agentskills.io specification: https://agentskills.io/specification
+ *
+ * SKILL.md format requirements:
+ * - YAML frontmatter containing name and description (required)
+ * - name: max 64 characters, lowercase letters, numbers, hyphens
+ * - description: max 1024 characters
+ * - Optional fields: license, compatibility, metadata, allowed-tools
+ */ /**
+ * Skill validation error
+ */ class SkillValidationError extends Error {
     field;
     constructor(message, field){
         super(message), this.field = field;
         this.name = 'SkillValidationError';
     }
 }
-function parseFrontmatter(content) {
+/**
+ * Simple YAML frontmatter parser
+ * Parses --- delimited YAML header
+ */ function parseFrontmatter(content) {
     const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
     const match = content.match(frontmatterRegex);
     if (!match) return {
@@ -1622,6 +3095,7 @@ function parseFrontmatter(content) {
     };
     const yamlContent = match[1];
     const markdownContent = match[2];
+    // Simple YAML parsing (supports basic key: value format)
     const data = {};
     const lines = yamlContent.split('\n');
     let currentKey = '';
@@ -1630,19 +3104,25 @@ function parseFrontmatter(content) {
     for (const line of lines){
         const trimmedLine = line.trim();
         if (!trimmedLine || trimmedLine.startsWith('#')) continue;
+        // Check if it's a new key: value pair
         const keyValueMatch = line.match(/^([a-zA-Z_-]+):\s*(.*)$/);
         if (keyValueMatch && !inMultiline) {
+            // Save previous value
             if (currentKey) data[currentKey] = parseYamlValue(currentValue.trim());
             currentKey = keyValueMatch[1];
             currentValue = keyValueMatch[2];
+            // Check if it's start of multiline string
             if ('|' === currentValue || '>' === currentValue) {
                 inMultiline = true;
                 currentValue = '';
             }
-        } else if (inMultiline && line.startsWith('  ')) currentValue += (currentValue ? '\n' : '') + line.slice(2);
+        } else if (inMultiline && line.startsWith('  ')) // Multiline string continuation
+        currentValue += (currentValue ? '\n' : '') + line.slice(2);
         else if (inMultiline && !line.startsWith('  ')) {
+            // Multiline string end
             inMultiline = false;
             data[currentKey] = currentValue.trim();
+            // Try to parse new line
             const newKeyMatch = line.match(/^([a-zA-Z_-]+):\s*(.*)$/);
             if (newKeyMatch) {
                 currentKey = newKeyMatch[1];
@@ -1650,49 +3130,80 @@ function parseFrontmatter(content) {
             }
         }
     }
+    // Save last value
     if (currentKey) data[currentKey] = parseYamlValue(currentValue.trim());
     return {
         data,
         content: markdownContent
     };
 }
-function parseYamlValue(value) {
+/**
+ * Parse YAML value
+ */ function parseYamlValue(value) {
     if (!value) return '';
+    // Boolean value
     if ('true' === value) return true;
     if ('false' === value) return false;
+    // Number
     if (/^-?\d+$/.test(value)) return parseInt(value, 10);
     if (/^-?\d+\.\d+$/.test(value)) return parseFloat(value);
+    // Remove quotes
     if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
     return value;
 }
-function validateSkillName(name) {
+/**
+ * Validate skill name format
+ *
+ * Specification requirements:
+ * - Max 64 characters
+ * - Only lowercase letters, numbers, hyphens allowed
+ * - Cannot start or end with hyphen
+ * - Cannot contain consecutive hyphens
+ */ function validateSkillName(name) {
     if (!name) throw new SkillValidationError('Skill name is required', 'name');
     if (name.length > 64) throw new SkillValidationError('Skill name must be at most 64 characters', 'name');
     if (!/^[a-z0-9]/.test(name)) throw new SkillValidationError('Skill name must start with a lowercase letter or number', 'name');
     if (!/[a-z0-9]$/.test(name)) throw new SkillValidationError('Skill name must end with a lowercase letter or number', 'name');
     if (/--/.test(name)) throw new SkillValidationError('Skill name cannot contain consecutive hyphens', 'name');
     if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(name) && name.length > 1) throw new SkillValidationError('Skill name can only contain lowercase letters, numbers, and hyphens', 'name');
+    // Single character name
     if (1 === name.length && !/^[a-z0-9]$/.test(name)) throw new SkillValidationError('Single character skill name must be a lowercase letter or number', 'name');
 }
-function validateSkillDescription(description) {
+/**
+ * Validate skill description
+ *
+ * Specification requirements:
+ * - Max 1024 characters
+ * - Cannot contain angle brackets
+ */ function validateSkillDescription(description) {
     if (!description) throw new SkillValidationError('Skill description is required', 'description');
     if (description.length > 1024) throw new SkillValidationError('Skill description must be at most 1024 characters', 'description');
     if (/<|>/.test(description)) throw new SkillValidationError('Skill description cannot contain angle brackets', 'description');
 }
-function parseSkillMd(content, options = {}) {
+/**
+ * Parse SKILL.md content
+ *
+ * @param content - SKILL.md file content
+ * @param options - Parse options
+ * @returns Parsed skill info, or null if format is invalid
+ * @throws SkillValidationError if validation fails in strict mode
+ */ function parseSkillMd(content, options = {}) {
     const { strict = false } = options;
     try {
         const { data, content: body } = parseFrontmatter(content);
+        // Check required fields
         if (!data.name || !data.description) {
             if (strict) throw new SkillValidationError('SKILL.md must have name and description in frontmatter');
             return null;
         }
         const name = String(data.name);
         const description = String(data.description);
+        // Validate field format
         if (strict) {
             validateSkillName(name);
             validateSkillDescription(description);
         }
+        // Parse allowed-tools
         let allowedTools;
         if (data['allowed-tools']) {
             const toolsStr = String(data['allowed-tools']);
@@ -1714,7 +3225,9 @@ function parseSkillMd(content, options = {}) {
         return null;
     }
 }
-function parseSkillMdFile(filePath, options = {}) {
+/**
+ * Parse SKILL.md from file path
+ */ function parseSkillMdFile(filePath, options = {}) {
     if (!external_node_fs_.existsSync(filePath)) {
         if (options.strict) throw new SkillValidationError(`SKILL.md not found: ${filePath}`);
         return null;
@@ -1722,11 +3235,15 @@ function parseSkillMdFile(filePath, options = {}) {
     const content = external_node_fs_.readFileSync(filePath, 'utf-8');
     return parseSkillMd(content, options);
 }
-function parseSkillFromDir(dirPath, options = {}) {
+/**
+ * Parse SKILL.md from skill directory
+ */ function parseSkillFromDir(dirPath, options = {}) {
     const skillMdPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(dirPath, 'SKILL.md');
     return parseSkillMdFile(skillMdPath, options);
 }
-function hasValidSkillMd(dirPath) {
+/**
+ * Check if directory contains valid SKILL.md
+ */ function hasValidSkillMd(dirPath) {
     const skillMdPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(dirPath, 'SKILL.md');
     if (!external_node_fs_.existsSync(skillMdPath)) return false;
     try {
@@ -1736,7 +3253,9 @@ function hasValidSkillMd(dirPath) {
         return false;
     }
 }
-function generateSkillMd(skill) {
+/**
+ * Generate SKILL.md content
+ */ function generateSkillMd(skill) {
     const frontmatter = [
         '---'
     ];
@@ -1749,4 +3268,4 @@ function generateSkillMd(skill) {
     frontmatter.push('');
     return frontmatter.join('\n') + skill.content;
 }
-export { CacheManager, ConfigLoader, DEFAULT_REGISTRIES, GitResolver, Installer, LockManager, SkillManager, SkillValidationError, agents, detectInstalledAgents, generateSkillMd, getAgentConfig, getAgentSkillsDir, getAllAgentTypes, getCanonicalSkillPath, getCanonicalSkillsDir, hasValidSkillMd, isPathSafe, isValidAgentType, logger_logger as logger, parseSkillFromDir, parseSkillMd, parseSkillMdFile, sanitizeName, shortenPath, validateSkillDescription, validateSkillName };
+export { CacheManager, ConfigLoader, DEFAULT_REGISTRIES, GitResolver, HttpResolver, Installer, LockManager, SkillManager, SkillValidationError, agents, detectInstalledAgents, generateSkillMd, getAgentConfig, getAgentSkillsDir, getAllAgentTypes, getCanonicalSkillPath, getCanonicalSkillsDir, hasValidSkillMd, isPathSafe, isValidAgentType, logger_logger as logger, parseSkillFromDir, parseSkillMd, parseSkillMdFile, sanitizeName, shortenPath, validateSkillDescription, validateSkillName };