skillscat 0.1.0 → 0.1.1

package/dist/index.js

@@ -2,7 +2,7 @@
 import { Command } from 'commander';
 import pc from 'picocolors';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync, readdirSync, rmSync, realpathSync, statSync } from 'node:fs';
-import { join, dirname, resolve, relative, isAbsolute } from 'node:path';
+import { join, dirname, posix, resolve, relative, isAbsolute } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
 import os, { platform, homedir, hostname, release } from 'node:os';
 import * as readline from 'node:readline';
@@ -23,16 +23,42 @@ function parseSource(source) {
             repo: shorthandMatch[2]
         };
     }
-    // GitHub URL: https://github.com/owner/repo or with tree/branch/path
-    const githubMatch = source.match(/github\.com\/([^\/]+)\/([^\/]+)(?:\/tree\/([^\/]+))?(?:\/(.+))?$/);
-    if (githubMatch) {
-        return {
-            platform: 'github',
-            owner: githubMatch[1],
-            repo: githubMatch[2].replace(/\.git$/, ''),
-            branch: githubMatch[3],
-            path: githubMatch[4]
-        };
+    // GitHub URL: https://github.com/owner/repo or with tree/blob refs
+    try {
+        const url = new URL(source);
+        const host = url.hostname.toLowerCase();
+        if (host === 'github.com' || host === 'www.github.com') {
+            const parts = url.pathname.split('/').filter(Boolean).map(decodeURIComponent);
+            if (parts.length >= 2) {
+                const owner = parts[0];
+                const repo = parts[1].replace(/\.git$/, '');
+                const route = parts[2];
+                if (route === 'tree' || route === 'blob') {
+                    const branch = parts[3];
+                    const path = parts.slice(4).join('/');
+                    return {
+                        platform: 'github',
+                        owner,
+                        repo,
+                        branch,
+                        path: path || undefined,
+                        refKind: route,
+                        hasExplicitRef: true,
+                        originalInput: source
+                    };
+                }
+                return {
+                    platform: 'github',
+                    owner,
+                    repo,
+                    path: parts.slice(2).join('/') || undefined,
+                    originalInput: source
+                };
+            }
+        }
+    }
+    catch {
+        // Not a valid URL, continue to other formats.
     }
     // GitLab URL: https://gitlab.com/owner/repo or with -/tree/branch/path
     const gitlabMatch = source.match(/gitlab\.com\/(.+?)(?:\/-\/tree\/([^\/]+))?(?:\/(.+))?$/);
@@ -236,9 +262,24 @@ function deleteSetting(key) {
 function getRegistryUrl() {
     return getSetting('registry') || DEFAULT_REGISTRY_URL$1;
 }
+function normalizeRegistryUrlForCompare(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.hash = '';
+        parsed.search = '';
+        parsed.pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+        return parsed.toString();
+    }
+    catch {
+        return url.replace(/\/+$/, '');
+    }
+}
+function isDefaultRegistry() {
+    return normalizeRegistryUrlForCompare(getRegistryUrl()) === normalizeRegistryUrlForCompare(DEFAULT_REGISTRY_URL$1);
+}
 
 const MAX_CACHE_ITEMS = 100;
-const PRUNE_PERCENTAGE = 0.2;
+const PRUNE_PERCENTAGE$1 = 0.2;
 /**
  * Get the skills cache directory
  */
@@ -364,7 +405,7 @@ function pruneCache(maxItems = MAX_CACHE_ITEMS) {
             return (index.skills[a]?.lastAccessedAt || 0) - (index.skills[b]?.lastAccessedAt || 0);
         });
         // Remove oldest PRUNE_PERCENTAGE
-        const toRemove = Math.ceil(keys.length * PRUNE_PERCENTAGE);
+        const toRemove = Math.ceil(keys.length * PRUNE_PERCENTAGE$1);
         const keysToRemove = sorted.slice(0, toRemove);
         const skillsDir = getSkillsCacheDir();
         for (const key of keysToRemove) {
@@ -386,23 +427,413 @@ function pruneCache(maxItems = MAX_CACHE_ITEMS) {
     }
 }
 
+const GITHUB_CACHE_VERSION = 1;
+const TREE_CACHE_TTL_MS = 5 * 60 * 1000;
+const MAX_TREE_CACHE_ITEMS = 100;
+const MAX_BLOB_CACHE_ITEMS = 1000;
+const PRUNE_PERCENTAGE = 0.2;
+function getGitHubCacheDir() {
+    return join(getCacheDir(), 'github');
+}
+function getTreeCacheDir() {
+    return join(getGitHubCacheDir(), 'trees');
+}
+function getBlobCacheDir() {
+    return join(getGitHubCacheDir(), 'blobs');
+}
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function ensureGitHubCacheDirs() {
+    ensureDir(getTreeCacheDir());
+    ensureDir(getBlobCacheDir());
+}
+function toCacheFileName(prefix, key) {
+    const digest = createHash('sha256').update(key).digest('hex');
+    return `${prefix}-${digest}.json`;
+}
+function readJsonFile(filePath) {
+    try {
+        if (!existsSync(filePath))
+            return null;
+        return JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonFile(filePath, value) {
+    ensureDir(dirname(filePath));
+    writeFileSync(filePath, JSON.stringify(value));
+}
+function hasValidCacheRecordBase(record) {
+    return !!record
+        && record.version === GITHUB_CACHE_VERSION
+        && typeof record.cachedAt === 'number'
+        && typeof record.lastAccessedAt === 'number';
+}
+function isValidTreeCacheRecord(record) {
+    if (!record || !hasValidCacheRecordBase(record)) {
+        return false;
+    }
+    const treeRecord = record;
+    return Array.isArray(treeRecord.tree);
+}
+function isValidBlobCacheRecord(record) {
+    if (!record || !hasValidCacheRecordBase(record)) {
+        return false;
+    }
+    const blobRecord = record;
+    return typeof blobRecord.dataBase64 === 'string';
+}
+function touchCacheRecord(filePath, record) {
+    try {
+        record.lastAccessedAt = Date.now();
+        writeFileSync(filePath, JSON.stringify(record));
+    }
+    catch {
+        // Best effort only
+    }
+}
+function pruneCacheDir(dir, maxItems) {
+    try {
+        ensureDir(dir);
+        const files = readdirSync(dir).filter((name) => name.endsWith('.json'));
+        if (files.length <= maxItems)
+            return;
+        const sortable = [];
+        for (const file of files) {
+            const record = readJsonFile(join(dir, file));
+            sortable.push({
+                file,
+                lastAccessedAt: hasValidCacheRecordBase(record) ? record.lastAccessedAt : 0,
+            });
+        }
+        sortable.sort((a, b) => a.lastAccessedAt - b.lastAccessedAt);
+        const toRemove = Math.max(1, Math.ceil(files.length * PRUNE_PERCENTAGE));
+        for (const item of sortable.slice(0, toRemove)) {
+            try {
+                unlinkSync(join(dir, item.file));
+            }
+            catch {
+                // ignore individual file failures
+            }
+        }
+    }
+    catch {
+        // ignore prune errors
+    }
+}
+function getTreeCachePath(owner, repo, ref) {
+    const key = `${owner}/${repo}@${ref}`;
+    return join(getTreeCacheDir(), toCacheFileName('tree', key));
+}
+function getBlobCachePath(sha) {
+    return join(getBlobCacheDir(), toCacheFileName('blob', sha));
+}
+function getCachedGitHubTree(owner, repo, ref) {
+    try {
+        const filePath = getTreeCachePath(owner, repo, ref);
+        const record = readJsonFile(filePath);
+        if (!isValidTreeCacheRecord(record)) {
+            return null;
+        }
+        if (Date.now() - record.cachedAt > TREE_CACHE_TTL_MS) {
+            return null;
+        }
+        touchCacheRecord(filePath, record);
+        return record.tree.map((item) => ({ ...item }));
+    }
+    catch {
+        return null;
+    }
+}
+function cacheGitHubTree(owner, repo, ref, tree) {
+    try {
+        ensureGitHubCacheDirs();
+        const now = Date.now();
+        const filePath = getTreeCachePath(owner, repo, ref);
+        const record = {
+            version: GITHUB_CACHE_VERSION,
+            cachedAt: now,
+            lastAccessedAt: now,
+            tree: tree.map((item) => ({ ...item })),
+        };
+        writeJsonFile(filePath, record);
+        pruneCacheDir(getTreeCacheDir(), MAX_TREE_CACHE_ITEMS);
+    }
+    catch {
+        // ignore cache write errors
+    }
+}
+function getCachedGitHubBlob(sha) {
+    try {
+        const filePath = getBlobCachePath(sha);
+        const record = readJsonFile(filePath);
+        if (!isValidBlobCacheRecord(record)) {
+            return null;
+        }
+        touchCacheRecord(filePath, record);
+        return Buffer.from(record.dataBase64, 'base64');
+    }
+    catch {
+        return null;
+    }
+}
+function cacheGitHubBlob(sha, bytes) {
+    try {
+        ensureGitHubCacheDirs();
+        const now = Date.now();
+        const filePath = getBlobCachePath(sha);
+        const record = {
+            version: GITHUB_CACHE_VERSION,
+            cachedAt: now,
+            lastAccessedAt: now,
+            dataBase64: Buffer.from(bytes).toString('base64'),
+        };
+        writeJsonFile(filePath, record);
+        pruneCacheDir(getBlobCacheDir(), MAX_BLOB_CACHE_ITEMS);
+    }
+    catch {
+        // ignore cache write errors
+    }
+}
+
+const DEFAULT_API_VERSION = '2022-11-28';
+const DEFAULT_USER_AGENT = 'skillscat-cli/1.0';
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function parseRetryAfterMs(headers) {
+    const retryAfter = headers.get('retry-after');
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds >= 0) {
+            return seconds * 1000;
+        }
+        const dateMs = Date.parse(retryAfter);
+        if (!Number.isNaN(dateMs)) {
+            return Math.max(0, dateMs - Date.now());
+        }
+    }
+    const reset = headers.get('x-ratelimit-reset');
+    if (reset) {
+        const epochSeconds = Number(reset);
+        if (Number.isFinite(epochSeconds) && epochSeconds > 0) {
+            return Math.max(0, epochSeconds * 1000 - Date.now());
+        }
+    }
+    return null;
+}
+function isRateLimited(response) {
+    if (response.status === 429)
+        return true;
+    if (response.status !== 403)
+        return false;
+    if (response.headers.get('x-ratelimit-remaining') === '0')
+        return true;
+    return response.headers.has('retry-after');
+}
+function getBackoffDelayMs(attempt, maxDelayMs) {
+    const exponential = Math.min(maxDelayMs, 500 * (2 ** attempt));
+    const jitter = Math.floor(Math.random() * 250);
+    return Math.min(maxDelayMs, exponential + jitter);
+}
+function getUrlHost(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function isGitHubDomain(host) {
+    if (!host)
+        return false;
+    return host === 'github.com'
+        || host.endsWith('.github.com')
+        || host === 'githubusercontent.com'
+        || host.endsWith('.githubusercontent.com');
+}
+/**
+ * Unified GitHub request helper with retry on rate limits / transient errors.
+ */
+async function githubRequest(url, options = {}) {
+    const { token, headers: extraHeaders, apiVersion = DEFAULT_API_VERSION, userAgent = DEFAULT_USER_AGENT, maxRetries = DEFAULT_MAX_RETRIES, retryableStatuses, maxDelayMs = 30_000, ...requestInit } = options;
+    const host = getUrlHost(url);
+    const githubDomain = isGitHubDomain(host);
+    const isApiHost = host === 'api.github.com';
+    const headers = new Headers(extraHeaders ?? {});
+    if (!headers.has('Accept'))
+        headers.set('Accept', 'application/vnd.github+json');
+    if (isApiHost && apiVersion && !headers.has('X-GitHub-Api-Version')) {
+        headers.set('X-GitHub-Api-Version', apiVersion);
+    }
+    if (!headers.has('User-Agent'))
+        headers.set('User-Agent', userAgent);
+    if (githubDomain && token && !headers.has('Authorization')) {
+        headers.set('Authorization', `Bearer ${token}`);
+    }
+    const statuses = new Set(retryableStatuses ?? Array.from(DEFAULT_RETRYABLE_STATUSES));
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const response = await fetch(url, {
+                ...requestInit,
+                headers,
+            });
+            const shouldRetry = statuses.has(response.status) || isRateLimited(response);
+            if (attempt < maxRetries && shouldRetry) {
+                const retryAfterMs = parseRetryAfterMs(response.headers);
+                const delayMs = Math.min(maxDelayMs, retryAfterMs ?? getBackoffDelayMs(attempt, maxDelayMs));
+                await sleep(delayMs);
+                continue;
+            }
+            return response;
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt >= maxRetries)
+                throw err;
+            await sleep(getBackoffDelayMs(attempt, maxDelayMs));
+        }
+    }
+    if (lastError instanceof Error)
+        throw lastError;
+    throw new Error('GitHub request failed');
+}
+
 const GITHUB_API$1 = 'https://api.github.com';
 const GITLAB_API = 'https://gitlab.com/api/v4';
+const MAX_GITHUB_SYMLINK_DEPTH = 8;
+class CachedGitHubRepoSnapshot {
+    owner;
+    repo;
+    explicitBranch;
+    repoInfoPromise;
+    branchPromise;
+    treePromise;
+    pathMapPromise;
+    blobBytesBySha = new Map();
+    fileBytesByPath = new Map();
+    constructor(owner, repo, branch) {
+        this.owner = owner;
+        this.repo = repo;
+        this.explicitBranch = branch;
+    }
+    matches(source) {
+        return source.platform === 'github'
+            && source.owner === this.owner
+            && source.repo === this.repo
+            && source.branch === this.explicitBranch;
+    }
+    getBranch() {
+        if (!this.branchPromise) {
+            this.branchPromise = this.explicitBranch
+                ? Promise.resolve(this.explicitBranch)
+                : this.getRepoInfo().then(info => info.default_branch);
+        }
+        return this.branchPromise;
+    }
+    getTree() {
+        if (!this.treePromise) {
+            this.treePromise = this.getBranch().then(branch => fetchGitHubTree(this.owner, this.repo, branch));
+        }
+        return this.treePromise;
+    }
+    getPathMap() {
+        if (!this.pathMapPromise) {
+            this.pathMapPromise = this.getTree().then((tree) => {
+                const map = new Map();
+                for (const item of tree) {
+                    map.set(normalizeRepoPath(item.path), item);
+                }
+                return map;
+            });
+        }
+        return this.pathMapPromise;
+    }
+    async getTreeItem(path) {
+        const pathMap = await this.getPathMap();
+        return pathMap.get(normalizeRepoPath(path)) ?? null;
+    }
+    getBlobBytesBySha(sha) {
+        return getOrCreate(this.blobBytesBySha, sha, () => fetchGitHubBlobBytesBySha(this.owner, this.repo, sha));
+    }
+    getFileBytes(path, item) {
+        const normalizedPath = normalizeRepoPath(path);
+        const cacheKey = item?.sha ? `sha:${item.sha}` : `path:${normalizedPath}`;
+        return getOrCreate(this.fileBytesByPath, cacheKey, async () => {
+            if (item?.sha && item.mode !== '120000') {
+                try {
+                    return await this.getBlobBytesBySha(item.sha);
+                }
+                catch {
+                    const branch = await this.getBranch();
+                    const file = await fetchGitHubFileBytes(this.owner, this.repo, normalizedPath, branch);
+                    if (file.sha && file.sha !== item.sha) {
+                        throw new Error(`GitHub file changed during fetch: ${normalizedPath}`);
+                    }
+                    return file.bytes;
+                }
+            }
+            const content = await fetchGitHubFileBytes(this.owner, this.repo, normalizedPath, await this.getBranch());
+            return content.bytes;
+        });
+    }
+    async getFileText(path, item) {
+        const bytes = await this.getFileBytes(path, item);
+        return bytes.toString('utf-8');
+    }
+    getRepoInfo() {
+        if (!this.repoInfoPromise) {
+            this.repoInfoPromise = fetchGitHubRepoInfo(this.owner, this.repo);
+        }
+        return this.repoInfoPromise;
+    }
+}
+function getOrCreate(map, key, factory) {
+    const existing = map.get(key);
+    if (existing) {
+        return existing;
+    }
+    const created = factory().catch((err) => {
+        map.delete(key);
+        throw err;
+    });
+    map.set(key, created);
+    return created;
+}
+function createGitHubRepoSnapshot(source) {
+    if (source.platform !== 'github') {
+        return null;
+    }
+    return new CachedGitHubRepoSnapshot(source.owner, source.repo, source.branch);
+}
+function getMatchingGitHubSnapshot(source, snapshot) {
+    if (!snapshot)
+        return null;
+    return snapshot.matches(source) ? snapshot : null;
+}
 /**
  * Get default branch for a GitHub repo
  */
 async function getGitHubDefaultBranch(owner, repo) {
-    const response = await fetch(`${GITHUB_API$1}/repos/${owner}/${repo}`, {
-        headers: {
-            'Accept': 'application/vnd.github+json',
-            'User-Agent': 'skillscat-cli/1.0'
-        }
+    const info = await fetchGitHubRepoInfo(owner, repo);
+    return info.default_branch;
+}
+async function fetchGitHubRepoInfo(owner, repo) {
+    const response = await githubRequest(`${GITHUB_API$1}/repos/${owner}/${repo}`, {
+        userAgent: 'skillscat-cli/1.0',
     });
     if (!response.ok) {
         throw new Error(`Repository not found: ${owner}/${repo}`);
     }
-    const data = await response.json();
-    return data.default_branch;
+    return await response.json();
 }
 /**
  * Get default branch for a GitLab repo
@@ -422,57 +853,75 @@ async function getGitLabDefaultBranch(owner, repo) {
  * Fetch repository tree from GitHub
  */
 async function fetchGitHubTree(owner, repo, branch) {
-    const response = await fetch(`${GITHUB_API$1}/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`, {
-        headers: {
-            'Accept': 'application/vnd.github+json',
-            'User-Agent': 'skillscat-cli/1.0'
-        }
+    const cachedTree = getCachedGitHubTree(owner, repo, branch);
+    if (cachedTree) {
+        return cachedTree;
+    }
+    const response = await githubRequest(`${GITHUB_API$1}/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`, {
+        userAgent: 'skillscat-cli/1.0',
     });
     if (!response.ok) {
         throw new Error(`Failed to fetch repository tree`);
     }
     const data = await response.json();
+    if (data.truncated) {
+        throw new Error(`Repository tree is too large to inspect via GitHub API (truncated response): ${owner}/${repo}. ` +
+            'Try installing a specific path instead.');
+    }
+    cacheGitHubTree(owner, repo, branch, data.tree);
     return data.tree;
 }
-/**
- * Fetch file content from GitHub
- */
-async function fetchGitHubFile(owner, repo, path, ref) {
-    const url = ref
-        ? `${GITHUB_API$1}/repos/${owner}/${repo}/contents/${path}?ref=${ref}`
-        : `${GITHUB_API$1}/repos/${owner}/${repo}/contents/${path}`;
-    const response = await fetch(url, {
-        headers: {
-            'Accept': 'application/vnd.github+json',
-            'User-Agent': 'skillscat-cli/1.0'
-        }
+async function fetchGitHubBlobBytesBySha(owner, repo, sha) {
+    const cachedBlob = getCachedGitHubBlob(sha);
+    if (cachedBlob) {
+        return cachedBlob;
+    }
+    const response = await githubRequest(`${GITHUB_API$1}/repos/${owner}/${repo}/git/blobs/${sha}`, {
+        userAgent: 'skillscat-cli/1.0',
     });
     if (!response.ok) {
-        throw new Error(`File not found: ${path}`);
+        throw new Error(`Failed to fetch blob: ${sha}`);
     }
     const data = await response.json();
-    if (data.encoding === 'base64' && data.content) {
-        return Buffer.from(data.content, 'base64').toString('utf-8');
+    if (data.encoding !== 'base64' || !data.content) {
+        throw new Error(`Unexpected blob encoding for ${sha}`);
     }
-    throw new Error(`Unexpected file encoding: ${data.encoding}`);
+    const decoded = Buffer.from(data.content.replace(/\n/g, ''), 'base64');
+    cacheGitHubBlob(sha, decoded);
+    return decoded;
 }
-/**
- * Get file SHA from GitHub (for update checking)
- */
-async function getGitHubFileSha(owner, repo, path, ref) {
+async function fetchGitHubFileBytes(owner, repo, path, ref) {
     const url = ref
         ? `${GITHUB_API$1}/repos/${owner}/${repo}/contents/${path}?ref=${ref}`
         : `${GITHUB_API$1}/repos/${owner}/${repo}/contents/${path}`;
-    const response = await fetch(url, {
-        headers: {
-            'Accept': 'application/vnd.github+json',
-            'User-Agent': 'skillscat-cli/1.0'
-        }
+    const response = await githubRequest(url, {
+        userAgent: 'skillscat-cli/1.0',
     });
-    if (!response.ok)
-        return null;
+    if (!response.ok) {
+        if (response.status === 404) {
+            throw new Error(`File not found: ${path}`);
+        }
+        throw new Error(`Failed to fetch file from GitHub (${response.status}): ${path}`);
+    }
     const data = await response.json();
-    return data.sha;
+    const contentType = data.type ?? 'file';
+    if (contentType !== 'file' && contentType !== 'symlink') {
+        throw new Error(`Unexpected GitHub content type for ${path}: ${String(data.type)}`);
+    }
+    if (data.encoding !== 'base64' || !data.content) {
+        throw new Error(`Unexpected file encoding: ${data.encoding}`);
+    }
+    return {
+        bytes: Buffer.from(data.content.replace(/\n/g, ''), 'base64'),
+        sha: data.sha,
+    };
+}
+async function fetchGitHubFileContent(owner, repo, path, ref) {
+    const file = await fetchGitHubFileBytes(owner, repo, path, ref);
+    return {
+        content: file.bytes.toString('utf-8'),
+        sha: file.sha,
+    };
 }
 /**
  * Fetch file content from GitLab
@@ -530,44 +979,66 @@ async function fetchGitLabTree(owner, repo, branch) {
 /**
  * Discover skills in a repository
  */
-async function discoverSkills(source) {
+async function discoverSkills(source, options) {
     const { platform, owner, repo, branch: sourceBranch, path: sourcePath } = source;
     const skills = [];
+    const matchedSnapshot = platform === 'github'
+        ? getMatchingGitHubSnapshot(source, options?.githubSnapshot)
+        : null;
+    const githubSnapshot = platform === 'github'
+        ? (matchedSnapshot ?? (!sourcePath ? createGitHubRepoSnapshot(source) : null))
+        : null;
     try {
         // Get default branch if not specified
         const branch = sourceBranch || (platform === 'github'
-            ? await getGitHubDefaultBranch(owner, repo)
+            ? await (githubSnapshot?.getBranch() ?? getGitHubDefaultBranch(owner, repo))
             : await getGitLabDefaultBranch(owner, repo));
         // If a specific path is provided, check only that path
         if (sourcePath) {
             const skillPath = sourcePath.endsWith('SKILL.md') ? sourcePath : `${sourcePath}/SKILL.md`;
             try {
-                const content = platform === 'github'
-                    ? await fetchGitHubFile(owner, repo, skillPath, branch)
-                    : await fetchGitLabFile(owner, repo, skillPath, branch);
+                let content;
+                let sha;
+                if (platform === 'github') {
+                    const treeItem = await githubSnapshot?.getTreeItem(skillPath) ?? null;
+                    if (treeItem?.type === 'blob') {
+                        content = await githubSnapshot.getFileText(skillPath, treeItem);
+                        sha = treeItem.sha || undefined;
+                    }
+                    else {
+                        const file = await fetchGitHubFileContent(owner, repo, skillPath, branch);
+                        content = file.content;
+                        sha = file.sha || undefined;
+                    }
+                }
+                else {
+                    content = await fetchGitLabFile(owner, repo, skillPath, branch);
+                }
                 const metadata = parseSkillFrontmatter(content);
                 if (metadata) {
-                    const sha = platform === 'github'
-                        ? await getGitHubFileSha(owner, repo, skillPath, branch)
-                        : undefined;
                     skills.push({
                         name: metadata.name,
                         description: metadata.description,
                         path: skillPath,
                         content,
-                        sha: sha || undefined,
+                        sha,
                         contentHash: calculateContentHash(content)
                     });
                 }
             }
-            catch {
-                // Skill not found at path
+            catch (err) {
+                if (isSourcePathNotFoundError(err)) {
+                    // Skill not found at path
+                }
+                else {
+                    throw err;
+                }
             }
             return skills;
         }
         // Fetch repository tree
         const tree = platform === 'github'
-            ? await fetchGitHubTree(owner, repo, branch)
+            ? await (githubSnapshot?.getTree() ?? fetchGitHubTree(owner, repo, branch))
             : await fetchGitLabTree(owner, repo, branch);
         // Find all SKILL.md files
         const skillFiles = tree.filter(item => item.path.endsWith('SKILL.md') &&
@@ -591,7 +1062,7 @@ async function discoverSkills(source) {
         for (const file of skillFiles) {
             try {
                 const content = platform === 'github'
-                    ? await fetchGitHubFile(owner, repo, file.path, branch)
+                    ? await githubSnapshot.getFileText(file.path, file)
                     : await fetchGitLabFile(owner, repo, file.path, branch);
                 const metadata = parseSkillFrontmatter(content);
                 if (metadata) {
@@ -615,6 +1086,153 @@ async function discoverSkills(source) {
         throw error;
     }
 }
+async function fetchSkillCompanionFilesWithOptions(source, skillFilePath, options) {
+    if (!skillFilePath || !skillFilePath.endsWith('SKILL.md')) {
+        return [];
+    }
+    if (source.platform !== 'github') {
+        return [];
+    }
+    const snapshot = getMatchingGitHubSnapshot(source, options?.githubSnapshot) ?? createGitHubRepoSnapshot(source);
+    if (!snapshot) {
+        throw new Error('Failed to initialize GitHub repository snapshot');
+    }
+    return fetchGitHubSkillCompanionFiles(source, skillFilePath, snapshot);
+}
+async function fetchGitHubSkillCompanionFiles(source, skillFilePath, snapshot) {
+    const tree = await snapshot.getTree();
+    const normalizedSkillFilePath = normalizeRepoPath(skillFilePath);
+    const skillDir = getRepoDirPath(normalizedSkillFilePath);
+    const nestedSkillDirs = getNestedSkillDirectories(tree, normalizedSkillFilePath);
+    const pathMap = await snapshot.getPathMap();
+    const files = [];
+    for (const item of tree) {
+        const repoPath = normalizeRepoPath(item.path);
+        if (item.type !== 'blob')
+            continue;
+        if (repoPath === normalizedSkillFilePath)
+            continue;
+        if (!isPathWithinDirectory(repoPath, skillDir))
+            continue;
+        if (isPathInNestedSkillDirectory(repoPath, nestedSkillDirs))
+            continue;
+        const relativePath = toRelativeSkillPath(repoPath, skillDir);
+        if (!relativePath)
+            continue;
+        const content = await resolveGitHubBlobOrSymlinkContent({
+            snapshot,
+            item,
+            currentPath: repoPath,
+            pathMap,
+            depth: 0,
+            visited: new Set(),
+        });
+        if (!content)
+            continue;
+        files.push({ path: relativePath, content });
+    }
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return files;
+}
+async function resolveGitHubBlobOrSymlinkContent({ snapshot, item, currentPath, pathMap, depth, visited, }) {
+    const symlinkMode = item.mode === '120000';
+    if (!symlinkMode) {
+        if (!item.sha)
+            return null;
+        return snapshot.getFileBytes(currentPath, item);
+    }
+    if (depth >= MAX_GITHUB_SYMLINK_DEPTH) {
+        throw new Error(`Symlink resolution depth exceeded for ${currentPath}`);
+    }
+    if (visited.has(currentPath)) {
+        throw new Error(`Symlink loop detected at ${currentPath}`);
+    }
+    const nextVisited = new Set(visited);
+    nextVisited.add(currentPath);
+    const targetBlob = await snapshot.getBlobBytesBySha(item.sha);
+    const targetPathRaw = targetBlob.toString('utf-8').replace(/\r?\n$/, '');
+    const resolvedTargetPath = resolveRepoSymlinkTarget(currentPath, targetPathRaw);
+    if (!resolvedTargetPath) {
+        return null;
+    }
+    const targetItem = pathMap.get(resolvedTargetPath);
+    if (!targetItem || targetItem.type !== 'blob') {
+        return null;
+    }
+    return resolveGitHubBlobOrSymlinkContent({
+        snapshot,
+        item: targetItem,
+        currentPath: resolvedTargetPath,
+        pathMap,
+        depth: depth + 1,
+        visited: nextVisited,
+    });
+}
+function getNestedSkillDirectories(tree, currentSkillFilePath) {
+    const currentSkillDir = getRepoDirPath(currentSkillFilePath);
+    const nested = new Set();
+    for (const item of tree) {
+        const itemPath = normalizeRepoPath(item.path);
+        if (item.type !== 'blob' || !itemPath.endsWith('/SKILL.md'))
+            continue;
+        if (itemPath === currentSkillFilePath)
+            continue;
+        const dir = getRepoDirPath(itemPath);
+        if (dir === currentSkillDir)
+            continue;
+        if (!isPathWithinDirectory(dir, currentSkillDir))
+            continue;
+        nested.add(dir);
+    }
+    return Array.from(nested);
+}
+function isPathInNestedSkillDirectory(path, nestedSkillDirs) {
+    for (const nestedDir of nestedSkillDirs) {
+        if (isPathWithinDirectory(path, nestedDir)) {
+            return true;
+        }
+    }
+    return false;
+}
+function normalizeRepoPath(path) {
+    const normalized = path.replace(/^\/+|\/+$/g, '');
+    if (!normalized)
+        return '';
+    return posix.normalize(normalized).replace(/^\.\//, '');
+}
+function getRepoDirPath(filePath) {
+    const dir = posix.dirname(filePath);
+    return dir === '.' ? '' : dir;
+}
+function isPathWithinDirectory(path, dir) {
+    if (!dir)
+        return true;
+    return path === dir || path.startsWith(`${dir}/`);
+}
+function toRelativeSkillPath(repoPath, skillDir) {
+    if (!skillDir)
+        return repoPath;
+    if (!repoPath.startsWith(`${skillDir}/`))
+        return '';
+    return repoPath.slice(skillDir.length + 1);
+}
+function resolveRepoSymlinkTarget(currentPath, targetPath) {
+    if (!targetPath)
+        return null;
+    const normalizedInput = targetPath.replace(/\\/g, '/');
+    if (normalizedInput.startsWith('/'))
+        return null;
+    const currentDir = getRepoDirPath(currentPath);
+    const resolved = normalizeRepoPath(posix.join(currentDir, normalizedInput));
+    if (!resolved)
+        return null;
+    if (resolved === '..' || resolved.startsWith('../'))
+        return null;
+    return resolved;
+}
+function isSourcePathNotFoundError(error) {
+    return error instanceof Error && error.message.startsWith('File not found:');
+}
 /**
  * Fetch a single skill by name from a repository
  */
@@ -1075,11 +1693,8 @@ async function fetchFromGitHub(owner, repo, skillPath) {
     const url = `${GITHUB_API}/repos/${owner}/${repo}/contents/${path}`;
     verboseLog(`Fetching from GitHub: ${url}`);
     try {
-        const response = await fetch(url, {
-            headers: {
-                'Accept': 'application/vnd.github+json',
-                'User-Agent': 'skillscat-cli/0.1.0'
-            }
+        const response = await githubRequest(url, {
+            userAgent: 'skillscat-cli/0.1.0',
         });
         if (!response.ok) {
             verboseLog(`GitHub fetch failed: ${response.status}`);
@@ -1167,6 +1782,110 @@ async function fetchSkill(skillIdentifier) {
         throw error;
     }
 }
+async function fetchSkillsByRepo(owner, repo, options) {
+    const registryUrl = getRegistryUrl();
+    const path = options?.path?.replace(/^\/+|\/+$/g, '');
+    const params = new URLSearchParams();
+    if (path)
+        params.set('path', path);
+    const query = params.toString();
+    const url = `${registryUrl}/repo/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}${query ? `?${query}` : ''}`;
+    const headers = await getAuthHeaders();
+    const startTime = Date.now();
+    verboseRequest('GET', url, headers);
+    try {
+        const response = await fetch(url, { headers });
+        verboseResponse(response.status, response.statusText, Date.now() - startTime);
+        if (!response.ok) {
+            if (response.status === 404) {
+                return { skills: [], total: 0 };
+            }
+            const parsed = parseHttpError(response.status, response.statusText);
+            throw new Error(parsed.message);
+        }
+        return await response.json();
+    }
+    catch (error) {
+        if (error instanceof Error && !error.message.includes('Rate limit')) {
+            const networkError = parseNetworkError(error);
+            throw new Error(networkError.message);
+        }
+        throw error;
+    }
+}
+
+const CLI_USER_AGENT = 'skillscat-cli/0.1.0';
+const BACKGROUND_SUBMIT_ENV = 'SKILLSCAT_BACKGROUND_SUBMIT';
+const BACKGROUND_SUBMIT_DISABLE_ENV = 'SKILLSCAT_DISABLE_BACKGROUND_SUBMIT';
+function normalizeSkillPath$1(path) {
+    if (!path)
+        return undefined;
+    const normalized = path.replace(/^\/+|\/+$/g, '');
+    if (!normalized)
+        return undefined;
+    const pathWithoutSkillFile = normalized.replace(/(?:^|\/)SKILL\.md$/i, '');
+    return pathWithoutSkillFile || undefined;
+}
+function buildGitHubRepoUrl(source) {
+    const base = `https://github.com/${source.owner}/${source.repo}`;
+    const path = source.path?.replace(/^\/+/, '');
+    if (!path)
+        return base;
+    return `${base}/${path}`;
+}
+function envFlagFalse(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === '0' || normalized === 'false' || normalized === 'off' || normalized === 'no';
+}
+function envFlagTrue(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'on' || normalized === 'yes';
+}
+function isBackgroundSubmitEnabled() {
+    if (envFlagTrue(process.env[BACKGROUND_SUBMIT_DISABLE_ENV])) {
+        return false;
+    }
+    if (process.env[BACKGROUND_SUBMIT_ENV] !== undefined) {
+        return !envFlagFalse(process.env[BACKGROUND_SUBMIT_ENV]);
+    }
+    return true;
+}
+/**
+ * Best-effort, fire-and-forget anonymous repo submission for indexing.
+ * Intentionally does not await the response and fails silently.
+ */
+function submitRepoForIndexingInBackground(source) {
+    if (source.platform !== 'github')
+        return;
+    if (!isBackgroundSubmitEnabled())
+        return;
+    try {
+        const baseUrl = getBaseUrl();
+        const payload = {
+            url: buildGitHubRepoUrl(source),
+        };
+        const normalizedSkillPath = normalizeSkillPath$1(source.path);
+        if (normalizedSkillPath) {
+            payload.skillPath = normalizedSkillPath;
+        }
+        void fetch(`${baseUrl}/api/submit`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': CLI_USER_AGENT,
+                'X-Skillscat-Background-Submit': '1',
+            },
+            body: JSON.stringify(payload),
+        }).catch(() => { });
+    }
+    catch {
+        // Intentionally fail silent.
+    }
+}
 
 function sanitizeSkillDirName(skillName) {
     const sanitized = skillName
@@ -1573,8 +2292,9 @@ function box(content, title) {
     console.log(pc.dim(bottom));
 }
 
+const COMPANION_MANIFEST_FILE = '.skillscat-companion-files.json';
+const COMPANION_MANIFEST_VERSION = 1;
 async function add(source, options) {
-    // Parse source
     const repoSource = parseSource(source);
     if (!repoSource) {
         error('Invalid source. Supported formats:');
@@ -1584,84 +2304,58 @@ async function add(source, options) {
         process.exit(1);
     }
     const sourceLabel = `${repoSource.owner}/${repoSource.repo}`;
+    const isExplicitGitHubRefSource = repoSource.platform === 'github' && repoSource.hasExplicitRef === true;
+    const githubSnapshot = createGitHubRepoSnapshot(repoSource);
+    if (isExplicitGitHubRefSource) {
+        verboseLog(`Explicit GitHub ${repoSource.refKind || 'ref'} source detected; using direct GitHub install path`);
+    }
     info$1(`Fetching skills from ${pc.cyan(sourceLabel)}...`);
-    // Check cache first for each potential skill path
     const cached = getCachedSkill(repoSource.owner, repoSource.repo, repoSource.path);
     if (cached && !options.force) {
         verboseLog('Found cached skill content');
     }
-    // Discover skills
     const discoverSpinner = spinner('Discovering skills');
-    let skills;
-    let installSource = repoSource;
-    let trackingSlug = `${repoSource.owner}/${repoSource.repo}`;
-    let updateStrategy = 'git';
-    let cacheOwner = repoSource.owner;
-    let cacheRepo = repoSource.repo;
-    let cachePath = repoSource.path;
-    let registrySlug;
+    let resolvedSkills = [];
     try {
-        skills = await discoverSkills(repoSource);
+        resolvedSkills = await resolveInstallSkills({
+            sourceInput: source,
+            repoSource,
+            requestedSkillNames: options.skill ?? [],
+            explicitRefBypassRegistry: isExplicitGitHubRefSource,
+            githubSnapshot,
+        });
     }
     catch (err) {
-        // GitHub/GitLab discovery failed — try the registry as fallback
-        verboseLog(`Git discovery failed: ${err instanceof Error ? err.message : 'unknown'}`);
-        verboseLog('Trying registry fallback...');
-        try {
-            const registrySkill = await fetchSkill(source);
-            if (registrySkill && registrySkill.content) {
-                const parsedGitSource = getSourceFromRegistrySkill(registrySkill);
-                installSource = parsedGitSource ?? installSource;
-                updateStrategy = 'registry';
-                registrySlug = getRegistrySlug$1(registrySkill, source);
-                trackingSlug = registrySlug;
-                if (parsedGitSource) {
-                    cacheOwner = parsedGitSource.owner;
-                    cacheRepo = parsedGitSource.repo;
-                    cachePath = parsedGitSource.path || registrySkill.skillPath;
-                }
-                else if (registrySkill.owner && registrySkill.repo) {
-                    cacheOwner = registrySkill.owner;
-                    cacheRepo = registrySkill.repo;
-                    cachePath = registrySkill.skillPath;
-                }
-                skills = [{
-                        name: registrySkill.name,
-                        description: registrySkill.description || '',
-                        path: registrySkill.skillPath
-                            ? (registrySkill.skillPath.endsWith('SKILL.md') ? registrySkill.skillPath : `${registrySkill.skillPath}/SKILL.md`)
-                            : 'SKILL.md',
-                        content: registrySkill.content,
-                        contentHash: registrySkill.contentHash,
-                    }];
-            }
-            else {
-                discoverSpinner.stop(false);
-                error(err instanceof Error ? err.message : 'Failed to discover skills');
-                process.exit(1);
-            }
-        }
-        catch {
-            discoverSpinner.stop(false);
-            error(err instanceof Error ? err.message : 'Failed to discover skills');
-            process.exit(1);
-        }
+        discoverSpinner.stop(false);
+        error(err instanceof Error ? err.message : 'Failed to discover skills');
+        process.exit(1);
     }
     discoverSpinner.stop(true);
-    if (skills.length === 0) {
+    if (resolvedSkills.length === 0) {
         warn('No skills found in this repository.');
         console.log(pc.dim('Make sure the repository contains SKILL.md files with valid frontmatter.'));
         process.exit(1);
     }
+    const missingRequestedNames = getMissingRequestedNames(options.skill ?? [], resolvedSkills);
+    if (missingRequestedNames.length > 0) {
+        error(`No skills found matching: ${missingRequestedNames.join(', ')}`);
+        if (resolvedSkills.length > 0) {
+            console.log(pc.dim('Available skills:'));
+            for (const entry of resolvedSkills) {
+                console.log(pc.dim(`  - ${entry.skill.name}`));
+            }
+        }
+        process.exit(1);
+    }
     // List mode - just show skills and exit
     if (options.list) {
         console.log();
-        console.log(pc.bold(`Found ${skills.length} skill(s):`));
+        console.log(pc.bold(`Found ${resolvedSkills.length} skill(s):`));
         console.log();
-        for (const skill of skills) {
-            console.log(`  ${pc.cyan(skill.name)}`);
-            console.log(`  ${pc.dim(skill.description)}`);
-            console.log(`  ${pc.dim(`Path: ${skill.path}`)}`);
+        for (const entry of resolvedSkills) {
+            console.log(`  ${pc.cyan(entry.skill.name)}`);
+            console.log(`  ${pc.dim(entry.skill.description)}`);
+            console.log(`  ${pc.dim(`Path: ${entry.skill.path}`)}`);
             console.log();
         }
         console.log(pc.dim('─'.repeat(50)));
@@ -1669,19 +2363,22 @@ async function add(source, options) {
         console.log(`  ${pc.cyan(`npx skillscat add ${source}`)}`);
         return;
     }
-    // Filter skills by name if specified
-    let selectedSkills = skills;
+    // Final name filter (safety net after mixed registry+git resolution)
+    let selectedEntries = resolvedSkills;
     if (options.skill && options.skill.length > 0) {
-        selectedSkills = skills.filter(s => options.skill.some(name => s.name.toLowerCase() === name.toLowerCase()));
-        if (selectedSkills.length === 0) {
+        selectedEntries = resolvedSkills.filter((entry) => options.skill.some((name) => entry.skill.name.toLowerCase() === name.toLowerCase()));
+        if (selectedEntries.length === 0) {
             error(`No skills found matching: ${options.skill.join(', ')}`);
             console.log(pc.dim('Available skills:'));
-            for (const skill of skills) {
-                console.log(pc.dim(`  - ${skill.name}`));
+            for (const entry of resolvedSkills) {
+                console.log(pc.dim(`  - ${entry.skill.name}`));
             }
             process.exit(1);
         }
     }
+    else if (!options.yes && resolvedSkills.length > 1) {
+        selectedEntries = [await selectSingleSkillInteractive(resolvedSkills)];
+    }
     // Detect or select agents
     let targetAgents;
     if (options.agent && options.agent.length > 0) {
@@ -1696,10 +2393,8 @@ async function add(source, options) {
         }
     }
     else {
-        // Auto-detect installed agents
         targetAgents = detectInstalledAgents();
         if (targetAgents.length === 0) {
-            // No agents detected, ask user
             if (!options.yes) {
                 console.log();
                 warn('No coding agents detected.');
@@ -1714,10 +2409,10 @@ async function add(source, options) {
                     targetAgents = AGENTS;
                 }
                 else {
-                    const indices = response.split(',').map(s => parseInt(s.trim()) - 1);
+                    const indices = response.split(',').map((s) => parseInt(s.trim()) - 1);
                     targetAgents = indices
-                        .filter(i => i >= 0 && i < AGENTS.length)
-                        .map(i => AGENTS[i]);
+                        .filter((i) => i >= 0 && i < AGENTS.length)
+                        .map((i) => AGENTS[i]);
                 }
                 if (targetAgents.length === 0) {
                     error('No agents selected.');
@@ -1725,20 +2420,19 @@ async function add(source, options) {
                 }
             }
             else {
-                // Default to Claude Code in --yes mode
-                targetAgents = AGENTS.filter(a => a.id === 'claude-code');
+                targetAgents = AGENTS.filter((a) => a.id === 'claude-code');
             }
         }
     }
     const isGlobal = options.global ?? false;
     const locationLabel = isGlobal ? 'global' : 'project';
     console.log();
-    console.log(pc.bold(`Installing ${selectedSkills.length} skill(s) to ${targetAgents.length} agent(s):`));
+    console.log(pc.bold(`Installing ${selectedEntries.length} skill(s) to ${targetAgents.length} agent(s):`));
     console.log();
-    // Show what will be installed
-    for (const skill of selectedSkills) {
-        console.log(`  ${pc.green('•')} ${pc.bold(skill.name)}`);
-        console.log(`    ${pc.dim(skill.description)}`);
+    for (const entry of selectedEntries) {
+        console.log(`  ${pc.green('•')} ${pc.bold(entry.skill.name)}`);
+        console.log(`    ${pc.dim(entry.skill.description)}`);
+        console.log(`    ${pc.dim(`Source: ${entry.updateStrategy === 'registry' ? 'registry' : 'github'}`)}`);
     }
     console.log();
     console.log(pc.dim('Target agents:'));
@@ -1747,7 +2441,6 @@ async function add(source, options) {
         console.log(`  ${pc.cyan('•')} ${agent.name} → ${pc.dim(path)}`);
     }
     console.log();
-    // Confirmation
     if (!options.yes) {
         const confirm = await prompt(`Install to ${locationLabel} directory? [Y/n] `);
         if (confirm.toLowerCase() === 'n') {
@@ -1755,19 +2448,30 @@ async function add(source, options) {
             process.exit(0);
         }
     }
-    // Install skills
+    const prepareSpinner = spinner('Preparing skill files');
+    try {
+        await hydrateCompanionFilesForInstall(selectedEntries, githubSnapshot);
+        prepareSpinner.stop(true);
+    }
+    catch (err) {
+        prepareSpinner.stop(false);
+        error(err instanceof Error ? err.message : 'Failed to prepare skill files');
+        process.exit(1);
+    }
     let installed = 0;
     let skipped = 0;
-    for (const skill of selectedSkills) {
+    let wroteGitDiscoveredSkill = false;
+    for (const entry of selectedEntries) {
+        const { skill } = entry;
         const activeAgentIds = new Set();
         for (const agent of targetAgents) {
             const skillDir = getSkillPath(agent, skill.name, isGlobal);
             const skillFile = join(skillDir, 'SKILL.md');
             const existedBefore = existsSync(skillFile);
-            // Check if already installed
             if (existedBefore && !options.force) {
                 const existingContent = readFileSync(skillFile, 'utf-8');
-                if (existingContent === skill.content) {
+                if (existingContent === skill.content
+                    && companionFilesAreUpToDate(skillDir, skill, { skipValidation: entry.companionFilesHydrationFailed === true })) {
                     skipped++;
                     activeAgentIds.add(agent.id);
                     continue;
@@ -1782,18 +2486,20 @@ async function add(source, options) {
                     }
                 }
             }
-            // Create directory and write file
             try {
                 mkdirSync(dirname(skillFile), { recursive: true });
                 writeFileSync(skillFile, skill.content, 'utf-8');
+                if (!entry.companionFilesHydrationFailed) {
+                    syncCompanionFiles(skillDir, skill);
+                }
                 installed++;
                 activeAgentIds.add(agent.id);
-                // Cache the skill content
-                if (cacheOwner && cacheRepo) {
-                    const cacheSkillPath = skill.path !== 'SKILL.md'
-                        ? skill.path.replace(/\/SKILL\.md$/, '')
-                        : cachePath?.replace(/\/SKILL\.md$/, '');
-                    cacheSkill(cacheOwner, cacheRepo, skill.content, updateStrategy === 'registry' ? 'registry' : 'github', cacheSkillPath, skill.sha);
+                if (entry.updateStrategy === 'git') {
+                    wroteGitDiscoveredSkill = true;
+                }
+                if (entry.cacheOwner && entry.cacheRepo) {
+                    const cacheSkillPath = normalizeSkillPath(entry.cachePath ?? skill.path);
+                    cacheSkill(entry.cacheOwner, entry.cacheRepo, skill.content, entry.updateStrategy === 'registry' ? 'registry' : 'github', cacheSkillPath, skill.sha);
                     verboseLog(`Cached skill: ${skill.name}`);
                 }
             }
@@ -1808,20 +2514,26 @@ async function add(source, options) {
             recordInstallation({
                 name: skill.name,
                 description: skill.description,
-                source: installSource,
-                registrySlug,
-                updateStrategy,
+                source: entry.installSource,
+                registrySlug: entry.registrySlug,
+                updateStrategy: entry.updateStrategy,
                 agents: Array.from(activeAgentIds),
                 global: isGlobal,
                 installedAt: Date.now(),
                 sha: skill.sha,
                 path: skill.path,
-                contentHash: skill.contentHash
+                contentHash: skill.contentHash,
             });
-            // Track installation on server (non-blocking, fail-silent)
-            trackInstallation(trackingSlug).catch(() => { });
+            trackInstallation(entry.trackingSlug).catch(() => { });
         }
     }
+    if (installed > 0 &&
+        wroteGitDiscoveredSkill &&
+        repoSource.platform === 'github' &&
+        !isExplicitGitHubRefSource &&
+        isDefaultRegistry()) {
+        submitRepoForIndexingInBackground(repoSource);
+    }
     console.log();
     if (installed > 0) {
         success(`Installed ${installed} skill(s) successfully!`);
@@ -1833,6 +2545,382 @@ async function add(source, options) {
     console.log(pc.dim('Skills are now available in your coding agents.'));
     console.log(pc.dim('Restart your agent or start a new session to use them.'));
 }
+async function resolveInstallSkills({ sourceInput, repoSource, requestedSkillNames, explicitRefBypassRegistry, githubSnapshot, }) {
+    const requestedNamesLower = new Set(requestedSkillNames.map((name) => name.toLowerCase()));
+    const needsRegistryFirst = repoSource.platform === 'github' && !explicitRefBypassRegistry;
+    let resolved = [];
+    let registryRepoMatchesFound = false;
+    let registrySummariesNeedingGitBackfill = [];
+    if (needsRegistryFirst) {
+        try {
+            const registryRepo = await fetchSkillsByRepo(repoSource.owner, repoSource.repo, {
+                path: normalizeSkillPath(repoSource.path),
+            });
+            if (registryRepo.skills.length > 0) {
+                registryRepoMatchesFound = true;
+                let summaries = registryRepo.skills;
+                if (repoSource.path) {
+                    const normalizedPath = normalizeSkillPath(repoSource.path);
+                    summaries = summaries.filter((item) => normalizeSkillPath(item.skillPath) === normalizedPath);
+                }
+                let selectedSummaries = summaries;
+                if (requestedNamesLower.size > 0) {
+                    selectedSummaries = summaries.filter((item) => requestedNamesLower.has(item.name.toLowerCase()));
+                }
+                if (selectedSummaries.length > 0) {
+                    const registryFetch = await fetchRegistryResolvedSkills(selectedSummaries, sourceInput, repoSource);
+                    resolved.push(...registryFetch.resolved);
+                    registrySummariesNeedingGitBackfill = registryFetch.missingSummaries;
+                }
+            }
+        }
+        catch (err) {
+            verboseLog(`Registry repo lookup failed: ${err instanceof Error ? err.message : 'unknown'}`);
+        }
+    }
+    const missingRequestedNames = requestedSkillNames.filter((name) => !resolved.some((entry) => entry.skill.name.toLowerCase() === name.toLowerCase()));
+    const shouldRunGitDiscovery = explicitRefBypassRegistry ||
+        repoSource.platform !== 'github' ||
+        !registryRepoMatchesFound ||
+        resolved.length === 0 ||
+        missingRequestedNames.length > 0 ||
+        registrySummariesNeedingGitBackfill.length > 0 ||
+        (repoSource.path && resolved.length === 0);
+    if (shouldRunGitDiscovery) {
+        try {
+            const gitSkills = await discoverSkills(repoSource, { githubSnapshot });
+            let gitResolved = gitSkills.map((skill) => toGitResolvedSkill(skill, repoSource));
+            if (missingRequestedNames.length > 0) {
+                const missingLower = new Set(missingRequestedNames.map((name) => name.toLowerCase()));
+                gitResolved = gitResolved.filter((entry) => missingLower.has(entry.skill.name.toLowerCase()));
+            }
+            else if (requestedNamesLower.size > 0 && resolved.length === 0) {
+                gitResolved = gitResolved.filter((entry) => requestedNamesLower.has(entry.skill.name.toLowerCase()));
+            }
+            else if (registrySummariesNeedingGitBackfill.length > 0) {
+                const backfillKeys = new Set(registrySummariesNeedingGitBackfill.map((summary) => getRegistrySummaryIdentityKey(summary)));
+                gitResolved = gitResolved.filter((entry) => backfillKeys.has(getResolvedSkillIdentityKey(entry)));
+            }
+            resolved = mergeResolvedSkills(resolved, gitResolved);
+        }
+        catch (err) {
+            if (explicitRefBypassRegistry) {
+                throw err;
+            }
+            // Fallback: preserve existing behavior for registry slugs or private skills.
+            if (resolved.length === 0 && true) {
+                const registrySkill = await fetchSkill(sourceInput).catch(() => null);
+                if (registrySkill?.content) {
+                    resolved.push(toRegistryResolvedSkill(registrySkill, sourceInput, repoSource));
+                    return mergeResolvedSkills([], resolved);
+                }
+            }
+            // If some registry skills were already resolved (partial hit), keep them.
+            if (resolved.length > 0) {
+                if (getMissingRequestedNames(requestedSkillNames, resolved).length > 0) {
+                    throw err;
+                }
+                return mergeResolvedSkills([], resolved);
+            }
+            throw err;
+        }
+    }
+    if (requestedNamesLower.size > 0 && resolved.length > 0) {
+        resolved = resolved.filter((entry) => requestedNamesLower.has(entry.skill.name.toLowerCase()));
+    }
+    return mergeResolvedSkills([], resolved);
+}
+async function fetchRegistryResolvedSkills(summaries, sourceInput, repoSource) {
+    const resolved = [];
+    const missingSummaries = [];
+    for (const summary of summaries) {
+        if (!summary.slug)
+            continue;
+        try {
+            const full = await fetchSkill(summary.slug);
+            if (!full?.content) {
+                missingSummaries.push(summary);
+                continue;
+            }
+            resolved.push(toRegistryResolvedSkill(full, sourceInput, repoSource));
+        }
+        catch (err) {
+            verboseLog(`Failed to fetch registry skill ${summary.slug}: ${err instanceof Error ? err.message : 'unknown'}`);
+            missingSummaries.push(summary);
+        }
+    }
+    return {
+        resolved,
+        missingSummaries,
+    };
+}
+function mergeResolvedSkills(existing, incoming) {
+    const merged = [...existing];
+    const seen = new Set(existing.map((entry) => getResolvedSkillIdentityKey(entry)));
+    for (const entry of incoming) {
+        const key = getResolvedSkillIdentityKey(entry);
+        if (seen.has(key)) {
+            continue;
+        }
+        merged.push(entry);
+        seen.add(key);
+    }
+    return merged;
+}
+function getResolvedSkillIdentityKey(entry) {
+    const normalizedPath = normalizeSkillPath(entry.skill.path);
+    if (normalizedPath)
+        return `path:${normalizedPath.toLowerCase()}`;
+    return `name:${entry.skill.name.toLowerCase()}`;
+}
+function getRegistrySummaryIdentityKey(summary) {
+    const normalizedPath = normalizeSkillPath(summary.skillPath);
+    if (normalizedPath)
+        return `path:${normalizedPath.toLowerCase()}`;
+    return `name:${summary.name.toLowerCase()}`;
+}
+function toGitResolvedSkill(skill, repoSource) {
+    return {
+        skill,
+        installSource: repoSource,
+        updateStrategy: 'git',
+        trackingSlug: `${repoSource.owner}/${repoSource.repo}`,
+        cacheOwner: repoSource.owner,
+        cacheRepo: repoSource.repo,
+        cachePath: normalizeSkillPath(skill.path) || normalizeSkillPath(repoSource.path),
+    };
+}
+function toRegistryResolvedSkill(skill, fallbackInput, fallbackSource) {
+    const parsedGitSource = getSourceFromRegistrySkill(skill) ?? fallbackSource;
+    const registrySlug = getRegistrySlug$1(skill, fallbackInput);
+    const normalizedSkillPath = normalizeSkillPath(skill.skillPath);
+    const skillPath = toSkillFilePath(normalizedSkillPath);
+    return {
+        skill: {
+            name: skill.name,
+            description: skill.description || '',
+            path: skillPath,
+            content: skill.content,
+            contentHash: skill.contentHash,
+        },
+        installSource: parsedGitSource,
+        registrySlug,
+        updateStrategy: 'registry',
+        trackingSlug: registrySlug,
+        cacheOwner: parsedGitSource?.owner || skill.owner,
+        cacheRepo: parsedGitSource?.repo || skill.repo,
+        cachePath: normalizeSkillPath(parsedGitSource?.path) || normalizedSkillPath,
+    };
+}
+async function selectSingleSkillInteractive(entries) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        error('Multiple skills found but no interactive terminal is available.');
+        console.log(pc.dim('Use `--yes` to install all skills, or `-s <name>` to choose a specific skill.'));
+        process.exit(1);
+    }
+    const inquirer = await import('inquirer');
+    const answer = await inquirer.default.prompt([
+        {
+            type: 'list',
+            name: 'skillKey',
+            message: 'Multiple skills found. Select one to install:',
+            choices: entries.map((entry, index) => ({
+                name: `${entry.skill.name}  ${pc.dim(`(${entry.skill.path})`)}${entry.skill.description ? ` - ${entry.skill.description}` : ''}`,
+                value: String(index),
+            })),
+        },
+    ]);
+    const selected = entries[Number.parseInt(answer.skillKey, 10)];
+    if (!selected) {
+        error('No skill selected.');
+        process.exit(1);
+    }
+    return selected;
+}
+async function hydrateCompanionFilesForInstall(entries, githubSnapshot) {
+    for (const entry of entries) {
+        if (entry.skill.companionFiles)
+            continue;
+        const installSource = entry.installSource;
+        if (!installSource || installSource.platform !== 'github') {
+            continue;
+        }
+        try {
+            entry.skill.companionFiles = await fetchSkillCompanionFilesWithOptions(installSource, entry.skill.path, { githubSnapshot });
+            entry.companionFilesHydrationFailed = false;
+        }
+        catch (err) {
+            verboseLog(`Failed to fetch companion files for ${entry.skill.name}: ${err instanceof Error ? err.message : 'unknown'}`);
+            entry.companionFilesHydrationFailed = true;
+        }
+    }
+}
+function companionFilesAreUpToDate(skillDir, skill, options) {
+    if (options?.skipValidation) {
+        return true;
+    }
+    const expectedPaths = getExpectedCompanionPaths(skill);
+    const manifestPaths = readCompanionManifest(skillDir);
+    if (expectedPaths.length === 0) {
+        if (manifestPaths && manifestPaths.length > 0) {
+            return false;
+        }
+        return true;
+    }
+    // Force one rewrite for legacy installs without manifest so we can record managed files.
+    if (!manifestPaths) {
+        return false;
+    }
+    if (!sameStringArrays(manifestPaths, expectedPaths)) {
+        return false;
+    }
+    for (const file of skill.companionFiles ?? []) {
+        const destination = join(skillDir, file.path);
+        if (!existsSync(destination)) {
+            return false;
+        }
+        try {
+            const existing = readFileSync(destination);
+            const expected = Buffer.from(file.content);
+            if (!existing.equals(expected)) {
+                return false;
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+function syncCompanionFiles(skillDir, skill) {
+    const expectedFiles = getExpectedCompanionFiles(skill);
+    const expectedPaths = expectedFiles.map((file) => file.path);
+    const previousPaths = readCompanionManifest(skillDir) ?? [];
+    for (const stalePath of previousPaths) {
+        if (expectedPaths.includes(stalePath)) {
+            continue;
+        }
+        const destination = join(skillDir, stalePath);
+        try {
+            rmSync(destination, { force: true });
+            pruneEmptyParentDirs(skillDir, destination);
+        }
+        catch {
+            // Best-effort cleanup only; write phase below still proceeds.
+        }
+    }
+    for (const file of expectedFiles) {
+        const destination = join(skillDir, file.path);
+        mkdirSync(dirname(destination), { recursive: true });
+        writeFileSync(destination, Buffer.from(file.content));
+    }
+    writeCompanionManifest(skillDir, expectedPaths);
+}
+function getExpectedCompanionFiles(skill) {
+    const files = skill.companionFiles ?? [];
+    const deduped = new Map();
+    for (const file of files) {
+        const normalized = normalizeCompanionRelativePath(file.path);
+        if (!normalized)
+            continue;
+        deduped.set(normalized, file.content);
+    }
+    return Array.from(deduped.entries())
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([path, content]) => ({ path, content }));
+}
+function getExpectedCompanionPaths(skill) {
+    return getExpectedCompanionFiles(skill).map((file) => file.path);
+}
+function readCompanionManifest(skillDir) {
+    const manifestPath = join(skillDir, COMPANION_MANIFEST_FILE);
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        if (parsed.version !== COMPANION_MANIFEST_VERSION || !Array.isArray(parsed.files)) {
+            return null;
+        }
+        const validFiles = parsed.files
+            .map((value) => (typeof value === 'string' ? normalizeCompanionRelativePath(value) : ''))
+            .filter((value) => Boolean(value));
+        validFiles.sort((a, b) => a.localeCompare(b));
+        return Array.from(new Set(validFiles));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCompanionManifest(skillDir, files) {
+    const manifestPath = join(skillDir, COMPANION_MANIFEST_FILE);
+    const normalizedFiles = Array.from(new Set(files.map(normalizeCompanionRelativePath).filter(Boolean)))
+        .sort((a, b) => a.localeCompare(b));
+    if (normalizedFiles.length === 0) {
+        try {
+            rmSync(manifestPath, { force: true });
+        }
+        catch {
+            // Ignore cleanup failures.
+        }
+        return;
+    }
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(manifestPath, JSON.stringify({
+        version: COMPANION_MANIFEST_VERSION,
+        files: normalizedFiles,
+    }, null, 2));
+}
+function normalizeCompanionRelativePath(path) {
+    const normalized = path.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+    if (!normalized)
+        return '';
+    const segments = normalized.split('/');
+    if (segments.some((segment) => !segment || segment === '.' || segment === '..')) {
+        return '';
+    }
+    if (segments.includes(COMPANION_MANIFEST_FILE)) {
+        return '';
+    }
+    return segments.join('/');
+}
+function pruneEmptyParentDirs(skillDir, filePath) {
+    let current = dirname(filePath);
+    while (current && current !== skillDir && current.startsWith(`${skillDir}`)) {
+        try {
+            const entries = readdirSync(current);
+            if (entries.length > 0) {
+                break;
+            }
+            rmSync(current, { recursive: false, force: true });
+        }
+        catch {
+            break;
+        }
+        current = dirname(current);
+    }
+}
+function sameStringArrays(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function normalizeSkillPath(path) {
+    if (!path)
+        return '';
+    const normalized = path.replace(/^\/+|\/+$/g, '');
+    if (!normalized)
+        return '';
+    return normalized.replace(/(?:^|\/)SKILL\.md$/i, '');
+}
+function toSkillFilePath(path) {
+    const normalized = normalizeSkillPath(path);
+    return normalized ? `${normalized}/SKILL.md` : 'SKILL.md';
+}
 function getSourceFromRegistrySkill(skill) {
     if (skill.githubUrl) {
         const source = parseSource(skill.githubUrl);
@@ -1845,7 +2933,7 @@ function getSourceFromRegistrySkill(skill) {
             platform: 'github',
             owner: skill.owner,
             repo: skill.repo,
-            path: skill.skillPath,
+            path: normalizeSkillPath(skill.skillPath) || undefined,
         };
     }
     return null;
@@ -1863,6 +2951,22 @@ function getRegistrySlug$1(skill, fallback) {
     }
     return fallback;
 }
+function getMissingRequestedNames(requestedSkillNames, resolved) {
+    if (requestedSkillNames.length === 0)
+        return [];
+    const foundNames = new Set(resolved.map((entry) => entry.skill.name.toLowerCase()));
+    const missing = [];
+    const seenMissing = new Set();
+    for (const requested of requestedSkillNames) {
+        const key = requested.toLowerCase();
+        if (foundNames.has(key) || seenMissing.has(key)) {
+            continue;
+        }
+        seenMissing.add(key);
+        missing.push(requested);
+    }
+    return missing;
+}
 
 function discoverLocalSkills(agents, global) {
     const skills = [];