@wipcomputer/wip-ldm-os 0.4.85-alpha.2 → 0.4.85-alpha.21

package/README.md

@@ -22,7 +22,18 @@ Open your AI and paste this:
 ```
 Read https://wip.computer/install/wip-ldm-os.txt
 
-Check if LDM OS is already installed. If it is, run ldm install --dry-run and show me what I have and what's new.
+Use the install document and live local checks as the source of truth. Do not search memory or prior notes for this install.
+
+Check if LDM OS is installed (`which ldm && ldm --version`). Branch.
+
+If installed: run `ldm status` and show me the version table and what's new for each component. Then ask:
+- Do you have questions?
+- Want to see a dry run?
+
+If yes to dry run, run `ldm install --dry-run`.
+
+If I say install, run:
+`npm install -g @wipcomputer/wip-ldm-os@latest && ldm install && ldm doctor`
 
 If not, walk me through setup and explain:
 
@@ -35,7 +46,14 @@ Then ask:
 - Do you have questions?
 - Want to see a dry run?
 
-If I say yes: Install the CLI first (npm install -g @wipcomputer/wip-ldm-os) and then run ldm install --dry-run.
+If yes to dry run, install the CLI first:
+`npm install -g @wipcomputer/wip-ldm-os`
+
+Then run:
+`ldm init --dry-run`
+
+If I say install, run:
+`ldm init`
 
 Show me exactly what will change. Don't install anything until I say "install".
 ```
@@ -105,6 +123,8 @@ The OS connects your AIs. Add-ons are what they actually use. Each one is a full
 ## More Info
 
 - [Architecture, principles, and technical details](TECHNICAL.md)
+- [Hosted MCP and relay source](src/hosted-mcp/README.md)
+- [Hosted relay self-host guide](src/hosted-mcp/docs/self-host.md)
 
 ## License
 

package/SKILL.md

@@ -27,6 +27,12 @@ metadata:
 
 # LDM OS
 
+## Source of truth
+
+Use this install document and live local checks as the source of truth. Do not search memory or prior notes for this install.
+
+Do not run GitHub release commands during the install-state flow. Do not run `gh release list` or `gh release view` unless the user explicitly asks for release notes. Install-state answers should come from local commands, `ldm status`, and npm package metadata.
+
 ## Step 1: Check if installed
 
 ```bash
@@ -62,12 +68,9 @@ Always a table. Every component with an update gets its own row.
 
 **Do NOT skip this step.**
 
-```bash
-gh release list --repo wipcomputer/<repo-name> --limit 5 --json tagName,name --jq '.[]'
-gh release view <tag> --repo wipcomputer/<repo-name> --json body --jq .body
-```
+Use the output of `ldm status`, installed package metadata, and npm metadata. Do not use GitHub release commands here.
 
-Translate release notes to user language. Every bullet answers "what changed for ME?"
+Translate available update information to user language. Every bullet answers "what changed for ME?" If the status output does not include enough detail for a component, say that clearly and do not invent release notes.
 
 Good: "Your AIs now explain what LDM OS actually does when you ask them to install it"
 Bad: "Restored rich product content to SKILL.md"

package/bin/ldm.js

@@ -22,7 +22,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, cpSync, chmodSync, unlinkSync, readlinkSync, renameSync, statSync, lstatSync, symlinkSync } from 'node:fs';
 import { join, basename, resolve, dirname } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execFileSync, execSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -211,6 +211,11 @@ function writeJSON(path, data) {
   writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
 }
 
+function parsePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(value || '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
 // ── CLI version check (#29) ──
 
 function checkCliVersion() {
@@ -229,6 +234,62 @@ function checkCliVersion() {
   }
 }
 
+function selectedLdmNpmTrack() {
+  return ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : 'latest';
+}
+
+function selectedLdmTrackLabel(npmTag) {
+  return npmTag === 'latest' ? '' : ` (${npmTag} track)`;
+}
+
+function latestLdmCliForSelectedTrack() {
+  const npmTag = selectedLdmNpmTrack();
+  const npmViewCmd = npmTag === 'latest'
+    ? 'npm view @wipcomputer/wip-ldm-os version 2>/dev/null'
+    : `npm view @wipcomputer/wip-ldm-os dist-tags.${npmTag} 2>/dev/null`;
+  const latest = execSync(npmViewCmd, {
+    encoding: 'utf8',
+    timeout: 15000,
+  }).trim();
+  return { latest, npmTag };
+}
+
+function maybeSelfUpdateLdmCliBeforeInstall() {
+  // This shared preflight covers both bare `ldm install` and targeted
+  // `ldm install <app>`. Dry runs never update, but still disclose skew.
+  if (process.env.LDM_SELF_UPDATED) return;
+
+  try {
+    const { latest, npmTag } = latestLdmCliForSelectedTrack();
+    if (!latest || !semverNewer(latest, PKG_VERSION)) return;
+
+    const trackLabel = selectedLdmTrackLabel(npmTag);
+
+    if (DRY_RUN) {
+      console.log(`  LDM OS CLI v${PKG_VERSION} -> v${latest}${trackLabel} is available.`);
+      console.log(`  Dry run only: continuing with v${PKG_VERSION}.`);
+      console.log('');
+      return;
+    }
+
+    console.log(`  LDM OS CLI v${PKG_VERSION} -> v${latest}${trackLabel}. Updating first...`);
+    try {
+      execSync(`npm install -g @wipcomputer/wip-ldm-os@${latest}`, { stdio: 'inherit', timeout: 60000 });
+      console.log(`  CLI updated to v${latest}. Re-running with new code...`);
+      console.log('');
+      const reArgs = process.argv.slice(2);
+      const child = spawnSync('ldm', reArgs.length > 0 ? reArgs : ['install'], {
+        stdio: 'inherit',
+        env: { ...process.env, LDM_SELF_UPDATED: '1' },
+      });
+      if (child.error) throw child.error;
+      process.exit(child.status ?? 1);
+    } catch (e) {
+      console.log(`  ! Self-update failed: ${e.message}. Continuing with v${PKG_VERSION}.`);
+    }
+  } catch {}
+}
+
 // ── Dead backup trigger cleanup (#207) ──
 // Three backup systems were competing. Only ai.openclaw.ldm-backup (3am) works.
 // This removes: broken cron entry (LDMDevTools.app), old com.wipcomputer.daily-backup.
@@ -738,6 +799,24 @@ function deployDocs() {
     console.log(`  + ${agentDocsCount} personalized doc(s) deployed to ${agentLibraryDest.replace(HOME, '~')}/`);
   }
 
+  // Migration-window compatibility write (added 2026-04-30).
+  // dev-guide-wipcomputerinc.md was migrated from ~/.ldm/shared/ to
+  // ~/.ldm/library/documentation/ on 2026-04-19, but agent boot files,
+  // ~/.claude/rules/, and other consumers still reference the old shared
+  // path. Without this write, the old path serves stale content and
+  // agents reading by the old path get pre-migration policy.
+  // Forward-migration (grep-update consumers, then remove this compat
+  // write) is tracked separately. See bugs/installer/ ticket
+  // 2026-04-30--cc-mini--dev-guide-split-path-migration.md.
+  const devGuideName = 'dev-guide-wipcomputerinc.md';
+  const devGuideNew = join(agentLibraryDest, devGuideName);
+  const devGuideOld = join(LDM_ROOT, 'shared', devGuideName);
+  if (existsSync(devGuideNew)) {
+    mkdirSync(dirname(devGuideOld), { recursive: true });
+    cpSync(devGuideNew, devGuideOld);
+    console.log(`  + Compat write: ${devGuideName} also deployed to ${devGuideOld.replace(HOME, '~')} (migration window)`);
+  }
+
   return docsCount + agentDocsCount;
 }
 
@@ -1422,23 +1501,6 @@ async function showCatalogPicker() {
 // ── ldm install ──
 
 async function cmdInstall() {
-  if (!DRY_RUN && !acquireInstallLock()) return;
-
-  // Ensure LDM is initialized
-  if (!existsSync(VERSION_PATH)) {
-    console.log('  LDM OS not initialized. Running init first...');
-    console.log('');
-    cmdInit();
-  }
-
-  const { setFlags, installFromPath, installSingleTool, installToolbox, detectHarnesses } = await import('../lib/deploy.mjs');
-  const { detectInterfacesJSON } = await import('../lib/detect.mjs');
-
-  // Refresh harness detection (catches newly installed harnesses)
-  detectHarnesses();
-
-  setFlags({ dryRun: DRY_RUN, jsonOutput: JSON_OUTPUT, origin: 'manual' });
-
   // --help flag (#81)
   if (args.includes('--help') || args.includes('-h')) {
     console.log(`
@@ -1458,6 +1520,25 @@ async function cmdInstall() {
     process.exit(0);
   }
 
+  maybeSelfUpdateLdmCliBeforeInstall();
+
+  if (!DRY_RUN && !acquireInstallLock()) return;
+
+  // Ensure LDM is initialized
+  if (!existsSync(VERSION_PATH)) {
+    console.log('  LDM OS not initialized. Running init first...');
+    console.log('');
+    cmdInit();
+  }
+
+  const { setFlags, installFromPath, installSingleTool, installToolbox, detectHarnesses } = await import('../lib/deploy.mjs');
+  const { detectInterfacesJSON } = await import('../lib/detect.mjs');
+
+  // Refresh harness detection (catches newly installed harnesses)
+  detectHarnesses();
+
+  setFlags({ dryRun: DRY_RUN, jsonOutput: JSON_OUTPUT, origin: 'manual' });
+
   // Find the target (skip flags)
   const target = args.slice(1).find(a => !a.startsWith('--'));
 
@@ -1903,38 +1984,6 @@ async function cmdInstallCatalog() {
   // No lock here. cmdInstall() already holds it when calling this.
   installLog(`ldm install started (v${PKG_VERSION}, DRY_RUN=${DRY_RUN})`);
 
-  // Self-update: check if CLI itself is outdated. Update first, then re-exec.
-  // This breaks the chicken-and-egg: new features in ldm install are always
-  // available because the installer upgrades itself before doing anything else.
-  // --alpha and --beta flags check the corresponding npm dist-tag instead of @latest.
-  if (!DRY_RUN && !process.env.LDM_SELF_UPDATED) {
-    try {
-      const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : 'latest';
-      const trackLabel = npmTag === 'latest' ? '' : ` (${npmTag} track)`;
-      const npmViewCmd = npmTag === 'latest'
-        ? 'npm view @wipcomputer/wip-ldm-os version 2>/dev/null'
-        : `npm view @wipcomputer/wip-ldm-os dist-tags.${npmTag} 2>/dev/null`;
-      const latest = execSync(npmViewCmd, {
-        encoding: 'utf8', timeout: 15000,
-      }).trim();
-      if (latest && semverNewer(latest, PKG_VERSION)) {
-        console.log(`  LDM OS CLI v${PKG_VERSION} -> v${latest}${trackLabel}. Updating first...`);
-        try {
-          execSync(`npm install -g @wipcomputer/wip-ldm-os@${latest}`, { stdio: 'inherit', timeout: 60000 });
-          console.log(`  CLI updated to v${latest}. Re-running with new code...`);
-          console.log('');
-          // Re-exec with the new binary. LDM_SELF_UPDATED prevents infinite loop.
-          // process.argv.slice(2) skips 'node' and the script path, keeps just 'install' + flags
-          const reArgs = process.argv.slice(2).join(' ') || 'install';
-          execSync(`LDM_SELF_UPDATED=1 ldm ${reArgs}`, { stdio: 'inherit' });
-          process.exit(0);
-        } catch (e) {
-          console.log(`  ! Self-update failed: ${e.message}. Continuing with v${PKG_VERSION}.`);
-        }
-      }
-    } catch {}
-  }
-
   autoDetectExtensions();
 
   // Migrate old registry entries to v2 format (#262)
@@ -3233,6 +3282,28 @@ async function cmdDoctor() {
 
 // ── ldm status ──
 
+const STATUS_NPM_TIMEOUT_MS = parsePositiveInt(process.env.LDM_STATUS_NPM_TIMEOUT_MS, 5000);
+const STATUS_TOTAL_BUDGET_MS = parsePositiveInt(process.env.LDM_STATUS_TOTAL_BUDGET_MS, 60000);
+
+function npmViewVersionForStatus(pkg, timeoutMs) {
+  return execFileSync('npm', ['view', pkg, 'version'], {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}
+
+function remainingStatusBudgetMs(startedAt) {
+  return Math.max(0, STATUS_TOTAL_BUDGET_MS - (Date.now() - startedAt));
+}
+
+function classifyStatusCheckError(error) {
+  if (error?.signal === 'SIGTERM' || error?.code === 'ETIMEDOUT' || String(error?.message || '').includes('ETIMEDOUT')) {
+    return 'timeout';
+  }
+  return 'unavailable';
+}
+
 function cmdStatus() {
   const version = readJSON(VERSION_PATH);
   const registry = readJSON(REGISTRY_PATH);
@@ -3254,14 +3325,29 @@ function cmdStatus() {
     return;
   }
 
-  // Check CLI version against npm
+  console.log('');
+  console.log(`  LDM OS v${version.version}`);
+  console.log(`  Installed: ${version.installed?.split('T')[0] || 'unknown'}`);
+  console.log(`  Updated:   ${version.updated?.split('T')[0] || 'unknown'}`);
+  console.log(`  Extensions: ${extCount}`);
+  console.log(`  Root: ${LDM_ROOT}`);
+
+  const statusStartedAt = Date.now();
+  const skipped = [];
+
+  console.log('');
+  console.log('  Checking updates:');
+
   let cliUpdate = null;
   try {
-    const latest = execSync('npm view @wipcomputer/wip-ldm-os version 2>/dev/null', {
-      encoding: 'utf8', timeout: 10000,
-    }).trim();
+    const timeout = Math.min(STATUS_NPM_TIMEOUT_MS, remainingStatusBudgetMs(statusStartedAt));
+    if (timeout <= 0) throw new Error('status update-check budget exhausted');
+    console.log('    ldm cli: checking npm');
+    const latest = npmViewVersionForStatus('@wipcomputer/wip-ldm-os', timeout);
     if (latest && semverNewer(latest, PKG_VERSION)) cliUpdate = latest;
-  } catch {}
+  } catch (error) {
+    skipped.push({ name: 'ldm cli', npm: '@wipcomputer/wip-ldm-os', reason: classifyStatusCheckError(error) });
+  }
 
   // Check extensions against npm using registry source info (#262)
   const updates = [];
@@ -3277,21 +3363,31 @@ function cmdStatus() {
     const currentVersion = info?.installed?.version || info.version;
     if (!currentVersion) continue;
     try {
-      const latest = execSync(`npm view ${npmPkg} version 2>/dev/null`, {
-        encoding: 'utf8', timeout: 10000,
-      }).trim();
+      const timeout = Math.min(STATUS_NPM_TIMEOUT_MS, remainingStatusBudgetMs(statusStartedAt));
+      if (timeout <= 0) {
+        skipped.push({ name, npm: npmPkg, reason: 'budget' });
+        continue;
+      }
+      console.log(`    ${name}: checking npm`);
+      const latest = npmViewVersionForStatus(npmPkg, timeout);
       if (latest && semverNewer(latest, currentVersion)) {
         updates.push({ name, current: currentVersion, latest, npm: npmPkg });
       }
-    } catch {}
+    } catch (error) {
+      skipped.push({ name, npm: npmPkg, reason: classifyStatusCheckError(error) });
+    }
   }
 
   console.log('');
-  console.log(`  LDM OS v${version.version}${cliUpdate ? ` (v${cliUpdate} available)` : ' (latest)'}`);
-  console.log(`  Installed: ${version.installed?.split('T')[0]}`);
-  console.log(`  Updated:   ${version.updated?.split('T')[0]}`);
-  console.log(`  Extensions: ${extCount}${updates.length > 0 ? `, ${updates.length} update(s) available` : ', all up to date'}`);
-  console.log(`  Root: ${LDM_ROOT}`);
+  if (updates.length === 0 && !cliUpdate && skipped.length === 0) {
+    console.log('  Update summary: all up to date');
+  } else {
+    const summaryParts = [];
+    if (updates.length > 0) summaryParts.push(`${updates.length} extension update(s) available`);
+    if (cliUpdate) summaryParts.push('CLI update available');
+    if (skipped.length > 0) summaryParts.push(`${skipped.length} update check(s) skipped`);
+    console.log(`  Update summary: ${summaryParts.join(', ')}`);
+  }
 
   if (updates.length > 0) {
     console.log('');
@@ -3307,6 +3403,14 @@ function cmdStatus() {
     console.log(`  CLI update: npm install -g @wipcomputer/wip-ldm-os@${cliUpdate}`);
   }
 
+  if (skipped.length > 0) {
+    console.log('');
+    console.log('  Update checks skipped:');
+    for (const item of skipped) {
+      console.log(`    ${item.name}: [${item.reason}] ${item.npm}`);
+    }
+  }
+
   console.log('');
 }
 
@@ -3987,7 +4091,7 @@ async function main() {
     console.log('    Module     ... ESM main/exports -> importable');
     console.log('    MCP Server ... mcp-server.mjs -> claude mcp add --scope user');
     console.log('    OpenClaw   ... openclaw.plugin.json -> ~/.ldm/extensions/ + ~/.openclaw/extensions/');
-    console.log('    Skill      ... SKILL.md -> ~/.openclaw/skills/<tool>/');
+    console.log('    Skill      ... SKILL.md or skills/<name>/SKILL.md -> agent skill paths');
     console.log('    CC Hook    ... guard.mjs or claudeCode.hook -> ~/.claude/settings.json');
     console.log('');
     console.log(`  v${PKG_VERSION}`);

package/docs/universal-installer/SPEC.md

@@ -144,13 +144,15 @@ A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
 
 A markdown file that teaches agents when and how to use the tool. The instruction interface. Follows the [Agent Skills Spec](https://agentskills.io/specification).
 
-**Convention:** `SKILL.md` at the repo root. YAML frontmatter with name, description. Optional `references/` directory for context files.
+**Convention:** either `SKILL.md` at the repo root, or one or more skill folders at `skills/<skill-name>/SKILL.md`. YAML frontmatter includes name and description. Optional `references/`, `agents/`, `scripts/`, and `assets/` directories live beside `SKILL.md`.
 
 **Platform variants:** Codex CLI reads `AGENTS.md` instead of `SKILL.md`, with the same role and the same content shape. Treat `AGENTS.md` as the Codex-flavored filename for this same interface, not a separate interface. A repo may ship both (or symlink one to the other) so it works in Codex and SKILL.md-aware agents.
 
-**Detection:** `SKILL.md` exists.
+**Detection:** `SKILL.md` exists, or at least one `skills/<skill-name>/SKILL.md` exists.
 
-**Install:** `SKILL.md` deployed to `~/.openclaw/skills/<name>/`. If `references/` exists, deployed alongside SKILL.md and to `settings/docs/skills/<name>/` in the workspace.
+**Install:** the skill folder is deployed to every supported local agent skill surface, including OpenClaw, Codex, Claude Code, and WIP agent compatibility paths when present. If `references/` exists, it is deployed alongside SKILL.md and to `settings/docs/skills/<name>/` in the workspace.
+
+**Npm package shape:** a public skill package can expose `SKILL.md` at package root. For example, `@wipcomputer/wip-ai-chat-ui` is sourced from a private repo folder at `design/skills/wip-ai-chat-ui/`, but publishes a tarball with `SKILL.md`, `agents/`, and `references/` at package root so `ldm install @wipcomputer/wip-ai-chat-ui` installs the skill directly.
 
 **Structure:**
 ```
@@ -162,6 +164,17 @@ repo/
     └── ...
 ```
 
+Multiple skills can also live in one repo:
+
+```text
+repo/
+└── skills/
+    └── wip-ai-chat-ui/
+        ├── SKILL.md
+        ├── agents/
+        └── references/
+```
+
 **Key rules (from Agent Skills Spec):**
 - SKILL.md body < 5000 tokens. Process goes in SKILL.md, context goes in references/.
 - Imperative language: "Run this command" not "This product enables..."

package/docs/universal-installer/TECHNICAL.md

@@ -148,13 +148,13 @@ A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
 
 A markdown file that teaches agents when and how to use the tool. The instruction interface. Follows the [Agent Skills Spec](https://agentskills.io/specification).
 
-**Convention:** `SKILL.md` at the repo root. Optional `references/` directory for context files.
+**Convention:** either `SKILL.md` at the repo root, or one or more skill folders at `skills/<skill-name>/SKILL.md`. Optional `references/`, `agents/`, `scripts/`, and `assets/` directories live beside `SKILL.md`.
 
 **Platform variants:** Codex CLI reads `AGENTS.md` with the same role and content shape. Treat as the Codex-flavored filename for this same interface, not a separate one.
 
-**Detection:** `SKILL.md` exists.
+**Detection:** `SKILL.md` exists, or at least one `skills/<skill-name>/SKILL.md` exists.
 
-**Install:** `ldm install` deploys `SKILL.md` to `~/.openclaw/skills/<name>/`. If `references/` exists, it is deployed alongside and also to `settings/docs/skills/<name>/` in the workspace (so all agents can read them).
+**Install:** `ldm install` deploys the skill folder to every supported local agent skill surface, including OpenClaw, Codex, Claude Code, and WIP agent compatibility paths when present. If `references/` exists, it is deployed alongside and also to `settings/docs/skills/<name>/` in the workspace so all agents can read them.
 
 **Key rules:**
 - SKILL.md body < 5000 tokens. Process in SKILL.md, context in references/.
@@ -364,7 +364,7 @@ ldm install                            # update all
 | `mcp-server.mjs` | MCP (local stdio) | Adds `command` + `args` entry to `.mcp.json` |
 | `mcp.remote.url` in `package.json` | Remote MCP | Adds `url` + `transport` entry to `.mcp.json`; prints Claude Desktop hint. **Implementation in flight ([ticket](../../ai/product/bugs/installer/2026-04-28--cc-mini--installer-remote-mcp-detection.md)).** |
 | `openclaw.plugin.json` | OpenClaw | Copies to `~/.openclaw/extensions/` |
-| `SKILL.md` | Skill | Reports path |
+| `SKILL.md` or `skills/<name>/SKILL.md` | Skill | Deploys skill folder to supported agent skill paths |
 | `guard.mjs` or `claudeCode.hook` | CC Hook | Adds to `~/.claude/settings.json` |
 | `.claude-plugin/plugin.json` | CC Plugin | Registers with Claude Code marketplace |
 

package/lib/deploy.mjs

@@ -177,6 +177,14 @@ export function detectHarnesses() {
     skills: join(codexHome, 'skills'),
   };
 
+  // WIP agent skill compatibility directory
+  const agentsHome = join(HOME, '.agents');
+  harnesses['wip-agents'] = {
+    detected: existsSync(agentsHome),
+    home: agentsHome,
+    skills: join(agentsHome, 'skills'),
+  };
+
   // Cursor
   const cursorHome = join(HOME, '.cursor');
   harnesses['cursor'] = {
@@ -207,7 +215,7 @@ export function detectHarnesses() {
 function getHarnesses() {
   try {
     const config = readJSON(LDM_CONFIG_PATH) || {};
-    if (config.harnesses) {
+    if (config.harnesses && config.harnesses['wip-agents']) {
       const workspace = (config.workspace || '').replace('~', HOME);
       return { harnesses: config.harnesses, workspace };
     }
@@ -1236,11 +1244,77 @@ function installClaudeCodeHookEvent(repoPath, door, toolName = basename(repoPath
   }
 }
 
-function installSkill(repoPath, toolName) {
+function copySkillTree(skillDir, dest, copyFullFolder = false) {
+  mkdirSync(dest, { recursive: true });
+  if (copyFullFolder) {
+    cpSync(skillDir, dest, { recursive: true });
+    return;
+  }
+
+  cpSync(join(skillDir, 'SKILL.md'), join(dest, 'SKILL.md'));
+  for (const child of ['references', 'agents', 'scripts', 'assets']) {
+    const src = join(skillDir, child);
+    if (existsSync(src)) cpSync(src, join(dest, child), { recursive: true });
+  }
+}
+
+const SKILL_COMPANION_DIRS = ['references', 'agents', 'scripts', 'assets'];
+
+function listSkillCopyEntries(skillDir, copyFullFolder = false) {
+  if (copyFullFolder) {
+    try {
+      return readdirSync(skillDir)
+        .filter((entry) => entry !== '.DS_Store')
+        .sort();
+    } catch {
+      return ['SKILL.md'];
+    }
+  }
+
+  const entries = ['SKILL.md'];
+  for (const child of SKILL_COMPANION_DIRS) {
+    if (existsSync(join(skillDir, child))) entries.push(`${child}/`);
+  }
+  return entries;
+}
+
+function printSkillDryRunPlan({ sourceSkillDir, refsSrc, toolName, harnesses, workspace, entries }) {
+  const formatTargetEntries = (base) => entries.map((entry) => join(base, entry));
+  const harnessTargets = Object.entries(harnesses)
+    .filter(([, h]) => h.detected && h.skills)
+    .map(([name, h]) => ({ name, base: join(h.skills, toolName) }));
+
+  ok(`Skill: ${toolName}`);
+  log(`Source: ${sourceSkillDir}`);
+  log('Would copy:');
+  for (const entry of entries) log(`- ${entry}`);
+
+  const permanentBase = join(LDM_EXTENSIONS, toolName);
+  log('Permanent copy:');
+  for (const target of formatTargetEntries(permanentBase)) log(`- ${target}`);
+
+  if (harnessTargets.length > 0) {
+    log('Agent skill targets:');
+    for (const target of harnessTargets) {
+      log(`- ${target.name}: ${target.base}`);
+      for (const entryTarget of formatTargetEntries(target.base)) log(`  - ${entryTarget}`);
+    }
+  } else {
+    log('Agent skill targets: no detected skill harnesses');
+  }
+
+  if (existsSync(refsSrc) && workspace && existsSync(workspace)) {
+    const homeRefsDest = join(workspace, 'settings', 'docs', 'skills', toolName);
+    log('Workspace docs target:');
+    log(`- ${homeRefsDest} (references/ only)`);
+  }
+}
+
+function installSkillFolder(skillDir, toolName, opts = {}) {
   const { harnesses, workspace } = getHarnesses();
 
-  // Find SKILL.md source: repo path first, then permanent copy at ~/.ldm/extensions/
-  let skillSrc = join(repoPath, 'SKILL.md');
+  // Find SKILL.md source: skill dir first, then permanent copy at ~/.ldm/extensions/
+  let skillSrc = join(skillDir, 'SKILL.md');
   const permanentSkill = join(LDM_EXTENSIONS, toolName, 'SKILL.md');
   if (!existsSync(skillSrc) && existsSync(permanentSkill)) skillSrc = permanentSkill;
   if (!existsSync(skillSrc)) return false;
@@ -1251,14 +1325,16 @@ function installSkill(repoPath, toolName) {
     return false;
   }
 
-  // Find references/ source: repo path first, then permanent copy
-  let refsSrc = join(repoPath, 'references');
+  const sourceSkillDir = dirname(skillSrc);
+
+  // Find references/ source: skill dir first, then permanent copy
+  let refsSrc = join(skillDir, 'references');
   const permanentRefs = join(LDM_EXTENSIONS, toolName, 'references');
   if (!existsSync(refsSrc) && existsSync(permanentRefs)) refsSrc = permanentRefs;
 
   if (DRY_RUN) {
-    const targets = Object.entries(harnesses).filter(([,h]) => h.detected && h.skills).map(([name]) => name);
-    ok(`Skill: would deploy ${toolName} to ${targets.join(', ')} (dry run)`);
+    const entries = listSkillCopyEntries(sourceSkillDir, opts.copyFullFolder);
+    printSkillDryRunPlan({ sourceSkillDir, refsSrc, toolName, harnesses, workspace, entries });
     return true;
   }
 
@@ -1267,21 +1343,13 @@ function installSkill(repoPath, toolName) {
 
     // 1. Save permanent copy to ~/.ldm/extensions/<name>/ (survives tmp cleanup)
     const ldmSkillDir = join(LDM_EXTENSIONS, toolName);
-    mkdirSync(ldmSkillDir, { recursive: true });
-    cpSync(skillSrc, join(ldmSkillDir, 'SKILL.md'));
-    if (existsSync(refsSrc) && refsSrc !== permanentRefs) {
-      cpSync(refsSrc, join(ldmSkillDir, 'references'), { recursive: true });
-    }
+    copySkillTree(sourceSkillDir, ldmSkillDir, opts.copyFullFolder);
 
     // 2. Deploy to every detected harness that has a skills path
     for (const [name, harness] of Object.entries(harnesses)) {
       if (!harness.detected || !harness.skills) continue;
       const dest = join(harness.skills, toolName);
-      mkdirSync(dest, { recursive: true });
-      cpSync(skillSrc, join(dest, 'SKILL.md'));
-      if (existsSync(refsSrc)) {
-        cpSync(refsSrc, join(dest, 'references'), { recursive: true });
-      }
+      copySkillTree(sourceSkillDir, dest, opts.copyFullFolder);
       deployed.push(name);
     }
 
@@ -1301,6 +1369,18 @@ function installSkill(repoPath, toolName) {
   }
 }
 
+function installSkill(repoPath, toolName, skillInfo = null) {
+  if (Array.isArray(skillInfo?.skills) && skillInfo.skills.length > 0) {
+    let installed = 0;
+    for (const skill of skillInfo.skills) {
+      if (installSkillFolder(skill.path, skill.name, { copyFullFolder: true })) installed++;
+    }
+    return installed > 0;
+  }
+
+  return installSkillFolder(repoPath, toolName);
+}
+
 // ── Single tool install ──
 
 export function installSingleTool(toolPath) {
@@ -1361,6 +1441,10 @@ export function installSingleTool(toolPath) {
       }
     }
 
+    if (interfaces.skill) {
+      installSkill(toolPath, toolName, interfaces.skill);
+    }
+
     return ifaceNames.length;
   }
 
@@ -1429,7 +1513,7 @@ export function installSingleTool(toolPath) {
 
   if (interfaces.skill) {
     // Skills always deploy. They're instruction files, not running code.
-    if (installSkill(toolPath, toolName)) installed++;
+    if (installSkill(toolPath, toolName, interfaces.skill)) installed++;
   }
 
   if (interfaces.module) {
@@ -1590,7 +1674,7 @@ export async function enableExtension(name) {
 
   if (interfaces.mcp) registerMCP(extPath, interfaces.mcp, name);
   if (interfaces.claudeCodeHook) installClaudeCodeHook(extPath, interfaces.claudeCodeHook);
-  if (interfaces.skill) installSkill(extPath, name);
+  if (interfaces.skill) installSkill(extPath, name, interfaces.skill);
 
   entry.enabled = true;
   entry.updatedAt = new Date().toISOString();