reskill 1.1.0 → 1.1.1

package/dist/cli/index.js

@@ -16,43 +16,71 @@ 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 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,
@@ -60,15 +88,30 @@ 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);
         }
     }
 };
-async function checkForUpdate(packageName, currentVersion, options = {}) {
+/**
+ * Update Notifier - Check for CLI updates from npm registry
+ *
+ * Provides non-blocking update notifications to users when a newer version is available.
+ */ /**
+ * Check for updates from npm registry
+ *
+ * @param packageName - Name of the package to check
+ * @param currentVersion - Current installed version
+ * @param options - Check options
+ * @returns Update check result, or null if check failed
+ */ async function checkForUpdate(packageName, currentVersion, options = {}) {
     const timeout = options.timeout ?? 3000;
     try {
         const controller = new AbortController();
@@ -88,10 +131,16 @@ async function checkForUpdate(packageName, currentVersion, options = {}) {
             hasUpdate
         };
     } catch  {
+        // Silently fail - don't interrupt user workflow
         return null;
     }
 }
-function formatUpdateMessage(result) {
+/**
+ * Format update message for display
+ *
+ * @param result - Update check result
+ * @returns Formatted message string, or empty string if no update
+ */ function formatUpdateMessage(result) {
     if (!result.hasUpdate) return '';
     return `
 ┌────────────────────────────────────────────────────┐
@@ -102,8 +151,15 @@ function formatUpdateMessage(result) {
 └────────────────────────────────────────────────────┘
 `;
 }
-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',
@@ -224,43 +280,68 @@ const agents = {
         detectInstalled: async ()=>(0, external_node_fs_.existsSync)((0, __WEBPACK_EXTERNAL_MODULE_node_path__.join)(agent_registry_home, '.neovate'))
     }
 };
-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 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);
@@ -268,6 +349,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);
@@ -275,41 +357,62 @@ 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');
 }
-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, '~');
@@ -317,7 +420,29 @@ function shortenPath(fullPath, cwd) {
     return fullPath;
 }
 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;
@@ -332,6 +457,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';
             }
@@ -343,12 +469,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,
@@ -363,14 +493,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',
@@ -384,6 +519,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,
@@ -396,9 +532,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/, '');
@@ -406,7 +545,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'
     ];
@@ -419,13 +562,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',
@@ -439,7 +586,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);
@@ -451,7 +600,10 @@ function compareVersions(a, b) {
     }
     return 0;
 }
-function buildRepoUrl(registry, ownerRepo) {
+/**
+ * Build repository URL from registry and path
+ */ function buildRepoUrl(registry, ownerRepo) {
+    // Handle known registries
     const registryUrls = {
         github: 'https://github.com',
         gitlab: 'https://gitlab.com'
@@ -459,16 +611,40 @@ function buildRepoUrl(registry, ownerRepo) {
     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 {
@@ -480,6 +656,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;
@@ -498,50 +675,88 @@ function parseGitUrl(url) {
     }
     return null;
 }
-const installer_AGENTS_DIR = '.agents';
+/**
+ * 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);
@@ -549,8 +764,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()) {
@@ -561,17 +781,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;
@@ -579,7 +806,9 @@ async function installer_createSymlink(target, linkPath) {
         return false;
     }
 }
-class Installer {
+/**
+ * Installer class - Multi-Agent installer
+ */ class Installer {
     cwd;
     isGlobal;
     installDir;
@@ -588,25 +817,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,
@@ -620,6 +863,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);
@@ -630,14 +874,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 {
@@ -663,7 +911,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);
@@ -671,24 +921,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 [];
@@ -697,49 +956,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
+   */ 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)) {
@@ -756,35 +1061,51 @@ class CacheManager {
                 '.git'
             ]
         });
+        // Save commit info
         const fs = await import("node:fs");
         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) {
+    /**
+   * 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: []
@@ -805,11 +1126,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'
             });
@@ -817,6 +1147,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'
             });
@@ -825,28 +1156,59 @@ 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: {},
     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;
@@ -854,20 +1216,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 {
@@ -877,22 +1257,37 @@ 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,
@@ -905,7 +1300,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 {
@@ -914,7 +1317,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 = {
@@ -924,20 +1333,42 @@ 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) {
+    // ==========================================================================
+    // Skills Management
+    // ==========================================================================
+    /**
+   * Add skill to configuration
+   */ addSkill(name, ref) {
         this.ensureConfigLoaded();
         if (this.config) {
             this.config.skills[name] = ref;
             this.save();
         }
     }
-    removeSkill(name) {
+    /**
+   * 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];
@@ -946,7 +1377,9 @@ class ConfigLoader {
         }
         return false;
     }
-    getSkills() {
+    /**
+   * Get all skills as a shallow copy
+   */ getSkills() {
         if (!this.config) {
             if (!this.exists()) return {};
             this.load();
@@ -955,41 +1388,85 @@ 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 {
+/**
+ * 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 = 'github';
-    parseRef(ref) {
+    /**
+   * 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];
@@ -1004,16 +1481,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,
@@ -1025,25 +1516,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 {
@@ -1056,53 +1555,71 @@ 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}`);
     }
-    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
@@ -1115,12 +1632,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/, '');
@@ -1144,7 +1663,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);
@@ -1157,8 +1678,14 @@ class GitResolver {
         };
     }
 }
-const LOCKFILE_VERSION = 1;
-class LockManager {
+/**
+ * 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;
@@ -1166,15 +1693,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: {}
@@ -1188,26 +1722,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];
@@ -1216,7 +1760,9 @@ class LockManager {
         }
         return false;
     }
-    lockSkill(name, options) {
+    /**
+   * Lock a skill
+   */ lockSkill(name, options) {
         const lockedSkill = {
             source: options.source,
             version: options.version,
@@ -1228,29 +1774,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);
@@ -1258,7 +1814,16 @@ class LockManager {
         this.lockData = null;
     }
 }
-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;
     cache;
@@ -1273,40 +1838,70 @@ class SkillManager {
         this.cache = new CacheManager();
         this.resolver = new GitResolver();
     }
-    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 = {}) {
+    /**
+   * Install skill
+   */ async install(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`);
@@ -1320,21 +1915,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,
@@ -1342,6 +1943,7 @@ 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);
@@ -1353,7 +1955,9 @@ class SkillManager {
         if (!installed) throw new Error(`Failed to get installed skill info for ${skillName}`);
         return installed;
     }
-    async installAll(options = {}) {
+    /**
+   * 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 {
@@ -1367,33 +1971,50 @@ 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 [];
             }
+            // Check if update is needed by getting remote commit first
             const resolved = await this.resolver.resolve(ref);
             const remoteCommit = await this.cache.getRemoteCommit(resolved.repoUrl, resolved.ref);
             if (!this.checkNeedsUpdate(name, remoteCommit)) {
@@ -1406,8 +2027,10 @@ class SkillManager {
             });
             updated.push(skill);
         } else {
+            // Update all
             const skills = this.config.getSkills();
             for (const [skillName, ref] of Object.entries(skills))try {
+                // Check if update is needed
                 const resolved = await this.resolver.resolve(ref);
                 const remoteCommit = await this.cache.getRemoteCommit(resolved.repoUrl, resolved.ref);
                 if (!this.checkNeedsUpdate(skillName, remoteCommit)) {
@@ -1425,9 +2048,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);
@@ -1438,15 +2066,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);
@@ -1455,7 +2088,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);
@@ -1463,7 +2098,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,
@@ -1473,35 +2110,49 @@ 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';
+            // 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,
@@ -1520,35 +2171,53 @@ 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)
+   * @param targetAgents - Target agents list
+   * @param options - Installation options
+   */ async installToAgents(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,
@@ -1556,15 +2225,18 @@ 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);
         }
+        // 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,
@@ -1576,17 +2248,30 @@ class SkillManager {
             results
         };
     }
-    async getDefaultTargetAgents() {
+    /**
+   * 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);
@@ -1596,10 +2281,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,
@@ -1607,14 +2296,18 @@ 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;
     }
 }
-const SUBCOMMANDS = [
+/**
+ * All available subcommands for reskill
+ */ const SUBCOMMANDS = [
     {
         name: 'install',
         description: 'Install a skill or all skills from skills.json'
@@ -1648,15 +2341,21 @@ const SUBCOMMANDS = [
         description: 'Setup shell completion'
     }
 ];
-const SKILL_COMPLETION_COMMANDS = [
+/**
+ * Commands that need skill name completion
+ */ const SKILL_COMPLETION_COMMANDS = [
     'info',
     'uninstall',
     'update'
 ];
-function getAgentNames() {
+/**
+ * Get all agent type names for completion
+ */ function getAgentNames() {
     return Object.keys(agents);
 }
-function getInstalledSkillNames() {
+/**
+ * Get installed skill names for completion
+ */ function getInstalledSkillNames() {
     try {
         const skillManager = new SkillManager();
         const skills = skillManager.list();
@@ -1665,12 +2364,23 @@ function getInstalledSkillNames() {
         return [];
     }
 }
-function handleCompletion() {
+/**
+ * Handle tab completion
+ *
+ * This function is called when the shell requests completion.
+ * It parses the current command line and returns appropriate completions.
+ */ function handleCompletion() {
     const env = __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].parseEnv(process.env);
+    // Not in completion mode
     if (!env.complete) return;
     const { prev, line } = env;
+    // Parse the command line to understand context
     const parts = line.trim().split(/\s+/);
-    const command = parts[1];
+    const command = parts[1]; // First word after 'reskill'
+    // Completing the subcommand (reskill <TAB>)
+    // Only show subcommands if:
+    // 1. Only 'reskill' is typed (parts.length === 1)
+    // 2. Or typing the subcommand (parts.length === 2 and not ending with space)
     if (1 === parts.length || 2 === parts.length && !line.endsWith(' ')) {
         const completions = SUBCOMMANDS.map((c)=>({
                 name: c.name,
@@ -1679,12 +2389,18 @@ function handleCompletion() {
         __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].log(completions);
         return;
     }
+    // Completing skill name for info/uninstall commands (only accept ONE skill argument)
+    // Only complete if we're at the first argument position (words === 2 means completing 2nd word)
     if (SKILL_COMPLETION_COMMANDS.includes(command)) {
+        // parts: ['reskill', 'info', ...args]
+        // If already has a skill argument, don't complete more
         if (parts.length > 2 && line.endsWith(' ')) {
+            // Already have an argument and user pressed space, no more completions
             __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].log([]);
             return;
         }
         if (parts.length > 3) {
+            // Already have more than one argument
             __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].log([]);
             return;
         }
@@ -1692,13 +2408,18 @@ function handleCompletion() {
         __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].log(skills);
         return;
     }
+    // Completing agent names for install -a/--agent
     if ('install' === command && ('-a' === prev || '--agent' === prev)) {
         const agentNames = getAgentNames();
         __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].log(agentNames);
         return;
     }
+    // Completing options for install command
+    // Only show options when user is typing an option (starts with -)
+    // Don't auto-complete '-' when user just typed 'install '
     if ('install' === command) {
         const { last } = env;
+        // Only complete if user has started typing an option (e.g., '-' or '--')
         if (last.startsWith('-')) {
             const options = [
                 {
@@ -1741,18 +2462,25 @@ function handleCompletion() {
             __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].log(options);
             return;
         }
+        // After 'install ' with no input, don't suggest anything
+        // (user might want to type a skill reference)
         __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].log([]);
         return;
     }
+    // Default: no completions
     __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].log([]);
 }
-const completionCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('completion').description('Setup shell completion for reskill').argument('[action]', 'Action: install, uninstall, or shell name (bash, zsh, fish)').action(async (action)=>{
+/**
+ * completion command - Setup shell completion
+ */ const completionCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('completion').description('Setup shell completion for reskill').argument('[action]', 'Action: install, uninstall, or shell name (bash, zsh, fish)').action(async (action)=>{
+    // Check if we're being called for completion
     const env = __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].parseEnv(process.env);
     if (env.complete) {
         handleCompletion();
         return;
     }
     if (!action) {
+        // Show help
         logger_logger.log('Shell completion for reskill');
         logger_logger.newline();
         logger_logger.log('Usage:');
@@ -1792,11 +2520,16 @@ const completionCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('com
         }
         return;
     }
+    // Unknown action
     logger_logger.error(`Unknown action: ${action}`);
     logger_logger.log('Use "reskill completion install" or "reskill completion uninstall"');
     process.exit(1);
 });
-function maybeHandleCompletion() {
+/**
+ * Check if completion is being requested and handle it
+ *
+ * This should be called at the start of CLI execution
+ */ function maybeHandleCompletion() {
     const env = __WEBPACK_EXTERNAL_MODULE_tabtab__["default"].parseEnv(process.env);
     if (env.complete) {
         handleCompletion();
@@ -1804,7 +2537,9 @@ function maybeHandleCompletion() {
     }
     return false;
 }
-function getStatusIcon(status) {
+/**
+ * Get status icon
+ */ function getStatusIcon(status) {
     switch(status){
         case 'ok':
             return __WEBPACK_EXTERNAL_MODULE_chalk__["default"].green('✓');
@@ -1814,7 +2549,13 @@ function getStatusIcon(status) {
             return __WEBPACK_EXTERNAL_MODULE_chalk__["default"].red('✗');
     }
 }
-function execCommand(command) {
+/**
+ * Execute command and return output
+ *
+ * @warning This function executes arbitrary shell commands. It is exported for
+ * testing purposes only. Do not use with untrusted input. Internal usage is
+ * limited to hardcoded commands (e.g., 'git --version').
+ */ function execCommand(command) {
     try {
         return (0, __WEBPACK_EXTERNAL_MODULE_node_child_process__.execSync)(command, {
             encoding: 'utf-8',
@@ -1828,7 +2569,9 @@ function execCommand(command) {
         return null;
     }
 }
-function getDirSize(dirPath) {
+/**
+ * Get directory size in bytes
+ */ function getDirSize(dirPath) {
     if (!(0, external_node_fs_.existsSync)(dirPath)) return 0;
     let size = 0;
     try {
@@ -1840,10 +2583,14 @@ function getDirSize(dirPath) {
             if (item.isDirectory()) size += getDirSize(itemPath);
             else if (item.isFile()) size += (0, external_node_fs_.statSync)(itemPath).size;
         }
-    } catch  {}
+    } catch  {
+    // Ignore permission errors
+    }
     return size;
 }
-function formatBytes(bytes) {
+/**
+ * Format bytes to human readable
+ */ function formatBytes(bytes) {
     if (0 === bytes) return '0 B';
     const k = 1024;
     const sizes = [
@@ -1855,10 +2602,13 @@ function formatBytes(bytes) {
     const i = Math.floor(Math.log(bytes) / Math.log(k));
     return `${Number.parseFloat((bytes / k ** i).toFixed(1))} ${sizes[i]}`;
 }
-function countCachedSkills(cacheDir) {
+/**
+ * Count cached skills
+ */ function countCachedSkills(cacheDir) {
     if (!(0, external_node_fs_.existsSync)(cacheDir)) return 0;
     let count = 0;
     try {
+        // Cache structure: ~/.reskill-cache/<registry>/<owner>/<repo>/<version>/
         const registries = (0, external_node_fs_.readdirSync)(cacheDir, {
             withFileTypes: true
         });
@@ -1884,10 +2634,14 @@ function countCachedSkills(cacheDir) {
                 }
             }
         }
-    } catch  {}
+    } catch  {
+    // Ignore errors
+    }
     return count;
 }
-async function checkReskillVersion(currentVersion, packageName) {
+/**
+ * Check reskill version
+ */ async function checkReskillVersion(currentVersion, packageName) {
     try {
         const result = await checkForUpdate(packageName, currentVersion);
         if (result?.hasUpdate) return {
@@ -1909,7 +2663,9 @@ async function checkReskillVersion(currentVersion, packageName) {
         };
     }
 }
-function checkNodeVersion() {
+/**
+ * Check Node.js version
+ */ function checkNodeVersion() {
     const version = process.version;
     const major = Number.parseInt(version.slice(1).split('.')[0], 10);
     const required = 18;
@@ -1925,7 +2681,9 @@ function checkNodeVersion() {
         message: `${version} (>=${required}.0.0 required)`
     };
 }
-function checkGitVersion() {
+/**
+ * Check Git version
+ */ function checkGitVersion() {
     const version = execCommand('git --version');
     if (!version) return {
         name: 'Git',
@@ -1933,6 +2691,7 @@ function checkGitVersion() {
         message: 'not found',
         hint: 'Please install Git: https://git-scm.com/downloads'
     };
+    // Extract version number from "git version X.Y.Z"
     const match = version.match(/git version (\d+\.\d+\.\d+)/);
     const versionNum = match ? match[1] : version;
     return {
@@ -1941,9 +2700,12 @@ function checkGitVersion() {
         message: versionNum
     };
 }
-function checkGitAuth() {
+/**
+ * Check Git authentication
+ */ function checkGitAuth() {
     const home = (0, __WEBPACK_EXTERNAL_MODULE_node_os__.homedir)();
     const sshDir = (0, __WEBPACK_EXTERNAL_MODULE_node_path__.join)(home, '.ssh');
+    // Check for SSH keys
     const sshKeyFiles = [
         'id_rsa',
         'id_ed25519',
@@ -1957,6 +2719,7 @@ function checkGitAuth() {
             break;
         }
     }
+    // Check for git credential helper
     const credentialHelper = execCommand('git config --global credential.helper');
     const hasCredentialHelper = !!credentialHelper;
     if (hasSSHKey && hasCredentialHelper) return {
@@ -1981,7 +2744,9 @@ function checkGitAuth() {
         hint: 'For private repos, add SSH key: ssh-keygen -t ed25519'
     };
 }
-function checkCacheDir() {
+/**
+ * Check cache directory
+ */ function checkCacheDir() {
     const cacheDir = process.env.RESKILL_CACHE_DIR || (0, __WEBPACK_EXTERNAL_MODULE_node_path__.join)((0, __WEBPACK_EXTERNAL_MODULE_node_os__.homedir)(), '.reskill-cache');
     if (!(0, external_node_fs_.existsSync)(cacheDir)) return {
         name: 'Cache directory',
@@ -1996,7 +2761,9 @@ function checkCacheDir() {
         message: `${cacheDir} (${formatBytes(size)}, ${count} skill${1 !== count ? 's' : ''} cached)`
     };
 }
-function checkSkillsJson(cwd) {
+/**
+ * Check skills.json
+ */ function checkSkillsJson(cwd) {
     const configLoader = new ConfigLoader(cwd);
     if (!configLoader.exists()) return {
         name: 'skills.json',
@@ -2021,11 +2788,15 @@ function checkSkillsJson(cwd) {
         };
     }
 }
-const RESERVED_REGISTRIES = [
+/**
+ * Reserved registry names that should not be overridden
+ */ const RESERVED_REGISTRIES = [
     'github',
     'gitlab'
 ];
-const DANGEROUS_INSTALL_DIRS = [
+/**
+ * Dangerous paths that should not be used as installDir
+ */ const DANGEROUS_INSTALL_DIRS = [
     'src',
     'lib',
     'dist',
@@ -2038,7 +2809,9 @@ const DANGEROUS_INSTALL_DIRS = [
     '.vscode',
     '.idea'
 ];
-const DANGEROUS_SKILL_NAMES = [
+/**
+ * Dangerous skill name patterns
+ */ const DANGEROUS_SKILL_NAMES = [
     '.git',
     '..',
     '.',
@@ -2046,9 +2819,16 @@ const DANGEROUS_SKILL_NAMES = [
     '__proto__',
     'constructor'
 ];
-const NETWORK_CHECK_TIMEOUT_MS = 5000;
-const CHECK_NAME_PAD_WIDTH = 26;
-function checkRegistryConflicts(cwd) {
+/**
+ * Network connectivity check timeout in milliseconds
+ */ const NETWORK_CHECK_TIMEOUT_MS = 5000;
+/**
+ * Padding width for check result names in output.
+ * Accounts for nested items with "  └─ " prefix (5 chars).
+ */ const CHECK_NAME_PAD_WIDTH = 26;
+/**
+ * Check for registry name conflicts
+ */ function checkRegistryConflicts(cwd) {
     const results = [];
     const configLoader = new ConfigLoader(cwd);
     if (!configLoader.exists()) return results;
@@ -2061,16 +2841,21 @@ function checkRegistryConflicts(cwd) {
             message: `"${name}" overrides built-in registry`,
             hint: 'Consider using a different name for custom registries'
         });
-    } catch  {}
+    } catch  {
+    // Ignore parse errors, handled by checkSkillsJson
+    }
     return results;
 }
-function checkInstallDir(cwd) {
+/**
+ * Check for dangerous installDir configuration
+ */ function checkInstallDir(cwd) {
     const configLoader = new ConfigLoader(cwd);
     if (!configLoader.exists()) return null;
     try {
         const defaults = configLoader.getDefaults();
         const installDir = defaults.installDir;
         if (!installDir) return null;
+        // Check for dangerous paths
         const normalizedDir = installDir.replace(/^\.\//, '').replace(/\/$/, '');
         if (DANGEROUS_INSTALL_DIRS.includes(normalizedDir.toLowerCase())) return {
             name: 'Dangerous installDir',
@@ -2078,16 +2863,21 @@ function checkInstallDir(cwd) {
             message: `"${installDir}" may conflict with important directories`,
             hint: 'Use a dedicated directory like ".skills" or ".agents/skills"'
         };
+        // Check for path traversal
         if (installDir.includes('..')) return {
             name: 'Dangerous installDir',
             status: 'error',
             message: `"${installDir}" contains path traversal`,
             hint: 'Use a simple directory name without ".."'
         };
-    } catch  {}
+    } catch  {
+    // Ignore parse errors
+    }
     return null;
 }
-function checkTargetAgents(cwd) {
+/**
+ * Check for invalid targetAgents configuration
+ */ function checkTargetAgents(cwd) {
     const results = [];
     const configLoader = new ConfigLoader(cwd);
     if (!configLoader.exists()) return results;
@@ -2100,10 +2890,14 @@ function checkTargetAgents(cwd) {
             message: `Unknown agent type: "${agent}"`,
             hint: 'Run: reskill install --help to see valid agent types'
         });
-    } catch  {}
+    } catch  {
+    // Ignore parse errors
+    }
     return results;
 }
-function checkSkillRefs(cwd) {
+/**
+ * Check for skill reference format errors
+ */ function checkSkillRefs(cwd) {
     const results = [];
     const configLoader = new ConfigLoader(cwd);
     if (!configLoader.exists()) return results;
@@ -2111,6 +2905,7 @@ function checkSkillRefs(cwd) {
         const skills = configLoader.getSkills();
         const resolver = new GitResolver();
         for (const [name, ref] of Object.entries(skills)){
+            // Check for dangerous skill names
             if (DANGEROUS_SKILL_NAMES.includes(name) || name.includes('/') || name.includes('\\')) {
                 results.push({
                     name: 'Dangerous skill name',
@@ -2120,6 +2915,7 @@ function checkSkillRefs(cwd) {
                 });
                 continue;
             }
+            // Try to parse the reference
             try {
                 resolver.parseRef(ref);
             } catch (error) {
@@ -2131,10 +2927,14 @@ function checkSkillRefs(cwd) {
                 });
             }
         }
-    } catch  {}
+    } catch  {
+    // Ignore parse errors
+    }
     return results;
 }
-function checkMonorepoVersions(cwd) {
+/**
+ * Check for version conflicts in monorepo skills
+ */ function checkMonorepoVersions(cwd) {
     const results = [];
     const configLoader = new ConfigLoader(cwd);
     if (!configLoader.exists()) return results;
@@ -2144,6 +2944,7 @@ function checkMonorepoVersions(cwd) {
         const repoVersions = new Map();
         for (const [name, ref] of Object.entries(skills))try {
             const parsed = resolver.parseRef(ref);
+            // Only check skills with subPath (monorepo)
             if (!parsed.subPath) continue;
             const repoKey = `${parsed.registry}:${parsed.owner}/${parsed.repo}`;
             const version = parsed.version || 'default';
@@ -2158,7 +2959,10 @@ function checkMonorepoVersions(cwd) {
                 versions.set(version, skillList);
             }
             skillList.push(name);
-        } catch  {}
+        } catch  {
+        // Skip invalid refs, handled by checkSkillRefs
+        }
+        // Check for multiple versions from same repo
         for (const [repo, versions] of repoVersions)if (versions.size > 1) {
             const versionList = [
                 ...versions.entries()
@@ -2170,10 +2974,14 @@ function checkMonorepoVersions(cwd) {
                 hint: 'Consider using the same version for all skills from this repo'
             });
         }
-    } catch  {}
+    } catch  {
+    // Ignore parse errors
+    }
     return results;
 }
-function checkSkillsLock(cwd) {
+/**
+ * Check skills.lock sync status
+ */ function checkSkillsLock(cwd) {
     const configLoader = new ConfigLoader(cwd);
     const lockManager = new LockManager(cwd);
     if (!configLoader.exists()) return {
@@ -2195,6 +3003,7 @@ function checkSkillsLock(cwd) {
             hint: 'Run: reskill install'
         };
     }
+    // Check if lock is in sync with config
     const configSkills = configLoader.getSkills();
     const lockedSkills = lockManager.getAll();
     const configNames = new Set(Object.keys(configSkills));
@@ -2229,20 +3038,25 @@ function checkSkillsLock(cwd) {
         message: `in sync (${lockedNames.size} skill${1 !== lockedNames.size ? 's' : ''} locked)`
     };
 }
-function isValidSymlink(path) {
+/**
+ * Check if a file is a valid symlink
+ */ function isValidSymlink(path) {
     try {
         const stat = (0, external_node_fs_.lstatSync)(path);
-        if (!stat.isSymbolicLink()) return true;
+        if (!stat.isSymbolicLink()) return true; // Not a symlink, so not a broken symlink
+        // Try to resolve the symlink target
         (0, external_node_fs_.realpathSync)(path);
         return true;
     } catch  {
         return false;
     }
 }
-function validateSkillJson(skillJsonPath) {
+/**
+ * Check if skill.json is valid JSON with required fields
+ */ function validateSkillJson(skillJsonPath) {
     if (!(0, external_node_fs_.existsSync)(skillJsonPath)) return {
         valid: true
-    };
+    }; // Not present is OK if SKILL.md exists
     try {
         const content = (0, external_node_fs_.readFileSync)(skillJsonPath, 'utf-8');
         const json = JSON.parse(content);
@@ -2264,7 +3078,9 @@ function validateSkillJson(skillJsonPath) {
         };
     }
 }
-function checkInstalledSkills(cwd) {
+/**
+ * Check installed skills with detailed diagnostics
+ */ function checkInstalledSkills(cwd) {
     const results = [];
     const skillManager = new SkillManager(cwd);
     const installed = skillManager.list();
@@ -2275,10 +3091,12 @@ function checkInstalledSkills(cwd) {
             message: 'none'
         }
     ];
+    // Check each installed skill for issues
     const issues = [];
     for (const skill of installed){
         const skillJsonPath = (0, __WEBPACK_EXTERNAL_MODULE_node_path__.join)(skill.path, 'skill.json');
         const skillMdPath = (0, __WEBPACK_EXTERNAL_MODULE_node_path__.join)(skill.path, 'SKILL.md');
+        // Check for broken symlink
         if (skill.isLinked && !isValidSymlink(skill.path)) {
             issues.push({
                 name: skill.name,
@@ -2287,6 +3105,7 @@ function checkInstalledSkills(cwd) {
             });
             continue;
         }
+        // Check for missing both files
         const hasSkillJson = (0, external_node_fs_.existsSync)(skillJsonPath);
         const hasSkillMd = (0, external_node_fs_.existsSync)(skillMdPath);
         if (!hasSkillJson && !hasSkillMd) {
@@ -2297,6 +3116,7 @@ function checkInstalledSkills(cwd) {
             });
             continue;
         }
+        // Validate skill.json if present
         if (hasSkillJson) {
             const validation = validateSkillJson(skillJsonPath);
             if (!validation.valid) issues.push({
@@ -2306,6 +3126,7 @@ function checkInstalledSkills(cwd) {
             });
         }
     }
+    // Build summary result
     const errorCount = issues.filter((i)=>'error' === i.severity).length;
     const warnCount = issues.filter((i)=>'warn' === i.severity).length;
     if (0 === issues.length) results.push({
@@ -2322,6 +3143,7 @@ function checkInstalledSkills(cwd) {
             message: `${installed.length} installed, ${issueText}`,
             hint: 'Run: reskill install --force to fix'
         });
+        // Add detailed issues
         for (const issue of issues)results.push({
             name: `  └─ ${issue.name}`,
             status: 'error' === issue.severity ? 'error' : 'warn',
@@ -2330,7 +3152,9 @@ function checkInstalledSkills(cwd) {
     }
     return results;
 }
-async function checkNetwork(host) {
+/**
+ * Check network connectivity
+ */ async function checkNetwork(host) {
     const displayName = host.replace('https://', '').replace('http://', '');
     try {
         const controller = new AbortController();
@@ -2360,40 +3184,57 @@ async function checkNetwork(host) {
         };
     }
 }
-function printResult(result) {
+/**
+ * Print check result
+ */ function printResult(result) {
     const icon = getStatusIcon(result.status);
     const name = result.name.padEnd(CHECK_NAME_PAD_WIDTH);
     const message = 'ok' === result.status ? result.message : __WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim(result.message);
     logger_logger.log(`${icon} ${name} ${message}`);
     if (result.hint) logger_logger.log(`  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('→')} ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim(result.hint)}`);
 }
-async function runDoctorChecks(options) {
+/**
+ * Run all checks
+ */ async function runDoctorChecks(options) {
     const { cwd, packageName, packageVersion, skipNetwork, skipConfigChecks } = options;
     const results = [];
+    // Version checks
     results.push(await checkReskillVersion(packageVersion, packageName));
     results.push(checkNodeVersion());
     results.push(checkGitVersion());
     results.push(checkGitAuth());
+    // Directory checks
     results.push(checkCacheDir());
     results.push(checkSkillsJson(cwd));
     results.push(checkSkillsLock(cwd));
     results.push(...checkInstalledSkills(cwd));
+    // Deep config checks (can be skipped for faster checks)
     if (!skipConfigChecks) {
+        // Registry conflicts
         results.push(...checkRegistryConflicts(cwd));
+        // installDir validation
         const installDirCheck = checkInstallDir(cwd);
         if (installDirCheck) results.push(installDirCheck);
+        // targetAgents validation
         results.push(...checkTargetAgents(cwd));
+        // Skill reference format validation
         results.push(...checkSkillRefs(cwd));
+        // Monorepo version consistency
         results.push(...checkMonorepoVersions(cwd));
     }
+    // Network checks
     if (!skipNetwork) {
         results.push(await checkNetwork('https://github.com'));
         results.push(await checkNetwork('https://gitlab.com'));
     }
     return results;
 }
-const doctorCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('doctor').description('Diagnose reskill environment and check for issues').option('--json', 'Output as JSON').option('--skip-network', 'Skip network connectivity checks').action(async (options)=>{
+/**
+ * doctor command - Diagnose reskill environment
+ */ const doctorCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('doctor').description('Diagnose reskill environment and check for issues').option('--json', 'Output as JSON').option('--skip-network', 'Skip network connectivity checks').action(async (options)=>{
+    // Get package info
     const __dirname = (0, __WEBPACK_EXTERNAL_MODULE_node_path__.dirname)((0, __WEBPACK_EXTERNAL_MODULE_node_url__.fileURLToPath)(import.meta.url));
+    // In bundled output, __dirname is dist/cli/, so ../../package.json
     const packageJson = JSON.parse((0, external_node_fs_.readFileSync)((0, __WEBPACK_EXTERNAL_MODULE_node_path__.join)(__dirname, '../../package.json'), 'utf-8'));
     if (!options.json) logger_logger.log(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].bold('\n🩺 Checking reskill environment...\n'));
     const results = await runDoctorChecks({
@@ -2406,7 +3247,9 @@ const doctorCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('doctor'
         console.log(JSON.stringify(results, null, 2));
         return;
     }
+    // Print results
     for (const result of results)printResult(result);
+    // Summary
     const errors = results.filter((r)=>'error' === r.status).length;
     const warnings = results.filter((r)=>'warn' === r.status).length;
     logger_logger.newline();
@@ -2417,7 +3260,9 @@ const doctorCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('doctor'
     if (warnings > 0) logger_logger.warn(`Found ${warnings} warning${1 !== warnings ? 's' : ''}, but reskill should work`);
     else logger_logger.success('All checks passed! reskill is ready to use.');
 });
-const infoCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('info').description('Show skill details').argument('<skill>', 'Skill name').option('-j, --json', 'Output as JSON').action((skillName, options)=>{
+/**
+ * info command - Show skill details
+ */ const infoCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('info').description('Show skill details').argument('<skill>', 'Skill name').option('-j, --json', 'Output as JSON').action((skillName, options)=>{
     const skillManager = new SkillManager();
     const info = skillManager.getInfo(skillName);
     if (options.json) {
@@ -2456,8 +3301,16 @@ const infoCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('info').de
         }
     } else logger_logger.warn(`Skill ${skillName} is not installed`);
 });
+// ============================================================================
+// Constants
+// ============================================================================
 const DEFAULT_INSTALL_DIR = '.skills';
-function displayConfigSummary(installDir) {
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Display configuration summary after initialization
+ */ function displayConfigSummary(installDir) {
     logger_logger.success('Created skills.json');
     logger_logger.newline();
     logger_logger.log('Configuration:');
@@ -2467,38 +3320,74 @@ function displayConfigSummary(installDir) {
     logger_logger.log('  reskill install <skill>  Install a skill');
     logger_logger.log('  reskill list             List installed skills');
 }
-const initCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('init').description('Initialize a new skills.json configuration').option('-d, --install-dir <dir>', 'Skills installation directory', DEFAULT_INSTALL_DIR).option('-y, --yes', 'Skip prompts and use defaults').action((options)=>{
+// ============================================================================
+// Command Definition
+// ============================================================================
+/**
+ * init command - Initialize skills.json configuration
+ *
+ * Creates a new skills.json file in the current directory with default settings.
+ * Will not overwrite an existing skills.json file.
+ *
+ * @example
+ * ```bash
+ * # Initialize with defaults
+ * reskill init
+ *
+ * # Initialize with custom install directory
+ * reskill init -d my-skills
+ *
+ * # Skip prompts (for CI/scripts)
+ * reskill init -y
+ * ```
+ */ const initCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('init').description('Initialize a new skills.json configuration').option('-d, --install-dir <dir>', 'Skills installation directory', DEFAULT_INSTALL_DIR).option('-y, --yes', 'Skip prompts and use defaults').action((options)=>{
     const configLoader = new ConfigLoader();
+    // Check if configuration already exists
     if (configLoader.exists()) {
         logger_logger.warn('skills.json already exists');
         return;
     }
+    // Create new configuration
     configLoader.create({
         defaults: {
             installDir: options.installDir
         }
     });
+    // Display summary (use options.installDir directly since we just set it)
     displayConfigSummary(options.installDir);
 });
-function formatAgentNames(agentTypes, maxShow = 5) {
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Format agent names list for display
+ * Truncates long lists with "+N more" suffix
+ */ function formatAgentNames(agentTypes, maxShow = 5) {
     const names = agentTypes.map((a)=>agents[a].displayName);
     if (names.length <= maxShow) return names.join(', ');
     const shown = names.slice(0, maxShow);
     const remaining = names.length - maxShow;
     return `${shown.join(', ')} +${remaining} more`;
 }
-function formatColoredAgentNames(agentTypes) {
+/**
+ * Format agent names with chalk coloring
+ */ function formatColoredAgentNames(agentTypes) {
     return agentTypes.map((a)=>__WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan(agents[a].displayName)).join(', ');
 }
-function filterValidAgents(storedAgents, validAgents) {
+/**
+ * Filter valid agent types from stored configuration
+ */ function filterValidAgents(storedAgents, validAgents) {
     if (!storedAgents || 0 === storedAgents.length) return;
     const filtered = storedAgents.filter((a)=>validAgents.includes(a));
     return filtered.length > 0 ? filtered : void 0;
 }
-function createInstallContext(skills, options) {
+/**
+ * Create install context from command arguments and options
+ */ function createInstallContext(skills, options) {
     const configLoader = new ConfigLoader();
     const allAgentTypes = Object.keys(agents);
     const hasSkillsJson = configLoader.exists();
+    // Load stored defaults from skills.json
     const storedDefaults = hasSkillsJson ? configLoader.getDefaults() : null;
     const storedAgents = filterValidAgents(storedDefaults?.targetAgents, allAgentTypes);
     const storedMode = storedDefaults?.installMode;
@@ -2516,20 +3405,31 @@ function createInstallContext(skills, options) {
         skipConfirm: options.yes ?? false
     };
 }
-async function resolveTargetAgents(ctx, spinner) {
+// ============================================================================
+// Agent Selection Logic
+// ============================================================================
+/**
+ * Resolve target agents based on options and context
+ */ async function resolveTargetAgents(ctx, spinner) {
     const { options, allAgentTypes, storedAgents, hasStoredAgents, isReinstallAll } = ctx;
+    // Priority 1: --all flag
     if (options.all) {
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.info(`Installing to all ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan(allAgentTypes.length)} agents`);
         return allAgentTypes;
     }
+    // Priority 2: -a/--agent flag
     if (options.agent && options.agent.length > 0) return resolveAgentsFromCLI(options.agent, allAgentTypes);
+    // Priority 3: Reinstall all with stored agents
     if (isReinstallAll && hasStoredAgents && storedAgents) {
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.info(`Using saved agents: ${formatColoredAgentNames(storedAgents)}`);
         return storedAgents;
     }
+    // Priority 4: Auto-detect and/or prompt
     return await detectAndPromptAgents(ctx, spinner);
 }
-function resolveAgentsFromCLI(agentArgs, validAgents) {
+/**
+ * Resolve agents from CLI -a option
+ */ function resolveAgentsFromCLI(agentArgs, validAgents) {
     const invalidAgents = agentArgs.filter((a)=>!validAgents.includes(a));
     if (invalidAgents.length > 0) {
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.error(`Invalid agents: ${invalidAgents.join(', ')}`);
@@ -2540,11 +3440,14 @@ function resolveAgentsFromCLI(agentArgs, validAgents) {
     __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.info(`Installing to: ${formatAgentNames(targetAgents)}`);
     return targetAgents;
 }
-async function detectAndPromptAgents(ctx, spinner) {
+/**
+ * Auto-detect agents and optionally prompt user
+ */ async function detectAndPromptAgents(ctx, spinner) {
     const { allAgentTypes, storedAgents, hasStoredAgents, skipConfirm } = ctx;
     spinner.start('Detecting installed agents...');
     const installedAgents = await detectInstalledAgents();
     spinner.stop(`Detected ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green(installedAgents.length)} agent${1 !== installedAgents.length ? 's' : ''}`);
+    // No agents detected
     if (0 === installedAgents.length) {
         if (skipConfirm) {
             __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.info('Installing to all agents (none detected)');
@@ -2552,15 +3455,19 @@ async function detectAndPromptAgents(ctx, spinner) {
         }
         return await promptAgentSelection(allAgentTypes, hasStoredAgents ? storedAgents : allAgentTypes);
     }
+    // Single agent or skip confirmation
     if (1 === installedAgents.length || skipConfirm) {
         const displayNames = formatColoredAgentNames(installedAgents);
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.info(`Installing to: ${displayNames}`);
         return installedAgents;
     }
+    // Multiple agents: let user select
     const initialAgents = hasStoredAgents ? storedAgents : installedAgents;
     return await promptAgentSelection(installedAgents, initialAgents, true);
 }
-async function promptAgentSelection(availableAgents, initialValues, showHint = false) {
+/**
+ * Prompt user to select agents
+ */ async function promptAgentSelection(availableAgents, initialValues, showHint = false) {
     if (0 === availableAgents.length) __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.warn('No coding agents detected. You can still install skills.');
     const agentChoices = availableAgents.map((a)=>({
             value: a,
@@ -2584,11 +3491,20 @@ async function promptAgentSelection(availableAgents, initialValues, showHint = f
     }
     return selected;
 }
-async function resolveInstallScope(ctx) {
+// ============================================================================
+// Installation Scope Logic
+// ============================================================================
+/**
+ * Resolve installation scope (global vs project)
+ */ async function resolveInstallScope(ctx) {
     const { options, isReinstallAll, skipConfirm } = ctx;
+    // Explicit --global flag
     if (void 0 !== options.global) return options.global;
+    // Skip prompt for reinstall-all (always project scope)
     if (isReinstallAll) return false;
+    // Skip prompt if --yes
     if (skipConfirm) return false;
+    // Prompt user
     const scope = await __WEBPACK_EXTERNAL_MODULE__clack_prompts__.select({
         message: 'Installation scope',
         options: [
@@ -2610,14 +3526,23 @@ async function resolveInstallScope(ctx) {
     }
     return scope;
 }
-async function resolveInstallMode(ctx) {
+// ============================================================================
+// Installation Mode Logic
+// ============================================================================
+/**
+ * Resolve installation mode (symlink vs copy)
+ */ async function resolveInstallMode(ctx) {
     const { options, storedMode, isReinstallAll, skipConfirm } = ctx;
+    // Priority 1: CLI --mode option
     if (options.mode) return options.mode;
+    // Priority 2: Reinstall all with stored mode
     if (isReinstallAll && storedMode) {
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.info(`Using saved install mode: ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan(storedMode)}`);
         return storedMode;
     }
+    // Priority 3: Skip confirmation
     if (skipConfirm) return storedMode ?? 'symlink';
+    // Priority 4: Prompt user
     const modeChoice = await __WEBPACK_EXTERNAL_MODULE__clack_prompts__.select({
         message: 'Installation method',
         initialValue: storedMode ?? 'symlink',
@@ -2640,7 +3565,12 @@ async function resolveInstallMode(ctx) {
     }
     return modeChoice;
 }
-async function installAllSkills(ctx, targetAgents, installMode, spinner) {
+// ============================================================================
+// Installation Execution
+// ============================================================================
+/**
+ * Install all skills from skills.json
+ */ async function installAllSkills(ctx, targetAgents, installMode, spinner) {
     const { configLoader, options } = ctx;
     if (!configLoader.exists()) {
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.error("skills.json not found. Run 'reskill init' first.");
@@ -2652,12 +3582,14 @@ async function installAllSkills(ctx, targetAgents, installMode, spinner) {
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.outro('Done');
         return;
     }
+    // Show installation summary
     displayInstallSummary({
         skillCount: Object.keys(skills).length,
         agentCount: targetAgents.length,
         scope: 'Project (./) ',
         mode: installMode
     });
+    // Execute installation (no confirmation for reinstall all)
     spinner.start('Installing skills...');
     const skillManager = new SkillManager(void 0, {
         global: false
@@ -2678,22 +3610,28 @@ async function installAllSkills(ctx, targetAgents, installMode, spinner) {
         totalFailed += targetAgents.length;
     }
     spinner.stop('Installation complete');
+    // Show results
     displayInstallResults(Object.keys(skills).length, targetAgents.length, totalInstalled, totalFailed);
+    // Save installation defaults
     if (totalInstalled > 0) configLoader.updateDefaults({
         targetAgents,
         installMode
     });
 }
-async function installSingleSkill(ctx, targetAgents, installGlobally, installMode, spinner) {
+/**
+ * Install a single skill
+ */ async function installSingleSkill(ctx, targetAgents, installGlobally, installMode, spinner) {
     const { skills, options, configLoader, skipConfirm } = ctx;
     const skill = skills[0];
     const cwd = process.cwd();
+    // Show installation summary
     const summaryLines = [
         __WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan(skill),
         `  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('→')} ${formatAgentNames(targetAgents)}`,
         `  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('Scope:')} ${installGlobally ? 'Global' : 'Project'}${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim(', Mode:')} ${installMode}`
     ];
     __WEBPACK_EXTERNAL_MODULE__clack_prompts__.note(summaryLines.join('\n'), 'Installation Summary');
+    // Confirm installation
     if (!skipConfirm) {
         const confirmed = await __WEBPACK_EXTERNAL_MODULE__clack_prompts__.confirm({
             message: 'Proceed with installation?'
@@ -2703,6 +3641,7 @@ async function installSingleSkill(ctx, targetAgents, installGlobally, installMod
             process.exit(0);
         }
     }
+    // Execute installation
     spinner.start(`Installing ${skill}...`);
     const skillManager = new SkillManager(void 0, {
         global: installGlobally
@@ -2713,19 +3652,24 @@ async function installSingleSkill(ctx, targetAgents, installGlobally, installMod
         mode: installMode
     });
     spinner.stop('Installation complete');
+    // Process and display results
     const successful = Array.from(results.entries()).filter(([, r])=>r.success);
     const failed = Array.from(results.entries()).filter(([, r])=>!r.success);
     displaySingleSkillResults(installed, successful, failed, cwd);
+    // Save installation defaults (only for project installs with success)
     if (!installGlobally && successful.length > 0 && configLoader.exists()) {
-        configLoader.reload();
+        configLoader.reload(); // Sync with SkillManager's changes
         configLoader.updateDefaults({
             targetAgents,
             installMode
         });
     }
 }
-async function installMultipleSkills(ctx, targetAgents, installGlobally, installMode, spinner) {
+/**
+ * Install multiple skills in batch
+ */ async function installMultipleSkills(ctx, targetAgents, installGlobally, installMode, spinner) {
     const { skills, options, configLoader, skipConfirm } = ctx;
+    // Show installation summary
     const summaryLines = [
         `${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan(skills.length)} skills:`,
         ...skills.map((s)=>`  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('•')} ${s}`),
@@ -2734,6 +3678,7 @@ async function installMultipleSkills(ctx, targetAgents, installGlobally, install
         `  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('Scope:')} ${installGlobally ? 'Global' : 'Project'}${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim(', Mode:')} ${installMode}`
     ];
     __WEBPACK_EXTERNAL_MODULE__clack_prompts__.note(summaryLines.join('\n'), 'Installation Summary');
+    // Confirm installation
     if (!skipConfirm) {
         const confirmed = await __WEBPACK_EXTERNAL_MODULE__clack_prompts__.confirm({
             message: 'Proceed with installation?'
@@ -2743,12 +3688,14 @@ async function installMultipleSkills(ctx, targetAgents, installGlobally, install
             process.exit(0);
         }
     }
+    // Execute installation for all skills in parallel
     const skillManager = new SkillManager(void 0, {
         global: installGlobally
     });
     const successfulSkills = [];
     const failedSkills = [];
     spinner.start(`Installing ${skills.length} skills in parallel...`);
+    // Create install promises for all skills
     const installPromises = skills.map(async (skillRef)=>{
         try {
             const { skill: installed, results } = await skillManager.installToAgents(skillRef, targetAgents, {
@@ -2776,8 +3723,10 @@ async function installMultipleSkills(ctx, targetAgents, installGlobally, install
             };
         }
     });
+    // Wait for all installations to complete
     const results = await Promise.all(installPromises);
     spinner.stop(`Processed ${skills.length} skills`);
+    // Aggregate results
     for (const result of results)if (result.success) {
         successfulSkills.push(result.skill);
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.success(`${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green('✓')} ${result.skill.name}@${result.skill.version}`);
@@ -2788,29 +3737,38 @@ async function installMultipleSkills(ctx, targetAgents, installGlobally, install
         });
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.error(`${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].red('✗')} ${result.skillRef}`);
     }
+    // Display batch results
     console.log();
     displayBatchInstallResults(successfulSkills, failedSkills, targetAgents.length);
+    // Save installation defaults (only for project installs with success)
     if (!installGlobally && successfulSkills.length > 0 && configLoader.exists()) {
-        configLoader.reload();
+        configLoader.reload(); // Sync with SkillManager's changes
         configLoader.updateDefaults({
             targetAgents,
             installMode
         });
     }
+    // Exit with error if any skills failed
     if (failedSkills.length > 0) process.exit(1);
 }
-function displayInstallSummary(info) {
+/**
+ * Display installation summary note
+ */ function displayInstallSummary(info) {
     const summaryLines = [
         `${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan(info.skillCount)} skill(s) → ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan(info.agentCount)} agent(s)`,
         `${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('Scope:')} ${info.scope}${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim(', Mode:')} ${info.mode}`
     ];
     __WEBPACK_EXTERNAL_MODULE__clack_prompts__.note(summaryLines.join('\n'), 'Installation Summary');
 }
-function displayInstallResults(skillCount, agentCount, totalInstalled, totalFailed) {
+/**
+ * Display installation results for batch install
+ */ function displayInstallResults(skillCount, agentCount, totalInstalled, totalFailed) {
     if (0 === totalFailed) __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.success(`Installed ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green(skillCount)} skill(s) to ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green(agentCount)} agent(s)`);
     else __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.warn(`Installed ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green(totalInstalled)} successfully, ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].red(totalFailed)} failed`);
 }
-function displayBatchInstallResults(successfulSkills, failedSkills, agentCount) {
+/**
+ * Display results for batch skill installation
+ */ function displayBatchInstallResults(successfulSkills, failedSkills, agentCount) {
     if (successfulSkills.length > 0) {
         const resultLines = successfulSkills.map((s)=>`  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green('✓')} ${s.name}@${s.version}`);
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.note(resultLines.join('\n'), __WEBPACK_EXTERNAL_MODULE_chalk__["default"].green(`Installed ${successfulSkills.length} skill(s) to ${agentCount} agent(s)`));
@@ -2820,7 +3778,9 @@ function displayBatchInstallResults(successfulSkills, failedSkills, agentCount)
         for (const { ref, error } of failedSkills)__WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.message(`  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].red('✗')} ${ref}: ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim(error)}`);
     }
 }
-function displaySingleSkillResults(installed, successful, failed, cwd) {
+/**
+ * Display results for single skill installation
+ */ function displaySingleSkillResults(installed, successful, failed, cwd) {
     if (successful.length > 0) {
         const resultLines = [];
         const firstResult = successful[0][1];
@@ -2828,6 +3788,7 @@ function displaySingleSkillResults(installed, successful, failed, cwd) {
             resultLines.push(`${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green('✓')} ${installed.name}@${installed.version} ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('(copied)')}`);
             for (const [, result] of successful)resultLines.push(`  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('→')} ${shortenPath(result.path, cwd)}`);
         } else {
+            // Symlink mode
             const displayPath = firstResult.canonicalPath ? shortenPath(firstResult.canonicalPath, cwd) : `${installed.name}@${installed.version}`;
             resultLines.push(`${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green('✓')} ${displayPath}`);
             const symlinked = successful.filter(([, r])=>!r.symlinkFailed).map(([a])=>agents[a].displayName);
@@ -2836,6 +3797,7 @@ function displaySingleSkillResults(installed, successful, failed, cwd) {
             if (copied.length > 0) resultLines.push(`  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].yellow('copied →')} ${copied.join(', ')}`);
         }
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.note(resultLines.join('\n'), __WEBPACK_EXTERNAL_MODULE_chalk__["default"].green(`Installed 1 skill to ${successful.length} agent${1 !== successful.length ? 's' : ''}`));
+        // Symlink failure warning
         const symlinkFailed = successful.filter(([, r])=>'symlink' === r.mode && r.symlinkFailed);
         if (symlinkFailed.length > 0) {
             const copiedAgentNames = symlinkFailed.map(([a])=>agents[a].displayName);
@@ -2843,31 +3805,57 @@ function displaySingleSkillResults(installed, successful, failed, cwd) {
             __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.message(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('  Files were copied instead. On Windows, enable Developer Mode for symlink support.'));
         }
     }
+    // Show failure message
     if (failed.length > 0) {
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.error(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].red(`Failed to install to ${failed.length} agent(s)`));
         for (const [agent, result] of failed)__WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.message(`  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].red('✗')} ${agents[agent].displayName}: ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim(result.error)}`);
     }
 }
-const installCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('install').alias('i').description('Install one or more skills, or all skills from skills.json').argument('[skills...]', 'Skill references (e.g., github:user/skill@v1.0.0 or git@github.com:user/repo.git)').option('-f, --force', 'Force reinstall even if already installed').option('-g, --global', 'Install globally to user home directory').option('--no-save', 'Do not save to skills.json').option('-a, --agent <agents...>', 'Specify target agents (e.g., cursor, claude-code)').option('--mode <mode>', 'Installation mode: symlink or copy').option('-y, --yes', 'Skip confirmation prompts').option('--all', 'Install to all agents (implies -y -g)').action(async (skills, options)=>{
+// ============================================================================
+// Command Definition
+// ============================================================================
+/**
+ * install command - Install a skill or all skills from skills.json
+ *
+ * Installation Flow:
+ * 1. Resolve target agents (CLI > stored > detected > prompt)
+ * 2. Resolve installation scope (global vs project)
+ * 3. Resolve installation mode (symlink vs copy)
+ * 4. Execute installation
+ * 5. Save defaults for future installs
+ *
+ * Behavior:
+ * - Single skill install: Prompts for agents/mode (stored config as defaults)
+ * - Reinstall all (no args): Uses stored config directly, no confirmation
+ */ const installCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('install').alias('i').description('Install one or more skills, or all skills from skills.json').argument('[skills...]', 'Skill references (e.g., github:user/skill@v1.0.0 or git@github.com:user/repo.git)').option('-f, --force', 'Force reinstall even if already installed').option('-g, --global', 'Install globally to user home directory').option('--no-save', 'Do not save to skills.json').option('-a, --agent <agents...>', 'Specify target agents (e.g., cursor, claude-code)').option('--mode <mode>', 'Installation mode: symlink or copy').option('-y, --yes', 'Skip confirmation prompts').option('--all', 'Install to all agents (implies -y -g)').action(async (skills, options)=>{
+    // Handle --all flag implications
     if (options.all) {
         options.yes = true;
         options.global = true;
     }
+    // Create execution context
     const ctx = createInstallContext(skills, options);
+    // Print banner
     console.log();
     __WEBPACK_EXTERNAL_MODULE__clack_prompts__.intro(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].bgCyan.black(' reskill '));
     try {
         const spinner = __WEBPACK_EXTERNAL_MODULE__clack_prompts__.spinner();
+        // Step 1: Resolve target agents
         const targetAgents = await resolveTargetAgents(ctx, spinner);
+        // Step 2: Resolve installation scope
         const installGlobally = await resolveInstallScope(ctx);
+        // Validate: Cannot install all skills globally
         if (ctx.isReinstallAll && installGlobally) {
             __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.error('Cannot install all skills globally. Please specify a skill to install.');
             process.exit(1);
         }
+        // Step 3: Resolve installation mode
         const installMode = await resolveInstallMode(ctx);
+        // Step 4: Execute installation
         if (ctx.isReinstallAll) await installAllSkills(ctx, targetAgents, installMode, spinner);
         else if (ctx.isBatchInstall) await installMultipleSkills(ctx, targetAgents, installGlobally, installMode, spinner);
         else await installSingleSkill(ctx, targetAgents, installGlobally, installMode, spinner);
+        // Done
         console.log();
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.outro(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green('Done!'));
     } catch (error) {
@@ -2876,7 +3864,9 @@ const installCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('instal
         process.exit(1);
     }
 });
-const listCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('list').alias('ls').description('List installed skills').option('-j, --json', 'Output as JSON').option('-g, --global', 'List globally installed skills').action((options)=>{
+/**
+ * list command - List installed skills
+ */ const listCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('list').alias('ls').description('List installed skills').option('-j, --json', 'Output as JSON').option('-g, --global', 'List globally installed skills').action((options)=>{
     const isGlobal = options.global || false;
     const skillManager = new SkillManager(void 0, {
         global: isGlobal
@@ -2908,7 +3898,9 @@ const listCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('list').al
     logger_logger.newline();
     logger_logger.log(`Total: ${skills.length} skill(s)`);
 });
-const outdatedCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('outdated').description('Check for outdated skills').option('-j, --json', 'Output as JSON').action(async (options)=>{
+/**
+ * outdated command - Check for outdated skills
+ */ const outdatedCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('outdated').description('Check for outdated skills').option('-j, --json', 'Output as JSON').action(async (options)=>{
     const configLoader = new ConfigLoader();
     if (!configLoader.exists()) {
         logger_logger.error("skills.json not found. Run 'reskill init' first.");
@@ -2959,7 +3951,9 @@ const outdatedCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('outda
         process.exit(1);
     }
 });
-const uninstallCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('uninstall').alias('un').alias('remove').alias('rm').description('Uninstall a skill').argument('<skill>', 'Skill name to uninstall').option('-g, --global', 'Uninstall from global installation (~/.claude/skills)').option('-y, --yes', 'Skip confirmation prompts').action(async (skillName, options)=>{
+/**
+ * uninstall command - Uninstall a skill
+ */ const uninstallCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('uninstall').alias('un').alias('remove').alias('rm').description('Uninstall a skill').argument('<skill>', 'Skill name to uninstall').option('-g, --global', 'Uninstall from global installation (~/.claude/skills)').option('-y, --yes', 'Skip confirmation prompts').action(async (skillName, options)=>{
     const isGlobal = options.global || false;
     const skipConfirm = options.yes || false;
     const skillManager = new SkillManager(void 0, {
@@ -2967,6 +3961,7 @@ const uninstallCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('unin
     });
     console.log();
     __WEBPACK_EXTERNAL_MODULE__clack_prompts__.intro(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].bgCyan.black(' reskill '));
+    // Check which agents have this skill installed
     const installer = new Installer({
         cwd: process.cwd(),
         global: isGlobal
@@ -2979,6 +3974,7 @@ const uninstallCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('unin
         __WEBPACK_EXTERNAL_MODULE__clack_prompts__.outro('Done');
         process.exit(0);
     }
+    // Show uninstallation summary
     const summaryLines = [];
     summaryLines.push(`${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan(skillName)}`);
     summaryLines.push(`  ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].dim('→')} ${installedAgents.map((a)=>agents[a].displayName).join(', ')}`);
@@ -2993,6 +3989,7 @@ const uninstallCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('unin
             process.exit(0);
         }
     }
+    // Uninstall from all detected agents
     const results = skillManager.uninstallFromAgents(skillName, installedAgents);
     const successCount = Array.from(results.values()).filter((r)=>r).length;
     if (successCount > 0) __WEBPACK_EXTERNAL_MODULE__clack_prompts__.log.success(`Uninstalled ${__WEBPACK_EXTERNAL_MODULE_chalk__["default"].cyan(skillName)} from ${successCount} agent(s)`);
@@ -3003,7 +4000,9 @@ const uninstallCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('unin
     console.log();
     __WEBPACK_EXTERNAL_MODULE__clack_prompts__.outro(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].green('Done!'));
 });
-const updateCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('update').alias('up').description('Update installed skills').argument('[skill]', 'Skill name to update (updates all if not specified)').action(async (skill)=>{
+/**
+ * update command - Update installed skills
+ */ const updateCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('update').alias('up').description('Update installed skills').argument('[skill]', 'Skill name to update (updates all if not specified)').action(async (skill)=>{
     const configLoader = new ConfigLoader();
     if (!configLoader.exists()) {
         logger_logger.error("skills.json not found. Run 'reskill init' first.");
@@ -3026,11 +4025,14 @@ const updateCommand = new __WEBPACK_EXTERNAL_MODULE_commander__.Command('update'
         process.exit(1);
     }
 });
+// Handle tab completion early (before commander parsing)
+// This is needed because tabtab expects to intercept the process early
 if (maybeHandleCompletion()) process.exit(0);
 const cli_rslib_entry_dirname = (0, __WEBPACK_EXTERNAL_MODULE_node_path__.dirname)((0, __WEBPACK_EXTERNAL_MODULE_node_url__.fileURLToPath)(import.meta.url));
 const cli_rslib_entry_packageJson = JSON.parse((0, external_node_fs_.readFileSync)((0, __WEBPACK_EXTERNAL_MODULE_node_path__.join)(cli_rslib_entry_dirname, '../../package.json'), 'utf-8'));
 const program = new __WEBPACK_EXTERNAL_MODULE_commander__.Command();
 program.name('reskill').description('AI Skills Package Manager - Git-based skills management for AI agents').version(cli_rslib_entry_packageJson.version);
+// Register all commands
 program.addCommand(initCommand);
 program.addCommand(installCommand);
 program.addCommand(listCommand);
@@ -3040,8 +4042,11 @@ program.addCommand(outdatedCommand);
 program.addCommand(uninstallCommand);
 program.addCommand(completionCommand);
 program.addCommand(doctorCommand);
+// Start update check in background (non-blocking)
 const updateCheckPromise = checkForUpdate(cli_rslib_entry_packageJson.name, cli_rslib_entry_packageJson.version);
+// Parse arguments and wait for async commands to complete
 program.parseAsync().then(async ()=>{
+    // After command execution, show update notification if available
     const result = await updateCheckPromise;
     if (result?.hasUpdate) logger_logger.log(formatUpdateMessage(result));
 });