cue-ai 0.5.0 → 0.7.0

package/src/lib/pr-throttle.ts

@@ -0,0 +1,209 @@
+/**
+ * Throttle + opt-out registry for cue's outbound PRs.
+ *
+ * Storage: ~/.cache/cue/pr-opened.json (atomically written).
+ *
+ * Three responsibilities:
+ *  1. **Cooldown per repo** — don't re-PR the same repo within `cooldownDays`
+ *     (default 90). Cue should *never* PR a repo twice without an invitation.
+ *  2. **Daily cap** — GitHub auto-flags accounts that open >30 PRs/day. We
+ *     cap ourselves at 25/day with headroom for retries.
+ *  3. **Opt-out cache** — if a repo's README contains `<!-- cue: ignore -->`
+ *     we record it once and never check again. Idempotent on every scan.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+const DEFAULT_PATH = join(
+  process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"),
+  "cue",
+  "pr-opened.json",
+);
+
+export const DEFAULT_COOLDOWN_DAYS = 90;
+export const DAILY_CAP = 25;
+
+export type EntryState =
+  | "open"        // PR open on GitHub
+  | "merged"      // PR was merged
+  | "closed"      // PR was closed without merge
+  | "opted-out"   // skipped — repo README has <!-- cue: ignore -->
+  | "skipped";    // skipped for any other reason (e.g. no fixes to apply)
+
+export interface ThrottleEntry {
+  repo: string;                // owner/name
+  state: EntryState;
+  openedAt: string;            // ISO timestamp
+  rulesFixed?: string[];       // R001, R005, etc. — only present when state was open
+  prNumber?: number;
+  prUrl?: string;
+  fork?: string;               // owner/name of cue's fork (null after cleanup)
+  branch?: string;             // branch on the fork
+  reason?: string;             // optional human-readable reason
+  cleanedAt?: string;          // when fork was deleted (cleanup-forks command)
+}
+
+export interface ThrottleDB {
+  version: 1;
+  history: ThrottleEntry[];
+}
+
+// ---------------------------------------------------------------------------
+// Read + write
+// ---------------------------------------------------------------------------
+
+function emptyDb(): ThrottleDB { return { version: 1, history: [] }; }
+
+export function loadDb(path: string = DEFAULT_PATH): ThrottleDB {
+  if (!existsSync(path)) return emptyDb();
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw) as ThrottleDB;
+    if (parsed.version !== 1 || !Array.isArray(parsed.history)) return emptyDb();
+    return parsed;
+  } catch {
+    return emptyDb();
+  }
+}
+
+/** Atomic write: temp file + rename. Survives concurrent writes. */
+export function saveDb(db: ThrottleDB, path: string = DEFAULT_PATH): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(db, null, 2) + "\n");
+  renameSync(tmp, path);
+}
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+/** Days since `iso` timestamp. */
+function daysSince(iso: string): number {
+  const ms = Date.now() - new Date(iso).getTime();
+  return ms / (1000 * 60 * 60 * 24);
+}
+
+/**
+ * Is this repo currently throttled? Returns reason string when throttled,
+ * null when free to post. Considers cooldown + opted-out state.
+ */
+export function isThrottled(
+  db: ThrottleDB,
+  repo: string,
+  cooldownDays: number = DEFAULT_COOLDOWN_DAYS,
+): string | null {
+  const entries = db.history.filter((e) => e.repo === repo);
+  if (entries.length === 0) return null;
+
+  // Opted out — permanent
+  if (entries.some((e) => e.state === "opted-out")) {
+    return "repo has <!-- cue: ignore --> in README";
+  }
+
+  // Most recent post-or-skip
+  entries.sort((a, b) => b.openedAt.localeCompare(a.openedAt));
+  const latest = entries[0]!;
+  const days = daysSince(latest.openedAt);
+  if (days < cooldownDays) {
+    const remaining = Math.ceil(cooldownDays - days);
+    return `cooldown: last interaction was ${Math.floor(days)}d ago (state=${latest.state}); ${remaining}d remaining`;
+  }
+  return null;
+}
+
+/** How many PRs we've opened in the last rolling 24h window. */
+export function todayCount(db: ThrottleDB): number {
+  return db.history.filter((e) => e.state === "open" && daysSince(e.openedAt) < 1).length;
+}
+
+/** Headroom under DAILY_CAP. Negative means we've already exceeded. */
+export function canPostMore(db: ThrottleDB): { ok: boolean; remaining: number; cap: number } {
+  const used = todayCount(db);
+  return { ok: used < DAILY_CAP, remaining: DAILY_CAP - used, cap: DAILY_CAP };
+}
+
+/** List entries by state — for the cleanup-forks command. */
+export function filterByState(db: ThrottleDB, states: EntryState[]): ThrottleEntry[] {
+  const set = new Set(states);
+  return db.history.filter((e) => set.has(e.state));
+}
+
+// ---------------------------------------------------------------------------
+// Mutations — always go through these helpers so audit history is correct
+// ---------------------------------------------------------------------------
+
+export function recordOpened(
+  db: ThrottleDB,
+  e: { repo: string; rulesFixed: string[]; prNumber: number; prUrl: string; fork: string; branch: string },
+): ThrottleDB {
+  db.history.push({
+    repo: e.repo,
+    state: "open",
+    openedAt: new Date().toISOString(),
+    rulesFixed: e.rulesFixed,
+    prNumber: e.prNumber,
+    prUrl: e.prUrl,
+    fork: e.fork,
+    branch: e.branch,
+  });
+  return db;
+}
+
+export function recordOptOut(db: ThrottleDB, repo: string): ThrottleDB {
+  db.history.push({
+    repo,
+    state: "opted-out",
+    openedAt: new Date().toISOString(),
+    reason: "README contains <!-- cue: ignore -->",
+  });
+  return db;
+}
+
+export function recordSkipped(db: ThrottleDB, repo: string, reason: string): ThrottleDB {
+  db.history.push({
+    repo,
+    state: "skipped",
+    openedAt: new Date().toISOString(),
+    reason,
+  });
+  return db;
+}
+
+export function updateEntryState(
+  db: ThrottleDB,
+  match: { repo: string; prNumber?: number },
+  newState: EntryState,
+  extra: Partial<ThrottleEntry> = {},
+): ThrottleDB {
+  for (const e of db.history) {
+    if (e.repo !== match.repo) continue;
+    if (match.prNumber !== undefined && e.prNumber !== match.prNumber) continue;
+    e.state = newState;
+    Object.assign(e, extra);
+  }
+  return db;
+}
+
+// ---------------------------------------------------------------------------
+// Opt-out check — fetches README via gh, looks for the marker
+// ---------------------------------------------------------------------------
+
+export const OPT_OUT_MARKER = "<!-- cue: ignore -->";
+/**
+ * Opposite of OPT_OUT_MARKER: when --opt-in-only mode is active, we only
+ * post PRs to repos whose README contains this marker. Lets authors flip
+ * the consent model from "assumed yes" to "explicit yes".
+ */
+export const OPT_IN_MARKER = "<!-- cue: ok -->";
+
+/**
+ * Look in the cached DB first; if not seen, caller should fetch the README
+ * and call `recordOptOut` if it matches. Keeping the fetch out of this module
+ * keeps it dependency-free + easily testable.
+ */
+export function hasRecordedOptOut(db: ThrottleDB, repo: string): boolean {
+  return db.history.some((e) => e.repo === repo && e.state === "opted-out");
+}

package/src/lib/profile-generator.test.ts

@@ -20,7 +20,7 @@ let profilesRoot: string;
 let priorProfilesDir: string | undefined;
 
 beforeEach(async () => {
-  scratchRoot = await mkdtemp(join(tmpdir(), "soul-profile-generator-"));
+  scratchRoot = await mkdtemp(join(tmpdir(), "cue-profile-generator-"));
   profilesRoot = join(scratchRoot, "profiles");
   priorProfilesDir = process.env.CUE_PROFILES_DIR;
   process.env.CUE_PROFILES_DIR = profilesRoot;

package/src/lib/profile-generator.ts

@@ -506,7 +506,7 @@ export function generateProfile(
     name: options.name,
     description:
       options.description ??
-      `Auto-generated from soul scan (${included.length} skills)`,
+      `Auto-generated from cue scan (${included.length} skills)`,
     agents: ["claude-code", "codex"],
   };
   if (options.inheritCore && core.length > 0) {
@@ -1024,7 +1024,7 @@ function renderProfileYaml(
 ): string {
   const skills = buildProfileSkills(included);
   const lines: string[] = [];
-  lines.push(`# Auto-generated by soul new ${profile.name} --from-scan.`);
+  lines.push(`# Auto-generated by cue new ${profile.name} --from-scan.`);
   if (core.length > 0) {
     lines.push("# Core candidates were detected as cross-cutting.");
     if (profile.inherits === "core") {

package/src/lib/profile-linter.test.ts

@@ -26,7 +26,7 @@ let configsRoot: string;
 let npxRepoRoot: string;
 
 beforeEach(async () => {
-  root = await mkdtemp(join(tmpdir(), "soul-profile-linter-"));
+  root = await mkdtemp(join(tmpdir(), "cue-profile-linter-"));
   profilesDir = join(root, "profiles");
   skillsRoot = join(root, "skills", "skills");
   pluginsRoot = join(root, "plugins");
@@ -132,7 +132,7 @@ describe("lintProfile", () => {
 
   test("reports W1, W2, W3, and W4 warnings", async () => {
     const localRefs: string[] = [];
-    for (let i = 0; i < 26; i++) {
+    for (let i = 0; i < 41; i++) {
       const ref = `bulk/skill-${i}`;
       localRefs.push(ref);
       await writeLocalSkill(ref);
@@ -217,7 +217,10 @@ describe("lintProfile", () => {
     );
 
     const messages = result.issues.map((issue) => issue.message).join("\n");
-    expect(rules(result).filter((rule) => rule === "E3")).toHaveLength(4);
+    // Plugin-not-installed is demoted to W5 (environmental), so the three
+    // genuine resolver errors stay as E3 and the plugin shows up as W5.
+    expect(rules(result).filter((rule) => rule === "E3")).toHaveLength(3);
+    expect(rules(result).filter((rule) => rule === "W5")).toHaveLength(1);
     expect(messages).toContain("local skill");
     expect(messages).toContain("npx skill");
     expect(messages).toContain("plugin");

package/src/lib/profile-linter.ts

@@ -1,16 +1,17 @@
 /**
- * Profile linter for `soul validate`.
+ * Profile linter for `cue validate`.
  *
  * The rules below are intentionally numbered and centralized so a later
  * suppression pass can key off stable ids such as `# lint: ignore W1`.
  *
- * W1: profile declares more than 25 skills.
+ * W1: profile declares more than 40 skills.
  * W2: profile declares more than 5 MCP servers.
  * W3: inheritance chain depth is greater than 2.
  * W4: a skill slug appears in both `skills.local` and `skills.npx`.
+ * W5: a referenced plugin is not installed locally (environmental, not a profile bug).
  * E1: profile `name:` collides with another profile.
  * E2: inheritance chain contains a cycle.
- * E3: referenced skill, MCP, or plugin cannot be resolved.
+ * E3: referenced skill or MCP cannot be resolved.
  */
 
 import { mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
@@ -38,15 +39,18 @@ import {
   resolveNpxDetailed,
   type NpxFetchFn,
 } from "./resolver-npx";
-import { resolvePlugins } from "./resolver-plugins";
+import { PluginNotInstalled, resolvePlugins } from "./resolver-plugins";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = process.env.CUE_REPO_ROOT ?? process.env.SOUL_REPO_ROOT ?? resolve(HERE, "..", "..");
 const DEFAULT_PROFILES_DIR = join(REPO_ROOT, "profiles");
 const DEFAULT_SKILLS_ROOT = join(REPO_ROOT, "resources", "skills", "skills");
 const DEFAULT_CONFIGS_ROOT = join(REPO_ROOT, "resources", "mcps", "configs");
+const DEFAULT_RULES_ROOT = join(REPO_ROOT, "resources", "rules");
+const DEFAULT_COMMANDS_ROOT = join(REPO_ROOT, "resources", "commands");
+const DEFAULT_HOOKS_ROOT = join(REPO_ROOT, "resources", "hooks");
 
-export type LintRuleId = "W1" | "W2" | "W3" | "W4" | "E1" | "E2" | "E3";
+export type LintRuleId = "W1" | "W2" | "W3" | "W4" | "W5" | "E1" | "E2" | "E3";
 export type DiagnosticRuleId = LintRuleId | "SCHEMA" | "LOAD";
 export type LintSeverity = "warning" | "error";
 
@@ -60,7 +64,7 @@ export const PROFILE_LINT_RULES: Record<LintRuleId, RuleDoc> = {
   W1: {
     severity: "warning",
     title: "too many skills",
-    description: "Profile declares more than 25 skills; this can bloat prompt tokens.",
+    description: "Profile declares more than 40 skills; this can bloat prompt tokens.",
   },
   W2: {
     severity: "warning",
@@ -77,6 +81,11 @@ export const PROFILE_LINT_RULES: Record<LintRuleId, RuleDoc> = {
     title: "ambiguous skill source",
     description: "A skill slug appears in both local and npx sources.",
   },
+  W5: {
+    severity: "warning",
+    title: "plugin not installed locally",
+    description: "A referenced plugin is not installed under ~/.claude/plugins (environmental — install with `/plugin marketplace add <name>`).",
+  },
   E1: {
     severity: "error",
     title: "profile name collision",
@@ -201,10 +210,51 @@ export async function lintProfile(
   await checkNpxSkills(resolved, result, opts);
   await checkPlugins(resolved, result, opts);
   await checkMcps(resolved, result, opts);
+  await checkResourceRefs(resolved, result, opts);
 
   return result;
 }
 
+async function checkResourceRefs(
+  profile: ResolvedProfile,
+  result: ProfileLintResult,
+  _opts: ProfileLinterOptions,
+): Promise<void> {
+  const { access } = await import("node:fs/promises");
+  const { isAbsolute } = await import("node:path");
+
+  const buckets: { label: string; refs: string[]; root: string; addExt: boolean }[] = [
+    { label: "rules",    refs: profile.rules,    root: DEFAULT_RULES_ROOT,    addExt: true },
+    { label: "commands", refs: profile.commands, root: DEFAULT_COMMANDS_ROOT, addExt: true },
+    { label: "hooks",    refs: profile.hooks,    root: DEFAULT_HOOKS_ROOT,    addExt: false },
+  ];
+
+  for (const { label, refs, root, addExt } of buckets) {
+    if (refs.length === 0) {
+      addCheck(result, label, `no ${label} declared`);
+      continue;
+    }
+    let ok = 0;
+    for (const ref of refs) {
+      const withExt = addExt && !ref.endsWith(".md") ? `${ref}.md` : ref;
+      const full = isAbsolute(withExt) ? withExt : join(root, withExt);
+      try {
+        await access(full);
+        ok++;
+      } catch {
+        addIssue(
+          result,
+          "E3",
+          "error",
+          `${label} reference "${ref}" not found at ${full}`,
+          { subject: ref },
+        );
+      }
+    }
+    if (ok === refs.length) addCheck(result, label, `${ok} resolved`);
+  }
+}
+
 async function withProfilesDir<T>(
   profilesRoot: string | undefined,
   fn: () => Promise<T>,
@@ -359,7 +409,7 @@ function checkStaticRules(
   result: ProfileLintResult,
 ): void {
   const skillCount = declaredSkillCount(profile);
-  if (skillCount > 25) {
+  if (skillCount > 40) {
     addIssue(
       result,
       "W1",
@@ -520,7 +570,7 @@ async function resolveOneNpxSkill(
     }
   }
 
-  const tempRepo = await mkdtemp(join(tmpdir(), "soul-validate-npx-"));
+  const tempRepo = await mkdtemp(join(tmpdir(), "cue-validate-npx-"));
   try {
     await mkdir(join(tempRepo, "profiles", "_cache", "npx"), { recursive: true });
     await resolveNpxDetailed(single, {
@@ -595,6 +645,19 @@ function addResolverIssue(
   ref: string,
   err: unknown,
 ): void {
+  // Plugin-not-installed is environmental state (the profile is correct, the
+  // user's machine just doesn't have the plugin yet) — demote to W5 warning
+  // rather than failing validation with E3.
+  if (err instanceof PluginNotInstalled) {
+    addIssue(
+      result,
+      "W5",
+      "warning",
+      `plugin "${ref}" is not installed locally — run /plugin marketplace add ${ref.split("@")[0]}`,
+      { subject: ref },
+    );
+    return;
+  }
   addIssue(
     result,
     "E3",

package/src/lib/profile-loader.test.ts

@@ -34,7 +34,7 @@ let scratchRoot: string;
 let priorEnv: string | undefined;
 
 beforeEach(async () => {
-  scratchRoot = await mkdtemp(join(tmpdir(), "soul-profile-loader-"));
+  scratchRoot = await mkdtemp(join(tmpdir(), "cue-profile-loader-"));
   priorEnv = process.env.CUE_PROFILES_DIR;
   process.env.CUE_PROFILES_DIR = scratchRoot;
 });

package/src/lib/profile-loader.ts

@@ -373,6 +373,15 @@ function foldChain(chain: Profile[]): ResolvedProfile {
         child.plugins?.map(normalizePluginRef),
       ),
       env: mergeEnv(acc.env, child.env),
+      rules: dedupePrimitiveArray(acc.rules, child.rules),
+      commands: dedupePrimitiveArray(acc.commands, child.commands),
+      hooks: dedupePrimitiveArray(acc.hooks, child.hooks),
+      // Persona is leaf-wins (child overrides parent fully). Concatenating
+      // would produce awkward "you are X. ALSO you are Y" priming.
+      persona: child.persona ?? acc.persona,
+      playbooks: dedupePrimitiveArray(acc.playbooks, child.playbooks),
+      qualityGates: dedupePrimitiveArray(acc.qualityGates, child.qualityGates),
+      evals: dedupePrimitiveArray(acc.evals, child.evals),
       inheritanceChain: [...acc.inheritanceChain, child.name],
     };
   }
@@ -401,6 +410,13 @@ function normalizeToResolved(p: Profile, chain: string[]): ResolvedProfile {
     mcps: (p.mcps ?? []).map(normalizeMCPRef),
     plugins: (p.plugins ?? []).map(normalizePluginRef),
     env: { ...(p.env ?? {}) },
+    rules: [...(p.rules ?? [])],
+    commands: [...(p.commands ?? [])],
+    hooks: [...(p.hooks ?? [])],
+    persona: p.persona ?? "",
+    playbooks: [...(p.playbooks ?? [])],
+    qualityGates: [...(p.qualityGates ?? [])],
+    evals: [...(p.evals ?? [])],
     inheritanceChain: chain,
   };
 }

package/src/lib/resolver-local.test.ts

@@ -67,7 +67,7 @@ function profile(local: string[]): ResolvedProfile {
 }
 
 beforeEach(async () => {
-  rootDir = await mkdtemp(join(tmpdir(), "soul-resolver-local-"));
+  rootDir = await mkdtemp(join(tmpdir(), "cue-resolver-local-"));
   skillsRoot = join(rootDir, "skills", "skills");
   await mkdir(skillsRoot, { recursive: true });
   await buildTree();

package/src/lib/resolver-npx.test.ts

@@ -29,7 +29,7 @@ let repoRoot: string;
 let calls: Array<{ repo: string; pin: string | undefined; skill: string; destDir: string }>;
 
 beforeEach(() => {
-  repoRoot = mkdtempSync(join(tmpdir(), "soul-test-"));
+  repoRoot = mkdtempSync(join(tmpdir(), "cue-test-"));
   // The resolver writes under <repoRoot>/profiles/_cache/npx/<key>/, so make
   // sure the parent dirs exist — cache.cachePut calls mkdirSync recursive.
   mkdirSync(join(repoRoot, "profiles", "_cache", "npx"), { recursive: true });
@@ -307,3 +307,78 @@ describe("resolveNpxDetailed", () => {
     );
   });
 });
+
+// --- flattenNpxLayout: post-fetch path relocation --------------------------
+
+describe("flattenNpxLayout", () => {
+  let staging: string;
+
+  beforeEach(() => {
+    staging = mkdtempSync(join(tmpdir(), "cue-flatten-test-"));
+  });
+  afterEach(() => {
+    try { rmSync(staging, { recursive: true, force: true }); } catch {}
+  });
+
+  it("relocates <staging>/.claude/skills/<skill>/ → <staging>/<skill>/", async () => {
+    const { flattenNpxLayout } = await import("./resolver-npx");
+
+    // Set up the layout the `skills` CLI actually produces.
+    const fromPath = join(staging, ".claude", "skills", "my-skill");
+    mkdirSync(fromPath, { recursive: true });
+    writeFileSync(join(fromPath, "SKILL.md"), "# my-skill\n");
+
+    flattenNpxLayout(staging, "my-skill");
+
+    const flatPath = join(staging, "my-skill");
+    expect(existsSync(flatPath)).toBe(true);
+    expect(existsSync(join(flatPath, "SKILL.md"))).toBe(true);
+    expect(existsSync(fromPath)).toBe(false);
+    // Cleanup: .claude/ should be gone now (was empty after the move).
+    expect(existsSync(join(staging, ".claude"))).toBe(false);
+  });
+
+  it("is a no-op if <staging>/<skill>/ already exists (don't clobber)", async () => {
+    const { flattenNpxLayout } = await import("./resolver-npx");
+
+    const existing = join(staging, "my-skill");
+    mkdirSync(existing, { recursive: true });
+    writeFileSync(join(existing, "EXISTING.md"), "do not overwrite\n");
+
+    const fromPath = join(staging, ".claude", "skills", "my-skill");
+    mkdirSync(fromPath, { recursive: true });
+    writeFileSync(join(fromPath, "NEW.md"), "would clobber existing\n");
+
+    flattenNpxLayout(staging, "my-skill");
+
+    // The existing skill is preserved.
+    expect(existsSync(join(existing, "EXISTING.md"))).toBe(true);
+    expect(existsSync(join(existing, "NEW.md"))).toBe(false);
+  });
+
+  it("is a no-op when source layout is absent (e.g. CLI changed again)", async () => {
+    const { flattenNpxLayout } = await import("./resolver-npx");
+
+    // Nothing in staging — flattening should be silent, not throw.
+    expect(() => flattenNpxLayout(staging, "missing-skill")).not.toThrow();
+    expect(existsSync(join(staging, "missing-skill"))).toBe(false);
+  });
+
+  it("leaves sibling skills under .claude/skills/ alone when relocating one", async () => {
+    const { flattenNpxLayout } = await import("./resolver-npx");
+
+    const skillsDir = join(staging, ".claude", "skills");
+    mkdirSync(join(skillsDir, "alpha"), { recursive: true });
+    mkdirSync(join(skillsDir, "beta"), { recursive: true });
+    writeFileSync(join(skillsDir, "alpha", "SKILL.md"), "");
+    writeFileSync(join(skillsDir, "beta", "SKILL.md"), "");
+
+    flattenNpxLayout(staging, "alpha");
+
+    // alpha got moved out, beta stayed in place — the .claude tree is still
+    // present because beta is still there.
+    expect(existsSync(join(staging, "alpha", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(skillsDir, "beta", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(skillsDir, "alpha"))).toBe(false);
+  });
+});

package/src/lib/resolver-npx.ts

@@ -118,7 +118,7 @@ export type NpxFetchFn = (
  * because the tests pass their own fetcher.
  */
 export const npxFetch: NpxFetchFn = async (repo, pin, skill, destDir) => {
-  const args = ["skills", "add", repo, "--skill", skill, "-a", "claude-code", "-y"];
+  const args = ["-y", "skills@latest", "add", repo, "--skill", skill, "-a", "claude-code", "-y"];
   if (pin) {
     // Pin format from schema: "git@<sha>" or "tag@<version>".
     // `npx skills add` accepts `--ref <ref>` for both shas and tags.
@@ -139,8 +139,40 @@ export const npxFetch: NpxFetchFn = async (repo, pin, skill, destDir) => {
       stderr: res.stderr,
     });
   }
+
+  flattenNpxLayout(destDir, skill);
 };
 
+/**
+ * The `skills` CLI drops fetched skills at `<destDir>/.claude/skills/<skill>/`
+ * (it follows Claude Code's runtime layout). Cue's resolver expects a flat
+ * `<destDir>/<skill>/` layout — so relocate here. Exported for tests; callers
+ * outside this module should not need this.
+ */
+export function flattenNpxLayout(destDir: string, skill: string): void {
+  const fromClaudeLayout = join(destDir, ".claude", "skills", skill);
+  const flatTarget = join(destDir, skill);
+  if (!existsSync(fromClaudeLayout) || existsSync(flatTarget)) return;
+
+  // Lazy import — avoids node:fs/promises overhead in the cached-fetch path.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const fs = require("node:fs") as typeof import("node:fs");
+  fs.renameSync(fromClaudeLayout, flatTarget);
+
+  // Clean up the now-empty .claude/skills/ scaffold so the staging dir
+  // doesn't accumulate cruft when multiple skills are pulled in sequence.
+  try {
+    const claudeSkills = join(destDir, ".claude", "skills");
+    if (existsSync(claudeSkills) && fs.readdirSync(claudeSkills).length === 0) {
+      fs.rmSync(claudeSkills, { recursive: true, force: true });
+    }
+    const claudeDir = join(destDir, ".claude");
+    if (existsSync(claudeDir) && fs.readdirSync(claudeDir).length === 0) {
+      fs.rmSync(claudeDir, { recursive: true, force: true });
+    }
+  } catch { /* cleanup is best-effort */ }
+}
+
 // ---------------------------------------------------------------------------
 // Public resolver
 // ---------------------------------------------------------------------------
@@ -156,7 +188,7 @@ export interface ResolveNpxOptions {
 
 export interface ResolveNpxResult {
   plans: LinkPlan[];
-  /** Per-entry cache key — useful for debugging / `soul doctor`. */
+  /** Per-entry cache key — useful for debugging / `cue doctor`. */
   keys: Record<string, string>;
 }
 
@@ -263,7 +295,7 @@ async function fetchInto(
   // If the slot already exists (partial-hit repair), we merge skill subdirs
   // into the existing slot rather than nuking it; this keeps already-good
   // skills warm.
-  const staging = mkdtempSync(join(tmpdir(), "soul-npx-"));
+  const staging = mkdtempSync(join(tmpdir(), "cue-npx-"));
   try {
     for (const skill of skills) {
       await fetcher(entry.repo, entry.pin, skill, staging);

package/src/lib/resolver-plugins.test.ts

@@ -23,7 +23,7 @@ import {
 let root: string;
 
 beforeEach(async () => {
-  root = await mkdtemp(join(tmpdir(), "soul-resolver-plugins-"));
+  root = await mkdtemp(join(tmpdir(), "cue-resolver-plugins-"));
 });
 
 afterEach(async () => {