claude-dev-env 2.15.0 → 2.16.0

package/bin/install.agents-home.test.mjs

@@ -0,0 +1,186 @@
+/**
+ * End-to-end install layout: skills and agents live under the agents home,
+ * and the Claude lookup paths are directory pointers to that home.
+ */
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import {
+    existsSync,
+    lstatSync,
+    mkdirSync,
+    mkdtempSync,
+    readFileSync,
+    realpathSync,
+    rmSync,
+    writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONTENT_DIRECTORIES } from './install.mjs';
+import {
+    MANAGED_AGENTS_DIRECTORY_NAME,
+    MANAGED_SKILLS_DIRECTORY_NAME,
+} from './install-constants.mjs';
+import { isDirectoryPointerTo } from './publish-directory-pointer.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+const SHIPPED_SKILL_NAME = 'privacy-hygiene';
+const SHIPPED_AGENT_FILE_NAME = 'clean-coder.md';
+const PERSONAL_SKILL_NAME = 'my-notes';
+
+/**
+ * @param {string} homeDirectory
+ * @param {string[]} extraArguments
+ * @returns {string}
+ */
+function runInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [INSTALLER_PATH, ...extraArguments], {
+        cwd: PACKAGE_DIRECTORY,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            CODEX_HOME: join(homeDirectory, '.codex'),
+        },
+    });
+}
+
+test('CONTENT_DIRECTORIES omits agents because that tree installs to the agents home', () => {
+    assert.equal(CONTENT_DIRECTORIES.includes(MANAGED_AGENTS_DIRECTORY_NAME), false);
+});
+
+test('a full install writes skills and agents under .agents and points .claude at them', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-home-'));
+    const claudeHome = join(homeDirectory, '.claude');
+    const agentsHome = join(homeDirectory, '.agents');
+    const skillsInstallDirectory = join(agentsHome, MANAGED_SKILLS_DIRECTORY_NAME);
+    const agentsInstallDirectory = join(agentsHome, MANAGED_AGENTS_DIRECTORY_NAME);
+    const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
+    const agentsLookupDirectory = join(claudeHome, MANAGED_AGENTS_DIRECTORY_NAME);
+    try {
+        runInstaller(homeDirectory, []);
+
+        const canonicalSkillFile = join(
+            skillsInstallDirectory, SHIPPED_SKILL_NAME, 'SKILL.md',
+        );
+        const lookupSkillFile = join(
+            skillsLookupDirectory, SHIPPED_SKILL_NAME, 'SKILL.md',
+        );
+        const canonicalAgentFile = join(agentsInstallDirectory, SHIPPED_AGENT_FILE_NAME);
+        const lookupAgentFile = join(agentsLookupDirectory, SHIPPED_AGENT_FILE_NAME);
+
+        assert.equal(existsSync(canonicalSkillFile), true, 'skill file lives under .agents/skills');
+        assert.equal(existsSync(canonicalAgentFile), true, 'agent file lives under .agents/agents');
+        assert.equal(lstatSync(skillsLookupDirectory).isSymbolicLink(), true);
+        assert.equal(lstatSync(agentsLookupDirectory).isSymbolicLink(), true);
+        assert.equal(
+            isDirectoryPointerTo(skillsLookupDirectory, skillsInstallDirectory),
+            true,
+        );
+        assert.equal(
+            isDirectoryPointerTo(agentsLookupDirectory, agentsInstallDirectory),
+            true,
+        );
+        assert.equal(
+            readFileSync(lookupSkillFile, 'utf8'),
+            readFileSync(canonicalSkillFile, 'utf8'),
+        );
+        assert.equal(realpathSync(lookupSkillFile), realpathSync(canonicalSkillFile));
+        assert.equal(
+            readFileSync(lookupAgentFile, 'utf8'),
+            readFileSync(canonicalAgentFile, 'utf8'),
+        );
+        assert.equal(realpathSync(lookupAgentFile), realpathSync(canonicalAgentFile));
+        assert.equal(
+            lstatSync(skillsInstallDirectory).isSymbolicLink(),
+            false,
+            'the agents-home skills directory is a real directory',
+        );
+        assert.equal(
+            lstatSync(agentsInstallDirectory).isSymbolicLink(),
+            false,
+            'the agents-home agents directory is a real directory',
+        );
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a real skills directory from an older install lands in .agents and stays readable through the pointer', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-relocate-'));
+    const claudeHome = join(homeDirectory, '.claude');
+    const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
+    const personalSkillFile = join(
+        skillsLookupDirectory, PERSONAL_SKILL_NAME, 'notes.md',
+    );
+    try {
+        mkdirSync(join(skillsLookupDirectory, PERSONAL_SKILL_NAME), { recursive: true });
+        writeFileSync(personalSkillFile, 'keep this personal skill\n');
+
+        runInstaller(homeDirectory, []);
+
+        const canonicalPersonalFile = join(
+            homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME,
+            PERSONAL_SKILL_NAME, 'notes.md',
+        );
+        assert.equal(lstatSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME)).isSymbolicLink(), true);
+        assert.equal(existsSync(canonicalPersonalFile), true);
+        assert.equal(
+            readFileSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md'), 'utf8'),
+            'keep this personal skill\n',
+        );
+        assert.equal(
+            realpathSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md')),
+            realpathSync(canonicalPersonalFile),
+        );
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('uninstall removes managed skill files from the agents home and leaves a personal skill reachable through the pointer', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-uninstall-'));
+    const claudeHome = join(homeDirectory, '.claude');
+    const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
+    try {
+        mkdirSync(join(skillsLookupDirectory, PERSONAL_SKILL_NAME), { recursive: true });
+        writeFileSync(
+            join(skillsLookupDirectory, PERSONAL_SKILL_NAME, 'notes.md'),
+            'keep this personal skill\n',
+        );
+        runInstaller(homeDirectory, []);
+        runInstaller(homeDirectory, ['--uninstall']);
+
+        const shippedSkillFile = join(
+            homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME,
+            SHIPPED_SKILL_NAME, 'SKILL.md',
+        );
+        const personalSkillFile = join(
+            homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME,
+            PERSONAL_SKILL_NAME, 'notes.md',
+        );
+        assert.equal(existsSync(shippedSkillFile), false);
+        assert.equal(existsSync(personalSkillFile), true);
+        assert.equal(
+            isDirectoryPointerTo(
+                join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME),
+                join(homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME),
+            ),
+            true,
+            'the lookup pointer stays so a personal skill remains discoverable',
+        );
+        assert.equal(
+            readFileSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md'), 'utf8'),
+            'keep this personal skill\n',
+        );
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});

package/bin/install.mjs

@@ -20,6 +20,7 @@ import {
     SKIPPED_SOURCE_FILE_EXTENSIONS,
     RUN_BACKUP_DIRECTORY_NAME_PATTERN,
     MANAGED_SKILLS_DIRECTORY_NAME,
+    MANAGED_AGENTS_DIRECTORY_NAME,
     MANAGED_HOOKS_DIRECTORY_NAME,
     SETTINGS_FILE_NAME,
     CODEX_RULES_PACKAGE_DIRECTORY_NAME,
@@ -31,6 +32,12 @@ import {
     parseExplicitTargetFromArgv,
     isAllowedInstallDestination,
 } from './resolve-install-root.mjs';
+import {
+    resolvePackageManagedDirectory,
+} from './resolve-package-managed-directory.mjs';
+import {
+    ensureDirectoryPointer,
+} from './publish-directory-pointer.mjs';
 import {
     parseInstallTargetSelectionFromArgv,
     resolveInstallTargets,
@@ -67,6 +74,7 @@ const INSTALL_ROOT_RESOLUTION = resolveInstallRoot({
     })(),
 });
 const CLAUDE_HOME = INSTALL_ROOT_RESOLUTION.managedRoot;
+const AGENTS_HOME = INSTALL_ROOT_RESOLUTION.agentsHome;
 const MANIFEST_FILE = INSTALL_ROOT_RESOLUTION.manifestFilePath;
 const MYPY_INI_INSTALL_PATH = INSTALL_ROOT_RESOLUTION.mypyIniInstallPath;
 const PACKAGE_NAME = 'claude-dev-env';
@@ -92,18 +100,21 @@ const INSTALL_TARGET_IDENTITY = (() => {
     }
 })();
 
-export const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents', 'system-prompts', 'scripts', '_shared', 'audit-rubrics'];
+export const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'system-prompts', 'scripts', '_shared', 'audit-rubrics'];
 
 /**
- * Every top-level directory under ~/.claude the installer writes into: the
- * content directories plus the two it fills through their own copy loops. The
- * uninstall purge walks this list to find the root a recorded file belongs to and
- * to drop a managed directory the purge empties, and the full-install stale-file
- * prune walks it to give each root its own diff.
+ * Every top-level lookup directory the installer writes into under ~/.claude:
+ * the content directories plus skills, agents, and hooks. Skills and agents
+ * live under the agents home; `~/.claude/skills` and `~/.claude/agents` are
+ * directory pointers to that home. The uninstall purge walks this list to find
+ * the root a recorded file belongs to and to drop a managed directory the purge
+ * empties, and the full-install stale-file prune walks it to give each root its
+ * own diff.
  */
 export const MANAGED_TOP_LEVEL_DIRECTORY_NAMES = [
     ...CONTENT_DIRECTORIES,
     MANAGED_SKILLS_DIRECTORY_NAME,
+    MANAGED_AGENTS_DIRECTORY_NAME,
     MANAGED_HOOKS_DIRECTORY_NAME,
 ];
 
@@ -114,6 +125,35 @@ const RETIRED_SKILL_REASON_LABEL = 'retired';
 const STALE_FILE_REASON_LABEL = 'stale';
 const MANIFEST_MANAGED_PERMISSIONS_KEY = 'managedPermissions';
 
+/**
+ * Managed-home-relative directories this package leaves to whoever deployed
+ * them: it writes nothing inside them and prunes nothing out of them.
+ *
+ * `scripts/profile-isolation-launchers` is the live CLI profile launcher. Its
+ * executable modules are deployed from a separate source, so a payload covering
+ * only part of that tree left config and code out of step. This package stopped
+ * shipping its part, and the stale-file prune reads a path the package no longer
+ * writes as stale, which would move the live files aside on the next install.
+ * Naming the directory here keeps both halves of the tree with their owner.
+ */
+const RETAINED_UNMANAGED_RELATIVE_PATHS = [
+    'scripts/profile-isolation-launchers',
+];
+
+/**
+ * Report whether a path a prior manifest recorded sits inside a directory this
+ * package leaves to another owner.
+ *
+ * @param {string} candidatePath The absolute path the prior manifest recorded.
+ * @param {string} managedHomeDirectory The managed home the relative names resolve against.
+ * @returns {boolean} True when the path sits inside a retained unmanaged directory.
+ */
+function isRetainedUnmanagedPath(candidatePath, managedHomeDirectory) {
+    return RETAINED_UNMANAGED_RELATIVE_PATHS.some(
+        relativePath => isInsideDirectory(candidatePath, join(managedHomeDirectory, relativePath)),
+    );
+}
+
 export const CORE_INCLUDE_DIRECTORIES = [
     'rules', 'docs', 'commands', 'agents', 'audit-rubrics', '_shared', 'scripts',
 ];
@@ -220,7 +260,10 @@ function discoverDependencyGroups() {
             description: dependencyPackageJson.description || dependencyName,
             packageRoot: dependencyRoot,
         };
-        const skillsDirectory = join(dependencyRoot, MANAGED_SKILLS_DIRECTORY_NAME);
+        const skillsDirectory = resolvePackageManagedDirectory(
+            dependencyRoot,
+            MANAGED_SKILLS_DIRECTORY_NAME,
+        );
         if (existsSync(skillsDirectory)) {
             group.skills = readdirSync(skillsDirectory, { withFileTypes: true })
                 .filter(entry => entry.isDirectory())
@@ -723,6 +766,10 @@ function owningManagedRoot(installedFilePath) {
         const managedRoot = join(CLAUDE_HOME, directoryName);
         if (isInsideDirectory(resolvedPath, managedRoot)) return managedRoot;
     }
+    for (const directoryName of [MANAGED_SKILLS_DIRECTORY_NAME, MANAGED_AGENTS_DIRECTORY_NAME]) {
+        const agentsRoot = join(AGENTS_HOME, directoryName);
+        if (isInsideDirectory(resolvedPath, agentsRoot)) return agentsRoot;
+    }
     const codexRulesDirectory = INSTALL_ROOT_RESOLUTION.codexRulesInstallDirectory;
     if (isInsideDirectory(resolvedPath, codexRulesDirectory)) return codexRulesDirectory;
     const cursorInstallDirectory = INSTALL_ROOT_RESOLUTION.cursorInstallDirectory;
@@ -730,6 +777,25 @@ function owningManagedRoot(installedFilePath) {
     return null;
 }
 
+/**
+ * Publish `~/.claude/skills` and `~/.claude/agents` as directory pointers to
+ * the agents home.
+ *
+ * Skills and agents live under `~/.agents` (or the per-root agents home).
+ * Claude Code discovers them at the lookup paths under the managed Claude root,
+ * so those two paths are pointers. A real directory from an older install at a
+ * lookup path is merged into the agents home before the pointer is written.
+ *
+ * @returns {string[]} The two lookup paths this run published.
+ */
+function publishSkillAndAgentLookupPointers() {
+    const skillsPointer = INSTALL_ROOT_RESOLUTION.skillsLookupDirectory;
+    const agentsPointer = INSTALL_ROOT_RESOLUTION.agentsLookupDirectory;
+    ensureDirectoryPointer(skillsPointer, INSTALL_ROOT_RESOLUTION.skillsInstallDirectory);
+    ensureDirectoryPointer(agentsPointer, INSTALL_ROOT_RESOLUTION.agentsInstallDirectory);
+    return [skillsPointer, agentsPointer];
+}
+
 /**
  * Report whether a path the prior manifest recorded is still a plain file this
  * run may move.
@@ -832,6 +898,7 @@ export function pruneStaleInstalledFiles(
         const stalePath = resolve(priorFile);
         if (!isInsideDirectory(stalePath, resolvedRoot)) continue;
         if (currentFileKeys.has(comparisonKeyForPath(stalePath, options))) continue;
+        if (isRetainedUnmanagedPath(stalePath, managedHomeDirectory)) continue;
         if (!isMovableStaleFile(stalePath)) continue;
         const backupRelativePath = relative(resolvedRoot, stalePath);
         const didMove = moveIntoRunBackup(
@@ -1944,6 +2011,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     console.log(`\nInstalling ${PACKAGE_NAME} (${groupLabel})...\n`);
     console.log(`  Python: ${pythonCommand}`);
     mkdirSync(CLAUDE_HOME, { recursive: true });
+    const publishedPointerPaths = publishSkillAndAgentLookupPointers();
 
     const activeGroups = selectedGroups
         ? selectedGroups.map(groupName => ({ groupName, ...INSTALL_GROUPS[groupName] }))
@@ -2017,6 +2085,27 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             }
         }
     }
+    const shouldCopyAgents = !allowedDirectories
+        || allowedDirectories.has(MANAGED_AGENTS_DIRECTORY_NAME);
+    if (shouldCopyAgents) {
+        for (const sourceRoot of allSourceRoots) {
+            const agentsSource = resolvePackageManagedDirectory(
+                sourceRoot,
+                MANAGED_AGENTS_DIRECTORY_NAME,
+            );
+            if (!existsSync(agentsSource)) continue;
+            const agentsDestination = INSTALL_ROOT_RESOLUTION.agentsLookupDirectory;
+            const stats = copyTree(agentsSource, agentsDestination);
+            if (!summary[MANAGED_AGENTS_DIRECTORY_NAME]) {
+                summary[MANAGED_AGENTS_DIRECTORY_NAME] = stats;
+            } else {
+                summary[MANAGED_AGENTS_DIRECTORY_NAME].created += stats.created;
+                summary[MANAGED_AGENTS_DIRECTORY_NAME].updated += stats.updated;
+                summary[MANAGED_AGENTS_DIRECTORY_NAME].paths.push(...stats.paths);
+            }
+            allInstalledFiles.push(...stats.paths);
+        }
+    }
     const shouldInstallCodexRules = !selectedGroups
         || activeGroups.some((eachGroup) => eachGroup.includeCodexRules);
     if (shouldInstallCodexRules) {
@@ -2047,7 +2136,10 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     const installedSkillNames = new Set();
     const copiedSkillNames = new Set();
     for (const sourceRoot of allSourceRoots) {
-        const skillsSource = join(sourceRoot, MANAGED_SKILLS_DIRECTORY_NAME);
+        const skillsSource = resolvePackageManagedDirectory(
+            sourceRoot,
+            MANAGED_SKILLS_DIRECTORY_NAME,
+        );
         if (!existsSync(skillsSource)) continue;
         const skillDirs = readdirSync(skillsSource, { withFileTypes: true }).filter(entry => entry.isDirectory());
         for (const skillDir of skillDirs) {
@@ -2066,7 +2158,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     }
     summary.skills = { created: skillsCreated, updated: skillsUpdated, pruned: 0, paths: skillPaths };
     allInstalledFiles.push(...skillPaths);
-    syncWrittenPaths(allInstalledFiles);
+    syncWrittenPaths([...allInstalledFiles, ...publishedPointerPaths]);
     throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
     throwIfFault(FAULT_PHASES.BEFORE_DURABLE_PROMOTION);
     const shouldInstallAnyHooks = shouldInstallAllHooks || (allowedHookFiles && allowedHookFiles.size > 0);
@@ -2101,7 +2193,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         console.log(`  Hook files: ${totalHooksCreated} new, ${totalHooksUpdated} updated`);
         summary.hookGroups = totalHookGroups;
         console.log(`  Hook groups: ${totalHookGroups} merged into settings.json`);
-        syncWrittenPaths(allInstalledFiles);
+        syncWrittenPaths([...allInstalledFiles, ...publishedPointerPaths]);
         throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
 
         console.warn(
@@ -2123,7 +2215,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             console.warn(`  Git hooks: ${gitHookInstallationResult.hooksPathConfigurationResult.reason}`);
         }
         console.log(`  Git hook shims: ${gitHookInstallationResult.createdShimPaths.length} files (pre-commit, pre-push, post-commit)`);
-        syncWrittenPaths(allInstalledFiles);
+        syncWrittenPaths([...allInstalledFiles, ...publishedPointerPaths]);
         throwIfFault(FAULT_PHASES.AFTER_GIT_CONFIG);
         throwIfFault(FAULT_PHASES.AFTER_LINK_PUBLICATION);
 
@@ -2143,7 +2235,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             console.warn(`      ${mypyIniInstallResult.expectedLine}`);
         }
     } else {
-        syncWrittenPaths(allInstalledFiles);
+        syncWrittenPaths([...allInstalledFiles, ...publishedPointerPaths]);
         throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
         throwIfFault(FAULT_PHASES.AFTER_GIT_CONFIG);
         throwIfFault(FAULT_PHASES.AFTER_LINK_PUBLICATION);
@@ -2162,7 +2254,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         );
     }
 
-    const claudeHubSource = join(PACKAGE_ROOT, 'CLAUDE.md');
+    const claudeHubSource = join(PACKAGE_ROOT, '.claude', 'CLAUDE.md');
     if (existsSync(claudeHubSource)) {
         const claudeHubDest = join(CLAUDE_HOME, 'CLAUDE.md');
         const backupPath = backupHubBeforeOverwrite(claudeHubDest, claudeHubSource, 'CLAUDE.md');
@@ -2228,7 +2320,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             ? { deny: managedPermissionDenyEntries }
             : null,
     );
-    syncWrittenPaths([...allInstalledFiles, MANIFEST_FILE, plan.settingsPath]);
+    syncWrittenPaths([...allInstalledFiles, MANIFEST_FILE, plan.settingsPath, ...publishedPointerPaths]);
     throwIfFault(FAULT_PHASES.AFTER_MANIFEST_WRITE);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
     for (const directory of CONTENT_DIRECTORIES) {
@@ -2245,6 +2337,10 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         const { created } = summary.cursorRules;
         console.log(`  cursor-rules: ${created} generated files`);
     }
+    if (summary[MANAGED_AGENTS_DIRECTORY_NAME]) {
+        const { created, updated } = summary[MANAGED_AGENTS_DIRECTORY_NAME];
+        console.log(`  ${MANAGED_AGENTS_DIRECTORY_NAME}: ${created + updated} files (${created} new, ${updated} updated)`);
+    }
     if (summary.skills) {
         const { created, updated, pruned } = summary.skills;
         const staleClause = pruned > 0 ? `, ${pruned} stale moved aside` : '';
@@ -2375,7 +2471,7 @@ function executeUninstallPlan(plan, helpers = {}) {
     }
     if (plan.skippedFiles.length > 0) {
         console.warn(
-            `  ${plan.skippedFiles.length} manifest record(s) skipped — each names a path outside ${CLAUDE_HOME}, outside ${MYPY_INI_INSTALL_PATH}, outside ${INSTALL_ROOT_RESOLUTION.codexRulesInstallDirectory}, and outside ${INSTALL_ROOT_RESOLUTION.cursorInstallDirectory}`,
+            `  ${plan.skippedFiles.length} manifest record(s) skipped — each names a path outside ${CLAUDE_HOME}, outside ${MYPY_INI_INSTALL_PATH}, outside ${INSTALL_ROOT_RESOLUTION.codexRulesInstallDirectory}, outside ${INSTALL_ROOT_RESOLUTION.cursorInstallDirectory}, and outside ${AGENTS_HOME}`,
         );
     }
     throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
@@ -2423,6 +2519,9 @@ function executeUninstallPlan(plan, helpers = {}) {
             }
         } catch { /* leave non-empty dirs */ }
     }
+    removeEmptyDirectoryTree(INSTALL_ROOT_RESOLUTION.skillsInstallDirectory);
+    removeEmptyDirectoryTree(INSTALL_ROOT_RESOLUTION.agentsInstallDirectory);
+    removeEmptyDirectoryTree(AGENTS_HOME);
     console.log(`\nRemoved ${removed} files.\n`);
     return removed;
 }
@@ -2541,6 +2640,7 @@ Examples:
   npx ${PACKAGE_NAME} --profiles editor,mel --only core
 
 Install location: ~/.claude/ by default; CLAUDE_CONFIG_DIR or --target selects another managed root.
+Skills and agents live under ~/.agents (sibling of ~/.claude). ~/.claude/skills and ~/.claude/agents are directory pointers to that home.
 Named profiles resolve under LLM_SETTINGS_PROFILES_ROOT or ~/.claude-profiles/<directoryName>.
 Codex exec-policy files copy into ~/.codex/rules, or CODEX_HOME/rules when CODEX_HOME is set.
 Cursor rule files generate into ~/.cursor/rules as stem-named mdc files, one per Claude rule.
@@ -2590,13 +2690,15 @@ function realPathOrSelf(filesystemPath) {
 }
 
 /**
- * Load profile id → directoryName from the A1 launcher contract when present.
- * Falls back to identity mapping when the file is missing, unreadable, or empty.
+ * Load profile id → directoryName for the install targets this package resolves.
+ *
+ * Each profile's directory carries the profile's own name, so the map is an
+ * identity over the ids a multi-target install accepts.
  *
  * @returns {Record<string, string>}
  */
 function loadDirectoryNameByProfileId() {
-    const fallbackDirectoryNameByProfileId = {
+    return {
         main: 'main',
         editor: 'editor',
         mel: 'mel',
@@ -2604,35 +2706,6 @@ function loadDirectoryNameByProfileId() {
         master: 'master',
         kimi: 'kimi',
     };
-    const manifestPath = join(
-        PACKAGE_ROOT,
-        'scripts',
-        'profile-isolation-launchers',
-        'config',
-        'profiles.manifest.json',
-    );
-    if (!existsSync(manifestPath)) {
-        return fallbackDirectoryNameByProfileId;
-    }
-    try {
-        const document = JSON.parse(readFileSync(manifestPath, 'utf8'));
-        /** @type {Record<string, string>} */
-        const directoryNameByProfileId = {};
-        const profiles = document && typeof document === 'object' ? document.profiles : null;
-        if (profiles && typeof profiles === 'object') {
-            for (const [eachProfileId, eachProfile] of Object.entries(profiles)) {
-                if (eachProfile && typeof eachProfile === 'object' && typeof eachProfile.directoryName === 'string') {
-                    directoryNameByProfileId[eachProfileId] = eachProfile.directoryName;
-                }
-            }
-        }
-        if (Object.keys(directoryNameByProfileId).length === 0) {
-            return fallbackDirectoryNameByProfileId;
-        }
-        return directoryNameByProfileId;
-    } catch {
-        return fallbackDirectoryNameByProfileId;
-    }
 }
 
 /**

package/bin/install.plan.test.mjs

@@ -180,6 +180,7 @@ test('update plan marks purge and lists E2 mutation kinds; journal omits hooks',
         assert.equal(plan.shouldPurgeBeforeReinstall, true);
         const allMutations = describeInstallMutations(plan);
         assert.ok(allMutations.includes('purge_managed_installation'));
+        assert.ok(allMutations.includes('publish_directory_pointers'));
         assert.ok(allMutations.includes('merge_hooks_settings'));
         assert.ok(allMutations.includes('write_manifest'));
         assert.ok(Object.isFrozen(allMutations));

package/bin/install.profile-root.test.mjs

@@ -11,11 +11,13 @@ import { fileURLToPath } from 'node:url';
 import { CODEX_RULES_SHIPPED_FILE_NAME } from './install-constants.mjs';
 import {
     resolveInstallRoot,
+    resolveAgentsHome,
     isPathWithinManagedRoot,
     isAllowedInstallDestination,
     parseExplicitTargetFromArgv,
     CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE,
     DEFAULT_CLAUDE_DIRECTORY_NAME,
+    DEFAULT_AGENTS_DIRECTORY_NAME,
 } from './resolve-install-root.mjs';
 
 const BIN_DIRECTORY = fileURLToPath(new URL('.', import.meta.url));
@@ -30,6 +32,23 @@ test('default target remains join(homeDirectory, .claude)', () => {
     });
     assert.equal(resolution.managedRoot, resolve(join(homeDirectory, DEFAULT_CLAUDE_DIRECTORY_NAME)));
     assert.equal(resolution.source, 'default-home');
+    assert.equal(resolution.agentsHome, resolve(join(homeDirectory, DEFAULT_AGENTS_DIRECTORY_NAME)));
+    assert.equal(
+        resolution.skillsInstallDirectory,
+        join(resolution.agentsHome, 'skills'),
+    );
+    assert.equal(
+        resolution.skillsLookupDirectory,
+        join(resolution.managedRoot, 'skills'),
+    );
+    assert.equal(
+        resolution.agentsInstallDirectory,
+        join(resolution.agentsHome, 'agents'),
+    );
+    assert.equal(
+        resolution.agentsLookupDirectory,
+        join(resolution.managedRoot, 'agents'),
+    );
 });
 
 test('CLAUDE_CONFIG_DIR selects the profile root over the home default', () => {
@@ -98,6 +117,20 @@ test('declared external mypy.ini is allowed; unrelated external paths are not',
         ),
         true,
     );
+    assert.equal(
+        isAllowedInstallDestination(
+            join(resolution.skillsInstallDirectory, 'privacy-hygiene', 'SKILL.md'),
+            resolution,
+        ),
+        true,
+    );
+    assert.equal(
+        isAllowedInstallDestination(
+            join(resolution.agentsInstallDirectory, 'clean-coder.md'),
+            resolution,
+        ),
+        true,
+    );
 });
 
 test('parseExplicitTargetFromArgv reads --target and --target=', () => {
@@ -143,7 +176,27 @@ test('installer destinations for disposable main, profile-a, and profile-b stay
                 isAllowedInstallDestination(resolution.mypyIniInstallPath, resolution),
                 true,
             );
+            assert.equal(
+                isAllowedInstallDestination(
+                    join(resolution.skillsInstallDirectory, 'fixture-skill', 'SKILL.md'),
+                    resolution,
+                ),
+                true,
+                `${eachProfileId}: skills install directory is an allowed destination`,
+            );
+            assert.equal(
+                resolution.agentsHome,
+                resolveAgentsHome(profileRoot),
+            );
+            assert.notEqual(
+                resolution.agentsHome,
+                resolve(join(homeDirectory, DEFAULT_AGENTS_DIRECTORY_NAME)),
+                `${eachProfileId}: a profile root keeps its own agents home`,
+            );
         }
+        const profileAHome = resolveAgentsHome(join(runRoot, 'profile-a'));
+        const profileBHome = resolveAgentsHome(join(runRoot, 'profile-b'));
+        assert.notEqual(profileAHome, profileBHome);
     } finally {
         rmSync(runRoot, { recursive: true, force: true });
     }