aicm 0.19.0 → 0.20.0

package/README.md

@@ -16,6 +16,7 @@ A CLI tool for managing Agentic configurations across projects.
 - [Features](#features)
   - [Rules](#rules)
   - [Commands](#commands)
+  - [Skills](#skills)
   - [Hooks](#hooks)
   - [MCP Servers](#mcp-servers)
   - [Assets](#assets)
@@ -23,6 +24,7 @@ A CLI tool for managing Agentic configurations across projects.
 - [Configuration](#configuration)
 - [CLI Commands](#cli-commands)
 - [Node.js API](#nodejs-api)
+- [FAQ](#faq)
 
 ## Why
 
@@ -85,6 +87,7 @@ After installation, open Cursor and ask it to do something. Your AI assistant wi
 │   ├── typescript.mdc
 │   └── react.mdc
 ├── commands/        # Command files (.md) [optional]
+├── skills/          # Agent Skills [optional]
 ├── assets/          # Auxiliary files [optional]
 └── hooks.json       # Hook configuration [optional]
 ```
@@ -139,7 +142,7 @@ The rules are now installed in `.cursor/rules/aicm/` and any MCP servers are con
 ### Notes
 
 - Generated files are always placed in subdirectories for deterministic cleanup and easy gitignore.
-- Users should add `.cursor/*/aicm/` to `.gitignore` to avoid tracking generated files. This single pattern covers all aicm-managed directories (rules, commands, assets, hooks).
+- Users should add `.cursor/*/aicm/`, `.cursor/skills/`, `.claude/`, and `.codex/` to `.gitignore` to avoid tracking generated files.
 
 ## Features
 
@@ -193,6 +196,65 @@ Configure your `aicm.json`:
 
 Command files ending in `.md` are installed to `.cursor/commands/aicm/` and appear in Cursor under the `/` command menu.
 
+### Skills
+
+aicm supports [Agent Skills](https://agentskills.io) - a standard format for giving AI agents new capabilities and expertise. Skills are folders containing instructions, scripts, and resources that agents can discover and use.
+
+Create a `skills/` directory where each subdirectory is a skill (containing a `SKILL.md` file):
+
+```
+my-project/
+├── aicm.json
+└── skills/
+    ├── pdf-processing/
+    │   ├── SKILL.md
+    │   ├── scripts/
+    │   │   └── extract.py
+    │   └── references/
+    │       └── REFERENCE.md
+    └── code-review/
+        └── SKILL.md
+```
+
+Each skill must have a `SKILL.md` file with YAML frontmatter:
+
+```markdown
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill forms, merge documents.
+---
+
+# PDF Processing Skill
+
+This skill enables working with PDF documents.
+
+## Usage
+
+Run the extraction script:
+scripts/extract.py
+```
+
+Configure your `aicm.json`:
+
+```json
+{
+  "rootDir": "./",
+  "targets": ["cursor"]
+}
+```
+
+Skills are installed to different locations based on the target:
+
+| Target     | Skills Location   |
+| ---------- | ----------------- |
+| **Cursor** | `.cursor/skills/` |
+| **Claude** | `.claude/skills/` |
+| **Codex**  | `.codex/skills/`  |
+
+When installed, each skill directory is copied in its entirety (including `scripts/`, `references/`, `assets/` subdirectories). A `.aicm.json` file is added inside each installed skill to track that it's managed by aicm.
+
+In workspace mode, skills are installed both to each package and merged at the root level, similar to commands.
+
 ### Hooks
 
 aicm provides first-class support for [Cursor Agent Hooks](https://docs.cursor.com/advanced/hooks), allowing you to intercept and extend the agent's behavior. Hooks enable you to run custom scripts before/after shell execution, file edits, MCP calls, and more.
@@ -369,9 +431,10 @@ aicm automatically detects workspaces if your `package.json` contains a `workspa
 ### How It Works
 
 1. **Discover packages**: Automatically find all directories containing `aicm.json` files in your repository.
-2. **Install per package**: Install rules and MCPs for each package individually in their respective directories.
+2. **Install per package**: Install rules, commands, and skills for each package individually in their respective directories.
 3. **Merge MCP servers**: Write a merged `.cursor/mcp.json` at the repository root containing all MCP servers from every package.
 4. **Merge commands**: Write a merged `.cursor/commands/aicm/` at the repository root containing all commands from every package.
+5. **Merge skills**: Write merged skills to the repository root (e.g., `.cursor/skills/`) containing all skills from every package.
 
 For example, in a workspace structure like:
 
@@ -429,7 +492,7 @@ Create an `aicm.json` file in your project root, or an `aicm` key in your projec
 
 ### Configuration Options
 
-- **rootDir**: Directory containing your aicm structure. Must contain one or more of: `rules/`, `commands/`, `assets/`, `hooks/`, or `hooks.json`. If not specified, aicm will only install rules from presets and will not pick up any local directories.
+- **rootDir**: Directory containing your aicm structure. Must contain one or more of: `rules/`, `commands/`, `skills/`, `assets/`, `hooks/`, or `hooks.json`. If not specified, aicm will only install rules from presets and will not pick up any local directories.
 - **targets**: IDEs/Agent targets where rules should be installed. Defaults to `["cursor"]`. Supported targets: `cursor`, `windsurf`, `codex`, `claude`.
 - **presets**: List of preset packages or paths to include.
 - **mcpServers**: MCP server configurations.
@@ -471,11 +534,14 @@ aicm uses a convention-based directory structure:
 ```
 my-project/
 ├── aicm.json
-├── rules/           # Rule files (.mdc) [required for rules]
+├── rules/           # Rule files (.mdc) [optional]
 │   ├── api.mdc
 │   └── testing.mdc
 ├── commands/        # Command files (.md) [optional]
 │   └── generate.md
+├── skills/          # Agent Skills [optional]
+│   └── my-skill/
+│       └── SKILL.md
 ├── assets/          # Auxiliary files [optional]
 │   ├── schema.json
 │   └── examples/
@@ -559,6 +625,50 @@ install({
 
 To prevent [prompt-injection](https://en.wikipedia.org/wiki/Prompt_injection), use only packages from trusted sources.
 
+## FAQ
+
+### Can I reference rules from commands or vice versa?
+
+**No, direct references between rules and commands are not supported.** This is because:
+
+- **Commands are hoisted** to the root level in workspace mode (`.cursor/commands/aicm/`)
+- **Rules remain nested** at the package level (`package-a/.cursor/rules/aicm/`)
+- This creates broken relative paths when commands try to reference rules
+
+**❌ Don't do this:**
+
+```markdown
+<!-- commands/validate.md -->
+
+Follow the rules in [api-rule.mdc](../rules/api-rule.mdc) <!-- BROKEN! -->
+```
+
+**✅ Do this instead:**
+
+```markdown
+<!-- Put shared content in assets/coding-standards.md -->
+
+# Coding Standards
+
+- Use TypeScript for all new code
+- Follow ESLint rules
+- Write unit tests for all functions
+```
+
+```markdown
+<!-- rules/api-rule.mdc -->
+
+Follow the coding standards in [coding-standards.md](../assets/coding-standards.md).
+```
+
+```markdown
+<!-- commands/validate.md -->
+
+Validate against our [coding standards](../assets/coding-standards.md).
+```
+
+Use shared assets for content that needs to be referenced by both rules and commands. Assets are properly rewritten and work in all modes.
+
 ## Contributing
 
 Contributions are welcome! Please feel free to open an issue or submit a Pull Request.

package/dist/api.d.ts

@@ -5,6 +5,12 @@ import { InstallOptions, InstallResult } from "./commands/install";
  * @returns Result of the install operation
  */
 export declare function install(options?: InstallOptions): Promise<InstallResult>;
+/**
+ * Check if workspaces mode is enabled without loading all rules/presets
+ * @param cwd Current working directory (optional, defaults to process.cwd())
+ * @returns True if workspaces mode is enabled
+ */
+export declare function checkWorkspacesEnabled(cwd?: string): Promise<boolean>;
 export type { InstallOptions, InstallResult } from "./commands/install";
 export type { ResolvedConfig, Config, RuleFile, CommandFile, MCPServers, } from "./utils/config";
 export type { HookFile, HooksJson, HookType, HookCommand } from "./utils/hooks";

package/dist/api.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.install = install;
+exports.checkWorkspacesEnabled = checkWorkspacesEnabled;
 const install_1 = require("./commands/install");
+const config_1 = require("./utils/config");
 /**
  * Install AICM rules based on configuration
  * @param options Installation options
@@ -10,3 +12,11 @@ const install_1 = require("./commands/install");
 async function install(options = {}) {
     return (0, install_1.install)(options);
 }
+/**
+ * Check if workspaces mode is enabled without loading all rules/presets
+ * @param cwd Current working directory (optional, defaults to process.cwd())
+ * @returns True if workspaces mode is enabled
+ */
+async function checkWorkspacesEnabled(cwd) {
+    return (0, config_1.checkWorkspacesEnabled)(cwd);
+}

package/dist/commands/clean.js

@@ -152,6 +152,54 @@ function cleanHooks(cwd, verbose) {
     }
     return hasChanges;
 }
+/**
+ * Clean aicm-managed skills from a skills directory
+ * Only removes skills that have .aicm.json (presence indicates aicm management)
+ */
+function cleanSkills(cwd, verbose) {
+    let cleanedCount = 0;
+    // Skills directories for each target
+    const skillsDirs = [
+        node_path_1.default.join(cwd, ".cursor", "skills"),
+        node_path_1.default.join(cwd, ".claude", "skills"),
+        node_path_1.default.join(cwd, ".codex", "skills"),
+    ];
+    for (const skillsDir of skillsDirs) {
+        if (!fs_extra_1.default.existsSync(skillsDir)) {
+            continue;
+        }
+        try {
+            const entries = fs_extra_1.default.readdirSync(skillsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory()) {
+                    continue;
+                }
+                const skillPath = node_path_1.default.join(skillsDir, entry.name);
+                const metadataPath = node_path_1.default.join(skillPath, ".aicm.json");
+                // Only clean skills that have .aicm.json (presence indicates aicm management)
+                if (fs_extra_1.default.existsSync(metadataPath)) {
+                    fs_extra_1.default.removeSync(skillPath);
+                    if (verbose) {
+                        console.log(chalk_1.default.gray(`  Removed skill ${skillPath}`));
+                    }
+                    cleanedCount++;
+                }
+            }
+            // Remove the skills directory if it's now empty
+            const remainingEntries = fs_extra_1.default.readdirSync(skillsDir);
+            if (remainingEntries.length === 0) {
+                fs_extra_1.default.removeSync(skillsDir);
+                if (verbose) {
+                    console.log(chalk_1.default.gray(`  Removed empty directory ${skillsDir}`));
+                }
+            }
+        }
+        catch (_a) {
+            console.warn(chalk_1.default.yellow(`Warning: Failed to clean skills in ${skillsDir}`));
+        }
+    }
+    return cleanedCount;
+}
 function cleanEmptyDirectories(cwd, verbose) {
     let cleanedCount = 0;
     const dirsToCheck = [
@@ -159,7 +207,12 @@ function cleanEmptyDirectories(cwd, verbose) {
         node_path_1.default.join(cwd, ".cursor", "commands"),
         node_path_1.default.join(cwd, ".cursor", "assets"),
         node_path_1.default.join(cwd, ".cursor", "hooks"),
+        node_path_1.default.join(cwd, ".cursor", "skills"),
         node_path_1.default.join(cwd, ".cursor"),
+        node_path_1.default.join(cwd, ".claude", "skills"),
+        node_path_1.default.join(cwd, ".claude"),
+        node_path_1.default.join(cwd, ".codex", "skills"),
+        node_path_1.default.join(cwd, ".codex"),
     ];
     for (const dir of dirsToCheck) {
         if (fs_extra_1.default.existsSync(dir)) {
@@ -211,6 +264,8 @@ async function cleanPackage(options = {}) {
         // Clean hooks
         if (cleanHooks(cwd, verbose))
             cleanedCount++;
+        // Clean skills
+        cleanedCount += cleanSkills(cwd, verbose);
         // Clean empty directories
         cleanedCount += cleanEmptyDirectories(cwd, verbose);
         return {
@@ -251,11 +306,9 @@ async function cleanWorkspaces(cwd, verbose = false) {
     };
 }
 async function clean(options = {}) {
-    var _a;
     const cwd = options.cwd || process.cwd();
     const verbose = options.verbose || false;
-    const shouldUseWorkspaces = ((_a = (await (0, config_1.loadConfig)(cwd))) === null || _a === void 0 ? void 0 : _a.config.workspaces) ||
-        (0, config_1.detectWorkspacesFromPackageJson)(cwd);
+    const shouldUseWorkspaces = await (0, config_1.checkWorkspacesEnabled)(cwd);
     if (shouldUseWorkspaces) {
         return cleanWorkspaces(cwd, verbose);
     }

package/dist/commands/install-workspaces.js

@@ -41,6 +41,52 @@ function collectWorkspaceCommandTargets(packages) {
     }
     return Array.from(targets);
 }
+/**
+ * Merge skills from multiple workspace packages
+ * Skills are merged flat (not namespaced by preset)
+ * Dedupes preset skills that appear in multiple packages
+ */
+function mergeWorkspaceSkills(packages) {
+    var _a;
+    const skills = [];
+    const seenPresetSkills = new Set();
+    for (const pkg of packages) {
+        // Skills are supported by cursor, claude, and codex targets
+        const hasSkillsTarget = pkg.config.config.targets.includes("cursor") ||
+            pkg.config.config.targets.includes("claude") ||
+            pkg.config.config.targets.includes("codex");
+        if (!hasSkillsTarget) {
+            continue;
+        }
+        for (const skill of (_a = pkg.config.skills) !== null && _a !== void 0 ? _a : []) {
+            if (skill.presetName) {
+                // Dedupe preset skills by preset+name combination
+                const presetKey = `${skill.presetName}::${skill.name}`;
+                if (seenPresetSkills.has(presetKey)) {
+                    continue;
+                }
+                seenPresetSkills.add(presetKey);
+            }
+            skills.push(skill);
+        }
+    }
+    return skills;
+}
+/**
+ * Collect all targets that support skills from workspace packages
+ */
+function collectWorkspaceSkillTargets(packages) {
+    const targets = new Set();
+    for (const pkg of packages) {
+        for (const target of pkg.config.config.targets) {
+            // Skills are supported by cursor, claude, and codex
+            if (target === "cursor" || target === "claude" || target === "codex") {
+                targets.add(target);
+            }
+        }
+    }
+    return Array.from(targets);
+}
 function mergeWorkspaceMcpServers(packages) {
     const merged = {};
     const info = {};
@@ -101,6 +147,7 @@ async function installWorkspacesPackages(packages, options = {}) {
     let totalCommandCount = 0;
     let totalAssetCount = 0;
     let totalHookCount = 0;
+    let totalSkillCount = 0;
     // Install packages sequentially for now (can be parallelized later)
     for (const pkg of packages) {
         const packagePath = pkg.absolutePath;
@@ -114,6 +161,7 @@ async function installWorkspacesPackages(packages, options = {}) {
             totalCommandCount += result.installedCommandCount;
             totalAssetCount += result.installedAssetCount;
             totalHookCount += result.installedHookCount;
+            totalSkillCount += result.installedSkillCount;
             results.push({
                 path: pkg.relativePath,
                 success: result.success,
@@ -122,6 +170,7 @@ async function installWorkspacesPackages(packages, options = {}) {
                 installedCommandCount: result.installedCommandCount,
                 installedAssetCount: result.installedAssetCount,
                 installedHookCount: result.installedHookCount,
+                installedSkillCount: result.installedSkillCount,
             });
         }
         catch (error) {
@@ -133,6 +182,7 @@ async function installWorkspacesPackages(packages, options = {}) {
                 installedCommandCount: 0,
                 installedAssetCount: 0,
                 installedHookCount: 0,
+                installedSkillCount: 0,
             });
         }
     }
@@ -144,6 +194,7 @@ async function installWorkspacesPackages(packages, options = {}) {
         totalCommandCount,
         totalAssetCount,
         totalHookCount,
+        totalSkillCount,
     };
 }
 /**
@@ -162,11 +213,12 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
             const isRoot = pkg.relativePath === ".";
             if (!isRoot)
                 return true;
-            // For root directories, only keep if it has rules, commands, or presets
+            // For root directories, only keep if it has rules, commands, skills, or presets
             const hasRules = pkg.config.rules && pkg.config.rules.length > 0;
             const hasCommands = pkg.config.commands && pkg.config.commands.length > 0;
+            const hasSkills = pkg.config.skills && pkg.config.skills.length > 0;
             const hasPresets = pkg.config.config.presets && pkg.config.config.presets.length > 0;
-            return hasRules || hasCommands || hasPresets;
+            return hasRules || hasCommands || hasSkills || hasPresets;
         });
         if (packages.length === 0) {
             return {
@@ -176,6 +228,7 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                 installedCommandCount: 0,
                 installedAssetCount: 0,
                 installedHookCount: 0,
+                installedSkillCount: 0,
                 packagesCount: 0,
             };
         }
@@ -206,6 +259,18 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
             (0, install_1.writeAssetsToTargets)(allAssets, workspaceCommandTargets);
             (0, install_1.writeCommandsToTargets)(dedupedWorkspaceCommands, workspaceCommandTargets);
         }
+        // Merge and write skills for workspace
+        const workspaceSkills = mergeWorkspaceSkills(packages);
+        const workspaceSkillTargets = collectWorkspaceSkillTargets(packages);
+        if (workspaceSkills.length > 0) {
+            (0, install_1.warnPresetSkillCollisions)(workspaceSkills);
+        }
+        if (!dryRun &&
+            workspaceSkills.length > 0 &&
+            workspaceSkillTargets.length > 0) {
+            const dedupedWorkspaceSkills = (0, install_1.dedupeSkillsForInstall)(workspaceSkills);
+            (0, install_1.writeSkillsToTargets)(dedupedWorkspaceSkills, workspaceSkillTargets);
+        }
         const { merged: rootMcp, conflicts } = mergeWorkspaceMcpServers(packages);
         const hasCursorTarget = packages.some((p) => p.config.config.targets.includes("cursor"));
         if (!dryRun && hasCursorTarget && Object.keys(rootMcp).length > 0) {
@@ -231,6 +296,9 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                     if (pkg.installedHookCount > 0) {
                         summaryParts.push(`${pkg.installedHookCount} hook${pkg.installedHookCount === 1 ? "" : "s"}`);
                     }
+                    if (pkg.installedSkillCount > 0) {
+                        summaryParts.push(`${pkg.installedSkillCount} skill${pkg.installedSkillCount === 1 ? "" : "s"}`);
+                    }
                     console.log(chalk_1.default.green(`✅ ${pkg.path} (${summaryParts.join(", ")})`));
                 }
                 else {
@@ -248,7 +316,10 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                 const hookSummary = result.totalHookCount > 0
                     ? `, ${result.totalHookCount} hook${result.totalHookCount === 1 ? "" : "s"} total`
                     : "";
-                console.log(chalk_1.default.green(`Successfully installed: ${result.packages.length - failedPackages.length}/${result.packages.length} packages (${result.totalRuleCount} rule${result.totalRuleCount === 1 ? "" : "s"} total${commandSummary}${hookSummary})`));
+                const skillSummary = result.totalSkillCount > 0
+                    ? `, ${result.totalSkillCount} skill${result.totalSkillCount === 1 ? "" : "s"} total`
+                    : "";
+                console.log(chalk_1.default.green(`Successfully installed: ${result.packages.length - failedPackages.length}/${result.packages.length} packages (${result.totalRuleCount} rule${result.totalRuleCount === 1 ? "" : "s"} total${commandSummary}${hookSummary}${skillSummary})`));
                 console.log(chalk_1.default.red(`Failed packages: ${failedPackages.map((p) => p.path).join(", ")}`));
             }
             const errorDetails = failedPackages
@@ -261,6 +332,7 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                 installedCommandCount: result.totalCommandCount,
                 installedAssetCount: result.totalAssetCount,
                 installedHookCount: result.totalHookCount,
+                installedSkillCount: result.totalSkillCount,
                 packagesCount: result.packages.length,
             };
         }
@@ -270,6 +342,7 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
             installedCommandCount: result.totalCommandCount,
             installedAssetCount: result.totalAssetCount,
             installedHookCount: result.totalHookCount,
+            installedSkillCount: result.totalSkillCount,
             packagesCount: result.packages.length,
         };
     });

package/dist/commands/install.d.ts

@@ -1,4 +1,4 @@
-import { ResolvedConfig, CommandFile, AssetFile, MCPServers, SupportedTarget } from "../utils/config";
+import { ResolvedConfig, CommandFile, AssetFile, SkillFile, MCPServers, SupportedTarget } from "../utils/config";
 export interface InstallOptions {
     /**
      * Base directory to use instead of process.cwd()
@@ -49,6 +49,10 @@ export interface InstallResult {
      * Number of hooks installed
      */
     installedHookCount: number;
+    /**
+     * Number of skills installed
+     */
+    installedSkillCount: number;
     /**
      * Number of packages installed
      */
@@ -56,6 +60,18 @@ export interface InstallResult {
 }
 export declare function writeAssetsToTargets(assets: AssetFile[], targets: SupportedTarget[]): void;
 export declare function writeCommandsToTargets(commands: CommandFile[], targets: SupportedTarget[]): void;
+/**
+ * Write skills to all supported target directories
+ */
+export declare function writeSkillsToTargets(skills: SkillFile[], targets: SupportedTarget[]): void;
+/**
+ * Warn about skill name collisions from different presets
+ */
+export declare function warnPresetSkillCollisions(skills: SkillFile[]): void;
+/**
+ * Dedupe skills by name (last one wins)
+ */
+export declare function dedupeSkillsForInstall(skills: SkillFile[]): SkillFile[];
 export declare function warnPresetCommandCollisions(commands: CommandFile[]): void;
 export declare function dedupeCommandsForInstall(commands: CommandFile[]): CommandFile[];
 /**

package/dist/commands/install.js

@@ -5,6 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeAssetsToTargets = writeAssetsToTargets;
 exports.writeCommandsToTargets = writeCommandsToTargets;
+exports.writeSkillsToTargets = writeSkillsToTargets;
+exports.warnPresetSkillCollisions = warnPresetSkillCollisions;
+exports.dedupeSkillsForInstall = dedupeSkillsForInstall;
 exports.warnPresetCommandCollisions = warnPresetCommandCollisions;
 exports.dedupeCommandsForInstall = dedupeCommandsForInstall;
 exports.writeMcpServersToFile = writeMcpServersToFile;
@@ -23,11 +26,27 @@ const install_workspaces_1 = require("./install-workspaces");
 /**
  * Rewrite asset references from source paths to installation paths
  * Only rewrites the ../assets/ pattern - everything else is preserved
+ *
+ * @param content - The file content to rewrite
+ * @param presetName - The preset name if this file is from a preset
+ * @param fileInstallDepth - The depth of the file's installation directory relative to .cursor/
+ *                           For example: .cursor/commands/aicm/file.md has depth 2 (commands, aicm)
+ *                                       .cursor/rules/aicm/preset/file.mdc has depth 3 (rules, aicm, preset)
  */
-function rewriteAssetReferences(content) {
-    // Replace ../assets/ with ../../assets/aicm/
+function rewriteAssetReferences(content, presetName, fileInstallDepth = 2) {
+    // Calculate the relative path from the file to .cursor/assets/aicm/
+    // We need to go up fileInstallDepth levels to reach .cursor/, then down to assets/aicm/
+    const upLevels = "../".repeat(fileInstallDepth);
+    // If this is from a preset, include the preset namespace in the asset path
+    let assetBasePath = "assets/aicm/";
+    if (presetName) {
+        const namespace = (0, config_1.extractNamespaceFromPresetPath)(presetName);
+        assetBasePath = node_path_1.default.posix.join("assets", "aicm", ...namespace) + "/";
+    }
+    const targetPath = upLevels + assetBasePath;
+    // Replace ../assets/ with the calculated target path
     // Handles both forward slashes and backslashes for cross-platform compatibility
-    return content.replace(/\.\.[\\/]assets[\\/]/g, "../../assets/aicm/");
+    return content.replace(/\.\.[\\/]assets[\\/]/g, targetPath);
 }
 function getTargetPaths() {
     const projectDir = process.cwd();
@@ -54,8 +73,18 @@ function writeCursorRules(rules, cursorRulesDir) {
         }
         const ruleFile = rulePath + ".mdc";
         fs_extra_1.default.ensureDirSync(node_path_1.default.dirname(ruleFile));
+        // Calculate the depth for asset path rewriting
+        // cursorRulesDir is .cursor/rules/aicm (depth 2 from .cursor)
+        // Add namespace depth if present
+        let fileInstallDepth = 2; // rules, aicm
+        if (rule.presetName) {
+            const namespace = (0, config_1.extractNamespaceFromPresetPath)(rule.presetName);
+            fileInstallDepth += namespace.length;
+        }
+        // Add any subdirectories in the rule name
+        fileInstallDepth += ruleNameParts.length - 1; // -1 because the last part is the filename
         // Rewrite asset references before writing
-        const content = rewriteAssetReferences(rule.content);
+        const content = rewriteAssetReferences(rule.content, rule.presetName, fileInstallDepth);
         fs_extra_1.default.writeFileSync(ruleFile, content);
     }
 }
@@ -69,8 +98,14 @@ function writeCursorCommands(commands, cursorCommandsDir) {
         const commandPath = node_path_1.default.join(cursorCommandsDir, ...commandNameParts);
         const commandFile = commandPath + ".md";
         fs_extra_1.default.ensureDirSync(node_path_1.default.dirname(commandFile));
+        // Calculate the depth for asset path rewriting
+        // cursorCommandsDir is .cursor/commands/aicm (depth 2 from .cursor)
+        // Commands are NOT namespaced by preset, but we still need to account for subdirectories
+        let fileInstallDepth = 2; // commands, aicm
+        // Add any subdirectories in the command name
+        fileInstallDepth += commandNameParts.length - 1; // -1 because the last part is the filename
         // Rewrite asset references before writing
-        const content = rewriteAssetReferences(command.content);
+        const content = rewriteAssetReferences(command.content, command.presetName, fileInstallDepth);
         fs_extra_1.default.writeFileSync(commandFile, content);
     }
 }
@@ -92,8 +127,12 @@ function writeRulesForFile(rules, assets, ruleDir, rulesFile) {
             // For local rules, maintain the original flat structure
             rulePath = node_path_1.default.join(ruleDir, ...ruleNameParts);
         }
-        // Rewrite asset references before writing
-        const content = rewriteAssetReferences(rule.content);
+        // For windsurf/codex/claude, assets are installed at the same namespace level as rules
+        // Example: .aicm/my-preset/rule.md and .aicm/my-preset/asset.json
+        // So we need to remove the 'assets/' part from the path
+        // ../assets/file.json -> ../file.json
+        // ../../assets/file.json -> ../../file.json
+        const content = rule.content.replace(/(\.\.[/\\])assets[/\\]/g, "$1");
         const physicalRulePath = rulePath + ".md";
         fs_extra_1.default.ensureDirSync(node_path_1.default.dirname(physicalRulePath));
         fs_extra_1.default.writeFileSync(physicalRulePath, content);
@@ -192,6 +231,105 @@ function writeCommandsToTargets(commands, targets) {
         // Other targets do not support commands yet
     }
 }
+/**
+ * Get the skills installation path for a target
+ * Returns null for targets that don't support skills
+ */
+function getSkillsTargetPath(target) {
+    const projectDir = process.cwd();
+    switch (target) {
+        case "cursor":
+            return node_path_1.default.join(projectDir, ".cursor", "skills");
+        case "claude":
+            return node_path_1.default.join(projectDir, ".claude", "skills");
+        case "codex":
+            return node_path_1.default.join(projectDir, ".codex", "skills");
+        case "windsurf":
+            // Windsurf does not support skills
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Write a single skill to the target directory
+ * Copies the entire skill directory and writes .aicm.json metadata
+ */
+function writeSkillToTarget(skill, targetSkillsDir) {
+    const skillTargetPath = node_path_1.default.join(targetSkillsDir, skill.name);
+    // Remove existing skill directory if it exists (to ensure clean install)
+    if (fs_extra_1.default.existsSync(skillTargetPath)) {
+        fs_extra_1.default.removeSync(skillTargetPath);
+    }
+    // Copy the entire skill directory
+    fs_extra_1.default.copySync(skill.sourcePath, skillTargetPath);
+    // Write .aicm.json metadata file
+    // The presence of this file indicates the skill is managed by aicm
+    const metadata = {
+        source: skill.source,
+    };
+    if (skill.presetName) {
+        metadata.presetName = skill.presetName;
+    }
+    const metadataPath = node_path_1.default.join(skillTargetPath, ".aicm.json");
+    fs_extra_1.default.writeJsonSync(metadataPath, metadata, { spaces: 2 });
+}
+/**
+ * Write skills to all supported target directories
+ */
+function writeSkillsToTargets(skills, targets) {
+    if (skills.length === 0)
+        return;
+    for (const target of targets) {
+        const targetSkillsDir = getSkillsTargetPath(target);
+        if (!targetSkillsDir) {
+            // Target doesn't support skills
+            continue;
+        }
+        // Ensure the skills directory exists
+        fs_extra_1.default.ensureDirSync(targetSkillsDir);
+        for (const skill of skills) {
+            writeSkillToTarget(skill, targetSkillsDir);
+        }
+    }
+}
+/**
+ * Warn about skill name collisions from different presets
+ */
+function warnPresetSkillCollisions(skills) {
+    const collisions = new Map();
+    for (const skill of skills) {
+        if (!skill.presetName)
+            continue;
+        const entry = collisions.get(skill.name);
+        if (entry) {
+            entry.presets.add(skill.presetName);
+            entry.lastPreset = skill.presetName;
+        }
+        else {
+            collisions.set(skill.name, {
+                presets: new Set([skill.presetName]),
+                lastPreset: skill.presetName,
+            });
+        }
+    }
+    for (const [skillName, { presets, lastPreset }] of collisions) {
+        if (presets.size > 1) {
+            const presetList = Array.from(presets).sort().join(", ");
+            console.warn(chalk_1.default.yellow(`Warning: multiple presets provide the "${skillName}" skill (${presetList}). Using definition from ${lastPreset}.`));
+        }
+    }
+}
+/**
+ * Dedupe skills by name (last one wins)
+ */
+function dedupeSkillsForInstall(skills) {
+    const unique = new Map();
+    for (const skill of skills) {
+        unique.set(skill.name, skill);
+    }
+    return Array.from(unique.values());
+}
 function warnPresetCommandCollisions(commands) {
     const collisions = new Map();
     for (const command of commands) {
@@ -312,10 +450,11 @@ async function installPackage(options = {}) {
                 installedCommandCount: 0,
                 installedAssetCount: 0,
                 installedHookCount: 0,
+                installedSkillCount: 0,
                 packagesCount: 0,
             };
         }
-        const { config, rules, commands, assets, mcpServers, hooks, hookFiles } = resolvedConfig;
+        const { config, rules, commands, assets, skills, mcpServers, hooks, hookFiles, } = resolvedConfig;
         if (config.skipInstall === true) {
             return {
                 success: true,
@@ -323,15 +462,19 @@ async function installPackage(options = {}) {
                 installedCommandCount: 0,
                 installedAssetCount: 0,
                 installedHookCount: 0,
+                installedSkillCount: 0,
                 packagesCount: 0,
             };
         }
         warnPresetCommandCollisions(commands);
         const commandsToInstall = dedupeCommandsForInstall(commands);
+        warnPresetSkillCollisions(skills);
+        const skillsToInstall = dedupeSkillsForInstall(skills);
         try {
             if (!options.dryRun) {
                 writeRulesToTargets(rules, assets, config.targets);
                 writeCommandsToTargets(commandsToInstall, config.targets);
+                writeSkillsToTargets(skillsToInstall, config.targets);
                 if (mcpServers && Object.keys(mcpServers).length > 0) {
                     writeMcpServersToTargets(mcpServers, config.targets, cwd);
                 }
@@ -342,12 +485,14 @@ async function installPackage(options = {}) {
             const uniqueRuleCount = new Set(rules.map((rule) => rule.name)).size;
             const uniqueCommandCount = new Set(commandsToInstall.map((command) => command.name)).size;
             const uniqueHookCount = (0, hooks_1.countHooks)(hooks);
+            const uniqueSkillCount = skillsToInstall.length;
             return {
                 success: true,
                 installedRuleCount: uniqueRuleCount,
                 installedCommandCount: uniqueCommandCount,
                 installedAssetCount: assets.length,
                 installedHookCount: uniqueHookCount,
+                installedSkillCount: uniqueSkillCount,
                 packagesCount: 1,
             };
         }
@@ -359,6 +504,7 @@ async function installPackage(options = {}) {
                 installedCommandCount: 0,
                 installedAssetCount: 0,
                 installedHookCount: 0,
+                installedSkillCount: 0,
                 packagesCount: 0,
             };
         }
@@ -379,6 +525,7 @@ async function install(options = {}) {
             installedCommandCount: 0,
             installedAssetCount: 0,
             installedHookCount: 0,
+            installedSkillCount: 0,
             packagesCount: 0,
         };
     }
@@ -411,11 +558,15 @@ async function installCommand(installOnCI, verbose, dryRun) {
         const ruleCount = result.installedRuleCount;
         const commandCount = result.installedCommandCount;
         const hookCount = result.installedHookCount;
+        const skillCount = result.installedSkillCount;
         const ruleMessage = ruleCount > 0 ? `${ruleCount} rule${ruleCount === 1 ? "" : "s"}` : null;
         const commandMessage = commandCount > 0
             ? `${commandCount} command${commandCount === 1 ? "" : "s"}`
             : null;
         const hookMessage = hookCount > 0 ? `${hookCount} hook${hookCount === 1 ? "" : "s"}` : null;
+        const skillMessage = skillCount > 0
+            ? `${skillCount} skill${skillCount === 1 ? "" : "s"}`
+            : null;
         const countsParts = [];
         if (ruleMessage) {
             countsParts.push(ruleMessage);
@@ -426,6 +577,9 @@ async function installCommand(installOnCI, verbose, dryRun) {
         if (hookMessage) {
             countsParts.push(hookMessage);
         }
+        if (skillMessage) {
+            countsParts.push(skillMessage);
+        }
         const countsMessage = countsParts.length > 0
             ? countsParts.join(", ").replace(/, ([^,]*)$/, " and $1")
             : "0 rules";
@@ -437,8 +591,11 @@ async function installCommand(installOnCI, verbose, dryRun) {
                 console.log(`Dry run: validated ${countsMessage}`);
             }
         }
-        else if (ruleCount === 0 && commandCount === 0 && hookCount === 0) {
-            console.log("No rules, commands, or hooks installed");
+        else if (ruleCount === 0 &&
+            commandCount === 0 &&
+            hookCount === 0 &&
+            skillCount === 0) {
+            console.log("No rules, commands, hooks, or skills installed");
         }
         else if (result.packagesCount > 1) {
             console.log(`Successfully installed ${countsMessage} across ${result.packagesCount} packages`);

package/dist/utils/config.d.ts

@@ -46,6 +46,12 @@ export interface AssetFile {
 }
 export type RuleFile = ManagedFile;
 export type CommandFile = ManagedFile;
+export interface SkillFile {
+    name: string;
+    sourcePath: string;
+    source: "local" | "preset";
+    presetName?: string;
+}
 export interface RuleCollection {
     [target: string]: RuleFile[];
 }
@@ -54,6 +60,7 @@ export interface ResolvedConfig {
     rules: RuleFile[];
     commands: CommandFile[];
     assets: AssetFile[];
+    skills: SkillFile[];
     mcpServers: MCPServers;
     hooks: HooksJson;
     hookFiles: HookFile[];
@@ -68,6 +75,11 @@ export declare function validateConfig(config: unknown, configFilePath: string,
 export declare function loadRulesFromDirectory(directoryPath: string, source: "local" | "preset", presetName?: string): Promise<RuleFile[]>;
 export declare function loadCommandsFromDirectory(directoryPath: string, source: "local" | "preset", presetName?: string): Promise<CommandFile[]>;
 export declare function loadAssetsFromDirectory(directoryPath: string, source: "local" | "preset", presetName?: string): Promise<AssetFile[]>;
+/**
+ * Load skills from a skills/ directory
+ * Each direct subdirectory containing a SKILL.md file is considered a skill
+ */
+export declare function loadSkillsFromDirectory(directoryPath: string, source: "local" | "preset", presetName?: string): Promise<SkillFile[]>;
 /**
  * Extract namespace from preset path for directory structure
  * Handles both npm packages and local paths consistently
@@ -82,10 +94,16 @@ export declare function loadAllRules(config: Config, cwd: string): Promise<{
     rules: RuleFile[];
     commands: CommandFile[];
     assets: AssetFile[];
+    skills: SkillFile[];
     mcpServers: MCPServers;
     hooks: HooksJson;
     hookFiles: HookFile[];
 }>;
 export declare function loadConfigFile(searchFrom?: string): Promise<CosmiconfigResult>;
+/**
+ * Check if workspaces mode is enabled without loading all rules/presets
+ * This is useful for commands that only need to know the workspace setting
+ */
+export declare function checkWorkspacesEnabled(cwd?: string): Promise<boolean>;
 export declare function loadConfig(cwd?: string): Promise<ResolvedConfig | null>;
 export declare function saveConfig(config: Config, cwd?: string): boolean;

package/dist/utils/config.js

@@ -11,11 +11,13 @@ exports.validateConfig = validateConfig;
 exports.loadRulesFromDirectory = loadRulesFromDirectory;
 exports.loadCommandsFromDirectory = loadCommandsFromDirectory;
 exports.loadAssetsFromDirectory = loadAssetsFromDirectory;
+exports.loadSkillsFromDirectory = loadSkillsFromDirectory;
 exports.extractNamespaceFromPresetPath = extractNamespaceFromPresetPath;
 exports.resolvePresetPath = resolvePresetPath;
 exports.loadPreset = loadPreset;
 exports.loadAllRules = loadAllRules;
 exports.loadConfigFile = loadConfigFile;
+exports.checkWorkspacesEnabled = checkWorkspacesEnabled;
 exports.loadConfig = loadConfig;
 exports.saveConfig = saveConfig;
 const fs_extra_1 = __importDefault(require("fs-extra"));
@@ -95,14 +97,16 @@ function validateConfig(config, configFilePath, cwd, isWorkspaceMode = false) {
         const hasRules = fs_extra_1.default.existsSync(node_path_1.default.join(rootPath, "rules"));
         const hasCommands = fs_extra_1.default.existsSync(node_path_1.default.join(rootPath, "commands"));
         const hasHooks = fs_extra_1.default.existsSync(node_path_1.default.join(rootPath, "hooks.json"));
+        const hasSkills = fs_extra_1.default.existsSync(node_path_1.default.join(rootPath, "skills"));
         // In workspace mode, root config doesn't need these directories
         // since packages will have their own configurations
         if (!isWorkspaceMode &&
             !hasRules &&
             !hasCommands &&
             !hasHooks &&
+            !hasSkills &&
             !hasPresets) {
-            throw new Error(`Root directory must contain at least one of: rules/, commands/, hooks.json, or have presets configured`);
+            throw new Error(`Root directory must contain at least one of: rules/, commands/, skills/, hooks.json, or have presets configured`);
         }
     }
     else if (!isWorkspaceMode && !hasPresets) {
@@ -201,6 +205,36 @@ async function loadAssetsFromDirectory(directoryPath, source, presetName) {
     }
     return assets;
 }
+/**
+ * Load skills from a skills/ directory
+ * Each direct subdirectory containing a SKILL.md file is considered a skill
+ */
+async function loadSkillsFromDirectory(directoryPath, source, presetName) {
+    const skills = [];
+    if (!fs_extra_1.default.existsSync(directoryPath)) {
+        return skills;
+    }
+    // Get all direct subdirectories
+    const entries = await fs_extra_1.default.readdir(directoryPath, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const skillPath = node_path_1.default.join(directoryPath, entry.name);
+        const skillMdPath = node_path_1.default.join(skillPath, "SKILL.md");
+        // Only include directories that contain a SKILL.md file
+        if (!fs_extra_1.default.existsSync(skillMdPath)) {
+            continue;
+        }
+        skills.push({
+            name: entry.name,
+            sourcePath: skillPath,
+            source,
+            presetName,
+        });
+    }
+    return skills;
+}
 /**
  * Extract namespace from preset path for directory structure
  * Handles both npm packages and local paths consistently
@@ -257,8 +291,9 @@ async function loadPreset(presetPath, cwd) {
     const hasCommands = fs_extra_1.default.existsSync(node_path_1.default.join(presetRootDir, "commands"));
     const hasHooks = fs_extra_1.default.existsSync(node_path_1.default.join(presetRootDir, "hooks.json"));
     const hasAssets = fs_extra_1.default.existsSync(node_path_1.default.join(presetRootDir, "assets"));
-    if (!hasRules && !hasCommands && !hasHooks && !hasAssets) {
-        throw new Error(`Preset "${presetPath}" must have at least one of: rules/, commands/, hooks.json, or assets/`);
+    const hasSkills = fs_extra_1.default.existsSync(node_path_1.default.join(presetRootDir, "skills"));
+    if (!hasRules && !hasCommands && !hasHooks && !hasAssets && !hasSkills) {
+        throw new Error(`Preset "${presetPath}" must have at least one of: rules/, commands/, skills/, hooks.json, or assets/`);
     }
     return {
         config: presetConfig,
@@ -269,6 +304,7 @@ async function loadAllRules(config, cwd) {
     const allRules = [];
     const allCommands = [];
     const allAssets = [];
+    const allSkills = [];
     const allHookFiles = [];
     const allHooksConfigs = [];
     let mergedMcpServers = { ...config.mcpServers };
@@ -300,6 +336,12 @@ async function loadAllRules(config, cwd) {
             const localAssets = await loadAssetsFromDirectory(assetsPath, "local");
             allAssets.push(...localAssets);
         }
+        // Load skills from skills/ subdirectory
+        const skillsPath = node_path_1.default.join(rootPath, "skills");
+        if (fs_extra_1.default.existsSync(skillsPath)) {
+            const localSkills = await loadSkillsFromDirectory(skillsPath, "local");
+            allSkills.push(...localSkills);
+        }
     }
     // Load presets
     if (config.presets) {
@@ -331,6 +373,12 @@ async function loadAllRules(config, cwd) {
                 const presetAssets = await loadAssetsFromDirectory(presetAssetsPath, "preset", presetPath);
                 allAssets.push(...presetAssets);
             }
+            // Load preset skills from skills/ subdirectory
+            const presetSkillsPath = node_path_1.default.join(presetRootDir, "skills");
+            if (fs_extra_1.default.existsSync(presetSkillsPath)) {
+                const presetSkills = await loadSkillsFromDirectory(presetSkillsPath, "preset", presetPath);
+                allSkills.push(...presetSkills);
+            }
             // Merge MCP servers from preset
             if (preset.config.mcpServers) {
                 mergedMcpServers = mergePresetMcpServers(mergedMcpServers, preset.config.mcpServers);
@@ -343,6 +391,7 @@ async function loadAllRules(config, cwd) {
         rules: allRules,
         commands: allCommands,
         assets: allAssets,
+        skills: allSkills,
         mcpServers: mergedMcpServers,
         hooks: mergedHooks,
         hookFiles: allHookFiles,
@@ -380,6 +429,18 @@ async function loadConfigFile(searchFrom) {
         throw new Error(`Failed to load configuration: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
 }
+/**
+ * Check if workspaces mode is enabled without loading all rules/presets
+ * This is useful for commands that only need to know the workspace setting
+ */
+async function checkWorkspacesEnabled(cwd) {
+    const workingDir = cwd || process.cwd();
+    const configResult = await loadConfigFile(workingDir);
+    if (!(configResult === null || configResult === void 0 ? void 0 : configResult.config)) {
+        return detectWorkspacesFromPackageJson(workingDir);
+    }
+    return resolveWorkspaces(configResult.config, configResult.filepath, workingDir);
+}
 async function loadConfig(cwd) {
     const workingDir = cwd || process.cwd();
     const configResult = await loadConfigFile(workingDir);
@@ -390,12 +451,13 @@ async function loadConfig(cwd) {
     const isWorkspaces = resolveWorkspaces(config, configResult.filepath, workingDir);
     validateConfig(config, configResult.filepath, workingDir, isWorkspaces);
     const configWithDefaults = applyDefaults(config, isWorkspaces);
-    const { rules, commands, assets, mcpServers, hooks, hookFiles } = await loadAllRules(configWithDefaults, workingDir);
+    const { rules, commands, assets, skills, mcpServers, hooks, hookFiles } = await loadAllRules(configWithDefaults, workingDir);
     return {
         config: configWithDefaults,
         rules,
         commands,
         assets,
+        skills,
         mcpServers,
         hooks,
         hookFiles,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicm",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "A TypeScript CLI tool for managing AI IDE rules across different projects and teams",
   "main": "dist/api.js",
   "types": "dist/api.d.ts",
@@ -12,6 +12,21 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "start": "node dist/bin/aicm.js",
+    "dev": "ts-node src/bin/aicm.ts",
+    "test": "pnpm build && jest",
+    "test:watch": "jest --watch",
+    "test:all": "npm run build && npm run test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint",
+    "prepare": "husky install && npx ts-node src/bin/aicm.ts install",
+    "version": "auto-changelog -p && git add CHANGELOG.md",
+    "release": "np --no-tests"
+  },
   "keywords": [
     "ai",
     "ide",
@@ -51,18 +66,5 @@
     "*.{js,ts,json,md,mjs}": "prettier --write",
     "*.ts": "eslint"
   },
-  "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch",
-    "start": "node dist/bin/aicm.js",
-    "dev": "ts-node src/bin/aicm.ts",
-    "test": "pnpm build && jest",
-    "test:watch": "jest --watch",
-    "test:all": "npm run build && npm run test",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "eslint",
-    "version": "auto-changelog -p && git add CHANGELOG.md",
-    "release": "np --no-tests"
-  }
-}
+  "packageManager": "pnpm@10.18.3"
+}