reskill 0.14.0 → 0.16.0

package/dist/index.js

@@ -190,12 +190,13 @@ function remove(targetPath) {
 }
 function copyDir(src, dest, options) {
     const exclude = options?.exclude || [];
+    const excludePrefix = options?.excludePrefix || '_';
     ensureDir(dest);
     const entries = external_node_fs_.readdirSync(src, {
         withFileTypes: true
     });
     for (const entry of entries){
-        if (exclude.includes(entry.name)) continue;
+        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);
         if (entry.isDirectory()) copyDir(srcPath, destPath, options);
@@ -272,7 +273,7 @@ function sanitizeName(name) {
     if (sanitized.length > 255) sanitized = sanitized.substring(0, 255);
     return sanitized;
 }
-const execAsync = (0, __WEBPACK_EXTERNAL_MODULE_node_util__.promisify)(__WEBPACK_EXTERNAL_MODULE_node_child_process__.exec);
+const git_execAsync = (0, __WEBPACK_EXTERNAL_MODULE_node_util__.promisify)(__WEBPACK_EXTERNAL_MODULE_node_child_process__.exec);
 class GitCloneError extends Error {
     repoUrl;
     originalError;
@@ -320,7 +321,7 @@ class GitCloneError extends Error {
     }
 }
 async function git(args, cwd) {
-    const { stdout } = await execAsync(`git ${args.join(' ')}`, {
+    const { stdout } = await git_execAsync(`git ${args.join(' ')}`, {
         cwd,
         encoding: 'utf-8'
     });
@@ -454,6 +455,202 @@ function parseGitUrl(url) {
     }
     return null;
 }
+const installer_AGENTS_DIR = '.agents';
+const installer_SKILLS_SUBDIR = 'skills';
+const DEFAULT_EXCLUDE_FILES = [
+    'README.md',
+    'metadata.json',
+    '.reskill-commit'
+];
+const EXCLUDE_PREFIX = '_';
+function installer_sanitizeName(name) {
+    let sanitized = name.replace(/[/\\:\0]/g, '');
+    sanitized = sanitized.replace(/^[.\s]+|[.\s]+$/g, '');
+    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) {
+    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) {
+    const baseDir = isGlobal ? (0, __WEBPACK_EXTERNAL_MODULE_node_os__.homedir)() : cwd || process.cwd();
+    return __WEBPACK_EXTERNAL_MODULE_node_path__.join(baseDir, installer_AGENTS_DIR, installer_SKILLS_SUBDIR);
+}
+function installer_ensureDir(dirPath) {
+    if (!external_node_fs_.existsSync(dirPath)) external_node_fs_.mkdirSync(dirPath, {
+        recursive: true
+    });
+}
+function installer_remove(targetPath) {
+    if (external_node_fs_.existsSync(targetPath)) external_node_fs_.rmSync(targetPath, {
+        recursive: true,
+        force: true
+    });
+}
+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){
+        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);
+        if (entry.isDirectory()) copyDirectory(srcPath, destPath, options);
+        else external_node_fs_.copyFileSync(srcPath, destPath);
+    }
+}
+async function installer_createSymlink(target, linkPath) {
+    try {
+        try {
+            const stats = external_node_fs_.lstatSync(linkPath);
+            if (stats.isSymbolicLink()) {
+                const existingTarget = external_node_fs_.readlinkSync(linkPath);
+                if (__WEBPACK_EXTERNAL_MODULE_node_path__.resolve(existingTarget) === __WEBPACK_EXTERNAL_MODULE_node_path__.resolve(target)) return true;
+                external_node_fs_.rmSync(linkPath);
+            } else external_node_fs_.rmSync(linkPath, {
+                recursive: true
+            });
+        } catch (err) {
+            if (err && 'object' == typeof err && 'code' in err) {
+                if ('ELOOP' === err.code) try {
+                    external_node_fs_.rmSync(linkPath, {
+                        force: true
+                    });
+                } catch  {}
+            }
+        }
+        const linkDir = __WEBPACK_EXTERNAL_MODULE_node_path__.dirname(linkPath);
+        installer_ensureDir(linkDir);
+        const relativePath = __WEBPACK_EXTERNAL_MODULE_node_path__.relative(linkDir, target);
+        const symlinkType = 'win32' === (0, __WEBPACK_EXTERNAL_MODULE_node_os__.platform)() ? 'junction' : void 0;
+        external_node_fs_.symlinkSync(relativePath, linkPath, symlinkType);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+class Installer {
+    cwd;
+    isGlobal;
+    constructor(options = {}){
+        this.cwd = options.cwd || process.cwd();
+        this.isGlobal = options.global || false;
+    }
+    getCanonicalPath(skillName) {
+        const sanitized = installer_sanitizeName(skillName);
+        const canonicalBase = installer_getCanonicalSkillsDir(this.isGlobal, this.cwd);
+        return __WEBPACK_EXTERNAL_MODULE_node_path__.join(canonicalBase, sanitized);
+    }
+    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 = {}) {
+        const agent = getAgentConfig(agentType);
+        const installMode = options.mode || 'symlink';
+        const sanitized = installer_sanitizeName(skillName);
+        const canonicalBase = installer_getCanonicalSkillsDir(this.isGlobal, this.cwd);
+        const canonicalDir = __WEBPACK_EXTERNAL_MODULE_node_path__.join(canonicalBase, sanitized);
+        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);
+        if (!installer_isPathSafe(canonicalBase, canonicalDir)) return {
+            success: false,
+            path: agentDir,
+            mode: installMode,
+            error: 'Invalid skill name: potential path traversal detected'
+        };
+        if (!installer_isPathSafe(agentBase, agentDir)) return {
+            success: false,
+            path: agentDir,
+            mode: installMode,
+            error: 'Invalid skill name: potential path traversal detected'
+        };
+        try {
+            if ('copy' === installMode) {
+                installer_ensureDir(agentDir);
+                installer_remove(agentDir);
+                copyDirectory(sourcePath, agentDir);
+                return {
+                    success: true,
+                    path: agentDir,
+                    mode: 'copy'
+                };
+            }
+            installer_ensureDir(canonicalDir);
+            installer_remove(canonicalDir);
+            copyDirectory(sourcePath, canonicalDir);
+            const symlinkCreated = await installer_createSymlink(canonicalDir, agentDir);
+            if (!symlinkCreated) {
+                try {
+                    installer_remove(agentDir);
+                } catch  {}
+                installer_ensureDir(agentDir);
+                copyDirectory(sourcePath, agentDir);
+                return {
+                    success: true,
+                    path: agentDir,
+                    canonicalPath: canonicalDir,
+                    mode: 'symlink',
+                    symlinkFailed: true
+                };
+            }
+            return {
+                success: true,
+                path: agentDir,
+                canonicalPath: canonicalDir,
+                mode: 'symlink'
+            };
+        } catch (error) {
+            return {
+                success: false,
+                path: agentDir,
+                mode: installMode,
+                error: error instanceof Error ? error.message : 'Unknown error'
+            };
+        }
+    }
+    async installToAgents(sourcePath, skillName, targetAgents, options = {}) {
+        const results = new Map();
+        for (const agent of targetAgents){
+            const result = await this.installForAgent(sourcePath, skillName, agent, options);
+            results.set(agent, result);
+        }
+        return results;
+    }
+    isInstalled(skillName, agentType) {
+        const skillPath = this.getAgentSkillPath(skillName, agentType);
+        return external_node_fs_.existsSync(skillPath);
+    }
+    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) {
+        const results = new Map();
+        for (const agent of targetAgents)results.set(agent, this.uninstallFromAgent(skillName, agent));
+        const canonicalPath = this.getCanonicalPath(skillName);
+        if (external_node_fs_.existsSync(canonicalPath)) installer_remove(canonicalPath);
+        return results;
+    }
+    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 [];
+        return external_node_fs_.readdirSync(skillsDir, {
+            withFileTypes: true
+        }).filter((entry)=>entry.isDirectory() || entry.isSymbolicLink()).map((entry)=>entry.name);
+    }
+}
 class CacheManager {
     cacheDir;
     constructor(cacheDir){
@@ -526,9 +723,7 @@ class CacheManager {
         if (!cached) throw new Error(`Skill ${parsed.raw} version ${version} not found in cache`);
         if (exists(destPath)) remove(destPath);
         copyDir(cached.path, destPath, {
-            exclude: [
-                '.reskill-commit'
-            ]
+            exclude: DEFAULT_EXCLUDE_FILES
         });
     }
     clearSkill(parsed, version) {
@@ -564,6 +759,31 @@ class CacheManager {
             registries
         };
     }
+    async getRemoteCommit(repoUrl, ref) {
+        const { exec } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execAsync = promisify(exec);
+        try {
+            const { stdout } = await execAsync(`git ls-remote ${repoUrl} ${ref}`, {
+                encoding: 'utf-8'
+            });
+            if (stdout.trim()) {
+                const [commit] = stdout.trim().split('\t');
+                return commit;
+            }
+            const { stdout: allRefs } = await execAsync(`git ls-remote ${repoUrl}`, {
+                encoding: 'utf-8'
+            });
+            const lines = allRefs.trim().split('\n');
+            for (const line of lines){
+                const [commit, refPath] = line.split('\t');
+                if (refPath === `refs/heads/${ref}` || refPath === `refs/tags/${ref}` || refPath === ref) return commit;
+            }
+            return '';
+        } catch  {
+            return '';
+        }
+    }
 }
 const DEFAULT_SKILLS_JSON = {
     skills: {},
@@ -870,200 +1090,6 @@ class GitResolver {
         };
     }
 }
-const installer_AGENTS_DIR = '.agents';
-const installer_SKILLS_SUBDIR = 'skills';
-function installer_sanitizeName(name) {
-    let sanitized = name.replace(/[/\\:\0]/g, '');
-    sanitized = sanitized.replace(/^[.\s]+|[.\s]+$/g, '');
-    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) {
-    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) {
-    const baseDir = isGlobal ? (0, __WEBPACK_EXTERNAL_MODULE_node_os__.homedir)() : cwd || process.cwd();
-    return __WEBPACK_EXTERNAL_MODULE_node_path__.join(baseDir, installer_AGENTS_DIR, installer_SKILLS_SUBDIR);
-}
-function installer_ensureDir(dirPath) {
-    if (!external_node_fs_.existsSync(dirPath)) external_node_fs_.mkdirSync(dirPath, {
-        recursive: true
-    });
-}
-function installer_remove(targetPath) {
-    if (external_node_fs_.existsSync(targetPath)) external_node_fs_.rmSync(targetPath, {
-        recursive: true,
-        force: true
-    });
-}
-function copyDirectory(src, dest, options) {
-    const exclude = new Set(options?.exclude || [
-        'README.md',
-        'metadata.json',
-        '.reskill-commit'
-    ]);
-    installer_ensureDir(dest);
-    const entries = external_node_fs_.readdirSync(src, {
-        withFileTypes: true
-    });
-    for (const entry of entries){
-        if (exclude.has(entry.name) || entry.name.startsWith('_')) continue;
-        const srcPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(src, entry.name);
-        const destPath = __WEBPACK_EXTERNAL_MODULE_node_path__.join(dest, entry.name);
-        if (entry.isDirectory()) copyDirectory(srcPath, destPath, options);
-        else external_node_fs_.copyFileSync(srcPath, destPath);
-    }
-}
-async function installer_createSymlink(target, linkPath) {
-    try {
-        try {
-            const stats = external_node_fs_.lstatSync(linkPath);
-            if (stats.isSymbolicLink()) {
-                const existingTarget = external_node_fs_.readlinkSync(linkPath);
-                if (__WEBPACK_EXTERNAL_MODULE_node_path__.resolve(existingTarget) === __WEBPACK_EXTERNAL_MODULE_node_path__.resolve(target)) return true;
-                external_node_fs_.rmSync(linkPath);
-            } else external_node_fs_.rmSync(linkPath, {
-                recursive: true
-            });
-        } catch (err) {
-            if (err && 'object' == typeof err && 'code' in err) {
-                if ('ELOOP' === err.code) try {
-                    external_node_fs_.rmSync(linkPath, {
-                        force: true
-                    });
-                } catch  {}
-            }
-        }
-        const linkDir = __WEBPACK_EXTERNAL_MODULE_node_path__.dirname(linkPath);
-        installer_ensureDir(linkDir);
-        const relativePath = __WEBPACK_EXTERNAL_MODULE_node_path__.relative(linkDir, target);
-        const symlinkType = 'win32' === (0, __WEBPACK_EXTERNAL_MODULE_node_os__.platform)() ? 'junction' : void 0;
-        external_node_fs_.symlinkSync(relativePath, linkPath, symlinkType);
-        return true;
-    } catch  {
-        return false;
-    }
-}
-class Installer {
-    cwd;
-    isGlobal;
-    constructor(options = {}){
-        this.cwd = options.cwd || process.cwd();
-        this.isGlobal = options.global || false;
-    }
-    getCanonicalPath(skillName) {
-        const sanitized = installer_sanitizeName(skillName);
-        const canonicalBase = installer_getCanonicalSkillsDir(this.isGlobal, this.cwd);
-        return __WEBPACK_EXTERNAL_MODULE_node_path__.join(canonicalBase, sanitized);
-    }
-    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 = {}) {
-        const agent = getAgentConfig(agentType);
-        const installMode = options.mode || 'symlink';
-        const sanitized = installer_sanitizeName(skillName);
-        const canonicalBase = installer_getCanonicalSkillsDir(this.isGlobal, this.cwd);
-        const canonicalDir = __WEBPACK_EXTERNAL_MODULE_node_path__.join(canonicalBase, sanitized);
-        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);
-        if (!installer_isPathSafe(canonicalBase, canonicalDir)) return {
-            success: false,
-            path: agentDir,
-            mode: installMode,
-            error: 'Invalid skill name: potential path traversal detected'
-        };
-        if (!installer_isPathSafe(agentBase, agentDir)) return {
-            success: false,
-            path: agentDir,
-            mode: installMode,
-            error: 'Invalid skill name: potential path traversal detected'
-        };
-        try {
-            if ('copy' === installMode) {
-                installer_ensureDir(agentDir);
-                installer_remove(agentDir);
-                copyDirectory(sourcePath, agentDir);
-                return {
-                    success: true,
-                    path: agentDir,
-                    mode: 'copy'
-                };
-            }
-            installer_ensureDir(canonicalDir);
-            installer_remove(canonicalDir);
-            copyDirectory(sourcePath, canonicalDir);
-            const symlinkCreated = await installer_createSymlink(canonicalDir, agentDir);
-            if (!symlinkCreated) {
-                try {
-                    installer_remove(agentDir);
-                } catch  {}
-                installer_ensureDir(agentDir);
-                copyDirectory(sourcePath, agentDir);
-                return {
-                    success: true,
-                    path: agentDir,
-                    canonicalPath: canonicalDir,
-                    mode: 'symlink',
-                    symlinkFailed: true
-                };
-            }
-            return {
-                success: true,
-                path: agentDir,
-                canonicalPath: canonicalDir,
-                mode: 'symlink'
-            };
-        } catch (error) {
-            return {
-                success: false,
-                path: agentDir,
-                mode: installMode,
-                error: error instanceof Error ? error.message : 'Unknown error'
-            };
-        }
-    }
-    async installToAgents(sourcePath, skillName, targetAgents, options = {}) {
-        const results = new Map();
-        for (const agent of targetAgents){
-            const result = await this.installForAgent(sourcePath, skillName, agent, options);
-            results.set(agent, result);
-        }
-        return results;
-    }
-    isInstalled(skillName, agentType) {
-        const skillPath = this.getAgentSkillPath(skillName, agentType);
-        return external_node_fs_.existsSync(skillPath);
-    }
-    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) {
-        const results = new Map();
-        for (const agent of targetAgents)results.set(agent, this.uninstallFromAgent(skillName, agent));
-        const canonicalPath = this.getCanonicalPath(skillName);
-        if (external_node_fs_.existsSync(canonicalPath)) installer_remove(canonicalPath);
-        return results;
-    }
-    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 [];
-        return external_node_fs_.readdirSync(skillsDir, {
-            withFileTypes: true
-        }).filter((entry)=>entry.isDirectory() || entry.isSymbolicLink()).map((entry)=>entry.name);
-    }
-}
 const LOCKFILE_VERSION = 1;
 class LockManager {
     projectRoot;
@@ -1127,6 +1153,7 @@ class LockManager {
         const lockedSkill = {
             source: options.source,
             version: options.version,
+            ref: options.ref,
             resolved: options.resolved,
             commit: options.commit,
             installedAt: new Date().toISOString()
@@ -1164,7 +1191,7 @@ class LockManager {
         this.lockData = null;
     }
 }
-const logger = {
+const logger_logger = {
     info (message) {
         console.log(__WEBPACK_EXTERNAL_MODULE_chalk__["default"].blue('ℹ'), message);
     },
@@ -1247,35 +1274,43 @@ class SkillManager {
         const { force = false, save = true } = options;
         const resolved = await this.resolver.resolve(ref);
         const { parsed, repoUrl } = resolved;
-        const version = resolved.ref;
+        const gitRef = resolved.ref;
         const skillName = parsed.subPath ? __WEBPACK_EXTERNAL_MODULE_node_path__.basename(parsed.subPath) : parsed.repo;
         const skillPath = this.getSkillPath(skillName);
         if (exists(skillPath) && !force) {
             const locked = this.lockManager.get(skillName);
-            if (locked && locked.version === version) {
-                logger.info(`${skillName}@${version} is already installed`);
+            const lockedRef = locked?.ref || locked?.version;
+            if (locked && lockedRef === gitRef) {
+                logger_logger.info(`${skillName}@${gitRef} is already installed`);
                 const installed = this.getInstalledSkill(skillName);
                 if (installed) return installed;
             }
             if (!force) {
-                logger.warn(`${skillName} is already installed. Use --force to reinstall.`);
+                logger_logger.warn(`${skillName} is already installed. Use --force to reinstall.`);
                 const installed = this.getInstalledSkill(skillName);
                 if (installed) return installed;
             }
         }
-        logger["package"](`Installing ${skillName}@${version}...`);
-        let cacheResult = await this.cache.get(parsed, version);
-        if (cacheResult) logger.debug(`Using cached ${skillName}@${version}`);
+        logger_logger["package"](`Installing ${skillName}@${gitRef}...`);
+        let cacheResult = await this.cache.get(parsed, gitRef);
+        if (cacheResult) logger_logger.debug(`Using cached ${skillName}@${gitRef}`);
         else {
-            logger.debug(`Caching ${skillName}@${version} from ${repoUrl}`);
-            cacheResult = await this.cache.cache(repoUrl, parsed, version, version);
+            logger_logger.debug(`Caching ${skillName}@${gitRef} from ${repoUrl}`);
+            cacheResult = await this.cache.cache(repoUrl, parsed, gitRef, gitRef);
         }
         ensureDir(this.getInstallDir());
         if (exists(skillPath)) remove(skillPath);
-        await this.cache.copyTo(parsed, version, skillPath);
+        await this.cache.copyTo(parsed, gitRef, skillPath);
+        let semanticVersion = gitRef;
+        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  {}
         if (!this.isGlobal) this.lockManager.lockSkill(skillName, {
             source: `${parsed.registry}:${parsed.owner}/${parsed.repo}${parsed.subPath ? `/${parsed.subPath}` : ''}`,
-            version,
+            version: semanticVersion,
+            ref: gitRef,
             resolved: repoUrl,
             commit: cacheResult.commit
         });
@@ -1283,8 +1318,9 @@ class SkillManager {
             this.config.ensureExists();
             this.config.addSkill(skillName, ref);
         }
+        const displayVersion = semanticVersion !== gitRef ? `${semanticVersion} (${gitRef})` : gitRef;
         const locationHint = this.isGlobal ? '(global)' : '';
-        logger.success(`Installed ${skillName}@${version} to ${skillPath} ${locationHint}`.trim());
+        logger_logger.success(`Installed ${skillName}@${displayVersion} to ${skillPath} ${locationHint}`.trim());
         const installed = this.getInstalledSkill(skillName);
         if (!installed) throw new Error(`Failed to get installed skill info for ${skillName}`);
         return installed;
@@ -1299,7 +1335,7 @@ class SkillManager {
             });
             installed.push(skill);
         } catch (error) {
-            logger.error(`Failed to install ${name}: ${error.message}`);
+            logger_logger.error(`Failed to install ${name}: ${error.message}`);
         }
         return installed;
     }
@@ -1307,22 +1343,33 @@ class SkillManager {
         const skillPath = this.getSkillPath(name);
         if (!exists(skillPath)) {
             const location = this.isGlobal ? '(global)' : '';
-            logger.warn(`Skill ${name} is not installed ${location}`.trim());
+            logger_logger.warn(`Skill ${name} is not installed ${location}`.trim());
             return false;
         }
         remove(skillPath);
         if (!this.isGlobal) this.lockManager.remove(name);
         if (!this.isGlobal && this.config.exists()) this.config.removeSkill(name);
         const locationHint = this.isGlobal ? '(global)' : '';
-        logger.success(`Uninstalled ${name} ${locationHint}`.trim());
+        logger_logger.success(`Uninstalled ${name} ${locationHint}`.trim());
         return true;
     }
+    checkNeedsUpdate(name, remoteCommit) {
+        const locked = this.lockManager.get(name);
+        if (!locked?.commit) return true;
+        return locked.commit !== remoteCommit;
+    }
     async update(name) {
         const updated = [];
         if (name) {
             const ref = this.config.getSkillRef(name);
             if (!ref) {
-                logger.error(`Skill ${name} not found in skills.json`);
+                logger_logger.error(`Skill ${name} not found in skills.json`);
+                return [];
+            }
+            const resolved = await this.resolver.resolve(ref);
+            const remoteCommit = await this.cache.getRemoteCommit(resolved.repoUrl, resolved.ref);
+            if (!this.checkNeedsUpdate(name, remoteCommit)) {
+                logger_logger.info(`${name} is already up to date`);
                 return [];
             }
             const skill = await this.install(ref, {
@@ -1333,13 +1380,19 @@ class SkillManager {
         } else {
             const skills = this.config.getSkills();
             for (const [skillName, ref] of Object.entries(skills))try {
+                const resolved = await this.resolver.resolve(ref);
+                const remoteCommit = await this.cache.getRemoteCommit(resolved.repoUrl, resolved.ref);
+                if (!this.checkNeedsUpdate(skillName, remoteCommit)) {
+                    logger_logger.info(`${skillName} is already up to date`);
+                    continue;
+                }
                 const skill = await this.install(ref, {
                     force: true,
                     save: false
                 });
                 updated.push(skill);
             } catch (error) {
-                logger.error(`Failed to update ${skillName}: ${error.message}`);
+                logger_logger.error(`Failed to update ${skillName}: ${error.message}`);
             }
         }
         return updated;
@@ -1356,7 +1409,7 @@ class SkillManager {
         const linkPath = this.getSkillPath(skillName);
         ensureDir(__WEBPACK_EXTERNAL_MODULE_node_path__.dirname(linkPath));
         createSymlink(absolutePath, linkPath);
-        logger.success(`Linked ${skillName} → ${absolutePath}`);
+        logger_logger.success(`Linked ${skillName} → ${absolutePath}`);
         return {
             name: skillName,
             path: linkPath,
@@ -1368,15 +1421,15 @@ class SkillManager {
     unlink(name) {
         const skillPath = this.getSkillPath(name);
         if (!exists(skillPath)) {
-            logger.warn(`Skill ${name} is not installed`);
+            logger_logger.warn(`Skill ${name} is not installed`);
             return false;
         }
         if (!isSymlink(skillPath)) {
-            logger.warn(`Skill ${name} is not a linked skill`);
+            logger_logger.warn(`Skill ${name} is not a linked skill`);
             return false;
         }
         remove(skillPath);
-        logger.success(`Unlinked ${name}`);
+        logger_logger.success(`Unlinked ${name}`);
         return true;
     }
     list() {
@@ -1446,7 +1499,8 @@ class SkillManager {
         const skills = this.config.getSkills();
         for (const [name, ref] of Object.entries(skills))try {
             const locked = this.lockManager.get(name);
-            const current = locked?.version || 'unknown';
+            const currentRef = locked?.ref || locked?.version || 'unknown';
+            const currentVersion = locked?.version || 'unknown';
             const parsed = this.resolver.parseRef(ref);
             const repoUrl = this.resolver.buildRepoUrl(parsed);
             const latestResolved = await this.resolver.resolveVersion(repoUrl, {
@@ -1455,15 +1509,15 @@ class SkillManager {
                 raw: 'latest'
             });
             const latest = latestResolved.ref;
-            const updateAvailable = current !== latest && 'unknown' !== current;
+            const updateAvailable = currentRef !== latest && 'unknown' !== currentRef;
             results.push({
                 name,
-                current,
+                current: currentVersion !== currentRef ? `${currentVersion} (${currentRef})` : currentRef,
                 latest,
                 updateAvailable
             });
         } catch (error) {
-            logger.debug(`Failed to check ${name}: ${error.message}`);
+            logger_logger.debug(`Failed to check ${name}: ${error.message}`);
             results.push({
                 name,
                 current: 'unknown',
@@ -1477,16 +1531,22 @@ class SkillManager {
         const { save = true, mode = 'symlink' } = options;
         const resolved = await this.resolver.resolve(ref);
         const { parsed, repoUrl } = resolved;
-        const version = resolved.ref;
+        const gitRef = resolved.ref;
         const skillName = parsed.subPath ? __WEBPACK_EXTERNAL_MODULE_node_path__.basename(parsed.subPath) : parsed.repo;
-        logger["package"](`Installing ${skillName}@${version} to ${targetAgents.length} agent(s)...`);
-        let cacheResult = await this.cache.get(parsed, version);
-        if (cacheResult) logger.debug(`Using cached ${skillName}@${version}`);
+        logger_logger["package"](`Installing ${skillName}@${gitRef} to ${targetAgents.length} agent(s)...`);
+        let cacheResult = await this.cache.get(parsed, gitRef);
+        if (cacheResult) logger_logger.debug(`Using cached ${skillName}@${gitRef}`);
         else {
-            logger.debug(`Caching ${skillName}@${version} from ${repoUrl}`);
-            cacheResult = await this.cache.cache(repoUrl, parsed, version, version);
+            logger_logger.debug(`Caching ${skillName}@${gitRef} from ${repoUrl}`);
+            cacheResult = await this.cache.cache(repoUrl, parsed, gitRef, gitRef);
         }
-        const sourcePath = this.cache.getCachePath(parsed, version);
+        const sourcePath = this.cache.getCachePath(parsed, gitRef);
+        let semanticVersion = gitRef;
+        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  {}
         const installer = new Installer({
             cwd: this.projectRoot,
             global: this.isGlobal
@@ -1496,7 +1556,8 @@ class SkillManager {
         });
         if (!this.isGlobal) this.lockManager.lockSkill(skillName, {
             source: `${parsed.registry}:${parsed.owner}/${parsed.repo}${parsed.subPath ? `/${parsed.subPath}` : ''}`,
-            version,
+            version: semanticVersion,
+            ref: gitRef,
             resolved: repoUrl,
             commit: cacheResult.commit
         });
@@ -1506,12 +1567,13 @@ class SkillManager {
         }
         const successCount = Array.from(results.values()).filter((r)=>r.success).length;
         const failCount = results.size - successCount;
-        if (0 === failCount) logger.success(`Installed ${skillName}@${version} to ${successCount} agent(s)`);
-        else logger.warn(`Installed ${skillName}@${version} to ${successCount} agent(s), ${failCount} failed`);
+        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`);
         const skill = {
             name: skillName,
             path: sourcePath,
-            version,
+            version: semanticVersion,
             source: `${parsed.registry}:${parsed.owner}/${parsed.repo}${parsed.subPath ? `/${parsed.subPath}` : ''}`
         };
         return {
@@ -1551,7 +1613,7 @@ class SkillManager {
         if (!this.isGlobal) this.lockManager.remove(name);
         if (!this.isGlobal && this.config.exists()) this.config.removeSkill(name);
         const successCount = Array.from(results.values()).filter((r)=>r).length;
-        logger.success(`Uninstalled ${name} from ${successCount} agent(s)`);
+        logger_logger.success(`Uninstalled ${name} from ${successCount} agent(s)`);
         return results;
     }
 }
@@ -1698,4 +1760,4 @@ function generateSkillMd(skill) {
     frontmatter.push('');
     return frontmatter.join('\n') + skill.content;
 }
-export { CacheManager, ConfigLoader, DEFAULT_REGISTRIES, GitResolver, Installer, LockManager, SkillManager, SkillValidationError, agents, detectInstalledAgents, generateSkillMd, getAgentConfig, getAgentSkillsDir, getAllAgentTypes, getCanonicalSkillPath, getCanonicalSkillsDir, hasValidSkillMd, isPathSafe, isValidAgentType, logger, parseSkillFromDir, parseSkillMd, parseSkillMdFile, sanitizeName, shortenPath, validateSkillDescription, validateSkillName };
+export { CacheManager, ConfigLoader, DEFAULT_REGISTRIES, GitResolver, Installer, LockManager, SkillManager, SkillValidationError, agents, detectInstalledAgents, generateSkillMd, getAgentConfig, getAgentSkillsDir, getAllAgentTypes, getCanonicalSkillPath, getCanonicalSkillsDir, hasValidSkillMd, isPathSafe, isValidAgentType, logger_logger as logger, parseSkillFromDir, parseSkillMd, parseSkillMdFile, sanitizeName, shortenPath, validateSkillDescription, validateSkillName };