agentloom 0.1.6 → 0.1.7

package/dist/core/copy.js

@@ -249,13 +249,6 @@ export function formatUsageError(input) {
     return lines.join("\n");
 }
 export function formatUnknownCommandError(command) {
-    if (command === "skills") {
-        return formatUsageError({
-            issue: 'Command "skills" was removed.',
-            usage: "agentloom skill <add|list|delete|find|update|sync> [options]",
-            example: "agentloom skill find typescript",
-        });
-    }
     return formatUsageError({
         issue: `Unknown command "${command}".`,
         usage: "agentloom --help",

package/dist/core/importer.js

@@ -7,12 +7,12 @@ import YAML from "yaml";
 import { buildAgentMarkdown, parseAgentsDir, targetFileNameForAgent, } from "./agents.js";
 import { normalizeCommandArgumentsForCanonical, normalizeCommandSelector, parseCommandsDir, resolveCommandSelections, } from "./commands.js";
 import { normalizeRuleSelector, parseRulesDir, resolveRuleSelections, stripRuleFileExtension, } from "./rules.js";
-import { applySkillProviderSideEffects, copySkillArtifacts, normalizeSkillSelector, parseSkillsDir, resolveSkillSelections, skillContentMatchesTarget, } from "./skills.js";
+import { applySkillProviderSideEffects, copySkillArtifacts, normalizeSkillSelector, parseSkillsDir, resolveSkillSelector, resolveSkillSelections, skillContentMatchesTarget, } from "./skills.js";
 import { ensureDir, hashContent, isObject, readJsonIfExists, relativePosix, slugify, writeTextAtomic, } from "./fs.js";
 import { ALL_PROVIDERS } from "../types.js";
 import { readLockfile, upsertLockEntry, writeLockfile } from "./lockfile.js";
 import { readCanonicalMcp, writeCanonicalMcp } from "./mcp.js";
-import { discoverSourceAgentsDir, discoverSourceCommandsDir, discoverSourceCommandsDirs, discoverSourceMcpPath, discoverSourceRulesDir, discoverSourceSkillsDir, prepareSource, } from "./sources.js";
+import { discoverPluginSourceRoots, discoverSourceAgentsDirs, discoverSourceCommandsDirs, discoverSourceMcpPaths, discoverSourceRulesDirs, discoverSourceSkillsDirs, prepareSource, } from "./sources.js";
 import { isProviderEntityFileName } from "./provider-entity-validation.js";
 export class NonInteractiveConflictError extends Error {
     constructor(message) {
@@ -51,67 +51,77 @@ export async function importSource(options) {
             ? `${options.source} (subdir: ${options.subdir})`
             : options.source;
     try {
-        const sourceAgentsDir = shouldImportAgents
-            ? discoverSourceAgentsDir(prepared.importRoot)
-            : null;
+        const pluginSourceRoots = discoverPluginSourceRoots(prepared.importRoot);
+        const sourceAgentsDirs = shouldImportAgents
+            ? discoverSourceAgentsDirs(prepared.importRoot)
+            : [];
         const sourceCommandsDirs = shouldImportCommands
             ? discoverSourceCommandsDirs(prepared.importRoot)
             : [];
-        const sourceCommandsDir = sourceCommandsDirs[0] ??
-            (shouldImportCommands
-                ? discoverSourceCommandsDir(prepared.importRoot)
-                : null);
-        const sourceMcpPath = shouldImportMcp
-            ? discoverSourceMcpPath(prepared.importRoot)
-            : null;
-        const sourceRulesDir = shouldImportRules
-            ? discoverSourceRulesDir(prepared.importRoot)
-            : null;
-        const sourceSkillsDir = shouldImportSkills
-            ? discoverSourceSkillsDir(prepared.importRoot)
-            : null;
-        const sourceAgents = sourceAgentsDir
-            ? parseSourceAgentsForImport(sourceAgentsDir)
+        const sourceMcpPaths = shouldImportMcp
+            ? discoverSourceMcpPaths(prepared.importRoot)
+            : [];
+        const sourceRulesDirs = shouldImportRules
+            ? discoverSourceRulesDirs(prepared.importRoot)
+            : [];
+        const sourceSkillsDirs = shouldImportSkills
+            ? discoverSourceSkillsDirs(prepared.importRoot)
+            : [];
+        const sourceAgents = sourceAgentsDirs.length > 0
+            ? parseSourceAgentsForImport(sourceAgentsDirs, pluginSourceRoots)
             : [];
         const sourceCommands = sourceCommandsDirs.length > 0
-            ? parseSourceCommandsForImport(sourceCommandsDirs)
+            ? parseSourceCommandsForImport(sourceCommandsDirs, pluginSourceRoots)
             : [];
-        const sourceMcp = sourceMcpPath
-            ? normalizeMcp(readJsonIfExists(sourceMcpPath))
+        const sourceMcp = sourceMcpPaths.length > 0
+            ? parseSourceMcpForImport(sourceMcpPaths, pluginSourceRoots)
             : null;
-        const sourceRules = sourceRulesDir ? parseRulesDir(sourceRulesDir) : [];
-        const sourceSkills = sourceSkillsDir ? parseSkillsDir(sourceSkillsDir) : [];
+        const sourceRules = sourceRulesDirs.length > 0
+            ? parseSourceRulesForImport(sourceRulesDirs, pluginSourceRoots)
+            : [];
+        const sourceSkills = sourceSkillsDirs.length > 0
+            ? parseSourceSkillsForImport(sourceSkillsDirs, pluginSourceRoots)
+            : [];
+        const sourceAgentsDir = sourceAgentsDirs[0] ?? null;
+        const sourceCommandsDir = sourceCommandsDirs[0] ?? null;
+        const sourceMcpPath = sourceMcpPaths[0] ?? null;
+        const sourceRulesDir = sourceRulesDirs[0] ?? null;
+        const sourceSkillsDir = sourceSkillsDirs[0] ?? null;
         const hasExplicitCommandSelection = (options.commandSelectors?.length ?? 0) > 0;
         const isAggregateImport = shouldImportAgents &&
             shouldImportCommands &&
             shouldImportMcp &&
             (options.importRules === undefined || shouldImportRules) &&
             shouldImportSkills;
-        if (shouldImportAgents && requireAgents && !sourceAgentsDir) {
-            throw new Error(`No source agents directory found under ${prepared.importRoot} (expected agents/, .agents/agents/, or .github/agents/).`);
+        if (shouldImportAgents && requireAgents && sourceAgentsDirs.length === 0) {
+            throw new Error(`No source agents directory found under ${prepared.importRoot} (expected agents/, .agents/agents/, or .github/agents/, including plugin sources declared in .claude-plugin/marketplace.json).`);
         }
         if (shouldImportAgents && requireAgents && sourceAgents.length === 0) {
             throw new Error(`No agent files found in ${sourceAgentsDir}.`);
         }
-        if (shouldImportCommands && options.requireCommands && !sourceCommandsDir) {
-            throw new Error(`No source commands directory found under ${prepared.importRoot} (expected .agents/commands/, commands/, prompts/, .gemini/commands/, or .github/prompts/).`);
+        if (shouldImportCommands &&
+            options.requireCommands &&
+            sourceCommandsDirs.length === 0) {
+            throw new Error(`No source commands directory found under ${prepared.importRoot} (expected .agents/commands/, commands/, prompts/, .gemini/commands/, or .github/prompts/, including plugin sources declared in .claude-plugin/marketplace.json).`);
         }
         if (shouldImportCommands &&
             options.requireCommands &&
             sourceCommands.length === 0) {
             throw new Error(`No command files found in ${sourceCommandsDir}.`);
         }
-        if (shouldImportMcp && options.requireMcp && !sourceMcpPath) {
-            throw new Error(`No source mcp.json found under ${prepared.importRoot} (expected mcp.json or .agents/mcp.json).`);
+        if (shouldImportMcp && options.requireMcp && sourceMcpPaths.length === 0) {
+            throw new Error(`No source mcp.json found under ${prepared.importRoot} (expected mcp.json or .agents/mcp.json, including plugin sources declared in .claude-plugin/marketplace.json).`);
         }
-        if (shouldImportRules && requireRules && !sourceRulesDir) {
-            throw new Error(`No source rules directory found under ${prepared.importRoot} (expected .agents/rules/ or rules/).`);
+        if (shouldImportRules && requireRules && sourceRulesDirs.length === 0) {
+            throw new Error(`No source rules directory found under ${prepared.importRoot} (expected .agents/rules/ or rules/, including plugin sources declared in .claude-plugin/marketplace.json).`);
         }
         if (shouldImportRules && requireRules && sourceRules.length === 0) {
             throw new Error(`No rule files found in ${sourceRulesDir}.`);
         }
-        if (shouldImportSkills && options.requireSkills && !sourceSkillsDir) {
-            throw new Error(`No source skills directory found under ${prepared.importRoot} (expected .agents/skills/, skills/, or root SKILL.md).`);
+        if (shouldImportSkills &&
+            options.requireSkills &&
+            sourceSkillsDirs.length === 0) {
+            throw new Error(`No source skills directory found under ${prepared.importRoot} (expected .agents/skills/, skills/, or root SKILL.md, including plugin sources declared in .claude-plugin/marketplace.json).`);
         }
         if (shouldImportSkills &&
             options.requireSkills &&
@@ -124,7 +134,7 @@ export async function importSource(options) {
             sourceRules.length === 0 &&
             sourceSkills.length === 0 &&
             Object.keys(sourceMcp?.mcpServers ?? {}).length === 0) {
-            throw new Error(`No importable entities found in source "${sourceLocation}".\nExpected agents/, .agents/agents/, .github/agents/, commands/, .agents/commands/, prompts/, .gemini/commands/, .github/prompts/, mcp.json/.agents/mcp.json, rules/.agents/rules/, skills/, .agents/skills/, or root SKILL.md.`);
+            throw new Error(`No importable entities found in source "${sourceLocation}".\nExpected agents/, .agents/agents/, .github/agents/, commands/, .agents/commands/, prompts/, .gemini/commands/, .github/prompts/, mcp.json/.agents/mcp.json, rules/.agents/rules/, skills/, .agents/skills/, root SKILL.md, or plugin sources from .claude-plugin/marketplace.json.`);
         }
         const shouldResolveAgents = shouldImportAgents &&
             (sourceAgents.length > 0 ||
@@ -198,8 +208,8 @@ export async function importSource(options) {
                 selectionMode: options.selectionMode,
             });
             selectedSkills = skillSelection.selectedSkills;
+            selectedSourceSkills = skillSelection.selectedSourceSkills;
             skillSelectionMode = skillSelection.selectionMode;
-            selectedSourceSkills = selectedSkills.map((skill) => skill.name);
         }
         const importedAgents = [];
         if (shouldImportAgents && selection.selectedAgents.length > 0) {
@@ -331,10 +341,16 @@ export async function importSource(options) {
                 ensureDir(options.paths.skillsDir);
             }
             for (const [index, sourceSkill] of selectedSkills.entries()) {
-                let targetSkillDirName = slugify(sourceSkill.name) || "skill";
-                const mappedTargetSkillDirName = resolveMappedTargetSkillName(sourceSkill.name, options.skillRenameMap);
+                const canonicalSkillDirName = slugify(sourceSkill.name) || "skill";
+                const legacySkillDirName = slugify(sourceSkill.sourceDirName) || "skill";
+                let targetSkillDirName = canonicalSkillDirName;
+                const mappedTargetSkillDirName = resolveMappedTargetSkillName(sourceSkill, selectedSkills, options.skillRenameMap);
                 if (mappedTargetSkillDirName) {
-                    targetSkillDirName = mappedTargetSkillDirName;
+                    targetSkillDirName =
+                        mappedTargetSkillDirName === legacySkillDirName &&
+                            legacySkillDirName !== canonicalSkillDirName
+                            ? canonicalSkillDirName
+                            : mappedTargetSkillDirName;
                 }
                 else if (options.rename &&
                     selectedSkills.length === 1 &&
@@ -347,6 +363,10 @@ export async function importSource(options) {
                 const resolvedSkillDirName = await resolveSkillConflict({
                     sourceSkill,
                     targetSkillDirName,
+                    legacySkillDirName: targetSkillDirName === canonicalSkillDirName
+                        ? legacySkillDirName
+                        : undefined,
+                    canonicalSkillDirName,
                     paths: options.paths,
                     yes: !!options.yes,
                     nonInteractive: !!options.nonInteractive,
@@ -355,10 +375,25 @@ export async function importSource(options) {
                 if (!resolvedSkillDirName)
                     continue;
                 const targetSkillDir = path.join(options.paths.skillsDir, resolvedSkillDirName);
+                if (resolvedSkillDirName === canonicalSkillDirName) {
+                    moveLegacySkillDirectoryToCanonicalIfUnchanged({
+                        sourceSkill,
+                        legacySkillDirName,
+                        canonicalSkillDirName,
+                        paths: options.paths,
+                    });
+                }
                 if (!skillContentMatchesTarget(sourceSkill, targetSkillDir)) {
                     fs.rmSync(targetSkillDir, { recursive: true, force: true });
                     copySkillArtifacts(sourceSkill, targetSkillDir);
                 }
+                if (resolvedSkillDirName === canonicalSkillDirName) {
+                    removeLegacySkillDirectory({
+                        legacySkillDirName,
+                        canonicalSkillDirName,
+                        paths: options.paths,
+                    });
+                }
                 importedSkills.push(resolvedSkillDirName);
                 telemetrySkills.push({
                     name: sourceSkill.name,
@@ -429,6 +464,7 @@ export async function importSource(options) {
                 selectedSourceMcpServers: selectedSourceMcpServersForLock,
                 selectedSourceRules: selectedSourceRulesForLock,
                 selectedSourceSkills: selectedSourceSkillsForLock,
+                selectedSkills,
                 skillsProviders: skillsProvidersForLock,
             });
         const shouldMergeCommandOnlyEntry = isCommandOnlyImport &&
@@ -605,17 +641,164 @@ export async function importSource(options) {
         prepared.cleanup();
     }
 }
-function parseSourceAgentsForImport(sourceAgentsDir) {
-    if (isGitHubAgentsDir(sourceAgentsDir)) {
-        return parseGitHubAgentsDirForImport(sourceAgentsDir);
+function parseSourceAgentsForImport(sourceAgentsDirs, pluginSourceRoots) {
+    const sourceAgents = sourceAgentsDirs.flatMap((sourceAgentsDir) => {
+        if (isGitHubAgentsDir(sourceAgentsDir)) {
+            return parseGitHubAgentsDirForImport(sourceAgentsDir);
+        }
+        return parseAgentsDir(sourceAgentsDir);
+    });
+    assertNoPluginSourceCollisions({
+        entityLabel: "agent",
+        pluginSourceRoots,
+        entries: sourceAgents.map((agent) => ({
+            key: targetFileNameForAgent(agent),
+            sourcePath: agent.sourcePath,
+        })),
+    });
+    return sourceAgents;
+}
+function parseSourceCommandsForImport(sourceCommandsDirs, pluginSourceRoots) {
+    const sourceCommands = sourceCommandsDirs.flatMap((dirPath) => parseSourceCommandsFromDir(dirPath));
+    assertNoPluginSourceCollisions({
+        entityLabel: "command",
+        pluginSourceRoots,
+        entries: sourceCommands.map((command) => ({
+            key: toCanonicalCommandFileName(command.fileName),
+            sourcePath: command.sourcePath,
+        })),
+    });
+    return mergeCanonicalCommandFiles(sourceCommands);
+}
+function parseSourceMcpForImport(sourceMcpPaths, pluginSourceRoots) {
+    const mergedMcpServers = {};
+    const seenServerSource = new Map();
+    for (const sourceMcpPath of sourceMcpPaths) {
+        const sourceMcp = normalizeMcp(readJsonIfExists(sourceMcpPath));
+        for (const [serverName, serverConfig] of Object.entries(sourceMcp.mcpServers)) {
+            const pluginSourceRoot = resolvePluginSourceRootForPath(sourceMcpPath, pluginSourceRoots);
+            const existing = seenServerSource.get(serverName);
+            if (existing &&
+                existing.pluginSourceRoot &&
+                pluginSourceRoot &&
+                existing.pluginSourceRoot !== pluginSourceRoot) {
+                throw buildPluginCollisionError({
+                    entityLabel: "mcp server",
+                    key: serverName,
+                    sourcePaths: [existing.sourcePath, sourceMcpPath],
+                });
+            }
+            mergedMcpServers[serverName] = serverConfig;
+            seenServerSource.set(serverName, {
+                sourcePath: sourceMcpPath,
+                pluginSourceRoot,
+            });
+        }
+    }
+    return {
+        version: 1,
+        mcpServers: mergedMcpServers,
+    };
+}
+function parseSourceRulesForImport(sourceRulesDirs, pluginSourceRoots) {
+    const sourceRules = sourceRulesDirs.flatMap((sourceRulesDir) => parseRulesDir(sourceRulesDir));
+    assertNoPluginSourceCollisions({
+        entityLabel: "rule",
+        pluginSourceRoots,
+        entries: sourceRules.map((rule) => ({
+            key: rule.id,
+            sourcePath: rule.sourcePath,
+        })),
+    });
+    return sourceRules;
+}
+function parseSourceSkillsForImport(sourceSkillsDirs, pluginSourceRoots) {
+    const sourceSkills = sourceSkillsDirs.flatMap((sourceSkillsDir) => parseSkillsDir(sourceSkillsDir));
+    assertNoPluginSourceCollisions({
+        entityLabel: "skill",
+        pluginSourceRoots,
+        entries: sourceSkills.map((skill) => ({
+            key: normalizeSkillSelector(skill.name),
+            sourcePath: skill.skillPath,
+        })),
+    });
+    assertNoDuplicateSkillNames(sourceSkills);
+    return sourceSkills;
+}
+function assertNoDuplicateSkillNames(sourceSkills) {
+    const byName = new Map();
+    for (const skill of sourceSkills) {
+        const normalizedName = normalizeSkillSelector(skill.name);
+        if (!normalizedName)
+            continue;
+        const matches = byName.get(normalizedName) ?? [];
+        matches.push({
+            name: skill.name,
+            sourcePath: skill.skillPath,
+        });
+        byName.set(normalizedName, matches);
+    }
+    for (const matches of byName.values()) {
+        const sourcePaths = [...new Set(matches.map((item) => item.sourcePath))];
+        if (sourcePaths.length < 2) {
+            continue;
+        }
+        const locations = sourcePaths
+            .map((sourcePath) => `- ${sourcePath}`)
+            .join("\n");
+        throw new Error(`Conflicting skill "${matches[0]?.name ?? "unknown"}" found in source:\n${locations}\nEnsure each SKILL.md frontmatter name is unique.`);
+    }
+}
+function assertNoPluginSourceCollisions(options) {
+    if (options.pluginSourceRoots.length === 0 || options.entries.length === 0) {
+        return;
+    }
+    const byKey = new Map();
+    for (const entry of options.entries) {
+        const normalizedKey = entry.key.trim().toLowerCase();
+        if (!normalizedKey)
+            continue;
+        const pluginSourceRoot = resolvePluginSourceRootForPath(entry.sourcePath, options.pluginSourceRoots);
+        const group = byKey.get(normalizedKey) ?? [];
+        group.push({
+            key: entry.key,
+            sourcePath: entry.sourcePath,
+            pluginSourceRoot,
+        });
+        byKey.set(normalizedKey, group);
+    }
+    for (const matches of byKey.values()) {
+        const pluginRoots = [
+            ...new Set(matches
+                .map((item) => item.pluginSourceRoot)
+                .filter((item) => Boolean(item))),
+        ];
+        if (pluginRoots.length < 2) {
+            continue;
+        }
+        throw buildPluginCollisionError({
+            entityLabel: options.entityLabel,
+            key: matches[0]?.key ?? "unknown",
+            sourcePaths: matches.map((item) => item.sourcePath),
+        });
     }
-    return parseAgentsDir(sourceAgentsDir);
 }
-function parseSourceCommandsForImport(sourceCommandsDir) {
-    const sourceCommandsDirs = Array.isArray(sourceCommandsDir)
-        ? sourceCommandsDir
-        : [sourceCommandsDir];
-    return mergeCanonicalCommandFiles(sourceCommandsDirs.flatMap((dirPath) => parseSourceCommandsFromDir(dirPath)));
+function buildPluginCollisionError(options) {
+    const locations = [...new Set(options.sourcePaths)]
+        .map((sourcePath) => `- ${sourcePath}`)
+        .join("\n");
+    return new Error(`Conflicting ${options.entityLabel} "${options.key}" found across plugin sources declared in .claude-plugin/marketplace.json:\n${locations}\nUse --subdir to import a single plugin source.`);
+}
+function resolvePluginSourceRootForPath(sourcePath, pluginSourceRoots) {
+    for (const pluginSourceRoot of [...pluginSourceRoots].sort((left, right) => right.length - left.length)) {
+        const normalizedRoot = path.resolve(pluginSourceRoot);
+        const normalizedPath = path.resolve(sourcePath);
+        if (normalizedPath === normalizedRoot ||
+            normalizedPath.startsWith(`${normalizedRoot}${path.sep}`)) {
+            return normalizedRoot;
+        }
+    }
+    return null;
 }
 function parseSourceCommandsFromDir(sourceCommandsDir) {
     if (isGeminiCommandsDir(sourceCommandsDir)) {
@@ -1117,7 +1300,7 @@ function findMatchingLockEntry(entries, key) {
         sameStringSelectionForMatch(entry.selectedSourceCommands, key.selectedSourceCommands) &&
         sameStringSelectionForMatch(entry.selectedSourceMcpServers, key.selectedSourceMcpServers) &&
         sameStringSelectionForMatch(entry.selectedSourceRules, key.selectedSourceRules, { wildcardWhenRightIsUndefined: true }) &&
-        sameStringSelectionForMatch(entry.selectedSourceSkills, key.selectedSourceSkills, { wildcardWhenRightIsUndefined: true }) &&
+        sameSkillSelectionForMatch(entry.selectedSourceSkills, key.selectedSourceSkills, key.selectedSkills, { wildcardWhenRightIsUndefined: true }) &&
         sameStringSelectionForMatch(entry.skillsProviders, key.skillsProviders, {
             wildcardWhenRightIsUndefined: true,
         }));
@@ -1161,6 +1344,39 @@ function sameStringSelectionForMatch(left, right, options = {}) {
     }
     return normalizedLeft.every((value, index) => value === normalizedRight[index]);
 }
+function sameSkillSelectionForMatch(left, right, selectedSkills, options = {}) {
+    if (options.wildcardWhenRightIsUndefined && right === undefined) {
+        return true;
+    }
+    const normalizedLeft = normalizeSkillSelectionsForMatch(left);
+    const normalizedRight = normalizeSkillSelectionsForMatch(right);
+    if (normalizedLeft.length === normalizedRight.length &&
+        normalizedLeft.every((value, index) => value === normalizedRight[index])) {
+        return true;
+    }
+    if (!selectedSkills || normalizedLeft.length !== selectedSkills.length) {
+        return false;
+    }
+    const remainingSelectors = new Set(normalizedLeft);
+    for (const skill of selectedSkills) {
+        const matchedSelector = [
+            normalizeSkillSelector(skill.name),
+            normalizeSkillSelector(skill.sourceDirName),
+        ].find((selector) => selector && remainingSelectors.has(selector));
+        if (!matchedSelector) {
+            return false;
+        }
+        remainingSelectors.delete(matchedSelector);
+    }
+    return remainingSelectors.size === 0;
+}
+function normalizeSkillSelectionsForMatch(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return [];
+    return [
+        ...new Set(value.map((item) => normalizeSkillSelector(item)).filter(Boolean)),
+    ].sort();
+}
 function uniqueStrings(values) {
     return [...new Set(values)];
 }
@@ -1279,20 +1495,65 @@ function normalizeSkillRenameMap(renameMap) {
         return undefined;
     return Object.fromEntries(normalizedEntries);
 }
-function resolveMappedTargetSkillName(sourceSkillName, renameMap) {
+function resolveMappedTargetSkillName(sourceSkill, selectedSkills, renameMap) {
     if (!renameMap)
         return undefined;
-    const normalizedSourceName = normalizeSkillSelector(sourceSkillName);
-    if (!normalizedSourceName)
-        return undefined;
     for (const [sourceSelector, importedName] of Object.entries(renameMap)) {
-        if (normalizeSkillSelector(sourceSelector) !== normalizedSourceName) {
+        const matchedSkill = resolveSkillSelector(selectedSkills, sourceSelector);
+        if (!matchedSkill || matchedSkill.sourcePath !== sourceSkill.sourcePath) {
             continue;
         }
         return slugify(path.basename(importedName.trim())) || "skill";
     }
     return undefined;
 }
+function moveLegacySkillDirectoryToCanonicalIfUnchanged(options) {
+    if (options.legacySkillDirName === options.canonicalSkillDirName) {
+        return;
+    }
+    const legacySkillDir = path.join(options.paths.skillsDir, options.legacySkillDirName);
+    if (!fs.existsSync(legacySkillDir) ||
+        !fs.statSync(legacySkillDir).isDirectory()) {
+        return;
+    }
+    const canonicalSkillDir = path.join(options.paths.skillsDir, options.canonicalSkillDirName);
+    if (fs.existsSync(canonicalSkillDir)) {
+        return;
+    }
+    if (!skillContentMatchesTarget(options.sourceSkill, legacySkillDir)) {
+        return;
+    }
+    moveDirectory(legacySkillDir, canonicalSkillDir);
+}
+function removeLegacySkillDirectory(options) {
+    if (options.legacySkillDirName === options.canonicalSkillDirName) {
+        return;
+    }
+    const legacySkillDir = path.join(options.paths.skillsDir, options.legacySkillDirName);
+    if (!fs.existsSync(legacySkillDir)) {
+        return;
+    }
+    const stat = fs.lstatSync(legacySkillDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        return;
+    }
+    fs.rmSync(legacySkillDir, { recursive: true, force: true });
+}
+function moveDirectory(sourceDir, targetDir) {
+    ensureDir(path.dirname(targetDir));
+    try {
+        fs.renameSync(sourceDir, targetDir);
+        return;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code !== "EXDEV") {
+            throw error;
+        }
+    }
+    fs.cpSync(sourceDir, targetDir, { recursive: true, force: true });
+    fs.rmSync(sourceDir, { recursive: true, force: true });
+}
 function normalizeSkillsProviders(providers) {
     if (!providers || providers.length === 0)
         return undefined;
@@ -1307,12 +1568,13 @@ function normalizeSkillsProviders(providers) {
 }
 async function resolveSkillConflict(options) {
     const targetPath = path.join(options.paths.skillsDir, options.targetSkillDirName);
-    if (!fs.existsSync(targetPath))
+    const conflictPath = resolveExistingSkillConflictPath(options, targetPath);
+    if (!conflictPath)
         return options.targetSkillDirName;
-    if (!fs.statSync(targetPath).isDirectory()) {
-        throw new Error(`Cannot import skill ${options.promptLabel}: ${targetPath} exists and is not a directory.`);
+    if (!fs.statSync(conflictPath).isDirectory()) {
+        throw new Error(`Cannot import skill ${options.promptLabel}: ${conflictPath} exists and is not a directory.`);
     }
-    if (skillContentMatchesTarget(options.sourceSkill, targetPath)) {
+    if (skillContentMatchesTarget(options.sourceSkill, conflictPath)) {
         return options.targetSkillDirName;
     }
     if (options.yes) {
@@ -1359,6 +1621,17 @@ async function resolveSkillConflict(options) {
     }
     return options.targetSkillDirName;
 }
+function resolveExistingSkillConflictPath(options, targetPath) {
+    if (fs.existsSync(targetPath)) {
+        return targetPath;
+    }
+    if (!options.legacySkillDirName ||
+        options.legacySkillDirName === options.canonicalSkillDirName) {
+        return null;
+    }
+    const legacyPath = path.join(options.paths.skillsDir, options.legacySkillDirName);
+    return fs.existsSync(legacyPath) ? legacyPath : null;
+}
 async function resolveAgentConflict(options) {
     const targetPath = path.join(options.paths.agentsDir, options.targetFileName);
     if (!fs.existsSync(targetPath))
@@ -1700,6 +1973,7 @@ async function resolveSkillsToImport(options) {
         }
         return {
             selectedSkills: selected,
+            selectedSourceSkills: selectors,
             selectionMode: "custom",
         };
     }
@@ -1713,6 +1987,7 @@ async function resolveSkillsToImport(options) {
     if (selectionResolution.skipImport) {
         return {
             selectedSkills: [],
+            selectedSourceSkills: [],
             selectionMode: "custom",
         };
     }
@@ -1721,6 +1996,7 @@ async function resolveSkillsToImport(options) {
         options.nonInteractive) {
         return {
             selectedSkills: options.sourceSkills,
+            selectedSourceSkills: options.sourceSkills.map((skill) => skill.name),
             selectionMode,
         };
     }
@@ -1741,6 +2017,9 @@ async function resolveSkillsToImport(options) {
         : new Set();
     return {
         selectedSkills: options.sourceSkills.filter((skill) => selectedNames.has(skill.name)),
+        selectedSourceSkills: options.sourceSkills
+            .filter((skill) => selectedNames.has(skill.name))
+            .map((skill) => skill.name),
         selectionMode,
     };
 }

package/dist/core/router.js

@@ -14,6 +14,13 @@ const ENTITY_NOUNS = new Set([
     "rule",
     "skill",
 ]);
+const ENTITY_NOUN_ALIASES = {
+    agents: "agent",
+    commands: "command",
+    mcps: "mcp",
+    rules: "rule",
+    skills: "skill",
+};
 const ENTITY_VERBS = new Set([
     "add",
     "list",
@@ -24,9 +31,10 @@ const ENTITY_VERBS = new Set([
 ]);
 const MCP_SERVER_VERBS = new Set(["add", "list", "delete"]);
 export function parseCommandRoute(argv) {
-    const root = argv[0]?.trim().toLowerCase();
-    if (!root)
+    const rawRoot = argv[0]?.trim().toLowerCase();
+    if (!rawRoot)
         return null;
+    const root = ENTITY_NOUN_ALIASES[rawRoot] ?? rawRoot;
     if (AGGREGATE_VERBS.has(root)) {
         return {
             mode: "aggregate",

package/dist/core/skills.d.ts

@@ -1,6 +1,8 @@
 import type { Provider, ScopePaths } from "../types.js";
 export interface CanonicalSkill {
     name: string;
+    aliases: string[];
+    sourceDirName: string;
     sourcePath: string;
     skillPath: string;
     layout: "nested" | "root";
@@ -8,6 +10,7 @@ export interface CanonicalSkill {
 export declare const ROOT_SKILL_ARTIFACT_DIRS: readonly ["references", "assets", "scripts", "templates", "examples"];
 export declare function parseSkillsDir(skillsDir: string): CanonicalSkill[];
 export declare function normalizeSkillSelector(value: string): string;
+export declare function resolveSkillSelector(skills: CanonicalSkill[], selector: string): CanonicalSkill | null;
 export declare function resolveSkillSelections(skills: CanonicalSkill[], selectors: string[]): {
     selected: CanonicalSkill[];
     unmatched: string[];

package/dist/core/skills.js

@@ -22,8 +22,12 @@ export function parseSkillsDir(skillsDir) {
         const skillFile = path.join(skillDir, "SKILL.md");
         if (!fs.existsSync(skillFile))
             continue;
+        const raw = fs.readFileSync(skillFile, "utf8");
+        const canonicalName = extractSkillName(raw) || entry.name;
         skills.push({
-            name: entry.name,
+            name: canonicalName,
+            aliases: buildSkillAliases(canonicalName, entry.name),
+            sourceDirName: entry.name,
             sourcePath: skillDir,
             skillPath: skillFile,
             layout: "nested",
@@ -37,9 +41,12 @@ export function parseSkillsDir(skillsDir) {
         return [];
     }
     const raw = fs.readFileSync(rootSkillFile, "utf8");
+    const canonicalName = extractSkillName(raw) || path.basename(skillsDir);
     return [
         {
-            name: extractSkillName(raw) || path.basename(skillsDir),
+            name: canonicalName,
+            aliases: buildSkillAliases(canonicalName, path.basename(skillsDir)),
+            sourceDirName: path.basename(skillsDir),
             sourcePath: skillsDir,
             skillPath: rootSkillFile,
             layout: "root",
@@ -61,6 +68,16 @@ function extractSkillName(raw) {
 export function normalizeSkillSelector(value) {
     return slugify(value.trim().replace(/\/+$/, "")).toLowerCase();
 }
+export function resolveSkillSelector(skills, selector) {
+    const normalizedSelector = normalizeSkillSelector(selector);
+    if (!normalizedSelector)
+        return null;
+    const canonicalMatch = skills.find((skill) => normalizeSkillSelector(skill.name) === normalizedSelector) ?? null;
+    if (canonicalMatch) {
+        return canonicalMatch;
+    }
+    return (skills.find((skill) => normalizeSkillSelector(skill.sourceDirName) === normalizedSelector) ?? null);
+}
 export function resolveSkillSelections(skills, selectors) {
     const normalizedSelectors = selectors
         .map((item) => item.trim())
@@ -70,14 +87,12 @@ export function resolveSkillSelections(skills, selectors) {
     const selectedMap = new Map();
     const unmatched = [];
     for (const selector of normalizedSelectors) {
-        const matches = skills.filter((skill) => normalizeSkillSelector(skill.name) === selector);
-        if (matches.length === 0) {
+        const match = resolveSkillSelector(skills, selector);
+        if (!match) {
             unmatched.push(selector);
             continue;
         }
-        for (const match of matches) {
-            selectedMap.set(match.name, match);
-        }
+        selectedMap.set(match.name, match);
     }
     return {
         selected: [...selectedMap.values()],
@@ -195,9 +210,7 @@ function enforceProviderSkillsSymlink(options) {
 function migrateProviderSkillsIntoCanonical(options) {
     const providerSkills = parseSkillsDir(options.providerSkillsDir);
     for (const skill of providerSkills) {
-        const targetSkillDirName = skill.layout === "nested"
-            ? path.basename(skill.sourcePath)
-            : slugify(skill.name) || "skill";
+        const targetSkillDirName = slugify(skill.name) || "skill";
         const targetSkillDir = path.join(options.canonicalSkillsDir, targetSkillDirName);
         if (fs.existsSync(targetSkillDir)) {
             const sameContent = skill.layout === "nested"
@@ -218,6 +231,9 @@ function migrateProviderSkillsIntoCanonical(options) {
         copyRootSkillArtifacts(skill.sourcePath, targetSkillDir);
     }
 }
+function buildSkillAliases(name, sourceDirName) {
+    return [...new Set([name, sourceDirName].filter(Boolean))];
+}
 function moveDirectory(sourceDir, targetDir) {
     ensureDir(path.dirname(targetDir));
     try {

package/dist/core/sources.d.ts

@@ -16,9 +16,14 @@ export declare function prepareSource(options: {
     ref?: string;
     subdir?: string;
 }): PreparedSource;
+export declare function discoverPluginSourceRoots(importRoot: string): string[];
 export declare function discoverSourceAgentsDir(importRoot: string): string | null;
+export declare function discoverSourceAgentsDirs(importRoot: string): string[];
 export declare function discoverSourceMcpPath(importRoot: string): string | null;
+export declare function discoverSourceMcpPaths(importRoot: string): string[];
 export declare function discoverSourceCommandsDirs(importRoot: string): string[];
 export declare function discoverSourceCommandsDir(importRoot: string): string | null;
 export declare function discoverSourceSkillsDir(importRoot: string): string | null;
+export declare function discoverSourceSkillsDirs(importRoot: string): string[];
 export declare function discoverSourceRulesDir(importRoot: string): string | null;
+export declare function discoverSourceRulesDirs(importRoot: string): string[];

package/dist/core/sources.js

@@ -56,31 +56,72 @@ export function prepareSource(options) {
         },
     };
 }
-export function discoverSourceAgentsDir(importRoot) {
-    const direct = path.join(importRoot, "agents");
-    if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
-        return direct;
+export function discoverPluginSourceRoots(importRoot) {
+    const marketplacePath = path.join(importRoot, ".claude-plugin", "marketplace.json");
+    if (!fs.existsSync(marketplacePath) ||
+        !fs.statSync(marketplacePath).isFile()) {
+        return [];
     }
-    const nested = path.join(importRoot, ".agents", "agents");
-    if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
-        return nested;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(marketplacePath, "utf8"));
     }
-    const githubAgents = path.join(importRoot, ".github", "agents");
-    if (fs.existsSync(githubAgents) && fs.statSync(githubAgents).isDirectory()) {
-        return githubAgents;
+    catch {
+        return [];
+    }
+    const plugins = Array.isArray(parsed?.plugins)
+        ? parsed.plugins
+        : [];
+    const discoveredRoots = [];
+    for (const plugin of plugins) {
+        if (!plugin ||
+            typeof plugin !== "object" ||
+            Array.isArray(plugin) ||
+            typeof plugin.source !== "string") {
+            continue;
+        }
+        const source = plugin.source.trim();
+        if (!source)
+            continue;
+        const pluginRoot = path.resolve(importRoot, source);
+        if (!isPathWithinRoot(importRoot, pluginRoot)) {
+            continue;
+        }
+        if (!fs.existsSync(pluginRoot) || !fs.statSync(pluginRoot).isDirectory()) {
+            continue;
+        }
+        discoveredRoots.push(pluginRoot);
     }
-    return null;
+    return dedupePaths(discoveredRoots);
+}
+export function discoverSourceAgentsDir(importRoot) {
+    return discoverSourceAgentsDirs(importRoot)[0] ?? null;
+}
+export function discoverSourceAgentsDirs(importRoot) {
+    const direct = discoverSourceAgentsDirsForRoot(importRoot);
+    if (direct.length > 0) {
+        return direct;
+    }
+    return dedupePaths(discoverPluginSourceRoots(importRoot).flatMap((pluginRoot) => discoverSourceAgentsDirsForRoot(pluginRoot)));
 }
 export function discoverSourceMcpPath(importRoot) {
-    const nested = path.join(importRoot, ".agents", "mcp.json");
-    if (fs.existsSync(nested))
-        return nested;
-    const direct = path.join(importRoot, "mcp.json");
-    if (fs.existsSync(direct))
+    return discoverSourceMcpPaths(importRoot)[0] ?? null;
+}
+export function discoverSourceMcpPaths(importRoot) {
+    const direct = discoverSourceMcpPathsForRoot(importRoot);
+    if (direct.length > 0) {
         return direct;
-    return null;
+    }
+    return dedupePaths(discoverPluginSourceRoots(importRoot).flatMap((pluginRoot) => discoverSourceMcpPathsForRoot(pluginRoot)));
 }
 export function discoverSourceCommandsDirs(importRoot) {
+    const direct = discoverSourceCommandsDirsForRoot(importRoot);
+    if (direct.length > 0) {
+        return direct;
+    }
+    return dedupePaths(discoverPluginSourceRoots(importRoot).flatMap((pluginRoot) => discoverSourceCommandsDirsForRoot(pluginRoot)));
+}
+function discoverSourceCommandsDirsForRoot(importRoot) {
     const nested = path.join(importRoot, ".agents", "commands");
     if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
         return [nested];
@@ -110,30 +151,84 @@ export function discoverSourceCommandsDir(importRoot) {
     return discoverSourceCommandsDirs(importRoot)[0] ?? null;
 }
 export function discoverSourceSkillsDir(importRoot) {
+    return discoverSourceSkillsDirs(importRoot)[0] ?? null;
+}
+export function discoverSourceSkillsDirs(importRoot) {
+    const direct = discoverSourceSkillsDirsForRoot(importRoot);
+    if (direct.length > 0) {
+        return direct;
+    }
+    return dedupePaths(discoverPluginSourceRoots(importRoot).flatMap((pluginRoot) => discoverSourceSkillsDirsForRoot(pluginRoot)));
+}
+export function discoverSourceRulesDir(importRoot) {
+    return discoverSourceRulesDirs(importRoot)[0] ?? null;
+}
+export function discoverSourceRulesDirs(importRoot) {
+    const direct = discoverSourceRulesDirsForRoot(importRoot);
+    if (direct.length > 0) {
+        return direct;
+    }
+    return dedupePaths(discoverPluginSourceRoots(importRoot).flatMap((pluginRoot) => discoverSourceRulesDirsForRoot(pluginRoot)));
+}
+function discoverSourceAgentsDirsForRoot(importRoot) {
+    const direct = path.join(importRoot, "agents");
+    if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
+        return [direct];
+    }
+    const nested = path.join(importRoot, ".agents", "agents");
+    if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
+        return [nested];
+    }
+    const githubAgents = path.join(importRoot, ".github", "agents");
+    if (fs.existsSync(githubAgents) && fs.statSync(githubAgents).isDirectory()) {
+        return [githubAgents];
+    }
+    return [];
+}
+function discoverSourceMcpPathsForRoot(importRoot) {
+    const nested = path.join(importRoot, ".agents", "mcp.json");
+    if (fs.existsSync(nested) && fs.statSync(nested).isFile()) {
+        return [nested];
+    }
+    const direct = path.join(importRoot, "mcp.json");
+    if (fs.existsSync(direct) && fs.statSync(direct).isFile()) {
+        return [direct];
+    }
+    return [];
+}
+function discoverSourceSkillsDirsForRoot(importRoot) {
     const nested = path.join(importRoot, ".agents", "skills");
     if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
-        return nested;
+        return [nested];
     }
     const direct = path.join(importRoot, "skills");
     if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
-        return direct;
+        return [direct];
     }
     const rootSkill = path.join(importRoot, "SKILL.md");
     if (fs.existsSync(rootSkill) && fs.statSync(rootSkill).isFile()) {
-        return importRoot;
+        return [importRoot];
     }
-    return null;
+    return [];
 }
-export function discoverSourceRulesDir(importRoot) {
+function discoverSourceRulesDirsForRoot(importRoot) {
     const nested = path.join(importRoot, ".agents", "rules");
     if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
-        return nested;
+        return [nested];
     }
     const direct = path.join(importRoot, "rules");
     if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
-        return direct;
+        return [direct];
     }
-    return null;
+    return [];
+}
+function dedupePaths(paths) {
+    return [...new Set(paths)];
+}
+function isPathWithinRoot(rootPath, targetPath) {
+    const relative = path.relative(rootPath, targetPath);
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
 }
 function resolveImportRoot(rootPath, subdir) {
     if (!subdir)

package/dist/sync/index.js

@@ -24,6 +24,7 @@ export async function syncFromCanonical(options) {
     const agents = parseAgentsDir(options.paths.agentsDir);
     const commands = parseCommandsDir(options.paths.commandsDir);
     const rules = parseRulesDir(options.paths.rulesDir);
+    const managedInstructionRules = rules.filter((rule) => rule.frontmatter.alwaysApply !== false);
     const mcp = readCanonicalMcp(options.paths);
     const manifest = readManifest(options.paths);
     const effectiveManifest = {
@@ -100,7 +101,7 @@ export async function syncFromCanonical(options) {
         syncManagedRuleInstructions({
             paths: options.paths,
             providers,
-            rules,
+            rules: managedInstructionRules,
             generated: generatedRules,
             updated: updatedRuleInstructionFiles,
             retained: retainedRuleInstructionFiles,
@@ -507,7 +508,18 @@ function syncManagedRuleInstructions(options) {
     }
     const cleanupTargets = new Set(getRuleInstructionPaths(options.paths, cleanupProviders));
     for (const targetPath of cleanupTargets) {
-        const existing = readTextIfExists(targetPath) ?? "";
+        if (!fs.existsSync(targetPath)) {
+            continue;
+        }
+        const stat = fs.lstatSync(targetPath);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            options.retained.add(targetPath);
+            continue;
+        }
+        const existing = readTextIfExists(targetPath);
+        if (existing === null) {
+            continue;
+        }
         const next = upsertManagedRuleBlocks(existing, activeTargets.has(targetPath) ? options.rules : []);
         const shouldTrackGenerated = activeTargets.has(targetPath) &&
             options.rules.length > 0 &&
@@ -531,7 +543,6 @@ function syncManagedRuleInstructions(options) {
                 }
             }
             else {
-                ensureDir(path.dirname(targetPath));
                 writeTextAtomic(targetPath, next);
             }
         }
@@ -550,7 +561,8 @@ function syncCopilotDiscoverySettings(options) {
         appendPathSetting(settings, "chat.agentFilesLocations", path.join(options.paths.homeDir, ".copilot", "agents"));
     }
     if (options.includeInstructionLocations) {
-        appendPathSetting(settings, "chat.instructionsFilesLocations", path.join(options.paths.homeDir, ".copilot", "copilot-instructions.md"));
+        const instructionPath = path.join(options.paths.homeDir, ".copilot", "copilot-instructions.md");
+        setPathSettingEnabled(settings, "chat.instructionsFilesLocations", instructionPath, fs.existsSync(instructionPath));
     }
     maybeWriteJson(settingsPath, settings, options.dryRun);
 }
@@ -724,6 +736,22 @@ function appendPathSetting(settings, key, settingPath) {
     }
     settings[key] = existing;
 }
+function setPathSettingEnabled(settings, key, settingPath, enabled) {
+    if (enabled) {
+        appendPathSetting(settings, key, settingPath);
+        return;
+    }
+    const existing = Array.isArray(settings[key])
+        ? settings[key].filter((value) => typeof value === "string" &&
+            value.trim() !== "" &&
+            value !== settingPath)
+        : [];
+    if (existing.length === 0) {
+        delete settings[key];
+        return;
+    }
+    settings[key] = existing;
+}
 function syncCodex(options) {
     const codexDir = getCodexRootDir(options.paths);
     const codexConfigPath = getCodexConfigPath(options.paths);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentloom",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Unified agent and MCP sync CLI for multi-provider AI tooling",
   "type": "module",
   "bin": {