skillscat 0.1.1 → 0.1.3

package/dist/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 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, posix, resolve, relative, isAbsolute } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, unlinkSync, readdirSync, rmSync, cpSync, realpathSync, statSync } from 'node:fs';
+import { join, dirname, posix, basename, 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';
-import { spawnSync, execFileSync } from 'node:child_process';
+import { spawnSync, execFileSync, execFile } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { createServer } from 'node:http';
 
@@ -98,6 +98,7 @@ const SKILL_DISCOVERY_PATHS = [
     'skills/.experimental',
     'skills/.system',
     '.opencode/skill',
+    '.agents',
     '.claude/skills',
     '.codex/skills',
     '.cursor/skills',
@@ -1103,7 +1104,6 @@ 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) {
@@ -1114,8 +1114,6 @@ async function fetchGitHubSkillCompanionFiles(source, skillFilePath, snapshot) {
             continue;
         if (!isPathWithinDirectory(repoPath, skillDir))
             continue;
-        if (isPathInNestedSkillDirectory(repoPath, nestedSkillDirs))
-            continue;
         const relativePath = toRelativeSkillPath(repoPath, skillDir);
         if (!relativePath)
             continue;
@@ -1168,32 +1166,6 @@ async function resolveGitHubBlobOrSymlinkContent({ snapshot, item, currentPath,
         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)
@@ -1658,6 +1630,27 @@ function parseSlug(slug) {
     }
     return { owner: match[1], name: match[2] };
 }
+/**
+ * Encode a slug for use in /skills/[owner]/[...name] paths
+ * @param slug - Skill slug in format "owner/name[/nested]"
+ * @returns Encoded path segment like "owner/name" (without leading slash)
+ */
+function encodeSlugForSkillPath(slug) {
+    const { owner, name } = parseSlug(slug);
+    const encodedName = name
+        .split('/')
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+    return `${encodeURIComponent(owner)}/${encodedName}`;
+}
+/**
+ * Build the canonical web skill path from a slug
+ * @param slug - Skill slug in format "owner/name[/nested]"
+ * @returns Path like "/skills/owner/name"
+ */
+function buildSkillPath(slug) {
+    return `/skills/${encodeSlugForSkillPath(slug)}`;
+}
 
 const GITHUB_API = 'https://api.github.com';
 async function getAuthHeaders() {
@@ -1887,6 +1880,7 @@ function submitRepoForIndexingInBackground(source) {
     }
 }
 
+const FALLBACK_AGENT_ID = 'agents';
 function sanitizeSkillDirName(skillName) {
     const sanitized = skillName
         .replace(/[\\/]/g, '-')
@@ -1902,6 +1896,13 @@ function sanitizeSkillDirName(skillName) {
     return sanitized;
 }
 const AGENTS = [
+    {
+        id: FALLBACK_AGENT_ID,
+        name: '.agents',
+        projectPath: '.agents/',
+        globalPath: join(homedir(), '.agents'),
+        aliases: ['.agents', 'generic']
+    },
     {
         id: 'amp',
         name: 'Amp',
@@ -1992,6 +1993,12 @@ const AGENTS = [
         projectPath: '.opencode/skill/',
         globalPath: join(homedir(), '.config', 'opencode', 'skill')
     },
+    {
+        id: 'openclaw',
+        name: 'OpenClaw',
+        projectPath: 'skills/',
+        globalPath: join(homedir(), '.openclaw', 'skills')
+    },
     {
         id: 'qoder',
         name: 'Qoder',
@@ -2017,21 +2024,51 @@ const AGENTS = [
         globalPath: join(homedir(), '.codeium', 'windsurf', 'skills')
     }
 ];
+function normalizeAgentId(id) {
+    return id.trim().toLowerCase().replace(/\s+/g, '-');
+}
+function getGlobalDetectionPath(agent) {
+    const normalized = agent.globalPath.replace(/[\\/]+$/, '');
+    const container = normalized.replace(/[\\/](?:skill|skills)$/i, '');
+    return container || normalized;
+}
+function getAgentBasePath(agent, global, cwd = process.cwd()) {
+    return global ? agent.globalPath : join(cwd, agent.projectPath);
+}
 /**
  * Detect which agents are installed by checking for their config directories
  */
 function detectInstalledAgents() {
     return AGENTS.filter(agent => {
-        // Check if global path exists (indicating agent is installed)
-        const globalDir = agent.globalPath.replace(/\/skills\/?$/, '').replace(/\/skill\/?$/, '');
-        return existsSync(globalDir);
+        const globalDir = getGlobalDetectionPath(agent);
+        return existsSync(agent.globalPath) || existsSync(globalDir);
     });
 }
+function detectProjectAgents(cwd = process.cwd()) {
+    return AGENTS.filter((agent) => existsSync(getAgentBasePath(agent, false, cwd)));
+}
+function preferSpecificAgents(agents) {
+    const specificAgents = agents.filter((agent) => agent.id !== FALLBACK_AGENT_ID);
+    return specificAgents.length > 0 ? specificAgents : agents;
+}
+function detectPreferredAgents(global, cwd = process.cwd()) {
+    if (global) {
+        const installedAgents = preferSpecificAgents(detectInstalledAgents());
+        return installedAgents.length > 0 ? installedAgents : [getFallbackAgent()];
+    }
+    const projectAgents = preferSpecificAgents(detectProjectAgents(cwd));
+    if (projectAgents.length > 0) {
+        return projectAgents;
+    }
+    const installedAgents = preferSpecificAgents(detectInstalledAgents());
+    return installedAgents.length > 0 ? installedAgents : [getFallbackAgent()];
+}
 /**
  * Get agent by ID
  */
 function getAgentById(id) {
-    return AGENTS.find(a => a.id === id || a.id === id.toLowerCase().replace(/\s+/g, '-'));
+    const normalized = normalizeAgentId(id);
+    return AGENTS.find((agent) => agent.id === normalized || agent.aliases?.some((alias) => normalizeAgentId(alias) === normalized));
 }
 /**
  * Get agents by IDs
@@ -2039,11 +2076,18 @@ function getAgentById(id) {
 function getAgentsByIds(ids) {
     return ids.map(id => getAgentById(id)).filter((a) => a !== undefined);
 }
+function getFallbackAgent() {
+    const fallbackAgent = getAgentById(FALLBACK_AGENT_ID);
+    if (!fallbackAgent) {
+        throw new Error('Fallback .agents target is not configured');
+    }
+    return fallbackAgent;
+}
 /**
  * Get skill installation path for an agent
  */
-function getSkillPath(agent, skillName, global) {
-    const basePath = global ? agent.globalPath : join(process.cwd(), agent.projectPath);
+function getSkillPath(agent, skillName, global, cwd = process.cwd()) {
+    const basePath = getAgentBasePath(agent, global, cwd);
     return join(basePath, sanitizeSkillDirName(skillName));
 }
 
@@ -2105,6 +2149,7 @@ function normalizeSkill(raw) {
         sha: typeof candidate.sha === 'string' ? candidate.sha : undefined,
         path,
         contentHash: typeof candidate.contentHash === 'string' ? candidate.contentHash : undefined,
+        installRoot: typeof candidate.installRoot === 'string' && candidate.installRoot ? candidate.installRoot : undefined,
     };
 }
 function loadDb() {
@@ -2149,11 +2194,75 @@ function sameSource(a, b) {
 function sameInstallationIdentity(a, b) {
     return (a.name === b.name &&
         a.global === b.global &&
+        (a.installRoot ?? '') === (b.installRoot ?? '') &&
         a.path === b.path &&
         (a.registrySlug ?? '') === (b.registrySlug ?? '') &&
         getUpdateStrategy$1(a) === getUpdateStrategy$1(b) &&
         sameSource(a.source, b.source));
 }
+function sameLegacyProjectIdentity(existing, next) {
+    return (!existing.global &&
+        !next.global &&
+        !existing.installRoot &&
+        Boolean(next.installRoot) &&
+        existing.name === next.name &&
+        existing.path === next.path &&
+        (existing.registrySlug ?? '') === (next.registrySlug ?? '') &&
+        getUpdateStrategy$1(existing) === getUpdateStrategy$1(next) &&
+        sameSource(existing.source, next.source));
+}
+function saveDbIfChanged(db, changed) {
+    if (changed) {
+        saveDb(db);
+    }
+    return db;
+}
+function reconcileInstallations(db) {
+    let changed = false;
+    const cwd = process.cwd();
+    db.skills = db.skills.flatMap((skill) => {
+        let reconciledSkill = skill;
+        if (!reconciledSkill.global && !reconciledSkill.installRoot) {
+            const hasCurrentWorkspaceMatch = reconciledSkill.agents.some((agentId) => {
+                const agent = getAgentById(agentId);
+                if (!agent) {
+                    return false;
+                }
+                const skillDir = getSkillPath(agent, reconciledSkill.name, false, cwd);
+                return existsSync(join(skillDir, 'SKILL.md'));
+            });
+            if (!hasCurrentWorkspaceMatch) {
+                return [reconciledSkill];
+            }
+            reconciledSkill = {
+                ...reconciledSkill,
+                installRoot: cwd,
+            };
+            changed = true;
+        }
+        const remainingAgents = reconciledSkill.agents.filter((agentId) => {
+            const agent = getAgentById(agentId);
+            if (!agent) {
+                changed = true;
+                return false;
+            }
+            const skillDir = getSkillPath(agent, reconciledSkill.name, reconciledSkill.global, reconciledSkill.installRoot);
+            return existsSync(join(skillDir, 'SKILL.md'));
+        });
+        if (remainingAgents.length === reconciledSkill.agents.length) {
+            return [reconciledSkill];
+        }
+        changed = true;
+        if (remainingAgents.length === 0) {
+            return [];
+        }
+        return [{
+                ...reconciledSkill,
+                agents: remainingAgents,
+            }];
+    });
+    return saveDbIfChanged(db, changed);
+}
 /**
  * Record a skill installation
  */
@@ -2164,7 +2273,8 @@ function recordInstallation(skill) {
         return;
     }
     // Replace only exact same installation identity.
-    db.skills = db.skills.filter((existing) => !sameInstallationIdentity(existing, normalized));
+    db.skills = db.skills.filter((existing) => !sameInstallationIdentity(existing, normalized) &&
+        !sameLegacyProjectIdentity(existing, normalized));
     db.skills.push(normalized);
     saveDb(db);
 }
@@ -2186,6 +2296,9 @@ function removeInstallation(skillName, options) {
         if (options?.global !== undefined && skill.global !== options.global) {
             return [skill];
         }
+        if (options?.installRoot !== undefined && (skill.installRoot ?? '') !== options.installRoot) {
+            return [skill];
+        }
         if (targetAgents && targetAgents.length > 0) {
             const remainingAgents = skill.agents.filter((agentId) => !targetAgents.includes(agentId));
             if (remainingAgents.length === 0) {
@@ -2197,11 +2310,60 @@ function removeInstallation(skillName, options) {
     });
     saveDb(db);
 }
+function copyInstallationAgent(sourceAgentId, targetAgentId, options) {
+    if (sourceAgentId === targetAgentId) {
+        return 0;
+    }
+    const db = loadDb();
+    let updated = 0;
+    const sourceSkillDirs = options?.sourceSkillDirs ? new Set(options.sourceSkillDirs) : null;
+    const sourceAgent = getAgentById(sourceAgentId);
+    db.skills = db.skills.map((skill) => {
+        if (options?.global !== undefined && skill.global !== options.global) {
+            return skill;
+        }
+        if (!skill.agents.includes(sourceAgentId) || skill.agents.includes(targetAgentId)) {
+            return skill;
+        }
+        let installRoot = skill.installRoot;
+        if (options?.installRoot !== undefined) {
+            if (installRoot) {
+                if (installRoot !== options.installRoot) {
+                    return skill;
+                }
+            }
+            else if (!skill.global &&
+                sourceAgent &&
+                existsSync(join(getSkillPath(sourceAgent, skill.name, false, options.installRoot), 'SKILL.md'))) {
+                installRoot = options.installRoot;
+            }
+            else {
+                return skill;
+            }
+        }
+        if (sourceSkillDirs && sourceAgent) {
+            const sourceSkillDir = getSkillPath(sourceAgent, skill.name, skill.global, installRoot);
+            if (!sourceSkillDirs.has(sourceSkillDir)) {
+                return skill;
+            }
+        }
+        updated += 1;
+        return {
+            ...skill,
+            installRoot,
+            agents: [...skill.agents, targetAgentId],
+        };
+    });
+    if (updated > 0) {
+        saveDb(db);
+    }
+    return updated;
+}
 /**
  * Get all installed skills
  */
 function getInstalledSkills() {
-    const db = loadDb();
+    const db = reconcileInstallations(loadDb());
     return db.skills;
 }
 
@@ -2295,6 +2457,7 @@ function box(content, title) {
 const COMPANION_MANIFEST_FILE = '.skillscat-companion-files.json';
 const COMPANION_MANIFEST_VERSION = 1;
 async function add(source, options) {
+    const explicitRepoInstall = options.repo === true;
     const repoSource = parseSource(source);
     if (!repoSource) {
         error('Invalid source. Supported formats:');
@@ -2316,14 +2479,18 @@ async function add(source, options) {
     }
     const discoverSpinner = spinner('Discovering skills');
     let resolvedSkills = [];
+    let selectionMode = 'default';
     try {
-        resolvedSkills = await resolveInstallSkills({
+        const resolution = await resolveInstallSkills({
             sourceInput: source,
             repoSource,
             requestedSkillNames: options.skill ?? [],
+            explicitRepoInstall,
             explicitRefBypassRegistry: isExplicitGitHubRefSource,
             githubSnapshot,
         });
+        resolvedSkills = resolution.resolved;
+        selectionMode = resolution.selectionMode;
     }
     catch (err) {
         discoverSpinner.stop(false);
@@ -2360,9 +2527,28 @@ async function add(source, options) {
         }
         console.log(pc.dim('─'.repeat(50)));
         console.log(pc.dim('Install with:'));
-        console.log(`  ${pc.cyan(`npx skillscat add ${source}`)}`);
+        console.log(`  ${pc.cyan(formatAddCommand(source, options))}`);
         return;
     }
+    if (selectionMode === 'install-all' && !options.yes && (!options.skill || options.skill.length === 0)) {
+        console.log();
+        if (explicitRepoInstall) {
+            info$1(`Treating ${pc.cyan(sourceLabel)} as a repository install.`);
+        }
+        else {
+            info$1(`No published skill slug matched ${pc.cyan(sourceLabel)}.`);
+        }
+        console.log(pc.dim(`Found ${resolvedSkills.length} published skill(s) in repository ${sourceLabel}:`));
+        for (const entry of resolvedSkills) {
+            console.log(pc.dim(`  - ${entry.skill.name}${formatSkillPathHint(entry.skill.path)}`));
+        }
+        console.log();
+        const confirm = await prompt(`Install all ${resolvedSkills.length} skill(s) from ${sourceLabel}? [y/N] `);
+        if (confirm.trim().toLowerCase() !== 'y') {
+            info$1('Installation cancelled.');
+            process.exit(0);
+        }
+    }
     // Final name filter (safety net after mixed registry+git resolution)
     let selectedEntries = resolvedSkills;
     if (options.skill && options.skill.length > 0) {
@@ -2376,11 +2562,13 @@ async function add(source, options) {
             process.exit(1);
         }
     }
-    else if (!options.yes && resolvedSkills.length > 1) {
+    else if (selectionMode !== 'install-all' && !options.yes && resolvedSkills.length > 1) {
         selectedEntries = [await selectSingleSkillInteractive(resolvedSkills)];
     }
     // Detect or select agents
     let targetAgents;
+    const isGlobal = options.global ?? false;
+    let usedFallbackAgent = false;
     if (options.agent && options.agent.length > 0) {
         targetAgents = getAgentsByIds(options.agent);
         if (targetAgents.length === 0) {
@@ -2393,38 +2581,12 @@ async function add(source, options) {
         }
     }
     else {
-        targetAgents = detectInstalledAgents();
-        if (targetAgents.length === 0) {
-            if (!options.yes) {
-                console.log();
-                warn('No coding agents detected.');
-                console.log(pc.dim('Select agents to install skills for:'));
-                console.log();
-                for (let i = 0; i < AGENTS.length; i++) {
-                    console.log(`  ${pc.dim(`${i + 1}.`)} ${AGENTS[i].name} (${AGENTS[i].id})`);
-                }
-                console.log();
-                const response = await prompt('Enter agent numbers (comma-separated) or "all": ');
-                if (response.toLowerCase() === 'all') {
-                    targetAgents = AGENTS;
-                }
-                else {
-                    const indices = response.split(',').map((s) => parseInt(s.trim()) - 1);
-                    targetAgents = indices
-                        .filter((i) => i >= 0 && i < AGENTS.length)
-                        .map((i) => AGENTS[i]);
-                }
-                if (targetAgents.length === 0) {
-                    error('No agents selected.');
-                    process.exit(1);
-                }
-            }
-            else {
-                targetAgents = AGENTS.filter((a) => a.id === 'claude-code');
-            }
+        targetAgents = detectPreferredAgents(isGlobal);
+        usedFallbackAgent = targetAgents.length === 1 && targetAgents[0]?.id === FALLBACK_AGENT_ID;
+        if (usedFallbackAgent) {
+            warn('No agent-specific directory detected. Installing to .agents.');
         }
     }
-    const isGlobal = options.global ?? false;
     const locationLabel = isGlobal ? 'global' : 'project';
     console.log();
     console.log(pc.bold(`Installing ${selectedEntries.length} skill(s) to ${targetAgents.length} agent(s):`));
@@ -2437,7 +2599,7 @@ async function add(source, options) {
     console.log();
     console.log(pc.dim('Target agents:'));
     for (const agent of targetAgents) {
-        const path = isGlobal ? agent.globalPath : join(process.cwd(), agent.projectPath);
+        const path = getAgentBasePath(agent, isGlobal);
         console.log(`  ${pc.cyan('•')} ${agent.name} → ${pc.dim(path)}`);
     }
     console.log();
@@ -2523,6 +2685,7 @@ async function add(source, options) {
                 sha: skill.sha,
                 path: skill.path,
                 contentHash: skill.contentHash,
+                installRoot: isGlobal ? undefined : process.cwd(),
             });
             trackInstallation(entry.trackingSlug).catch(() => { });
         }
@@ -2544,13 +2707,32 @@ async function add(source, options) {
     console.log();
     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.'));
+    if (usedFallbackAgent) {
+        console.log(pc.dim('Need a tool-specific copy later? Run `npx skillscat convert <agent>` to copy from .agents.'));
+    }
 }
-async function resolveInstallSkills({ sourceInput, repoSource, requestedSkillNames, explicitRefBypassRegistry, githubSnapshot, }) {
+async function resolveInstallSkills({ sourceInput, repoSource, requestedSkillNames, explicitRepoInstall, explicitRefBypassRegistry, githubSnapshot, }) {
     const requestedNamesLower = new Set(requestedSkillNames.map((name) => name.toLowerCase()));
     const needsRegistryFirst = repoSource.platform === 'github' && !explicitRefBypassRegistry;
+    const ambiguousSlugOrRepoInput = isAmbiguousSlugOrRepoInput(sourceInput, repoSource);
+    const preferRepoSelection = explicitRepoInstall || ambiguousSlugOrRepoInput;
+    const canShortCircuitExactSlug = ambiguousSlugOrRepoInput && !explicitRepoInstall && requestedNamesLower.size === 0;
     let resolved = [];
+    let selectionMode = 'default';
     let registryRepoMatchesFound = false;
     let registrySummariesNeedingGitBackfill = [];
+    if (canShortCircuitExactSlug) {
+        const registrySlugSkill = await fetchSkill(sourceInput).catch((err) => {
+            verboseLog(`Registry slug lookup failed: ${err instanceof Error ? err.message : 'unknown'}`);
+            return null;
+        });
+        if (registrySlugSkill?.content) {
+            return {
+                resolved: [toRegistryResolvedSkill(registrySlugSkill, sourceInput, repoSource)],
+                selectionMode,
+            };
+        }
+    }
     if (needsRegistryFirst) {
         try {
             const registryRepo = await fetchSkillsByRepo(repoSource.owner, repoSource.repo, {
@@ -2567,6 +2749,9 @@ async function resolveInstallSkills({ sourceInput, repoSource, requestedSkillNam
                 if (requestedNamesLower.size > 0) {
                     selectedSummaries = summaries.filter((item) => requestedNamesLower.has(item.name.toLowerCase()));
                 }
+                else if (preferRepoSelection) {
+                    selectionMode = 'install-all';
+                }
                 if (selectedSummaries.length > 0) {
                     const registryFetch = await fetchRegistryResolvedSkills(selectedSummaries, sourceInput, repoSource);
                     resolved.push(...registryFetch.resolved);
@@ -2608,11 +2793,14 @@ async function resolveInstallSkills({ sourceInput, repoSource, requestedSkillNam
                 throw err;
             }
             // Fallback: preserve existing behavior for registry slugs or private skills.
-            if (resolved.length === 0 && true) {
+            if (!explicitRepoInstall && resolved.length === 0 && true) {
                 const registrySkill = await fetchSkill(sourceInput).catch(() => null);
                 if (registrySkill?.content) {
                     resolved.push(toRegistryResolvedSkill(registrySkill, sourceInput, repoSource));
-                    return mergeResolvedSkills([], resolved);
+                    return {
+                        resolved: mergeResolvedSkills([], resolved),
+                        selectionMode,
+                    };
                 }
             }
             // If some registry skills were already resolved (partial hit), keep them.
@@ -2620,7 +2808,10 @@ async function resolveInstallSkills({ sourceInput, repoSource, requestedSkillNam
                 if (getMissingRequestedNames(requestedSkillNames, resolved).length > 0) {
                     throw err;
                 }
-                return mergeResolvedSkills([], resolved);
+                return {
+                    resolved: mergeResolvedSkills([], resolved),
+                    selectionMode,
+                };
             }
             throw err;
         }
@@ -2628,7 +2819,10 @@ async function resolveInstallSkills({ sourceInput, repoSource, requestedSkillNam
     if (requestedNamesLower.size > 0 && resolved.length > 0) {
         resolved = resolved.filter((entry) => requestedNamesLower.has(entry.skill.name.toLowerCase()));
     }
-    return mergeResolvedSkills([], resolved);
+    return {
+        resolved: mergeResolvedSkills([], resolved),
+        selectionMode,
+    };
 }
 async function fetchRegistryResolvedSkills(summaries, sourceInput, repoSource) {
     const resolved = [];
@@ -2917,10 +3111,24 @@ function normalizeSkillPath(path) {
         return '';
     return normalized.replace(/(?:^|\/)SKILL\.md$/i, '');
 }
+function formatSkillPathHint(path) {
+    const normalized = normalizeSkillPath(path);
+    return normalized ? ` (${normalized})` : '';
+}
+function formatAddCommand(source, options) {
+    return options.repo ? `npx skillscat add ${source} --repo` : `npx skillscat add ${source}`;
+}
 function toSkillFilePath(path) {
     const normalized = normalizeSkillPath(path);
     return normalized ? `${normalized}/SKILL.md` : 'SKILL.md';
 }
+function isAmbiguousSlugOrRepoInput(sourceInput, repoSource) {
+    return (repoSource.platform === 'github'
+        && !repoSource.path
+        && !repoSource.branch
+        && repoSource.hasExplicitRef !== true
+        && sourceInput.trim() === `${repoSource.owner}/${repoSource.repo}`);
+}
 function getSourceFromRegistrySkill(skill) {
     if (skill.githubUrl) {
         const source = parseSource(skill.githubUrl);
@@ -3034,7 +3242,7 @@ async function list(options) {
         warn('No skills installed.');
         console.log();
         console.log(pc.dim('Install skills with:'));
-        console.log(`  ${pc.cyan('npx skillscat add <owner>/<repo>')}`);
+        console.log(`  ${pc.cyan('npx skillscat add <slug>')}`);
         console.log();
         console.log(pc.dim('Or search for skills:'));
         console.log(`  ${pc.cyan('npx skillscat search <query>')}`);
@@ -3168,13 +3376,15 @@ async function search(query, options = {}) {
     console.log(pc.dim('─'.repeat(50)));
     console.log();
     console.log(pc.dim('Install a skill:'));
-    console.log(`  ${pc.cyan('npx skillscat add <owner>/<repo>')}`);
+    console.log(`  ${pc.cyan('npx skillscat add <slug>')}`);
     console.log();
-    console.log(pc.dim('View skill details:'));
+    console.log(pc.dim('Inspect a repository first:'));
     console.log(`  ${pc.cyan('npx skillscat info <owner>/<repo>')}`);
 }
 
 async function remove(skillName, options) {
+    // Reconcile tracked installs so manual deletions do not leave stale records behind.
+    getInstalledSkills();
     // Determine which agents to check
     let agents;
     if (options.agent && options.agent.length > 0) {
@@ -3209,6 +3419,7 @@ async function remove(skillName, options) {
         removeInstallation(skillName, {
             agents: agents.map((agent) => agent.id),
             global: isGlobal,
+            installRoot: isGlobal ? undefined : process.cwd(),
         });
     }
     if (removed === 0) {
@@ -3382,7 +3593,7 @@ async function update(skillName, options) {
             skillAgents.push(...agents.filter(a => skill.agents.includes(a.id)));
         }
         for (const agent of skillAgents) {
-            const skillDir = getSkillPath(agent, skill.name, skill.global);
+            const skillDir = getSkillPath(agent, skill.name, skill.global, skill.installRoot);
             const skillFile = join(skillDir, 'SKILL.md');
             try {
                 mkdirSync(dirname(skillFile), { recursive: true });
@@ -3410,6 +3621,78 @@ async function update(skillName, options) {
     success(`Updated ${updated} skill(s) successfully!`);
 }
 
+function getSkillDirectories(basePath) {
+    if (!existsSync(basePath)) {
+        return [];
+    }
+    return readdirSync(basePath, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(basePath, entry.name))
+        .filter((skillDir) => existsSync(join(skillDir, 'SKILL.md')));
+}
+async function convert(targetAgentId, options) {
+    const isGlobal = options.global ?? false;
+    const sourceAgent = getAgentById(options.from ?? FALLBACK_AGENT_ID);
+    const targetAgent = getAgentById(targetAgentId);
+    if (!sourceAgent) {
+        error(`Invalid source agent: ${options.from ?? FALLBACK_AGENT_ID}`);
+        process.exit(1);
+    }
+    if (!targetAgent) {
+        error(`Invalid target agent: ${targetAgentId}`);
+        process.exit(1);
+    }
+    const sourceBase = getAgentBasePath(sourceAgent, isGlobal);
+    const targetBase = getAgentBasePath(targetAgent, isGlobal);
+    if (sourceBase === targetBase) {
+        error('Source and target directories are the same.');
+        process.exit(1);
+    }
+    const sourceSkills = getSkillDirectories(sourceBase);
+    if (sourceSkills.length === 0) {
+        warn(`No skills found in ${sourceAgent.name}.`);
+        console.log(pc.dim(`Checked: ${sourceBase}`));
+        return;
+    }
+    let copied = 0;
+    let skipped = 0;
+    const copiedSkillDirs = [];
+    for (const sourceSkillDir of sourceSkills) {
+        const skillName = basename(sourceSkillDir);
+        const targetSkillDir = join(targetBase, skillName);
+        if (existsSync(targetSkillDir)) {
+            if (!options.force) {
+                skipped += 1;
+                continue;
+            }
+            rmSync(targetSkillDir, { recursive: true, force: true });
+        }
+        mkdirSync(dirname(targetSkillDir), { recursive: true });
+        cpSync(sourceSkillDir, targetSkillDir, { recursive: true });
+        copied += 1;
+        copiedSkillDirs.push(sourceSkillDir);
+    }
+    if (copied === 0) {
+        warn(`All ${sourceSkills.length} skill(s) already exist in ${targetAgent.name}.`);
+        console.log(pc.dim('Use `--force` to overwrite the target copy.'));
+        return;
+    }
+    const trackedUpdates = copyInstallationAgent(sourceAgent.id, targetAgent.id, {
+        global: isGlobal,
+        installRoot: isGlobal ? undefined : process.cwd(),
+        sourceSkillDirs: copiedSkillDirs,
+    });
+    console.log();
+    success(`Copied ${copied} skill(s) from ${sourceAgent.name} to ${targetAgent.name}.`);
+    console.log(pc.dim(`${sourceBase} → ${targetBase}`));
+    if (skipped > 0) {
+        info$1(`Skipped ${skipped} existing skill(s). Use --force to overwrite them.`);
+    }
+    if (trackedUpdates > 0) {
+        console.log(pc.dim(`Updated ${trackedUpdates} tracked installation(s) so future updates also target ${targetAgent.name}.`));
+    }
+}
+
 const PACKAGE_NAME = 'skillscat';
 function safeExec(command, args) {
     try {
@@ -3640,8 +3923,9 @@ async function info(source) {
     }
     console.log(pc.dim('─'.repeat(50)));
     console.log();
-    console.log(pc.bold('Install:'));
-    console.log(`  ${pc.cyan(`npx skillscat add ${source}`)}`);
+    console.log(pc.bold('Install published skills by slug:'));
+    console.log(`  ${pc.cyan('npx skillscat add <slug>')}`);
+    console.log(`  ${pc.dim('Use search or the web detail page to discover the exact published slug for this repository.')}`);
     console.log();
     // Show compatible agents
     console.log(pc.bold('Compatible agents:'));
@@ -4092,6 +4376,14 @@ async function publish(skillPath, options) {
     }
 }
 
+function printSubmitMessage(message) {
+    for (const line of message.split('\n')) {
+        console.log(pc.dim(line));
+    }
+}
+const IGNORED_DISCOVERY_DIRS = new Set([
+    '.git',
+]);
 /**
  * Check if a URL is a valid GitHub URL
  */
@@ -4182,8 +4474,7 @@ function findSkillMd(cwd, maxDepth = 3) {
         try {
             const entries = readdirSync(dir);
             for (const entry of entries) {
-                // Skip dot folders
-                if (entry.startsWith('.'))
+                if (IGNORED_DISCOVERY_DIRS.has(entry))
                     continue;
                 const fullPath = join(dir, entry);
                 try {
@@ -4364,26 +4655,46 @@ async function submit(urlArg, _options) {
             process.exit(1);
         }
         if (response.status === 400) {
-            console.error(pc.red(`Submission failed: ${result.error || 'Invalid request'}`));
-            if (result.error?.includes('SKILL.md')) {
+            const submitError = result.error || result.message || 'Invalid request';
+            console.error(pc.red(`Submission failed: ${submitError}`));
+            if (result.code === 'no_skill_md_found') {
                 console.log();
-                console.log(pc.dim('Make sure your repository has a SKILL.md file in the root directory.'));
+                console.log(pc.dim('Make sure your repository has a SKILL.md file in the repository root or a supported subdirectory, including dot folders.'));
                 console.log(pc.dim('Learn more: https://skillscat.com/docs/skill-format'));
             }
-            if (result.error?.includes('fork') || result.error?.includes('Fork')) {
+            if (result.code === 'fork_no_unique_commits') {
                 console.log();
-                console.log(pc.dim('Please submit the original repository instead of a fork.'));
+                console.log(pc.dim('Please submit the original repository, or add your own commits to the fork first.'));
+            }
+            if (result.code === 'fork_behind_upstream') {
+                console.log();
+                console.log(pc.dim('Please sync your fork with upstream before submitting it.'));
             }
             process.exit(1);
         }
         if (!response.ok || !result.success) {
             console.error(pc.red(`Submission failed: ${result.error || result.message || 'Unknown error'}`));
+            if (result.code === 'github_rate_limited' && result.retryAfterSeconds) {
+                console.log(pc.dim(`Try again in about ${result.retryAfterSeconds} seconds.`));
+            }
             process.exit(1);
         }
         // Success!
+        const submittedCount = result.submitted ?? 0;
+        const existingCount = result.existing ?? 0;
         console.log();
-        console.log(pc.green('Skill submitted successfully!'));
-        console.log(pc.dim(result.message || 'It will appear in the catalog once processed.'));
+        if (existingCount > 0 && submittedCount === 0) {
+            console.log(pc.green('No new submission needed.'));
+        }
+        else {
+            console.log(pc.green('Skill submitted successfully!'));
+        }
+        printSubmitMessage(result.message || 'It will appear in the catalog once processed.');
+        if (result.existingSlug) {
+            console.log();
+            console.log(`View it at: ${pc.cyan(`${baseUrl}/skills/${result.existingSlug}`)}`);
+            console.log(`Install with: ${pc.cyan(`skillscat add ${result.existingSlug}`)}`);
+        }
     }
     catch (error) {
         console.error(pc.red('Failed to connect to SkillsCat.'));
@@ -4394,6 +4705,60 @@ async function submit(urlArg, _options) {
     }
 }
 
+function normalizeReason(value) {
+    if (!value)
+        return null;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'security' || normalized === 'copyright') {
+        return normalized;
+    }
+    return null;
+}
+async function report(slug, options = {}) {
+    const token = await getValidToken();
+    if (!token) {
+        error('Authentication required.');
+        console.log(pc.dim('Run `skillscat login` first.'));
+        process.exit(1);
+    }
+    let reason = normalizeReason(options.reason);
+    if (!reason) {
+        const answer = await prompt('Report reason [security/copyright]: ');
+        reason = normalizeReason(answer);
+    }
+    if (!reason) {
+        error('Invalid report reason. Use `security` or `copyright`.');
+        process.exit(1);
+    }
+    const baseUrl = getBaseUrl();
+    const response = await fetch(`${baseUrl}/api/skills/${encodeURIComponent(slug)}/report`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            Origin: baseUrl,
+            'User-Agent': 'skillscat-cli/0.1.0',
+        },
+        body: JSON.stringify({
+            reason,
+            details: options.details || undefined,
+        }),
+    });
+    const payload = await response.json();
+    if (!response.ok || !payload.success) {
+        error(payload.error || payload.message || 'Failed to submit report');
+        process.exit(1);
+    }
+    success(payload.message || 'Report submitted');
+    if (reason === 'security' && payload.report) {
+        console.log(`  Open security reports: ${pc.cyan(String(payload.report.openSecurityReportCount))}`);
+        console.log(`  Risk level: ${pc.cyan(payload.report.riskLevel)}`);
+        if (payload.report.premiumEscalated) {
+            console.log(`  ${pc.yellow('Premium review queued')}`);
+        }
+    }
+}
+
 /**
  * Find skill by slug using two-segment path
  */
@@ -4487,6 +4852,208 @@ async function unpublishSkill(slug, options) {
     }
 }
 
+function hasCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return false;
+    }
+    const lookupCommand = process.platform === 'win32' ? 'where' : 'which';
+    const result = spawnSync(lookupCommand, [trimmed], {
+        stdio: 'ignore',
+    });
+    return result.status === 0;
+}
+function getEnvBrowserCommand(url) {
+    const rawBrowser = process.env.BROWSER?.trim();
+    if (!rawBrowser || rawBrowser.toLowerCase() === 'none') {
+        return null;
+    }
+    const [command, ...rawArgs] = rawBrowser.split(/\s+/);
+    if (!command) {
+        return null;
+    }
+    let replacedUrl = false;
+    const args = rawArgs.map((arg) => {
+        if (!arg.includes('%s')) {
+            return arg;
+        }
+        replacedUrl = true;
+        return arg.replace(/%s/g, url);
+    });
+    if (!replacedUrl) {
+        args.push(url);
+    }
+    return { command, args };
+}
+function getDefaultBrowserCommand(url) {
+    if (process.platform === 'darwin') {
+        return { command: 'open', args: [url] };
+    }
+    if (process.platform === 'win32') {
+        return { command: 'rundll32', args: ['url.dll,FileProtocolHandler', url] };
+    }
+    if ((process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) && hasCommand('wslview')) {
+        return { command: 'wslview', args: [url] };
+    }
+    return { command: 'xdg-open', args: [url] };
+}
+function getBrowserCommand(url) {
+    return getEnvBrowserCommand(url) || getDefaultBrowserCommand(url);
+}
+function hasBrowserEnvironment() {
+    const rawBrowser = process.env.BROWSER?.trim();
+    if (rawBrowser?.toLowerCase() === 'none') {
+        return false;
+    }
+    if (rawBrowser) {
+        return true;
+    }
+    if (process.env.CI) {
+        return false;
+    }
+    if (process.platform === 'linux') {
+        if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) {
+            return true;
+        }
+        return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+    }
+    return true;
+}
+function canOpenUrlInBrowser() {
+    if (!hasBrowserEnvironment()) {
+        return false;
+    }
+    return hasCommand(getBrowserCommand('https://skills.cat').command);
+}
+async function openUrlInBrowser(url) {
+    if (!canOpenUrlInBrowser()) {
+        return false;
+    }
+    const browserCommand = getBrowserCommand(url);
+    return new Promise((resolve) => {
+        execFile(browserCommand.command, browserCommand.args, (err) => {
+            resolve(!err);
+        });
+    });
+}
+
+class ViewHttpError extends Error {
+}
+function normalizeOutputFormat(output) {
+    if (!output) {
+        return null;
+    }
+    const normalized = output.trim().toLowerCase();
+    if (normalized === 'html' || normalized === 'markdown') {
+        return normalized;
+    }
+    return null;
+}
+function getSiteBaseUrl() {
+    const registryUrl = getRegistryUrl();
+    try {
+        const parsed = new URL(registryUrl);
+        const pathname = parsed.pathname.replace(/\/+$/, '');
+        const strippedPathname = pathname.endsWith('/registry')
+            ? pathname.slice(0, -'/registry'.length)
+            : pathname.endsWith('/openclaw')
+                ? pathname.slice(0, -'/openclaw'.length)
+                : pathname;
+        return `${parsed.protocol}//${parsed.host}${strippedPathname}`;
+    }
+    catch {
+        return registryUrl.replace(/\/(?:registry|openclaw)\/?$/, '');
+    }
+}
+function buildSkillUrl(slug) {
+    return `${getSiteBaseUrl()}${buildSkillPath(slug)}`;
+}
+async function buildViewHeaders(output) {
+    const token = await getValidToken();
+    const headers = {
+        'User-Agent': output === 'markdown'
+            ? 'skillscat-cli/0.1.0 OpenClaw/1.0'
+            : 'skillscat-cli/0.1.0',
+        Accept: output === 'markdown'
+            ? 'text/markdown, text/plain;q=0.9, */*;q=0.8'
+            : 'text/html,application/xhtml+xml;q=0.9,*/*;q=0.8',
+    };
+    if (token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+    return headers;
+}
+async function fetchSkillDocument(slug, output) {
+    const url = buildSkillUrl(slug);
+    const headers = await buildViewHeaders(output);
+    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) {
+            const httpError = parseHttpError(response.status, response.statusText);
+            throw new ViewHttpError(httpError.message);
+        }
+        return response.text();
+    }
+    catch (err) {
+        if (!(err instanceof ViewHttpError)) {
+            const networkError = parseNetworkError(err);
+            throw new Error(networkError.message);
+        }
+        throw err;
+    }
+}
+function writeOutput(body) {
+    console.log(body);
+}
+async function view(slug, options = {}) {
+    try {
+        parseSlug(slug);
+    }
+    catch {
+        error('Invalid slug. Expected format: owner/name');
+        process.exit(1);
+    }
+    if (options.output) {
+        const output = normalizeOutputFormat(options.output);
+        if (!output) {
+            error('Invalid output format. Use `html` or `markdown`.');
+            process.exit(1);
+        }
+        try {
+            const body = await fetchSkillDocument(slug, output);
+            writeOutput(body);
+            return;
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : 'Failed to fetch skill view');
+            process.exit(1);
+        }
+    }
+    const url = buildSkillUrl(slug);
+    if (canOpenUrlInBrowser()) {
+        const opened = await openUrlInBrowser(url);
+        if (opened) {
+            info$1(`Opened ${slug} in your browser.`);
+            return;
+        }
+        warn('Unable to open a browser automatically. Printing markdown instead.');
+    }
+    else {
+        warn('No browser environment detected. Printing markdown instead.');
+    }
+    try {
+        const markdown = await fetchSkillDocument(slug, 'markdown');
+        writeOutput(markdown);
+    }
+    catch (err) {
+        error(err instanceof Error ? err.message : 'Failed to fetch skill view');
+        process.exit(1);
+    }
+}
+
 const DEFAULT_REGISTRY_URL = 'https://skills.cat/registry';
 const VALID_KEYS = ['registry'];
 async function configSet(key, value, options = {}) {
@@ -4578,7 +5145,8 @@ program
     .alias('i')
     .description('Add a skill from a repository')
     .option('-g, --global', 'Install to user directory instead of project')
-    .option('-a, --agent <agents...>', 'Target specific agents (e.g., claude-code, cursor)')
+    .option('-a, --agent <agents...>', 'Target specific agents (e.g., claude-code, cursor, agents)')
+    .option('-r, --repo', 'Treat <source> as a repository instead of an exact published skill slug')
     .option('-s, --skill <skills...>', 'Install specific skills by name')
     .option('-l, --list', 'List available skills without installing')
     .option('-y, --yes', 'Skip confirmation prompts')
@@ -4610,6 +5178,14 @@ program
     .option('-a, --agent <agents...>', 'Update for specific agents')
     .option('--check', 'Check for updates without installing')
     .action(update);
+program
+    .command('convert <agent>')
+    .alias('sync')
+    .description('Copy skills from .agents into a specific agent directory')
+    .option('--from <agent>', 'Source agent directory to copy from', 'agents')
+    .option('-g, --global', 'Copy from user directory instead of project')
+    .option('-f, --force', 'Overwrite existing skills in the target directory')
+    .action(convert);
 // Self-upgrade command
 program
     .command('self-upgrade')
@@ -4629,6 +5205,12 @@ program
     .command('info <source>')
     .description('Show detailed information about a skill or repository')
     .action(info);
+// View command
+program
+    .command('view <slug>')
+    .description('Open a published skill in the browser or print its rendered output')
+    .option('-o, --output <format>', 'Print `html` or `markdown` to stdout instead of opening a browser')
+    .action(view);
 // Login command
 program
     .command('login')
@@ -4660,6 +5242,12 @@ program
     .command('submit [url]')
     .description('Submit a GitHub repository to SkillsCat registry')
     .action(submit);
+program
+    .command('report <slug>')
+    .description('Report a skill for security or copyright concerns')
+    .option('-r, --reason <reason>', 'Report reason (security or copyright)')
+    .option('-d, --details <details>', 'Optional report details')
+    .action(report);
 // Unpublish command
 program
     .command('unpublish <slug>')