feat(skills): flatten skill directories to avoid nesting limitations

Each skill now gets a completely flat directory name (e.g., aipm-marketplace-plugin-skill) with no nesting, addressing Claude Code's limitation with nested directories (issue #10238). Also fixed fallback for meta-plugins where skills are defined in plugin.json rather than marketplace manifest.

Author: yordis

bun.lock

@@ -21,7 +21,7 @@
     "ci:all": "bun run format:check && bun run typecheck && bun run test",
     "test": "bun test",
     "test:coverage": "bun test --coverage",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "dev": "bun --watch src/cli.ts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -33,6 +33,7 @@
     "@straw-hat/prettier-config": "3.1.5",
     "@types/bun": "1.2.2",
     "@types/lodash.merge": "4.6.9",
+    "@typescript/native-preview": "7.0.0-dev.20251014.1",
     "prettier": "3.6.2"
   },
   "peerDependencies": {

package.json

@@ -1,12 +1,9 @@
-import merge from 'lodash.merge';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { getConfigPath, getNotInitializedMessage, loadPluginsConfig } from '../config/loader';
-import { DIR_CURSOR, FILE_AIPM_CONFIG, FILE_AIPM_CONFIG_LOCAL } from '../constants';
+import { loadClaudeCodeMarketplaces } from '../config/loader';
+import { DIR_CURSOR } from '../constants';
 import { getErrorMessage } from '../errors';
-import { loadTargetConfig, saveConfig } from '../helpers/aipm-config';
 import { fileExists } from '../helpers/fs';
-import { resolveMarketplacePath } from '../helpers/git';
 import { defaultIO } from '../helpers/io';
 import { getMarketplaceType, loadMarketplaceManifest, resolvePluginPath } from '../helpers/marketplace';
 import { isMetaPlugin, parsePluginId, validatePluginStructure } from '../helpers/plugin';
@@ -26,54 +23,42 @@ export async function pluginInstall(options: unknown): Promise<void> {
   const cwd = cmd.cwd || process.cwd();
 
   try {
-    const { config, sources } = await loadPluginsConfig(cwd);
-
-    if (!sources.project && !sources.local) {
-      const error = new Error(getNotInitializedMessage());
-      defaultIO.logError(error.message);
-      throw error;
-    }
-    const configName = cmd.local ? getConfigPath(FILE_AIPM_CONFIG_LOCAL) : getConfigPath(FILE_AIPM_CONFIG);
-
     const { pluginName, marketplaceName } = parsePluginId(cmd.pluginId);
 
-    const marketplace = config.marketplaces[marketplaceName];
+    // Auto-discover Claude Code marketplaces
+    const claudeMarketplaces = await loadClaudeCodeMarketplaces();
+
+    const marketplace = claudeMarketplaces[marketplaceName];
 
     if (!marketplace) {
-      const error = new Error(`Marketplace '${marketplaceName}' not found. Add it first with 'marketplace add'.`);
+      const error = new Error(
+        `Marketplace '${marketplaceName}' not found in Claude Code. ` +
+          `Available marketplaces: ${Object.keys(claudeMarketplaces).join(', ')}`,
+      );
       defaultIO.logError(error.message);
       throw error;
     }
 
-    const marketplacePath = await resolveMarketplacePath(marketplaceName, marketplace, cwd, {
-      dryRun: cmd.dryRun,
-    });
+    const marketplacePath = marketplace.path;
 
     if (!marketplacePath) {
-      const error = new Error(`Marketplace '${marketplaceName}' has no path/url configured`);
+      const error = new Error(`Marketplace '${marketplaceName}' has no path`);
       defaultIO.logError(error.message);
       throw error;
     }
 
-    // In dry-run mode, skip validation for git/url marketplaces that haven't been cached yet.
-    // Directory marketplaces can still be validated since they exist locally.
-    const isDirectoryMarketplace = marketplace.source === 'directory';
-    const shouldSkipValidation = cmd.dryRun && !isDirectoryMarketplace;
-
     let manifest: Awaited<ReturnType<typeof loadMarketplaceManifest>> = null;
     let pluginPath: string | null = null;
 
-    if (!shouldSkipValidation) {
+    if (!cmd.dryRun) {
       manifest = await loadMarketplaceManifest(marketplacePath, getMarketplaceType(marketplaceName));
 
       // Resolve plugin path: try manifest first, then search recursively if needed
       pluginPath = await resolvePluginPath(marketplacePath, pluginName, manifest);
 
       if (!(await fileExists(pluginPath))) {
         const error = new Error(
-          `Plugin '${pluginName}' not found in marketplace '${marketplaceName}'. ` +
-            `Checked path: ${pluginPath}. ` +
-            `If the plugin is in a nested directory, use the full path shown in search results.`,
+          `Plugin '${pluginName}' not found in marketplace '${marketplaceName}'. ` + `Checked path: ${pluginPath}.`,
         );
         defaultIO.logError(error.message);
         throw error;
@@ -90,27 +75,11 @@ export async function pluginInstall(options: unknown): Promise<void> {
       }
     }
 
-    const isAlreadyEnabled = config.plugins[cmd.pluginId]?.enabled;
-
-    if (isAlreadyEnabled && !cmd.force) {
-      defaultIO.logInfo(`Plugin '${cmd.pluginId}' is already installed`);
-      return;
-    }
-
     if (cmd.dryRun) {
-      defaultIO.logInfo(`[DRY RUN] Would enable plugin '${cmd.pluginId}' in ${configName}`);
-      defaultIO.logInfo(`[DRY RUN] Would sync ${cmd.pluginId} to .cursor/`);
+      defaultIO.logInfo(`[DRY RUN] Would sync ${cmd.pluginId} to .cursor/skills/`);
       return;
     }
 
-    const targetConfig = await loadTargetConfig(cwd, cmd.local);
-    const updatedConfig = merge({}, targetConfig, {
-      plugins: { [cmd.pluginId]: { enabled: true } },
-    });
-
-    await saveConfig(cwd, updatedConfig, cmd.local);
-    defaultIO.logSuccess(`Enabled plugin '${cmd.pluginId}' in ${configName}`);
-
     // pluginPath is guaranteed to be set here since we skip validation only in dry-run mode,
     // and dry-run mode returns early above
     if (!pluginPath) {
@@ -120,10 +89,21 @@ export async function pluginInstall(options: unknown): Promise<void> {
     const cursorDir = join(cwd, DIR_CURSOR);
     const isMetaPluginCheck = isMetaPlugin(marketplacePath, pluginPath, manifest);
 
-    const syncResult =
-      isMetaPluginCheck && manifest
-        ? await syncMetaPluginToCursor(marketplacePath, manifest, pluginName, marketplaceName, cursorDir)
-        : await syncPluginToCursor(pluginPath, marketplaceName, pluginName, cursorDir);
+    // Check if it's a meta-plugin with skills defined in the manifest
+    let syncResult;
+    if (isMetaPluginCheck && manifest) {
+      const pluginEntry = manifest.plugins.find((p) => p.name === pluginName);
+      if (pluginEntry && pluginEntry.skills && pluginEntry.skills.length > 0) {
+        // True meta-plugin with skills in manifest
+        syncResult = await syncMetaPluginToCursor(marketplacePath, manifest, pluginName, marketplaceName, cursorDir);
+      } else {
+        // Meta-plugin path but skills are in plugin.json (not in marketplace manifest)
+        // Fall back to regular plugin sync
+        syncResult = await syncPluginToCursor(pluginPath, marketplaceName, pluginName, cursorDir);
+      }
+    } else {
+      syncResult = await syncPluginToCursor(pluginPath, marketplaceName, pluginName, cursorDir);
+    }
 
     const summary = formatSyncResult(syncResult);
 

src/commands/plugin-install.ts

@@ -152,3 +152,24 @@ export function getConfigPaths(baseDir: string) {
     gitignore: join(baseDir, FILE_GITIGNORE),
   };
 }
+
+/**
+ * Load Claude Code's marketplaces without requiring AIPM config
+ */
+export async function loadClaudeCodeMarketplaces(): Promise<Record<string, MarketplaceSource>> {
+  const claudeMarketplaces: Record<string, MarketplaceSource> = {};
+
+  if (await isClaudeCodeInstalled()) {
+    const claudeCodeMarketplaces = await readClaudeCodeMarketplaces();
+
+    for (const [marketplaceName, marketplaceConfig] of Object.entries(claudeCodeMarketplaces)) {
+      const prefixedName = `claude/${marketplaceName}`;
+      claudeMarketplaces[prefixedName] = convertClaudeMarketplaceToAIPM(
+        marketplaceName,
+        marketplaceConfig,
+      ) as MarketplaceSource;
+    }
+  }
+
+  return claudeMarketplaces;
+}

src/config/loader.ts

@@ -1,4 +1,5 @@
 import { cp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import type { Dirent } from 'node:fs';
 import { basename, extname, join } from 'node:path';
 import { DIR_AIPM_NAMESPACE, DIR_HOOKS, DIR_SKILLS, FILE_HOOKS_JSON } from '../constants';
 import { DirectoryNotFoundError, isFileNotFoundError } from '../errors';
@@ -32,7 +33,7 @@ export type SyncResult = AipmPluginSyncResult | ClaudeCodePluginSyncResult;
  * - commands/*.md → .cursor/commands/aipm/marketplace-name/plugin-name/
  * - rules/*.mdc → .cursor/rules/aipm/marketplace-name/plugin-name/
  * - agents/*.md → .cursor/agents/aipm/marketplace-name/plugin-name/
- * - skills/*.md → .cursor/skills/aipm/marketplace-name/plugin-name/
+ * - skills/ → .cursor/skills/aipm-marketplace-plugin/ (flattened dir name, see #10238)
  * - hooks/* → .cursor/hooks/aipm/marketplace-name/plugin-name/
  */
 export async function syncPluginToCursor(
@@ -74,13 +75,30 @@ export async function syncPluginToCursor(
   );
   result.agentsCount = agentsResult;
 
-  // Sync skills/*.md to .cursor/skills/aipm/marketplace/plugin/
-  const skillsResult = await syncDirectory(
-    join(pluginPath, 'skills'),
-    join(cursorDir, 'skills', DIR_AIPM_NAMESPACE, marketplaceName, pluginName),
-    ['.md'],
-  );
-  result.skillsCount = skillsResult;
+  // Sync skills/ to .cursor/skills/aipm-marketplace-plugin-skill/ (flat directory names)
+  // Each skill subdirectory gets its own flattened name to avoid nesting
+  const skillsSourcePath = join(pluginPath, 'skills');
+
+  if (await fileExists(skillsSourcePath)) {
+    let entries: Dirent[] = [];
+    try {
+      entries = await readdir(skillsSourcePath, { withFileTypes: true });
+    } catch (error: unknown) {
+      if (!isFileNotFoundError(error)) {
+        throw new DirectoryNotFoundError(skillsSourcePath, { cause: error });
+      }
+    }
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const flattenedSkillName = getFlattenedSkillName(DIR_AIPM_NAMESPACE, marketplaceName, pluginName, entry.name);
+        const skillSourcePath = join(skillsSourcePath, entry.name);
+        const skillTargetPath = join(cursorDir, 'skills', flattenedSkillName);
+        await cp(skillSourcePath, skillTargetPath, { recursive: true });
+        result.skillsCount++;
+      }
+    }
+  }
 
   // Sync hooks - check for hooks.json and translate if needed
   const hooksResult = await syncHooks(pluginPath, marketplaceName, pluginName, cursorDir);
@@ -249,6 +267,27 @@ async function syncHooks(
   }
 }
 
+/**
+ * Generates a flattened skill name using delimiter
+ * e.g., "aipm-marketplace-plugin" or "aipm-marketplace-plugin-skill-subskill"
+ *
+ * Claude Code does not support nested directories for skills.
+ * See: https://github.com/anthropics/claude-code/issues/10238
+ * All skills must be flat files in .cursor/skills/ directory.
+ */
+function getFlattenedSkillName(
+  namespace: string,
+  marketplaceName: string,
+  pluginName: string,
+  skillPath?: string,
+): string {
+  const parts = [namespace, marketplaceName.replace(/\//g, '-'), pluginName];
+  if (skillPath) {
+    parts.push(skillPath.replace(/\//g, '-'));
+  }
+  return parts.join('-');
+}
+
 /**
  * Syncs a directory, copying files with specified extensions
  * @param sourceDir Source directory
@@ -296,6 +335,10 @@ async function syncDirectory(sourceDir: string, targetDir: string, extensions: s
  * Syncs a Claude Code meta-plugin to Cursor directories.
  * Meta-plugins point to the marketplace root and define skills in the manifest.
  * We sync each skill directory listed in the manifest's skills array.
+ *
+ * Skill directory paths are flattened to avoid nested directories
+ * (Claude Code does not support nested skill directories).
+ * See: https://github.com/anthropics/claude-code/issues/10238
  */
 export async function syncMetaPluginToCursor(
   marketplacePath: string,
@@ -315,11 +358,16 @@ export async function syncMetaPluginToCursor(
     const normalizedSkillPath = skillPath.replace(/^\.\//, '');
     const fullSkillPath = join(marketplacePath, normalizedSkillPath);
 
-    const marketplaceSegments = marketplaceName.split('/');
-    const targetPath = join(cursorDir, DIR_SKILLS, DIR_AIPM_NAMESPACE, ...marketplaceSegments, normalizedSkillPath);
+    // Strip 'skills/' prefix if present, then flatten the remaining path
+    // e.g., 'skills/document-skills/xlsx' -> 'document-skills/xlsx' -> 'document-skills-xlsx'
+    const skillNamePath = normalizedSkillPath.replace(/^skills\//, '');
+    const flattenedSkillName = getFlattenedSkillName(DIR_AIPM_NAMESPACE, marketplaceName, pluginName, skillNamePath);
+    const targetPath = join(cursorDir, DIR_SKILLS, flattenedSkillName);
 
-    const count = await syncDirectory(fullSkillPath, targetPath, ['.md']);
-    skillsCount += count;
+    if (await fileExists(fullSkillPath)) {
+      await cp(fullSkillPath, targetPath, { recursive: true });
+      skillsCount++;
+    }
   }
 
   return { type: 'claudecode', skillsCount };

src/helpers/sync-strategy.ts

@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pluginInstall } from '../../src/commands/plugin-install';
+import { fileExists } from '../../src/helpers/fs';
+
+describe('plugin-install (simplified - no config required)', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = await mkdtemp(join(tmpdir(), 'aipm-simplified-'));
+    await mkdir(join(testDir, '.cursor'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test('should install a plugin from Claude Code without init', async () => {
+    // No .aipm/ directory created, no config needed
+    const options = {
+      pluginId: 'document-skills@claude/anthropic-agent-skills',
+      cwd: testDir,
+    };
+
+    await pluginInstall(options);
+
+    // Verify skills were synced
+    const skillsDir = join(testDir, '.cursor', 'skills');
+    expect(await fileExists(skillsDir)).toBe(true);
+
+    // Verify flattened skill directories (each skill is flattened as a separate dir)
+    const xlsxSkillDir = join(skillsDir, 'aipm-claude-anthropic-agent-skills-document-skills-xlsx');
+    expect(await fileExists(xlsxSkillDir)).toBe(true);
+
+    // Verify internal structure is preserved within the skill
+    const skillMd = join(xlsxSkillDir, 'SKILL.md');
+    expect(await fileExists(skillMd)).toBe(true);
+  });
+
+  test('should error if marketplace not found in Claude Code', async () => {
+    const options = {
+      pluginId: 'some-plugin@claude/nonexistent-marketplace',
+      cwd: testDir,
+    };
+
+    await expect(pluginInstall(options)).rejects.toThrow(
+      "Marketplace 'claude/nonexistent-marketplace' not found in Claude Code",
+    );
+  });
+
+  test('should work from any directory without project setup', async () => {
+    // Fresh temp directory with minimal structure
+    const options = {
+      pluginId: 'example-skills@claude/anthropic-agent-skills',
+      cwd: testDir,
+    };
+
+    // Should succeed without any config files or init
+    await pluginInstall(options);
+
+    // Verify the plugin was installed
+    const skillsDir = join(testDir, '.cursor', 'skills');
+    expect(await fileExists(skillsDir)).toBe(true);
+  });
+});