aicm 0.20.0 → 0.20.1

package/README.md

@@ -17,6 +17,7 @@ A CLI tool for managing Agentic configurations across projects.
   - [Rules](#rules)
   - [Commands](#commands)
   - [Skills](#skills)
+  - [Agents](#agents)
   - [Hooks](#hooks)
   - [MCP Servers](#mcp-servers)
   - [Assets](#assets)
@@ -88,6 +89,7 @@ After installation, open Cursor and ask it to do something. Your AI assistant wi
 │   └── react.mdc
 ├── commands/        # Command files (.md) [optional]
 ├── skills/          # Agent Skills [optional]
+├── agents/          # Subagents (.md) [optional]
 ├── assets/          # Auxiliary files [optional]
 └── hooks.json       # Hook configuration [optional]
 ```
@@ -142,7 +144,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/`, `.cursor/skills/`, `.claude/`, and `.codex/` to `.gitignore` to avoid tracking generated files.
+- Users may add `.cursor/*/aicm/`, `.cursor/skills/`, `.cursor/agents/`, `.claude/`, and `.codex/` to `.gitignore` to avoid tracking generated files.
 
 ## Features
 
@@ -255,6 +257,77 @@ When installed, each skill directory is copied in its entirety (including `scrip
 
 In workspace mode, skills are installed both to each package and merged at the root level, similar to commands.
 
+### Agents
+
+aicm supports [Cursor Subagents](https://cursor.com/docs/context/subagents) and [Claude Code Subagents](https://code.claude.com/docs/en/sub-agents) - specialized AI assistants that can be delegated specific tasks. Agents are markdown files with YAML frontmatter that define custom prompts, descriptions, and model configurations.
+
+Create an `agents/` directory in your project (at the `rootDir` location):
+
+```
+my-project/
+├── aicm.json
+└── agents/
+    ├── code-reviewer.md
+    ├── debugger.md
+    └── specialized/
+        └── security-auditor.md
+```
+
+Each agent file should have YAML frontmatter with at least a `name` and `description`:
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for quality and best practices. Use after code changes.
+model: inherit
+---
+
+You are a senior code reviewer ensuring high standards of code quality and security.
+
+When invoked:
+
+1. Run git diff to see recent changes
+2. Focus on modified files
+3. Begin review immediately
+
+Review checklist:
+
+- Code is clear and readable
+- Functions and variables are well-named
+- No duplicated code
+- Proper error handling
+```
+
+Configure your `aicm.json`:
+
+```json
+{
+  "rootDir": "./",
+  "targets": ["cursor", "claude"]
+}
+```
+
+Agents are installed to different locations based on the target:
+
+| Target     | Agents Location   |
+| ---------- | ----------------- |
+| **Cursor** | `.cursor/agents/` |
+| **Claude** | `.claude/agents/` |
+
+A `.aicm.json` metadata file is created in the agents directory to track which agents are managed by aicm. This allows the clean command to remove only aicm-managed agents while preserving any manually created agents.
+
+**Supported Configuration Fields:**
+
+Only fields that work in both Cursor and Claude Code are documented:
+
+- `name` - Unique identifier (defaults to filename without extension)
+- `description` - When the agent should be used for task delegation
+- `model` - Model to use (`inherit`, or platform-specific values like `sonnet`, `haiku`, `fast`)
+
+> **Note:** Users may include additional platform-specific fields (e.g., `tools`, `hooks` for Claude Code, or `readonly`, `is_background` for Cursor) - aicm will preserve them, but they only work on the respective platform.
+
+In workspace mode, agents are installed both to each package and merged at the root level, similar to commands and skills.
+
 ### 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.
@@ -431,10 +504,11 @@ 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, commands, and skills for each package individually in their respective directories.
+2. **Install per package**: Install rules, commands, skills, and agents 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.
+6. **Merge agents**: Write merged agents to the repository root (e.g., `.cursor/agents/`) containing all agents from every package.
 
 For example, in a workspace structure like:
 
@@ -492,7 +566,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/`, `skills/`, `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/`, `agents/`, `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.
@@ -542,6 +616,8 @@ my-project/
 ├── skills/          # Agent Skills [optional]
 │   └── my-skill/
 │       └── SKILL.md
+├── agents/          # Subagents (.md) [optional]
+│   └── code-reviewer.md
 ├── assets/          # Auxiliary files [optional]
 │   ├── schema.json
 │   └── examples/

package/dist/commands/clean.js

@@ -200,6 +200,62 @@ function cleanSkills(cwd, verbose) {
     }
     return cleanedCount;
 }
+/**
+ * Clean aicm-managed agents from agents directories
+ * Only removes agents that are tracked in .aicm.json metadata file
+ */
+function cleanAgents(cwd, verbose) {
+    let cleanedCount = 0;
+    // Agents directories for each target
+    const agentsDirs = [
+        node_path_1.default.join(cwd, ".cursor", "agents"),
+        node_path_1.default.join(cwd, ".claude", "agents"),
+    ];
+    for (const agentsDir of agentsDirs) {
+        const metadataPath = node_path_1.default.join(agentsDir, ".aicm.json");
+        if (!fs_extra_1.default.existsSync(metadataPath)) {
+            continue;
+        }
+        try {
+            const metadata = fs_extra_1.default.readJsonSync(metadataPath);
+            // Remove all managed agents (names only)
+            for (const agentName of metadata.managedAgents || []) {
+                // Skip invalid names containing path separators (security check)
+                if (agentName.includes("/") || agentName.includes("\\")) {
+                    console.warn(chalk_1.default.yellow(`Warning: Skipping invalid agent name "${agentName}" (contains path separator)`));
+                    continue;
+                }
+                const fullPath = node_path_1.default.join(agentsDir, agentName + ".md");
+                if (fs_extra_1.default.existsSync(fullPath)) {
+                    fs_extra_1.default.removeSync(fullPath);
+                    if (verbose) {
+                        console.log(chalk_1.default.gray(`  Removed agent ${fullPath}`));
+                    }
+                    cleanedCount++;
+                }
+            }
+            // Remove the metadata file
+            fs_extra_1.default.removeSync(metadataPath);
+            if (verbose) {
+                console.log(chalk_1.default.gray(`  Removed ${metadataPath}`));
+            }
+            // Remove the agents directory if it's now empty
+            if (fs_extra_1.default.existsSync(agentsDir)) {
+                const remainingEntries = fs_extra_1.default.readdirSync(agentsDir);
+                if (remainingEntries.length === 0) {
+                    fs_extra_1.default.removeSync(agentsDir);
+                    if (verbose) {
+                        console.log(chalk_1.default.gray(`  Removed empty directory ${agentsDir}`));
+                    }
+                }
+            }
+        }
+        catch (_a) {
+            console.warn(chalk_1.default.yellow(`Warning: Failed to clean agents in ${agentsDir}`));
+        }
+    }
+    return cleanedCount;
+}
 function cleanEmptyDirectories(cwd, verbose) {
     let cleanedCount = 0;
     const dirsToCheck = [
@@ -208,8 +264,10 @@ function cleanEmptyDirectories(cwd, verbose) {
         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", "agents"),
         node_path_1.default.join(cwd, ".cursor"),
         node_path_1.default.join(cwd, ".claude", "skills"),
+        node_path_1.default.join(cwd, ".claude", "agents"),
         node_path_1.default.join(cwd, ".claude"),
         node_path_1.default.join(cwd, ".codex", "skills"),
         node_path_1.default.join(cwd, ".codex"),
@@ -266,6 +324,8 @@ async function cleanPackage(options = {}) {
             cleanedCount++;
         // Clean skills
         cleanedCount += cleanSkills(cwd, verbose);
+        // Clean agents
+        cleanedCount += cleanAgents(cwd, verbose);
         // Clean empty directories
         cleanedCount += cleanEmptyDirectories(cwd, verbose);
         return {

package/dist/commands/install-workspaces.js

@@ -87,6 +87,51 @@ function collectWorkspaceSkillTargets(packages) {
     }
     return Array.from(targets);
 }
+/**
+ * Merge agents from multiple workspace packages
+ * Agents are merged flat (not namespaced by preset)
+ * Dedupes preset agents that appear in multiple packages
+ */
+function mergeWorkspaceAgents(packages) {
+    var _a;
+    const agents = [];
+    const seenPresetAgents = new Set();
+    for (const pkg of packages) {
+        // Agents are supported by cursor and claude targets
+        const hasAgentsTarget = pkg.config.config.targets.includes("cursor") ||
+            pkg.config.config.targets.includes("claude");
+        if (!hasAgentsTarget) {
+            continue;
+        }
+        for (const agent of (_a = pkg.config.agents) !== null && _a !== void 0 ? _a : []) {
+            if (agent.presetName) {
+                // Dedupe preset agents by preset+name combination
+                const presetKey = `${agent.presetName}::${agent.name}`;
+                if (seenPresetAgents.has(presetKey)) {
+                    continue;
+                }
+                seenPresetAgents.add(presetKey);
+            }
+            agents.push(agent);
+        }
+    }
+    return agents;
+}
+/**
+ * Collect all targets that support agents from workspace packages
+ */
+function collectWorkspaceAgentTargets(packages) {
+    const targets = new Set();
+    for (const pkg of packages) {
+        for (const target of pkg.config.config.targets) {
+            // Agents are supported by cursor and claude
+            if (target === "cursor" || target === "claude") {
+                targets.add(target);
+            }
+        }
+    }
+    return Array.from(targets);
+}
 function mergeWorkspaceMcpServers(packages) {
     const merged = {};
     const info = {};
@@ -148,6 +193,7 @@ async function installWorkspacesPackages(packages, options = {}) {
     let totalAssetCount = 0;
     let totalHookCount = 0;
     let totalSkillCount = 0;
+    let totalAgentCount = 0;
     // Install packages sequentially for now (can be parallelized later)
     for (const pkg of packages) {
         const packagePath = pkg.absolutePath;
@@ -162,6 +208,7 @@ async function installWorkspacesPackages(packages, options = {}) {
             totalAssetCount += result.installedAssetCount;
             totalHookCount += result.installedHookCount;
             totalSkillCount += result.installedSkillCount;
+            totalAgentCount += result.installedAgentCount;
             results.push({
                 path: pkg.relativePath,
                 success: result.success,
@@ -171,6 +218,7 @@ async function installWorkspacesPackages(packages, options = {}) {
                 installedAssetCount: result.installedAssetCount,
                 installedHookCount: result.installedHookCount,
                 installedSkillCount: result.installedSkillCount,
+                installedAgentCount: result.installedAgentCount,
             });
         }
         catch (error) {
@@ -183,6 +231,7 @@ async function installWorkspacesPackages(packages, options = {}) {
                 installedAssetCount: 0,
                 installedHookCount: 0,
                 installedSkillCount: 0,
+                installedAgentCount: 0,
             });
         }
     }
@@ -195,6 +244,7 @@ async function installWorkspacesPackages(packages, options = {}) {
         totalAssetCount,
         totalHookCount,
         totalSkillCount,
+        totalAgentCount,
     };
 }
 /**
@@ -213,12 +263,13 @@ 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, skills, or presets
+            // For root directories, only keep if it has rules, commands, skills, agents, 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 hasAgents = pkg.config.agents && pkg.config.agents.length > 0;
             const hasPresets = pkg.config.config.presets && pkg.config.config.presets.length > 0;
-            return hasRules || hasCommands || hasSkills || hasPresets;
+            return hasRules || hasCommands || hasSkills || hasAgents || hasPresets;
         });
         if (packages.length === 0) {
             return {
@@ -229,6 +280,7 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                 installedAssetCount: 0,
                 installedHookCount: 0,
                 installedSkillCount: 0,
+                installedAgentCount: 0,
                 packagesCount: 0,
             };
         }
@@ -271,6 +323,18 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
             const dedupedWorkspaceSkills = (0, install_1.dedupeSkillsForInstall)(workspaceSkills);
             (0, install_1.writeSkillsToTargets)(dedupedWorkspaceSkills, workspaceSkillTargets);
         }
+        // Merge and write agents for workspace
+        const workspaceAgents = mergeWorkspaceAgents(packages);
+        const workspaceAgentTargets = collectWorkspaceAgentTargets(packages);
+        if (workspaceAgents.length > 0) {
+            (0, install_1.warnPresetAgentCollisions)(workspaceAgents);
+        }
+        if (!dryRun &&
+            workspaceAgents.length > 0 &&
+            workspaceAgentTargets.length > 0) {
+            const dedupedWorkspaceAgents = (0, install_1.dedupeAgentsForInstall)(workspaceAgents);
+            (0, install_1.writeAgentsToTargets)(dedupedWorkspaceAgents, workspaceAgentTargets);
+        }
         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) {
@@ -299,6 +363,9 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                     if (pkg.installedSkillCount > 0) {
                         summaryParts.push(`${pkg.installedSkillCount} skill${pkg.installedSkillCount === 1 ? "" : "s"}`);
                     }
+                    if (pkg.installedAgentCount > 0) {
+                        summaryParts.push(`${pkg.installedAgentCount} agent${pkg.installedAgentCount === 1 ? "" : "s"}`);
+                    }
                     console.log(chalk_1.default.green(`✅ ${pkg.path} (${summaryParts.join(", ")})`));
                 }
                 else {
@@ -319,7 +386,10 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                 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})`));
+                const agentSummary = result.totalAgentCount > 0
+                    ? `, ${result.totalAgentCount} agent${result.totalAgentCount === 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}${agentSummary})`));
                 console.log(chalk_1.default.red(`Failed packages: ${failedPackages.map((p) => p.path).join(", ")}`));
             }
             const errorDetails = failedPackages
@@ -333,6 +403,7 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
                 installedAssetCount: result.totalAssetCount,
                 installedHookCount: result.totalHookCount,
                 installedSkillCount: result.totalSkillCount,
+                installedAgentCount: result.totalAgentCount,
                 packagesCount: result.packages.length,
             };
         }
@@ -343,6 +414,7 @@ async function installWorkspaces(cwd, installOnCI, verbose = false, dryRun = fal
             installedAssetCount: result.totalAssetCount,
             installedHookCount: result.totalHookCount,
             installedSkillCount: result.totalSkillCount,
+            installedAgentCount: result.totalAgentCount,
             packagesCount: result.packages.length,
         };
     });

package/dist/commands/install.d.ts

@@ -1,4 +1,4 @@
-import { ResolvedConfig, CommandFile, AssetFile, SkillFile, MCPServers, SupportedTarget } from "../utils/config";
+import { ResolvedConfig, CommandFile, AssetFile, SkillFile, AgentFile, MCPServers, SupportedTarget } from "../utils/config";
 export interface InstallOptions {
     /**
      * Base directory to use instead of process.cwd()
@@ -53,6 +53,10 @@ export interface InstallResult {
      * Number of skills installed
      */
     installedSkillCount: number;
+    /**
+     * Number of agents installed
+     */
+    installedAgentCount: number;
     /**
      * Number of packages installed
      */
@@ -72,6 +76,20 @@ export declare function warnPresetSkillCollisions(skills: SkillFile[]): void;
  * Dedupe skills by name (last one wins)
  */
 export declare function dedupeSkillsForInstall(skills: SkillFile[]): SkillFile[];
+/**
+ * Write agents to all supported target directories
+ * Similar to skills, agents are written directly to the agents directory
+ * with a .aicm.json metadata file tracking which agents are managed
+ */
+export declare function writeAgentsToTargets(agents: AgentFile[], targets: SupportedTarget[]): void;
+/**
+ * Warn about agent name collisions from different presets
+ */
+export declare function warnPresetAgentCollisions(agents: AgentFile[]): void;
+/**
+ * Dedupe agents by name (last one wins)
+ */
+export declare function dedupeAgentsForInstall(agents: AgentFile[]): AgentFile[];
 export declare function warnPresetCommandCollisions(commands: CommandFile[]): void;
 export declare function dedupeCommandsForInstall(commands: CommandFile[]): CommandFile[];
 /**

package/dist/commands/install.js

@@ -8,6 +8,9 @@ exports.writeCommandsToTargets = writeCommandsToTargets;
 exports.writeSkillsToTargets = writeSkillsToTargets;
 exports.warnPresetSkillCollisions = warnPresetSkillCollisions;
 exports.dedupeSkillsForInstall = dedupeSkillsForInstall;
+exports.writeAgentsToTargets = writeAgentsToTargets;
+exports.warnPresetAgentCollisions = warnPresetAgentCollisions;
+exports.dedupeAgentsForInstall = dedupeAgentsForInstall;
 exports.warnPresetCommandCollisions = warnPresetCommandCollisions;
 exports.dedupeCommandsForInstall = dedupeCommandsForInstall;
 exports.writeMcpServersToFile = writeMcpServersToFile;
@@ -330,6 +333,115 @@ function dedupeSkillsForInstall(skills) {
     }
     return Array.from(unique.values());
 }
+/**
+ * Get the agents installation path for a target
+ * Returns null for targets that don't support agents
+ */
+function getAgentsTargetPath(target) {
+    const projectDir = process.cwd();
+    switch (target) {
+        case "cursor":
+            return node_path_1.default.join(projectDir, ".cursor", "agents");
+        case "claude":
+            return node_path_1.default.join(projectDir, ".claude", "agents");
+        case "codex":
+        case "windsurf":
+            // Codex and Windsurf do not support agents
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Write agents to all supported target directories
+ * Similar to skills, agents are written directly to the agents directory
+ * with a .aicm.json metadata file tracking which agents are managed
+ */
+function writeAgentsToTargets(agents, targets) {
+    if (agents.length === 0)
+        return;
+    for (const target of targets) {
+        const targetAgentsDir = getAgentsTargetPath(target);
+        if (!targetAgentsDir) {
+            // Target doesn't support agents
+            continue;
+        }
+        // Ensure the agents directory exists
+        fs_extra_1.default.ensureDirSync(targetAgentsDir);
+        // Read existing metadata to clean up old managed agents
+        const metadataPath = node_path_1.default.join(targetAgentsDir, ".aicm.json");
+        if (fs_extra_1.default.existsSync(metadataPath)) {
+            try {
+                const existingMetadata = fs_extra_1.default.readJsonSync(metadataPath);
+                // Remove previously managed agents
+                for (const agentName of existingMetadata.managedAgents || []) {
+                    // Skip invalid names containing path separators
+                    if (agentName.includes("/") || agentName.includes("\\")) {
+                        console.warn(chalk_1.default.yellow(`Warning: Skipping invalid agent name "${agentName}" (contains path separator)`));
+                        continue;
+                    }
+                    const fullPath = node_path_1.default.join(targetAgentsDir, agentName + ".md");
+                    if (fs_extra_1.default.existsSync(fullPath)) {
+                        fs_extra_1.default.removeSync(fullPath);
+                    }
+                }
+            }
+            catch (_a) {
+                // Ignore errors reading metadata
+            }
+        }
+        const managedAgents = [];
+        for (const agent of agents) {
+            // Use base name only
+            const agentName = node_path_1.default.basename(agent.name, node_path_1.default.extname(agent.name));
+            const agentFile = node_path_1.default.join(targetAgentsDir, agentName + ".md");
+            fs_extra_1.default.writeFileSync(agentFile, agent.content);
+            managedAgents.push(agentName);
+        }
+        // Write metadata file to track managed agents
+        const metadata = {
+            managedAgents,
+        };
+        fs_extra_1.default.writeJsonSync(metadataPath, metadata, { spaces: 2 });
+    }
+}
+/**
+ * Warn about agent name collisions from different presets
+ */
+function warnPresetAgentCollisions(agents) {
+    const collisions = new Map();
+    for (const agent of agents) {
+        if (!agent.presetName)
+            continue;
+        const entry = collisions.get(agent.name);
+        if (entry) {
+            entry.presets.add(agent.presetName);
+            entry.lastPreset = agent.presetName;
+        }
+        else {
+            collisions.set(agent.name, {
+                presets: new Set([agent.presetName]),
+                lastPreset: agent.presetName,
+            });
+        }
+    }
+    for (const [agentName, { 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 "${agentName}" agent (${presetList}). Using definition from ${lastPreset}.`));
+        }
+    }
+}
+/**
+ * Dedupe agents by name (last one wins)
+ */
+function dedupeAgentsForInstall(agents) {
+    const unique = new Map();
+    for (const agent of agents) {
+        unique.set(agent.name, agent);
+    }
+    return Array.from(unique.values());
+}
 function warnPresetCommandCollisions(commands) {
     const collisions = new Map();
     for (const command of commands) {
@@ -451,10 +563,11 @@ async function installPackage(options = {}) {
                 installedAssetCount: 0,
                 installedHookCount: 0,
                 installedSkillCount: 0,
+                installedAgentCount: 0,
                 packagesCount: 0,
             };
         }
-        const { config, rules, commands, assets, skills, mcpServers, hooks, hookFiles, } = resolvedConfig;
+        const { config, rules, commands, assets, skills, agents, mcpServers, hooks, hookFiles, } = resolvedConfig;
         if (config.skipInstall === true) {
             return {
                 success: true,
@@ -463,6 +576,7 @@ async function installPackage(options = {}) {
                 installedAssetCount: 0,
                 installedHookCount: 0,
                 installedSkillCount: 0,
+                installedAgentCount: 0,
                 packagesCount: 0,
             };
         }
@@ -470,11 +584,14 @@ async function installPackage(options = {}) {
         const commandsToInstall = dedupeCommandsForInstall(commands);
         warnPresetSkillCollisions(skills);
         const skillsToInstall = dedupeSkillsForInstall(skills);
+        warnPresetAgentCollisions(agents);
+        const agentsToInstall = dedupeAgentsForInstall(agents);
         try {
             if (!options.dryRun) {
                 writeRulesToTargets(rules, assets, config.targets);
                 writeCommandsToTargets(commandsToInstall, config.targets);
                 writeSkillsToTargets(skillsToInstall, config.targets);
+                writeAgentsToTargets(agentsToInstall, config.targets);
                 if (mcpServers && Object.keys(mcpServers).length > 0) {
                     writeMcpServersToTargets(mcpServers, config.targets, cwd);
                 }
@@ -486,6 +603,7 @@ async function installPackage(options = {}) {
             const uniqueCommandCount = new Set(commandsToInstall.map((command) => command.name)).size;
             const uniqueHookCount = (0, hooks_1.countHooks)(hooks);
             const uniqueSkillCount = skillsToInstall.length;
+            const uniqueAgentCount = agentsToInstall.length;
             return {
                 success: true,
                 installedRuleCount: uniqueRuleCount,
@@ -493,6 +611,7 @@ async function installPackage(options = {}) {
                 installedAssetCount: assets.length,
                 installedHookCount: uniqueHookCount,
                 installedSkillCount: uniqueSkillCount,
+                installedAgentCount: uniqueAgentCount,
                 packagesCount: 1,
             };
         }
@@ -505,6 +624,7 @@ async function installPackage(options = {}) {
                 installedAssetCount: 0,
                 installedHookCount: 0,
                 installedSkillCount: 0,
+                installedAgentCount: 0,
                 packagesCount: 0,
             };
         }
@@ -526,6 +646,7 @@ async function install(options = {}) {
             installedAssetCount: 0,
             installedHookCount: 0,
             installedSkillCount: 0,
+            installedAgentCount: 0,
             packagesCount: 0,
         };
     }
@@ -559,6 +680,7 @@ async function installCommand(installOnCI, verbose, dryRun) {
         const commandCount = result.installedCommandCount;
         const hookCount = result.installedHookCount;
         const skillCount = result.installedSkillCount;
+        const agentCount = result.installedAgentCount;
         const ruleMessage = ruleCount > 0 ? `${ruleCount} rule${ruleCount === 1 ? "" : "s"}` : null;
         const commandMessage = commandCount > 0
             ? `${commandCount} command${commandCount === 1 ? "" : "s"}`
@@ -567,6 +689,9 @@ async function installCommand(installOnCI, verbose, dryRun) {
         const skillMessage = skillCount > 0
             ? `${skillCount} skill${skillCount === 1 ? "" : "s"}`
             : null;
+        const agentMessage = agentCount > 0
+            ? `${agentCount} agent${agentCount === 1 ? "" : "s"}`
+            : null;
         const countsParts = [];
         if (ruleMessage) {
             countsParts.push(ruleMessage);
@@ -580,6 +705,9 @@ async function installCommand(installOnCI, verbose, dryRun) {
         if (skillMessage) {
             countsParts.push(skillMessage);
         }
+        if (agentMessage) {
+            countsParts.push(agentMessage);
+        }
         const countsMessage = countsParts.length > 0
             ? countsParts.join(", ").replace(/, ([^,]*)$/, " and $1")
             : "0 rules";
@@ -594,8 +722,9 @@ async function installCommand(installOnCI, verbose, dryRun) {
         else if (ruleCount === 0 &&
             commandCount === 0 &&
             hookCount === 0 &&
-            skillCount === 0) {
-            console.log("No rules, commands, hooks, or skills installed");
+            skillCount === 0 &&
+            agentCount === 0) {
+            console.log("No rules, commands, hooks, skills, or agents installed");
         }
         else if (result.packagesCount > 1) {
             console.log(`Successfully installed ${countsMessage} across ${result.packagesCount} packages`);

package/dist/utils/config.d.ts

@@ -52,6 +52,7 @@ export interface SkillFile {
     source: "local" | "preset";
     presetName?: string;
 }
+export type AgentFile = ManagedFile;
 export interface RuleCollection {
     [target: string]: RuleFile[];
 }
@@ -61,6 +62,7 @@ export interface ResolvedConfig {
     commands: CommandFile[];
     assets: AssetFile[];
     skills: SkillFile[];
+    agents: AgentFile[];
     mcpServers: MCPServers;
     hooks: HooksJson;
     hookFiles: HookFile[];
@@ -80,6 +82,11 @@ export declare function loadAssetsFromDirectory(directoryPath: string, source: "
  * 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[]>;
+/**
+ * Load agents from an agents/ directory
+ * Agents are markdown files (.md) with YAML frontmatter
+ */
+export declare function loadAgentsFromDirectory(directoryPath: string, source: "local" | "preset", presetName?: string): Promise<AgentFile[]>;
 /**
  * Extract namespace from preset path for directory structure
  * Handles both npm packages and local paths consistently
@@ -95,6 +102,7 @@ export declare function loadAllRules(config: Config, cwd: string): Promise<{
     commands: CommandFile[];
     assets: AssetFile[];
     skills: SkillFile[];
+    agents: AgentFile[];
     mcpServers: MCPServers;
     hooks: HooksJson;
     hookFiles: HookFile[];

package/dist/utils/config.js

@@ -12,6 +12,7 @@ exports.loadRulesFromDirectory = loadRulesFromDirectory;
 exports.loadCommandsFromDirectory = loadCommandsFromDirectory;
 exports.loadAssetsFromDirectory = loadAssetsFromDirectory;
 exports.loadSkillsFromDirectory = loadSkillsFromDirectory;
+exports.loadAgentsFromDirectory = loadAgentsFromDirectory;
 exports.extractNamespaceFromPresetPath = extractNamespaceFromPresetPath;
 exports.resolvePresetPath = resolvePresetPath;
 exports.loadPreset = loadPreset;
@@ -98,6 +99,7 @@ function validateConfig(config, configFilePath, cwd, isWorkspaceMode = false) {
         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"));
+        const hasAgents = fs_extra_1.default.existsSync(node_path_1.default.join(rootPath, "agents"));
         // In workspace mode, root config doesn't need these directories
         // since packages will have their own configurations
         if (!isWorkspaceMode &&
@@ -105,8 +107,9 @@ function validateConfig(config, configFilePath, cwd, isWorkspaceMode = false) {
             !hasCommands &&
             !hasHooks &&
             !hasSkills &&
+            !hasAgents &&
             !hasPresets) {
-            throw new Error(`Root directory must contain at least one of: rules/, commands/, skills/, hooks.json, or have presets configured`);
+            throw new Error(`Root directory must contain at least one of: rules/, commands/, skills/, agents/, hooks.json, or have presets configured`);
         }
     }
     else if (!isWorkspaceMode && !hasPresets) {
@@ -235,6 +238,35 @@ async function loadSkillsFromDirectory(directoryPath, source, presetName) {
     }
     return skills;
 }
+/**
+ * Load agents from an agents/ directory
+ * Agents are markdown files (.md) with YAML frontmatter
+ */
+async function loadAgentsFromDirectory(directoryPath, source, presetName) {
+    const agents = [];
+    if (!fs_extra_1.default.existsSync(directoryPath)) {
+        return agents;
+    }
+    const pattern = node_path_1.default.join(directoryPath, "**/*.md").replace(/\\/g, "/");
+    const filePaths = await (0, fast_glob_1.default)(pattern, {
+        onlyFiles: true,
+        absolute: true,
+    });
+    filePaths.sort();
+    for (const filePath of filePaths) {
+        const content = await fs_extra_1.default.readFile(filePath, "utf8");
+        const relativePath = node_path_1.default.relative(directoryPath, filePath);
+        const agentName = relativePath.replace(/\.md$/, "").replace(/\\/g, "/");
+        agents.push({
+            name: agentName,
+            content,
+            sourcePath: filePath,
+            source,
+            presetName,
+        });
+    }
+    return agents;
+}
 /**
  * Extract namespace from preset path for directory structure
  * Handles both npm packages and local paths consistently
@@ -292,8 +324,14 @@ async function loadPreset(presetPath, cwd) {
     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"));
     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/`);
+    const hasAgents = fs_extra_1.default.existsSync(node_path_1.default.join(presetRootDir, "agents"));
+    if (!hasRules &&
+        !hasCommands &&
+        !hasHooks &&
+        !hasAssets &&
+        !hasSkills &&
+        !hasAgents) {
+        throw new Error(`Preset "${presetPath}" must have at least one of: rules/, commands/, skills/, agents/, hooks.json, or assets/`);
     }
     return {
         config: presetConfig,
@@ -305,6 +343,7 @@ async function loadAllRules(config, cwd) {
     const allCommands = [];
     const allAssets = [];
     const allSkills = [];
+    const allAgents = [];
     const allHookFiles = [];
     const allHooksConfigs = [];
     let mergedMcpServers = { ...config.mcpServers };
@@ -342,6 +381,12 @@ async function loadAllRules(config, cwd) {
             const localSkills = await loadSkillsFromDirectory(skillsPath, "local");
             allSkills.push(...localSkills);
         }
+        // Load agents from agents/ subdirectory
+        const agentsPath = node_path_1.default.join(rootPath, "agents");
+        if (fs_extra_1.default.existsSync(agentsPath)) {
+            const localAgents = await loadAgentsFromDirectory(agentsPath, "local");
+            allAgents.push(...localAgents);
+        }
     }
     // Load presets
     if (config.presets) {
@@ -379,6 +424,12 @@ async function loadAllRules(config, cwd) {
                 const presetSkills = await loadSkillsFromDirectory(presetSkillsPath, "preset", presetPath);
                 allSkills.push(...presetSkills);
             }
+            // Load preset agents from agents/ subdirectory
+            const presetAgentsPath = node_path_1.default.join(presetRootDir, "agents");
+            if (fs_extra_1.default.existsSync(presetAgentsPath)) {
+                const presetAgents = await loadAgentsFromDirectory(presetAgentsPath, "preset", presetPath);
+                allAgents.push(...presetAgents);
+            }
             // Merge MCP servers from preset
             if (preset.config.mcpServers) {
                 mergedMcpServers = mergePresetMcpServers(mergedMcpServers, preset.config.mcpServers);
@@ -392,6 +443,7 @@ async function loadAllRules(config, cwd) {
         commands: allCommands,
         assets: allAssets,
         skills: allSkills,
+        agents: allAgents,
         mcpServers: mergedMcpServers,
         hooks: mergedHooks,
         hookFiles: allHookFiles,
@@ -451,13 +503,14 @@ 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, skills, mcpServers, hooks, hookFiles } = await loadAllRules(configWithDefaults, workingDir);
+    const { rules, commands, assets, skills, agents, mcpServers, hooks, hookFiles, } = await loadAllRules(configWithDefaults, workingDir);
     return {
         config: configWithDefaults,
         rules,
         commands,
         assets,
         skills,
+        agents,
         mcpServers,
         hooks,
         hookFiles,

package/dist/utils/safe-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check if a resolved path is safely within the specified base directory.
+ * This prevents path traversal attacks where malicious paths like "../../../etc"
+ * or absolute paths could escape the intended directory.
+ *
+ * @param baseDir - The directory that should contain the path
+ * @param relativePath - The potentially untrusted relative path
+ * @returns The safely resolved full path, or null if the path would escape baseDir
+ */
+export declare function resolveSafePath(baseDir: string, relativePath: string): string | null;

package/dist/utils/safe-path.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSafePath = resolveSafePath;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Check if a resolved path is safely within the specified base directory.
+ * This prevents path traversal attacks where malicious paths like "../../../etc"
+ * or absolute paths could escape the intended directory.
+ *
+ * @param baseDir - The directory that should contain the path
+ * @param relativePath - The potentially untrusted relative path
+ * @returns The safely resolved full path, or null if the path would escape baseDir
+ */
+function resolveSafePath(baseDir, relativePath) {
+    // Resolve both to absolute paths
+    const resolvedBase = node_path_1.default.resolve(baseDir);
+    const resolvedTarget = node_path_1.default.resolve(baseDir, relativePath);
+    // The resolved path must start with the base directory + separator
+    // This ensures it's truly inside the directory, not a sibling with similar prefix
+    // e.g., /foo/bar should not match /foo/bar-other
+    if (!resolvedTarget.startsWith(resolvedBase + node_path_1.default.sep)) {
+        return null;
+    }
+    return resolvedTarget;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicm",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "A TypeScript CLI tool for managing AI IDE rules across different projects and teams",
   "main": "dist/api.js",
   "types": "dist/api.d.ts",