@ghl-ai/aw 0.1.49-beta.0 → 0.1.50-beta.0

package/c4/templates/scripts/aw-c4-bootstrap.sh

@@ -12,9 +12,9 @@
 #   - .codex/scripts/codex-web-bootstrap.sh    (passes --harness codex-web)
 #
 # Override knobs (env):
-#   AW_PACKAGE   npm spec to install. Defaults to @ghl-ai/aw@latest. Override
-#                with @ghl-ai/aw@beta to opt into pre-release builds, or pin to
-#                @ghl-ai/aw@0.1.x for reproducible CI runs.
+#   AW_PACKAGE   npm spec to install. Defaults to @ghl-ai/aw@latest.
+#                Override to pin a specific @ghl-ai/aw@0.1.x for reproducible
+#                CI runs.
 set -Eeuo pipefail
 
 # GitHub auth is resolved inside `aw c4` so GITHUB_PAT, GITHUB_TOKEN, and

package/cli.mjs

@@ -89,9 +89,11 @@ function printHelp() {
     sec('Setup'),
     cmd('aw init', 'Initialize workspace (auto-installs suggested integrations)'),
     cmd('aw init --namespace <team/sub-team>', 'Add a team namespace (optional)'),
+    cmd('aw init skills <path...>', 'Initialize/link only specific skill folders'),
     cmd('aw init --no-integrations', 'Skip integration setup (Codex, Caveman, Graphify, etc)'),
     `  ${chalk.dim('Teams: platform, revex, mobile, commerce, leadgen, crm, marketplace, ai')}`,
     `  ${chalk.dim('Example: aw init --namespace revex/courses')}`,
+    `  ${chalk.dim('Example: aw init skills platform/core/skills/pr-review')}`,
     cmd('aw init-repo', 'Scaffold cloud-bootstrap files (idempotent, --dry-run/--force/--diff)'),
 
     sec('Download'),
@@ -152,6 +154,7 @@ function printHelp() {
     cmd('aw pull <team>/agents', 'All agents from a team'),
     cmd('aw pull <team>/agents/<name>', 'One specific agent'),
     cmd('aw pull <team>/skills/<name>', 'One specific skill folder'),
+    cmd('aw init skills <team>/<path>/skills/<name>', 'Install and link only selected skill symlinks'),
     '',
     `  ${chalk.dim('# Push your local changes to registry')}`,
     cmd('aw push', 'Push all modified files (one PR)'),

package/commands/c4.mjs

@@ -350,10 +350,10 @@ export async function c4Command(rawArgs, overrides = {}) {
     return exit(0);
   }
 
-  // Step 6 — npm install -g @ghl-ai/aw.
-  const npmRes = spawnSync('npm', ['install', '-g', '@ghl-ai/aw'], { stdio: 'pipe' });
+  // Step 6 — npm install -g @ghl-ai/aw@latest.
+  const npmRes = spawnSync('npm', ['install', '-g', '@ghl-ai/aw@latest'], { stdio: 'pipe' });
   if (npmRes && npmRes.status !== 0) {
-    writer.stderr('[aw-c4] npm install -g @ghl-ai/aw failed (non-fatal); using existing aw if present\n');
+    writer.stderr('[aw-c4] npm install -g @ghl-ai/aw@latest failed (non-fatal); using existing aw if present\n');
   }
 
   // Step 7 — aw init --silent.

package/commands/init.mjs

@@ -23,7 +23,7 @@ import * as p from '@clack/prompts';
 import * as config from '../config.mjs';
 import * as fmt from '../fmt.mjs';
 import { chalk, setSilent } from '../fmt.mjs';
-import { linkWorkspace } from '../link.mjs';
+import { linkWorkspace, linkSkills, normalizeSkillTarget } from '../link.mjs';
 import { generateCommands, copyInstructions, initAwDocs, syncHomeHarnessInstructions } from '../integrate.mjs';
 import { setupMcp } from '../mcp.mjs';
 import { applyStoredStartupPreferences, ensureAwRuntimeHook } from '../startup.mjs';
@@ -108,6 +108,35 @@ function scaffoldNamespace(awHome, folderName) {
   }
 }
 
+function getSkillInitSpecs(args) {
+  const positional = args._positional || [];
+  const mode = positional[0];
+  const rawTargets = [];
+
+  if (mode === 'skill' || mode === 'skills') {
+    rawTargets.push(...positional.slice(1));
+  }
+
+  if (args['--skill']) {
+    rawTargets.push(args['--skill']);
+  }
+
+  if ((mode === 'skill' || mode === 'skills' || args['--skill']) && rawTargets.length === 0) {
+    fmt.cancel(`Missing skill path.\n\n  ${chalk.dim('Example:')} ${chalk.bold('aw init skills platform/core/skills/pr-review')}`);
+  }
+
+  if (rawTargets.length === 0) return [];
+
+  try {
+    return [...new Map(rawTargets.map(input => {
+      const spec = normalizeSkillTarget(input);
+      return [spec.registryPath, spec];
+    })).values()];
+  } catch (e) {
+    fmt.cancel(e.message);
+  }
+}
+
 // ── Ensure ~/.aw/.git/info/exclude has the whitelist block ─────────────
 //
 // Strategy: only .aw_registry/, .aw_rules/, content/, and .aw_docs/ are
@@ -215,6 +244,14 @@ export async function initCommand(args) {
   let user = args['--user'] || '';
   const silent = args['--silent'] === true;
   const skipIntegrations = args['--no-integrations'] === true;
+  const skillSpecs = getSkillInitSpecs(args);
+  const skillTargets = skillSpecs.map(spec => spec.registryPath);
+  const isSkillInit = skillTargets.length > 0;
+  const skillNamespace = skillSpecs[0]?.namespace || null;
+
+  if (isSkillInit && namespace) {
+    fmt.cancel('Use either `aw init skills <path...>` or `aw init --namespace <team/sub-team>`, not both.');
+  }
 
   // In silent mode, suppress ALL fmt output and show a single spinner.
   // setSilent(true) makes every fmt.* call a no-op — internal functions
@@ -323,8 +360,26 @@ export async function initCommand(args) {
   if (isGitNative) {
     const cfg = config.load(GLOBAL_AW_DIR);
 
-    const isNewSubTeam = folderName && cfg && !cfg.include.includes(folderName);
-    if (isNewSubTeam) {
+    const newSkillTargets = isSkillInit && cfg
+      ? skillTargets.filter(target => !cfg.include.some(pattern => target === pattern || target.startsWith(pattern + '/')))
+      : [];
+    const isNewSubTeam = !isSkillInit && folderName && cfg && !cfg.include.includes(folderName);
+
+    if (isSkillInit) {
+      if (newSkillTargets.length > 0) {
+        if (!silent) fmt.logStep(`Adding ${chalk.cyan(newSkillTargets.length)} skill${newSkillTargets.length > 1 ? 's' : ''}...`);
+        addToSparseCheckout(AW_HOME, [
+          ...newSkillTargets.map(target => `.aw_registry/${target}`),
+          DOCS_SOURCE_DIR,
+          AW_DOCS_DIR,
+          RULES_SOURCE_DIR,
+          `.aw_registry/AW-PROTOCOL.md`,
+        ]);
+        for (const target of newSkillTargets) config.addPattern(GLOBAL_AW_DIR, target);
+      } else if (!silent) {
+        fmt.logStep('Already initialized — syncing selected skills...');
+      }
+    } else if (isNewSubTeam) {
       if (!silent) fmt.logStep(`Adding sub-team ${chalk.cyan(folderName)}...`);
       const newSparsePaths = [`.aw_registry/${folderName}`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR];
       addToSparseCheckout(AW_HOME, newSparsePaths);
@@ -352,6 +407,7 @@ export async function initCommand(args) {
 
     ensureAwGitignore(AW_HOME);
     const freshCfg = config.load(GLOBAL_AW_DIR);
+    const activeNamespace = skillNamespace || freshCfg?.namespace || team;
     syncRulesTargets(HOME);
     if (cwd !== HOME) {
       syncRulesTargets(cwd);
@@ -374,8 +430,8 @@ export async function initCommand(args) {
     await installAwEcc(cwd, { silent });
 
     ensureAwRuntimeHook(HOME);
-    syncHomeAndProjectInstructions(cwd, freshCfg?.namespace || team);
-    await setupMcp(HOME, freshCfg?.namespace || team, { silent });
+    syncHomeAndProjectInstructions(cwd, activeNamespace);
+    await setupMcp(HOME, activeNamespace, { silent });
     applyStoredStartupPreferences(HOME);
     const removedLegacyStartupFiles = cwd !== HOME ? removeWorkspaceHookDefaults(cwd) : [];
     installGlobalHooks();
@@ -409,10 +465,12 @@ export async function initCommand(args) {
     if (!silent) fmt.logStep('Wiring IDE symlinks...');
     const projectRegistryDir = cwd !== HOME ? join(cwd, '.aw', REGISTRY_DIR) : null;
     const awDirForLinks = (projectRegistryDir && existsSync(projectRegistryDir)) ? projectRegistryDir : null;
-    const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
-    const commands = generateCommands(HOME, { silent: true });
+    const symlinks = isSkillInit
+      ? linkSkills(HOME, skillTargets, awDirForLinks, { silent: true, exclusive: true })
+      : linkWorkspace(HOME, awDirForLinks, { silent: true });
+    const commands = isSkillInit ? 0 : generateCommands(HOME, { silent: true });
     if (cwd !== HOME) installLocalCommitHook(cwd);
-    if (!silent) fmt.logStep(`IDE wired — ${chalk.bold(symlinks)} symlinks · ${chalk.bold(commands)} commands`);
+    if (!silent) fmt.logStep(`IDE wired — ${chalk.bold(symlinks)} ${isSkillInit ? 'skill symlinks' : 'symlinks'} · ${chalk.bold(commands)} commands`);
 
     // Write hook manifest after all hook installation is complete
     try { writeHookManifest({ eccVersion: AW_ECC_TAG, awVersion: VERSION }); } catch { /* best effort */ }
@@ -420,7 +478,7 @@ export async function initCommand(args) {
     // Auto-install suggested integrations (Codex, Caveman, Graphify, etc) - unless --no-integrations
     let installedIntegrations = [];
     if (!silent && !skipIntegrations && !isNewSubTeam) {
-      installedIntegrations = await autoInstallIntegrations(freshCfg?.namespace || team, { silent });
+      installedIntegrations = await autoInstallIntegrations(activeNamespace, { silent });
     }
 
     if (silent) {
@@ -431,7 +489,7 @@ export async function initCommand(args) {
         `⟁  ${isNewSubTeam ? `Sub-team ${chalk.cyan(folderName)} added` : 'Up to date'}`,
         '',
         `  ${chalk.green('✓')} Registry synced`,
-        `  ${chalk.green('✓')} IDE refreshed — ${chalk.bold(symlinks)} symlinks · ${chalk.bold(commands)} commands`,
+        `  ${chalk.green('✓')} IDE refreshed — ${chalk.bold(symlinks)} ${isSkillInit ? 'skill symlinks' : 'symlinks'} · ${chalk.bold(commands)} commands`,
         removedLegacyStartupFiles.length > 0
           ? `  ${chalk.green('✓')} Removed ${removedLegacyStartupFiles.length} legacy repo startup file${removedLegacyStartupFiles.length > 1 ? 's' : ''}`
           : null,
@@ -465,13 +523,24 @@ export async function initCommand(args) {
   }
 
   // Determine sparse paths
-  const sparsePaths = [`.aw_registry/platform`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR, `.aw_registry/AW-PROTOCOL.md`, `CODEOWNERS`];
-  if (folderName) {
+  const sparsePaths = isSkillInit
+    ? [
+        ...skillTargets.map(target => `.aw_registry/${target}`),
+        DOCS_SOURCE_DIR,
+        AW_DOCS_DIR,
+        RULES_SOURCE_DIR,
+        `.aw_registry/AW-PROTOCOL.md`,
+        `CODEOWNERS`,
+      ]
+    : [`.aw_registry/platform`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR, `.aw_registry/AW-PROTOCOL.md`, `CODEOWNERS`];
+  if (!isSkillInit && folderName) {
     sparsePaths.push(`.aw_registry/${folderName}`);
   }
 
   fmt.note([
-    folderName ? `${chalk.dim('namespace:')}  ${folderName}` : `${chalk.dim('namespace:')}  ${chalk.dim('none')}`,
+    isSkillInit
+      ? `${chalk.dim('skills:')}     ${skillTargets.join(', ')}`
+      : (folderName ? `${chalk.dim('namespace:')}  ${folderName}` : `${chalk.dim('namespace:')}  ${chalk.dim('none')}`),
     user ? `${chalk.dim('user:')}       ${user}` : null,
     `${chalk.dim('version:')}    v${VERSION}`,
   ].filter(Boolean).join('\n'), 'Config');
@@ -511,8 +580,11 @@ export async function initCommand(args) {
   }
 
   // Create sync config — default to 'platform' when no namespace specified
-  const cfg = config.create(GLOBAL_AW_DIR, { namespace: team || 'platform', user });
-  if (folderName) {
+  const activeNamespace = skillNamespace || team || 'platform';
+  const cfg = config.create(GLOBAL_AW_DIR, { namespace: activeNamespace, user });
+  if (isSkillInit) {
+    for (const target of skillTargets) config.addPattern(GLOBAL_AW_DIR, target);
+  } else if (folderName) {
     config.addPattern(GLOBAL_AW_DIR, folderName);
     scaffoldNamespace(AW_HOME, folderName);
   }
@@ -533,8 +605,8 @@ export async function initCommand(args) {
 
   // Parallel batch B: post-ECC setup (instructions and MCP are independent)
   const [, mcpFiles] = await Promise.all([
-    Promise.resolve(syncHomeAndProjectInstructions(cwd, team)),
-    setupMcp(HOME, team, { silent }),
+    Promise.resolve(syncHomeAndProjectInstructions(cwd, activeNamespace)),
+    setupMcp(HOME, activeNamespace, { silent }),
   ]);
   // applyStoredStartupPreferences reads settings written by ECC — keep after batch B
   applyStoredStartupPreferences(HOME);
@@ -572,11 +644,13 @@ export async function initCommand(args) {
   const awDirForLinks = (projectRegistryDir && existsSync(projectRegistryDir)) ? projectRegistryDir : null;
   // Parallel batch C: symlinks + commands are independent
   if (cwd !== HOME) installLocalCommitHook(cwd);
-  const [symlinks, commands] = [
-    linkWorkspace(HOME, awDirForLinks, { silent: true }),
-    generateCommands(HOME, { silent: true }),
-  ];
-  if (!silent) fmt.logStep(`IDE wired — ${chalk.bold(symlinks)} symlinks · ${chalk.bold(commands)} commands`);
+  const [symlinks, commands] = isSkillInit
+    ? [linkSkills(HOME, skillTargets, awDirForLinks, { silent: true, exclusive: true }), 0]
+    : [
+        linkWorkspace(HOME, awDirForLinks, { silent: true }),
+        generateCommands(HOME, { silent: true }),
+      ];
+  if (!silent) fmt.logStep(`IDE wired — ${chalk.bold(symlinks)} ${isSkillInit ? 'skill symlinks' : 'symlinks'} · ${chalk.bold(commands)} commands`);
 
   // Write hook manifest after all hook installation is complete
   try { writeHookManifest({ eccVersion: AW_ECC_TAG, awVersion: VERSION }); } catch { /* best effort */ }
@@ -587,7 +661,7 @@ export async function initCommand(args) {
   // Auto-install suggested integrations (Codex, Caveman, Graphify, etc) - unless --no-integrations
   let installedIntegrations = [];
   if (!silent && !skipIntegrations) {
-    installedIntegrations = await autoInstallIntegrations(team, { silent });
+    installedIntegrations = await autoInstallIntegrations(activeNamespace, { silent });
   }
 
   // Offer to update if a newer version is available

package/commands/push.mjs

@@ -518,91 +518,6 @@ function writeAwDocsLinkSummary(projectRoot, links, publishConfig) {
   }
 }
 
-function normalizeAwDocsRelPath(value) {
-  if (!value) return null;
-  let relPath = String(value).replace(/\\/g, '/').replace(/^\.\//, '');
-  if (relPath.startsWith(`${AW_DOCS_DIR}/`)) relPath = relPath.slice(AW_DOCS_DIR.length + 1);
-  return relPath.replace(/^\/+/, '');
-}
-
-function featureSlugForAwDocsRelPath(relPath) {
-  const normalized = normalizeAwDocsRelPath(relPath);
-  if (!normalized) return null;
-  const parts = normalized.split('/');
-  if (parts[0] !== 'features' || !parts[1]) return null;
-  return parts[1];
-}
-
-function setIfChanged(target, key, value) {
-  if (target[key] === value) return false;
-  target[key] = value;
-  return true;
-}
-
-function inferredMarkdownSourcePath(projectRoot, htmlRelPath) {
-  const sourceRelPath = htmlRelPath.replace(/\.html$/i, '.md');
-  if (sourceRelPath === htmlRelPath) return null;
-  if (!existsSync(join(projectRoot, AW_DOCS_DIR, sourceRelPath))) return null;
-  return `${AW_DOCS_DIR}/${sourceRelPath}`;
-}
-
-function hydrateAwDocsFeatureStateLinks(projectRoot, links, publishConfig) {
-  const htmlLinksByFeature = new Map();
-  for (const link of links) {
-    if (!/\.html$/i.test(link.relPath)) continue;
-    const featureSlug = featureSlugForAwDocsRelPath(link.relPath);
-    if (!featureSlug) continue;
-    const featureLinks = htmlLinksByFeature.get(featureSlug) || [];
-    featureLinks.push(link);
-    htmlLinksByFeature.set(featureSlug, featureLinks);
-  }
-
-  for (const [featureSlug, featureLinks] of htmlLinksByFeature) {
-    const statePath = join(projectRoot, AW_DOCS_DIR, 'features', featureSlug, 'state.json');
-    if (!existsSync(statePath)) continue;
-
-    let state;
-    try {
-      state = JSON.parse(readFileSync(statePath, 'utf8'));
-    } catch (e) {
-      throw new Error(`Invalid ${AW_DOCS_DIR}/features/${featureSlug}/state.json: ${e.message}`);
-    }
-
-    const artifacts = Array.isArray(state.html_companion_artifacts)
-      ? state.html_companion_artifacts
-      : [];
-    let changed = !Array.isArray(state.html_companion_artifacts);
-
-    for (const link of featureLinks) {
-      const htmlPath = `${AW_DOCS_DIR}/${link.relPath}`;
-      const existing = artifacts.find(artifact => normalizeAwDocsRelPath(artifact?.html_path) === link.relPath);
-      const artifact = existing || {};
-      if (!existing) {
-        const sourcePath = inferredMarkdownSourcePath(projectRoot, link.relPath);
-        if (sourcePath) artifact.source_path = sourcePath;
-        artifacts.push(artifact);
-        changed = true;
-      }
-
-      changed = setIfChanged(artifact, 'html_path', htmlPath) || changed;
-      changed = setIfChanged(artifact, 'publish_status', 'published') || changed;
-      changed = setIfChanged(artifact, 'remote_repo', publishConfig.repo) || changed;
-      changed = setIfChanged(artifact, 'remote_branch', publishConfig.branch) || changed;
-      changed = setIfChanged(artifact, 'remote_path', link.publishedPath) || changed;
-      changed = setIfChanged(artifact, 'platform_docs_path', link.publishedPath) || changed;
-      changed = setIfChanged(artifact, 'remote_url', link.remoteUrl) || changed;
-      changed = setIfChanged(artifact, 'teamofone_url', link.remoteUrl) || changed;
-      changed = setIfChanged(artifact, 'github_url', link.repositoryUrl) || changed;
-      changed = setIfChanged(artifact, 'repository_url', link.repositoryUrl) || changed;
-    }
-
-    if (!changed) continue;
-    state.html_companion_artifacts = artifacts;
-    state.updated_at = new Date().toISOString();
-    writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
-  }
-}
-
 async function commitAndPushAwDocsRepo(docsRepoDir, { message, branch }) {
   await execFile('git', ['add', '-A'], { cwd: docsRepoDir, encoding: 'utf8' });
   await execFile('git', ['commit', '-m', message], {
@@ -697,8 +612,6 @@ async function publishProjectAwDocs(cwd, home, dryRun, scope = null) {
     return { hasDocs: true, publishedPaths, links };
   }
 
-  hydrateAwDocsFeatureStateLinks(projectRoot, links, publishConfig);
-
   const s = fmt.spinner();
   s.start(`Publishing ${files.length} AW doc${files.length > 1 ? 's' : ''} to ${publishConfig.repo}...`);
   try {

package/constants.mjs

@@ -33,7 +33,7 @@ export const AW_DOCS_BASE_BRANCH = 'master-sync';
 export const AW_DOCS_SEED_BRANCH = process.env.AW_DOCS_SEED_BRANCH || 'scaffold';
 export const AW_DOCS_PUBLISH_DIR = 'aw_docs';
 export const AW_DOCS_PUBLIC_BASE_URL = process.env.AW_DOCS_PUBLIC_BASE_URL || `https://github.com/${AW_DOCS_REPO}/blob/${AW_DOCS_BASE_BRANCH}`;
-export const AW_DOCS_TEAMOFONE_ORIGIN = process.env.AW_DOCS_TEAMOFONE_ORIGIN || 'https://teamofone.servers.stg.msgsndr.net';
+export const AW_DOCS_TEAMOFONE_ORIGIN = process.env.AW_DOCS_TEAMOFONE_ORIGIN || 'https://teamofone.msgsndr.net';
 export const AW_DOCS_TEAMOFONE_BASE_URL = process.env.AW_DOCS_TEAMOFONE_BASE_URL || `${AW_DOCS_TEAMOFONE_ORIGIN}/too/docs/GoHighLevel/ghl-aw-docs`;
 
 export function defaultAwDocsGithubDocsConfig() {

package/integrate.mjs

@@ -649,9 +649,6 @@ No active runs. Use \`/aw:<team>-<command>\` to start a workflow.
   // config.json — registry paths, sync settings
   const configPath = join(awDocsDir, 'config.json');
   const defaultConfig = {
-    docs: {
-      outputMode: 'dual',
-    },
     sync: {
       eager: true,
       batch_threshold: 10,
@@ -671,10 +668,6 @@ No active runs. Use \`/aw:<team>-<command>\` to start a workflow.
       const existing = JSON.parse(readFileSync(configPath, 'utf8'));
       nextConfig = {
         ...existing,
-        docs: {
-          ...defaultConfig.docs,
-          ...(existing.docs || {}),
-        },
         sync: {
           ...defaultConfig.sync,
           ...(existing.sync || {}),

package/link.mjs

@@ -16,6 +16,11 @@ const IDE_DIRS = ['.claude', '.cursor', '.codex'];
 const FILE_TYPES = ['agents'];
 const ALL_KNOWN_TYPES = new Set([...FILE_TYPES, 'skills', 'commands', 'evals', 'references', 'docs']);
 
+function realHomeDir() {
+  const rawHome = homedir();
+  try { return realpathSync(rawHome); } catch { return rawHome; }
+}
+
 /**
  * List namespace directories inside .aw_registry/ (skip dotfiles).
  */
@@ -77,7 +82,7 @@ function cleanIdeSymlinks(cwd) {
     cleanSymlinksRecursive(ideDir);
   }
   // Also clean .agents/skills/ (global only — Codex reads from ~/.agents/skills/)
-  const HOME = homedir();
+  const HOME = realHomeDir();
   if (cwd === HOME) {
     const agentsSkillsDir = join(cwd, '.agents', 'skills');
     if (existsSync(agentsSkillsDir)) cleanSymlinksRecursive(agentsSkillsDir);
@@ -120,6 +125,117 @@ function flatName(ns, name) {
   return `${ns}-${name}`;
 }
 
+function stripRegistryPrefix(input) {
+  return String(input || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/\/SKILL\.md$/i, '')
+    .replace(/^.*?\.aw_registry\//, '')
+    .replace(/^\.\/+/, '')
+    .replace(/\/+$/, '');
+}
+
+export function normalizeSkillTarget(input) {
+  const normalized = stripRegistryPrefix(input);
+  const parts = normalized.split('/').filter(Boolean);
+  const skillIndex = parts.indexOf('skills');
+
+  if (skillIndex < 1 || skillIndex === parts.length - 1) {
+    throw new Error(`Skill target must look like <team>/<path>/skills/<name>: ${input}`);
+  }
+
+  if (parts.length !== skillIndex + 2) {
+    throw new Error(`Skill target must point at a skill folder, not a nested file: ${input}`);
+  }
+
+  const namespace = parts[0];
+  const segments = parts.slice(1, skillIndex);
+  const skill = parts[skillIndex + 1];
+  const registryPath = [namespace, ...segments, 'skills', skill].join('/');
+  const flat = [namespace, ...segments, skill].join('-');
+  return { namespace, segments, skill, registryPath, flat };
+}
+
+function cleanSkillSymlinks(cwd) {
+  for (const ide of IDE_DIRS) {
+    const skillsDir = join(cwd, ide, 'skills');
+    if (existsSync(skillsDir)) cleanSymlinksRecursive(skillsDir);
+  }
+
+  if (cwd === realHomeDir()) {
+    const agentsSkillsDir = join(cwd, '.agents', 'skills');
+    if (existsSync(agentsSkillsDir)) cleanSymlinksRecursive(agentsSkillsDir);
+  }
+}
+
+function linkOneSkill(cwd, awDir, target) {
+  const skillDir = join(awDir, target.namespace, ...target.segments, 'skills', target.skill);
+  if (!existsSync(skillDir) || !lstatSync(skillDir).isDirectory()) {
+    throw new Error(`Skill not found in registry: ${target.registryPath}`);
+  }
+
+  let created = 0;
+  for (const ide of IDE_DIRS) {
+    const linkDir = join(cwd, ide, 'skills');
+    mkdirSync(linkDir, { recursive: true });
+    const linkPath = join(linkDir, target.flat);
+    const relTarget = relative(linkDir, skillDir);
+    forceSymlink(relTarget, linkPath);
+    created++;
+  }
+
+  if (cwd === realHomeDir()) {
+    const agentsSkillsDir = join(cwd, '.agents', 'skills');
+    mkdirSync(agentsSkillsDir, { recursive: true });
+    const linkPath = join(agentsSkillsDir, target.flat);
+    const relTarget = relative(agentsSkillsDir, skillDir);
+    forceSymlink(relTarget, linkPath);
+    created++;
+  }
+
+  return created;
+}
+
+/**
+ * Create/refresh symlinks for specific skills only.
+ *
+ * Unlike linkWorkspace(), this does not walk every namespace. It can be used
+ * by lean init flows to avoid exposing every registry skill to IDE runtimes.
+ */
+export function linkSkills(cwd, skillTargets, awDirOverride = null, { silent = false, exclusive = false } = {}) {
+  try { cwd = realpathSync(cwd); } catch { /* use as-is */ }
+
+  const GLOBAL_AW_DIR = join(realHomeDir(), '.aw_registry');
+  let awDir = awDirOverride || getLocalRegistryDir(cwd, GLOBAL_AW_DIR);
+  try { awDir = realpathSync(awDir); } catch { /* use as-is if it doesn't exist */ }
+  if (!existsSync(awDir)) return 0;
+
+  const targets = [...new Map(skillTargets.map(input => {
+    const target = normalizeSkillTarget(input);
+    return [target.registryPath, target];
+  })).values()];
+
+  for (const target of targets) {
+    const skillDir = join(awDir, target.namespace, ...target.segments, 'skills', target.skill);
+    if (!existsSync(skillDir) || !lstatSync(skillDir).isDirectory()) {
+      throw new Error(`Skill not found in registry: ${target.registryPath}`);
+    }
+  }
+
+  if (exclusive) cleanSkillSymlinks(cwd);
+
+  let created = 0;
+  for (const target of targets) {
+    created += linkOneSkill(cwd, awDir, target);
+  }
+
+  if (created > 0 && !silent) {
+    fmt.logSuccess(`Linked ${created} skill symlink${created > 1 ? 's' : ''}`);
+  }
+
+  return created;
+}
+
 /**
  * Create/refresh all IDE symlinks.
  *
@@ -140,7 +256,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
   // where $HOME may be /var/... but process.cwd() resolves to /private/var/...
   try { cwd = realpathSync(cwd); } catch { /* use as-is */ }
 
-  const GLOBAL_AW_DIR = join(homedir(), '.aw_registry');
+  const GLOBAL_AW_DIR = join(realHomeDir(), '.aw_registry');
   let awDir = awDirOverride || getLocalRegistryDir(cwd, GLOBAL_AW_DIR);
   try { awDir = realpathSync(awDir); } catch { /* use as-is if it doesn't exist */ }
   if (!existsSync(awDir)) return 0;
@@ -246,7 +362,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
   }
 
   // Codex per-skill symlinks: ~/.agents/skills/<name> (global only)
-  if (cwd === homedir()) {
+  if (cwd === realHomeDir()) {
     const agentsSkillsDir = join(cwd, '.agents/skills');
     for (const ns of namespaces) {
       for (const { typeDirPath: skillsDir, segments } of findNestedTypeDirs(join(awDir, ns), 'skills')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.49-beta.0",
+  "version": "0.1.50-beta.0",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {