skillpass 0.3.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brad Traversy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -20,10 +20,10 @@ Requires Node 20 or newer. No runtime dependencies.
 ## Commands
 
 ```
-skillpass search [query] [--target <tool>] [--category <slug>] [--packs] [--json]
+skillpass search [query] [--ai] [--target <tool>] [--category <slug>] [--packs] [--json]
 skillpass scan <path> [--json]
 skillpass report <slug>[@version] [--json]
-skillpass add <slug>[@version] [--target <tool> [--global] | --dir <path>] [--yes]
+skillpass add <slug>[@version] [--target <tool>... [--global] | --dir <path>] [--yes]
 skillpass remove <slug> [--target <tool> [--global] | --dir <path>]
 skillpass update <slug>[@version] [--target <tool> [--global]] [--yes]
 skillpass outdated
@@ -38,6 +38,10 @@ skillpass --version | --help
 `--target claude-code`, `--category security-review`, or `--packs` for
 multi-skill workflow packs.
 
+`skillpass search --ai "turn a video into an article"` searches by meaning
+instead of by keyword, through the directory's free AI search. Results come
+back in relevance order and the same filters apply.
+
 ### Inspect
 
 `skillpass report <slug>` prints the version's Skill Passport before you
@@ -52,9 +56,15 @@ risk, then downloads the validated snapshot and re-verifies every byte against
 the pinned source hash before anything touches disk. Installs are atomic - a
 failed write leaves nothing behind.
 
-- `--target claude-code` installs to `.claude/skills/<slug>` (project) or
-  `~/.claude/skills/<slug>` with `--global`
-- `--target codex` installs to `.agents/skills/<slug>`
+- `--target <tool>` installs into the tool's skills folder, or its user-level
+  folder with `--global`:
+  - `claude-code`: `.claude/skills/` and `~/.claude/skills/`
+  - `agents`: the shared `.agents/skills/` and `~/.agents/skills/` that
+    `codex`, `cursor`, `windsurf`, `github-copilot`, `gemini-cli`, and
+    `opencode` all read; any of those names resolves to the same folders
+  - `cline`: `.cline/skills/` and `~/.cline/skills/`
+- Repeat `--target` to install into several tools in one pass with one
+  pre-flight; targets that share a folder install once
 - `--dir <path>` installs anywhere
 - No flags in a terminal: an interactive picker
 

package/dist/cli.js

@@ -492,16 +492,7 @@ function unzipSync(data, opts) {
 }
 
 // src/add.ts
-import {
-  existsSync as existsSync2,
-  mkdirSync as mkdirSync2,
-  readdirSync as readdirSync3,
-  renameSync,
-  rmdirSync,
-  rmSync,
-  statSync as statSync3,
-  writeFileSync as writeFileSync2
-} from "node:fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync as readdirSync3, renameSync, rmdirSync, rmSync, statSync as statSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname, isAbsolute, join as join4, resolve as resolve2 } from "node:path";
 
 // ../validator/src/load.ts
@@ -15348,14 +15339,7 @@ var aiReviewSchema = external_exports.object({
 
 // ../skill-schema/src/submission.ts
 var SUBMISSION_SOURCE_TYPES = ["github_url", "zip"];
-var SUBMISSION_STATUSES = [
-  "draft",
-  "validating",
-  "passed",
-  "warning",
-  "failed",
-  "published"
-];
+var SUBMISSION_STATUSES = ["draft", "validating", "passed", "warning", "failed", "published"];
 var submissionSourceTypeSchema = external_exports.enum(SUBMISSION_SOURCE_TYPES);
 var submissionStatusSchema = external_exports.enum(SUBMISSION_STATUSES);
 var MAX_ZIP_BYTES = 10 * 1024 * 1024;
@@ -15716,6 +15700,13 @@ function readManifest(files) {
   return { state: "ok", data: result.data };
 }
 var FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
+function readDeclaredVersion(frontmatter) {
+  const top = /^version:\s*["']?([^"'\s]+)["']?\s*$/m.exec(frontmatter);
+  if (top) return top[1];
+  const block = /^metadata:\s*\n((?:[ \t]+\S.*(?:\n|$))*)/m.exec(frontmatter);
+  const nested = block && /^[ \t]+version:\s*["']?([^"'\s]+)["']?\s*$/m.exec(block[1]);
+  return nested ? nested[1] : void 0;
+}
 function readSkillMeta(content) {
   const out = {};
   const fm = FRONTMATTER_RE.exec(content);
@@ -15743,6 +15734,8 @@ function readSkillMeta(content) {
         out[key] = parts.join(" ").replace(/^["']|["']$/g, "");
       }
     }
+    const version2 = readDeclaredVersion(fm[1]);
+    if (version2) out.version = version2;
   }
   if (!out.description) {
     const prose = firstParagraph(body);
@@ -15792,6 +15785,7 @@ function inferManifest(files, fallbackName) {
   return {
     schemaVersion: "0.1",
     name,
+    ...meta3.version && SEMVER_RE.test(meta3.version) ? { version: meta3.version } : {},
     description: meta3.description ?? name,
     targets: inferTargets(files),
     permissions,
@@ -15826,9 +15820,7 @@ function readmeProse(files) {
   return readme ? firstParagraph(readme.content) : void 0;
 }
 function inferNestedManifest(files, fallbackName) {
-  const members = collectMemberFiles(files).sort(
-    (a, b) => a.folder < b.folder ? -1 : a.folder > b.folder ? 1 : 0
-  );
+  const members = collectMemberFiles(files).sort((a, b) => a.folder < b.folder ? -1 : a.folder > b.folder ? 1 : 0);
   if (members.length === 0) {
     return null;
   }
@@ -15841,10 +15833,7 @@ function inferNestedManifest(files, fallbackName) {
     let entryName = slugForSkill(meta3.name ?? member.folder);
     if (used.has(entryName)) entryName = slugForSkill(member.folder);
     used.add(entryName);
-    const targets = member.plainPath ? inferTargets(files) : [
-      ...member.claudePath ? ["claude-code"] : [],
-      ...member.agentsPath ? ["codex"] : []
-    ];
+    const targets = member.plainPath ? inferTargets(files) : [...member.claudePath ? ["claude-code"] : [], ...member.agentsPath ? ["codex"] : []];
     for (const target of targets) packTargets.add(target);
     return {
       name: entryName,
@@ -16031,10 +16020,12 @@ var CREDENTIAL_PATTERNS = [
   },
   {
     code: "credential-harvesting",
-    // The ::/. lookbehinds skip code identifiers (`Box::leak(secret)`,
-    // `.leak(`) so security docs naming anti-patterns don't flag.
+    // The verb has to sit where an instruction puts it (line or sentence
+    // start, or after then/and/to/should/must): narrative like "timing leaks
+    // secret bits" has a noun subject and does not fire. The ::/. lookbehinds
+    // skip code identifiers (`Box::leak(secret)`, `.leak(`).
     pattern: new RegExp(
-      String.raw`(?<!\b(?:never|not|don'?t|avoids?|prevents?|stops?)\s)(?<!::)(?<!\.)\b(?:exfiltrates?|steals?|harvests?|dumps?|leaks?)\b[^.\n]{0,60}?${SECRET_NOUN}`,
+      String.raw`(?:^[-*\d.)\s]*|[.:;!?]\s+|\b(?:then|and|or|to|should|must|now|please)\s+)(?<!\b(?:never|not|don'?t|avoids?|prevents?|stops?)\s)(?<!::)(?<!\.)(?:exfiltrate|steal|harvest|dump|leak)s?\b[^.\n]{0,60}?${SECRET_NOUN}`,
       "i"
     ),
     message: "matches a credential-exfiltration phrase"
@@ -16048,14 +16039,28 @@ var CREDENTIAL_PATTERNS = [
     message: "matches a credential-file network-transmission phrase"
   }
 ];
-var advisory = (rows) => rows.map((row2) => ({ ...row2, severity: "warning" }));
+var advisory = (rows, mentionAware = false) => rows.map((row2) => ({ ...row2, severity: "warning", mentionAware }));
 var ALL_ROWS = [
   ...SECRET_PATTERNS,
-  ...advisory(INJECTION_PATTERNS),
+  ...advisory(INJECTION_PATTERNS, true),
   ...advisory(DANGEROUS_PATTERNS),
   ...advisory(MALWARE_PATTERNS),
-  ...advisory(CREDENTIAL_PATTERNS)
+  ...advisory(CREDENTIAL_PATTERNS, true)
 ];
+var MENTION_LEAD_RE = /\b(?:flags?|flagged|detects?|detecting|look(?:ing)?\s+for|watch\s+for|check(?:ing)?\s+for|signs?\s+of|indicators?\s+of|evidence\s+of|red\s+flags?|examples?|e\.g\.|such\s+as|attempts?\s+to|designed\s+to|(?:code|scripts?|files?|comments?|text|instructions?)\s+that)\b/i;
+var TRANSMIT_VERB_RE = /\b(?:post|send|curl|transmit|exfiltrate)s?\b/i;
+function matchAnchor(line, match) {
+  if (match[0]) return match.index;
+  const verb = line.search(TRANSMIT_VERB_RE);
+  return verb < 0 ? line.length : verb;
+}
+function isMention(line, anchor, inFence) {
+  if (inFence || line.trimStart().startsWith("|")) return true;
+  const before = line.slice(0, anchor);
+  const inside = (mark) => (before.split(mark).length - 1) % 2 === 1;
+  return inside('"') || inside("`") || MENTION_LEAD_RE.test(before);
+}
+var FENCE_RE = /^\s*(?:```|~~~)/;
 var DOCUMENTED_PLACEHOLDERS = ["AKIAIOSFODNN7EXAMPLE", "AKIAI44QH8DHBEXAMPLE"];
 var withoutPlaceholders = (line) => DOCUMENTED_PLACEHOLDERS.reduce((l, p) => l.replaceAll(p, " "), line);
 var REDACTIONS = ALL_ROWS.filter((row2) => row2.redact).map(
@@ -16065,9 +16070,17 @@ var redactLine = (line) => REDACTIONS.reduce((l, re) => l.replace(re, "[redacted
 var contentRule = (pkg) => {
   const findings = [];
   for (const file2 of pkg.files) {
+    let inFence = false;
     file2.content.split("\n").forEach((rawLine, i2) => {
+      if (FENCE_RE.test(rawLine)) {
+        inFence = !inFence;
+        return;
+      }
       const line = withoutPlaceholders(rawLine);
-      const hits = ALL_ROWS.filter((row2) => row2.pattern.test(line));
+      const hits = ALL_ROWS.filter((row2) => {
+        const match = row2.pattern.exec(line);
+        return match !== null && !(row2.mentionAware && isMention(line, matchAnchor(line, match), inFence));
+      });
       if (hits.length === 0) return;
       const snippet = redactLine(line).trim();
       for (const row2 of hits) {
@@ -16225,10 +16238,23 @@ async function getParsed(fetchImpl, url2, schema) {
   try {
     body = await res.json();
   } catch {
-    return { ok: false, notFound: false, message: `unexpected response from the API (${res.status})` };
+    return {
+      ok: false,
+      notFound: false,
+      message: `unexpected response from the API (${res.status})`,
+      status: res.status
+    };
   }
   if (typeof body !== "object" || body === null || !("success" in body) || body.success !== true) {
-    return res.status === 404 ? { ok: false, notFound: true, message: "not found" } : { ok: false, notFound: false, message: `the API returned an error (${res.status})` };
+    const error51 = body?.error;
+    const apiError = typeof error51 === "string" ? { apiError: error51 } : {};
+    return res.status === 404 ? { ok: false, notFound: true, message: "not found", status: 404, ...apiError } : {
+      ok: false,
+      notFound: false,
+      message: `the API returned an error (${res.status})`,
+      status: res.status,
+      ...apiError
+    };
   }
   const parsed = schema.safeParse(body.data);
   if (!parsed.success) {
@@ -16458,10 +16484,7 @@ function renderPreflightReport(detail, preflight, st = PLAIN) {
     ...renderDiff(preflight.diff)
   ];
   if (preflight.blocked) {
-    lines.push(
-      "",
-      st.red(`BLOCKED: ${preflight.blockedReason ?? "this version cannot be downloaded"}`)
-    );
+    lines.push("", st.red(`BLOCKED: ${preflight.blockedReason ?? "this version cannot be downloaded"}`));
   }
   return lines;
 }
@@ -16484,37 +16507,39 @@ function renderDiff(diff) {
 // src/targets.ts
 import { homedir } from "node:os";
 import { join as join3, resolve } from "node:path";
-function installAreas(home = homedir()) {
-  return {
-    "claude-code": { project: join3(".claude", "skills"), global: join3(home, ".claude", "skills") },
-    codex: { project: join3(".agents", "skills") }
-  };
+var SHARED = { project: join3(".agents", "skills"), global: join3(".agents", "skills"), layout: "codex" };
+var INSTALL_TOOLS = {
+  "claude-code": { project: join3(".claude", "skills"), global: join3(".claude", "skills"), layout: "claude-code" },
+  agents: SHARED,
+  codex: SHARED,
+  cursor: SHARED,
+  windsurf: SHARED,
+  "github-copilot": SHARED,
+  "gemini-cli": SHARED,
+  opencode: SHARED,
+  cline: { project: join3(".cline", "skills"), global: join3(".cline", "skills"), layout: "codex" }
+};
+var INSTALL_TOOL_NAMES = Object.keys(INSTALL_TOOLS);
+function lookupTool(name) {
+  return Object.hasOwn(INSTALL_TOOLS, name) ? INSTALL_TOOLS[name] : void 0;
+}
+var MAPPED_TARGETS = TARGETS.filter((t) => lookupTool(t) !== void 0);
+function layoutTarget(tool) {
+  return lookupTool(tool)?.layout;
+}
+function declaresTool(declared, tool) {
+  const layout = layoutTarget(tool);
+  return declared.includes(tool) || layout !== void 0 && declared.includes(layout);
 }
-var MAPPED_TARGETS = Object.keys(installAreas());
 function resolveTargetArea(target, global = false, home) {
-  if (!TARGETS.includes(target)) {
-    return {
-      ok: false,
-      message: `unknown target "${target}" (known tools: ${TARGETS.join(", ")})`
-    };
-  }
-  const area = installAreas(home)[target];
-  if (!area) {
-    return {
-      ok: false,
-      message: `${target} has no standard skills folder yet; use --dir to pick a location`
-    };
-  }
-  if (global) {
-    if (!area.global) {
-      return {
-        ok: false,
-        message: `${target} has no user-level skills folder; install per project instead`
-      };
+  const tool = lookupTool(target);
+  if (!tool) {
+    if (TARGETS.includes(target)) {
+      return { ok: false, message: `${target} has no standard skills folder yet; use --dir to pick a location` };
     }
-    return { ok: true, dir: area.global };
+    return { ok: false, message: `unknown target "${target}" (known tools: ${INSTALL_TOOL_NAMES.join(", ")})` };
   }
-  return { ok: true, dir: area.project };
+  return { ok: true, dir: global ? join3(home ?? homedir(), tool.global) : tool.project };
 }
 function resolveTargetDir(target, slug, global = false, home) {
   const area = resolveTargetArea(target, global, home);
@@ -16524,24 +16549,48 @@ function mappableDeclaredTargets(declared) {
   return declared.filter((t) => MAPPED_TARGETS.includes(t));
 }
 function knownAreas(cwd, home) {
-  const areas = [];
-  const byTarget = installAreas(home);
-  for (const tool of MAPPED_TARGETS) {
-    const area = byTarget[tool];
-    if (!area) {
-      continue;
-    }
-    areas.push({
-      tool,
-      global: false,
-      label: `${tool} project (${area.project})`,
-      dir: resolve(cwd, area.project)
-    });
-    if (area.global) {
-      areas.push({ tool, global: true, label: `${tool} user (${area.global})`, dir: area.global });
+  const areas = /* @__PURE__ */ new Map();
+  for (const [name, tool] of Object.entries(INSTALL_TOOLS)) {
+    const scopes = [
+      { global: false, display: tool.project, dir: resolve(cwd, tool.project) },
+      { global: true, display: join3(home ?? homedir(), tool.global), dir: join3(home ?? homedir(), tool.global) }
+    ];
+    for (const scope of scopes) {
+      const existing = areas.get(scope.dir);
+      if (existing) {
+        if (!existing.tools.includes(name)) existing.tools.push(name);
+        existing.project ||= !scope.global;
+        existing.global ||= scope.global;
+        existing.label = areaLabel(existing);
+        continue;
+      }
+      const area = {
+        tools: [name],
+        layout: tool.layout,
+        project: !scope.global,
+        global: scope.global,
+        label: "",
+        dir: scope.dir
+      };
+      area.label = areaLabel(area, scope.display);
+      areas.set(scope.dir, area);
     }
   }
-  return areas;
+  return [...areas.values()];
+}
+function areaLabel(area, display) {
+  const shown = display ?? area.label.slice(0, area.label.indexOf(" ("));
+  const scopes = [...area.project ? ["project"] : [], ...area.global ? ["user"] : []].join(", ");
+  return `${shown} (${scopes}) - ${area.tools.join(", ")}`;
+}
+function resolveArea(target, global, cwd, home) {
+  const resolved = resolveTargetArea(target, global, home);
+  if (!resolved.ok) {
+    return resolved;
+  }
+  const dir = resolve(cwd, resolved.dir);
+  const area = knownAreas(cwd, home).find((a) => a.dir === dir);
+  return area ? { ok: true, area } : { ok: false, message: `no known skills area for ${target}` };
 }
 
 // src/add.ts
@@ -16623,54 +16672,26 @@ function writeTree(files, target) {
     throw err2;
   }
 }
-function installChoices(declared, slug) {
-  const choices = [];
-  const ordered = [
-    ...MAPPED_TARGETS.filter((t) => declared.includes(t)),
-    ...MAPPED_TARGETS.filter((t) => !declared.includes(t))
-  ];
-  for (const tool of ordered) {
-    const note = declared.includes(tool) ? "" : " - not declared by this skill";
-    const resolved = resolveTargetDir(tool, slug);
-    if (resolved.ok) {
-      choices.push({ label: `${tool} skills folder (${resolved.dir})${note}`, dir: resolved.dir });
-    }
-    const global = resolveTargetDir(tool, slug, true);
-    if (global.ok) {
-      choices.push({
-        label: `${tool} user-level skills folder (${global.dir})${note}`,
-        dir: global.dir
-      });
-    }
-  }
+function orderedAreas(declared, cwd, home) {
+  const areas = knownAreas(cwd, home).map((area) => ({
+    ...area,
+    declared: area.tools.some((tool) => declaresTool(declared, tool))
+  }));
+  return [...areas.filter((a) => a.declared), ...areas.filter((a) => !a.declared)];
+}
+function installChoices(declared, slug, cwd, home) {
+  const choices = orderedAreas(declared, cwd, home).map((area) => ({
+    label: `${area.label}${area.declared ? "" : " - not declared by this skill"}`,
+    dir: join4(area.dir, slug)
+  }));
   choices.push({ label: `current directory (./${slug})`, dir: slug });
   return choices;
 }
-function packChoices(declared, slug, count) {
-  const choices = [];
-  const ordered = [
-    ...MAPPED_TARGETS.filter((t) => declared.includes(t)),
-    ...MAPPED_TARGETS.filter((t) => !declared.includes(t))
-  ];
-  for (const tool of ordered) {
-    const note = declared.includes(tool) ? "" : " - not declared by this pack";
-    const project = resolveTargetArea(tool);
-    if (project.ok) {
-      choices.push({
-        label: `${tool} skills folder (${project.dir}) - ${count} skills${note}`,
-        tool,
-        global: false
-      });
-    }
-    const global = resolveTargetArea(tool, true);
-    if (global.ok) {
-      choices.push({
-        label: `${tool} user-level skills folder (${global.dir}) - ${count} skills${note}`,
-        tool,
-        global: true
-      });
-    }
-  }
+function packChoices(declared, slug, count, cwd, home) {
+  const choices = orderedAreas(declared, cwd, home).map((area) => ({
+    label: `${area.label} - ${count} skills${area.declared ? "" : " - not declared by this pack"}`,
+    area
+  }));
   choices.push({ label: `current directory (./${slug}, raw pack source)` });
   return choices;
 }
@@ -16685,23 +16706,20 @@ async function promptIndex(ask, count, push) {
 }
 async function choosePackLocation(ctx, detail, memberCount, prompt) {
   if (prompt) {
-    const choices = packChoices(detail.targets, ctx.slug, memberCount);
+    const choices = packChoices(detail.targets, ctx.slug, memberCount, ctx.cwd, ctx.home);
     ctx.push("", "Install location:");
     choices.forEach((choice, i2) => ctx.push(`  ${i2 + 1}) ${choice.label}`));
     const chosen = choices[await promptIndex(prompt, choices.length, ctx.push)];
-    return chosen.tool ? { tool: chosen.tool, global: chosen.global ?? false } : { dir: ctx.slug };
+    return chosen.area ? { area: chosen.area } : { dir: ctx.slug };
   }
   const mappable = mappableDeclaredTargets(detail.targets);
   if (mappable.length > 0) {
-    ctx.push(
-      "",
-      `tip: --target ${mappable[0]} installs the ${memberCount} skills into the tool's skills folder`
-    );
+    ctx.push("", `tip: --target ${mappable[0]} installs the ${memberCount} skills into the tool's skills folder`);
   }
   return { dir: ctx.slug };
 }
 async function chooseSingleLocation(ctx, detail, prompt) {
-  const choices = installChoices(detail.targets, ctx.slug);
+  const choices = installChoices(detail.targets, ctx.slug, ctx.cwd, ctx.home);
   if (prompt && choices.length > 1) {
     ctx.push("", "Install location:");
     choices.forEach((choice, i2) => ctx.push(`  ${i2 + 1}) ${choice.label}`));
@@ -16713,20 +16731,15 @@ async function chooseSingleLocation(ctx, detail, prompt) {
   }
   return ctx.slug;
 }
-async function installPack(ctx, members, tool, global) {
+async function installPack(ctx, members, targets) {
   const { push, done, slug, preflight } = ctx;
-  const area = resolveTargetArea(tool, global);
-  if (!area.ok) {
-    push("", `error: ${area.message}`);
+  const resolved = targets.map(({ area, tool }) => ({ area, tool, ...resolvePackMembers(members, area.layout) }));
+  const unsupported = resolved.find((r) => r.installs.length === 0);
+  if (unsupported) {
+    push("", `error: none of this pack's skills support ${unsupported.tool}`);
     return done(2);
   }
-  const { installs, skipped } = resolvePackMembers(members, tool);
-  if (installs.length === 0) {
-    push("", `error: none of this pack's skills support ${tool}`);
-    return done(2);
-  }
-  const areaAbs = resolve2(ctx.cwd, area.dir);
-  const conflicts = installs.map((m) => join4(areaAbs, m.name)).filter(isOccupied);
+  const conflicts = resolved.flatMap((r) => r.installs.map((m) => join4(r.area.dir, m.name))).filter(isOccupied);
   if (conflicts.length > 0) {
     push(
       "",
@@ -16740,41 +16753,47 @@ async function installPack(ctx, members, tool, global) {
     push("", `error: ${download.message}`);
     return done(2);
   }
-  const plans = planMembers(installs, download.files);
-  const missing = plans.find((p) => p.files.length === 0);
+  const planned = resolved.map((r) => ({ ...r, plans: planMembers(r.installs, download.files) }));
+  const missing = planned.flatMap((r) => r.plans).find((p) => p.files.length === 0);
   if (missing) {
     push("", `error: the snapshot has no files for "${missing.name}"; nothing was installed`);
     return done(2);
   }
-  for (const name of skipped) {
-    push("", `note: ${name} does not support ${tool}; skipped`);
+  for (const r of planned) {
+    for (const name of r.skipped) {
+      push("", `note: ${name} does not support ${r.tool}; skipped`);
+    }
   }
-  const written = [];
-  try {
-    for (const plan of plans) {
-      writeTree(plan.files, join4(areaAbs, plan.name));
-      written.push(plan.name);
-      recordReceipt(areaAbs, plan.name, receiptFor(preflight, slug));
+  const landed = [];
+  const describe3 = (dir, names) => planned.length > 1 ? `${dir}: ${names.join(", ")}` : names.join(", ");
+  for (const r of planned) {
+    const written = [];
+    try {
+      for (const plan of r.plans) {
+        writeTree(plan.files, join4(r.area.dir, plan.name));
+        written.push(plan.name);
+        recordReceipt(r.area.dir, plan.name, receiptFor(preflight, slug));
+      }
+    } catch {
+      const before = [...landed, ...written.length > 0 ? [describe3(r.area.dir, written)] : []];
+      const where = planned.length > 1 ? ` in ${r.area.dir}` : "";
+      push(
+        "",
+        `error: could not write ${r.plans[written.length].name}${where}; installed before the failure: ${before.join("; ") || "none"}`
+      );
+      return done(2);
     }
-  } catch {
-    push(
-      "",
-      `error: could not write ${plans[written.length].name}; installed before the failure: ${written.join(", ") || "none"}`
-    );
-    return done(2);
+    landed.push(describe3(r.area.dir, written));
+    push("", `Installed ${written.length} skills to ${r.area.dir}`, `  ${written.join(", ")}`);
   }
-  push(
-    "",
-    `Installed ${written.length} skills to ${areaAbs}`,
-    `  ${written.join(", ")}`,
-    "Source hash verified against the Skill Passport."
-  );
+  push("Source hash verified against the Skill Passport.");
   return done(0);
 }
-async function installSingle(ctx, targetDir) {
+async function installSingle(ctx, targetDirs) {
   const { push, done, slug, preflight } = ctx;
-  const target = resolve2(ctx.cwd, targetDir);
-  if (existsSync2(target)) {
+  const targets = targetDirs.map((dir) => resolve2(ctx.cwd, dir));
+  for (const target of targets) {
+    if (!existsSync2(target)) continue;
     if (!statSync3(target).isDirectory()) {
       push("", `error: target ${target} already exists and is not a directory`);
       return done(2);
@@ -16789,33 +16808,40 @@ async function installSingle(ctx, targetDir) {
     push("", `error: ${download.message}`);
     return done(2);
   }
-  try {
-    writeTree(download.files, target);
-  } catch {
-    push("", "error: could not write the install; nothing was installed");
-    return done(2);
-  }
-  const area = knownAreas(ctx.cwd).find((a) => a.dir === dirname(target));
-  if (area) {
-    recordReceipt(area.dir, slug, receiptFor(preflight));
+  const areas = knownAreas(ctx.cwd, ctx.home);
+  const landed = [];
+  for (const target of targets) {
+    try {
+      writeTree(download.files, target);
+    } catch {
+      push(
+        "",
+        landed.length === 0 ? "error: could not write the install; nothing was installed" : `error: could not write ${target}; installed before the failure: ${landed.join(", ")}`
+      );
+      return done(2);
+    }
+    landed.push(target);
+    const area = areas.find((a) => a.dir === dirname(target));
+    if (area) {
+      recordReceipt(area.dir, slug, receiptFor(preflight));
+    }
+    push("", `Installed ${download.files.length} file(s) to ${target}`);
   }
-  push(
-    "",
-    `Installed ${download.files.length} file(s) to ${target}`,
-    "Source hash verified against the Skill Passport."
-  );
+  push("Source hash verified against the Skill Passport.");
   return done(0);
 }
 async function runAdd(ref, opts = {}) {
   const { push, done } = createOutput(opts.emit);
-  if (opts.target && opts.dir) {
+  const tools = [...new Set([opts.target ?? []].flat())];
+  if (tools.length > 0 && opts.dir) {
     push(TARGET_OR_DIR);
     return done(2);
   }
-  if (opts.global && !opts.target) {
+  if (opts.global && tools.length === 0) {
     push(GLOBAL_NEEDS_TARGET);
     return done(2);
   }
+  const cwd = opts.cwd ?? process.cwd();
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
   const apiUrl = resolveApiUrl(opts.apiUrl);
   const fetched = await fetchPreflight(fetchImpl, apiUrl, ref);
@@ -16830,21 +16856,21 @@ async function runAdd(ref, opts = {}) {
   }
   const members = detail.packMembers ?? [];
   const isPack = members.length > 0;
-  let targetDir = opts.dir;
-  let pack;
-  if (opts.target) {
-    const resolved = isPack ? resolveTargetArea(opts.target, opts.global) : resolveTargetDir(opts.target, slug, opts.global);
+  const targets = [];
+  for (const tool of tools) {
+    const resolved = resolveArea(tool, opts.global ?? false, cwd, opts.home);
     if (!resolved.ok) {
       push("", `error: ${resolved.message}`);
       return done(2);
     }
-    if (isPack) {
-      pack = { tool: opts.target, global: opts.global ?? false };
-    } else {
-      targetDir = resolved.dir;
+    const shared = targets.find((t) => t.area.dir === resolved.area.dir);
+    if (shared) {
+      push("", `note: ${tool} and ${shared.tool} share ${resolved.area.dir}; installing once`);
+      continue;
     }
-    if (!detail.targets.includes(opts.target)) {
-      push("", `warning: this skill does not declare ${opts.target} as a target`);
+    targets.push({ area: resolved.area, tool });
+    if (!declaresTool(detail.targets, tool)) {
+      push("", `warning: this skill does not declare ${tool} as a target`);
     }
   }
   const confirmed = await confirmRisk(
@@ -16855,30 +16881,28 @@ async function runAdd(ref, opts = {}) {
     push
   );
   if (!confirmed) return done(2);
-  const ctx = {
-    push,
-    done,
-    fetchImpl,
-    apiUrl,
-    cwd: opts.cwd ?? process.cwd(),
-    slug,
-    preflight
-  };
-  if (isPack && pack === void 0 && targetDir === void 0) {
-    const location = await choosePackLocation(ctx, detail, members.length, opts.promptImpl);
-    if ("tool" in location) pack = location;
-    else targetDir = location.dir;
-  }
-  if (pack !== void 0) {
-    return installPack(ctx, members, pack.tool, pack.global);
-  }
-  if (isPack && opts.dir) {
+  const ctx = { push, done, fetchImpl, apiUrl, cwd, home: opts.home, slug, preflight };
+  if (isPack) {
+    if (targets.length > 0) {
+      return installPack(ctx, members, targets);
+    }
+    if (opts.dir === void 0) {
+      const location = await choosePackLocation(ctx, detail, members.length, opts.promptImpl);
+      return "area" in location ? installPack(ctx, members, [{ area: location.area, tool: location.area.tools[0] }]) : installSingle(ctx, [location.dir]);
+    }
     push(
       "",
       `note: --dir installs the raw pack source; --target <tool> installs the ${members.length} skills individually`
     );
+    return installSingle(ctx, [opts.dir]);
   }
-  return installSingle(ctx, targetDir ?? await chooseSingleLocation(ctx, detail, opts.promptImpl));
+  if (targets.length > 0) {
+    return installSingle(
+      ctx,
+      targets.map((t) => join4(t.area.dir, slug))
+    );
+  }
+  return installSingle(ctx, [opts.dir ?? await chooseSingleLocation(ctx, detail, opts.promptImpl)]);
 }
 
 // src/list.ts
@@ -16923,11 +16947,7 @@ async function identifyByHash(fetchImpl, apiUrl, slug, dir) {
   } catch {
     return void 0;
   }
-  const detail = await getParsed(
-    fetchImpl,
-    `${apiUrl}/skills/${encodeURIComponent(slug)}`,
-    publicSkillDetailSchema
-  );
+  const detail = await getParsed(fetchImpl, `${apiUrl}/skills/${encodeURIComponent(slug)}`, publicSkillDetailSchema);
   if (!detail.ok) {
     return void 0;
   }
@@ -16972,9 +16992,7 @@ async function runOutdated(opts = {}) {
         }
         seenPacks.add(receipt.pack.slug);
         tracked += 1;
-        const members = Object.values(receipts).filter(
-          (r) => r.pack?.slug === receipt.pack?.slug
-        ).length;
+        const members = Object.values(receipts).filter((r) => r.pack?.slug === receipt.pack?.slug).length;
         const latest = latestBySlug.get(receipt.pack.slug)?.version;
         if (latest === void 0) {
           rows.push(`  ${receipt.pack.slug}  ${receipt.pack.version}  not in the directory`);
@@ -16982,9 +17000,7 @@ async function runOutdated(opts = {}) {
           rows.push(`  ${receipt.pack.slug}  ${receipt.pack.version}  current (pack, ${members} skills)`);
         } else {
           outdatedCount += 1;
-          rows.push(
-            `  ${receipt.pack.slug}  ${receipt.pack.version} -> ${latest}  (pack, ${members} skills)`
-          );
+          rows.push(`  ${receipt.pack.slug}  ${receipt.pack.version} -> ${latest}  (pack, ${members} skills)`);
         }
         continue;
       }
@@ -17060,7 +17076,7 @@ function runRemove(slug, opts = {}) {
   if (!opts.dir) {
     let areas = knownAreas(cwd, opts.home);
     if (opts.target) {
-      areas = areas.filter((a) => a.tool === opts.target && a.global === (opts.global ?? false));
+      areas = areas.filter((a) => a.tools.includes(opts.target) && (opts.global ? a.global : a.project));
     }
     const packHits = areas.map((area) => ({
       area,
@@ -17082,10 +17098,7 @@ function runRemove(slug, opts = {}) {
         removeReceipt(area.dir, name);
       }
       return {
-        lines: [
-          `Removed pack ${slug} (${members.length} skills) from ${area.dir}`,
-          `  ${members.sort().join(", ")}`
-        ],
+        lines: [`Removed pack ${slug} (${members.length} skills) from ${area.dir}`, `  ${members.sort().join(", ")}`],
         exitCode: 0
       };
     }
@@ -17100,9 +17113,7 @@ function runRemove(slug, opts = {}) {
   } else if (opts.dir) {
     dir = resolve3(cwd, opts.dir);
   } else {
-    const found = candidateDirs(slug, cwd, opts.home).filter(
-      (candidate) => existsSync4(candidate)
-    );
+    const found = candidateDirs(slug, cwd, opts.home).filter((candidate) => existsSync4(candidate));
     if (found.length === 0) {
       return { lines: [`error: ${slug} is not installed in any known location`], exitCode: 2 };
     }
@@ -17221,25 +17232,23 @@ async function runSearch(opts = {}) {
   }
   if (opts.category && !CATEGORY_SLUGS.includes(opts.category)) {
     return {
-      lines: [
-        `error: unknown category "${opts.category}" (known categories: ${CATEGORY_SLUGS.join(", ")})`
-      ],
+      lines: [`error: unknown category "${opts.category}" (known categories: ${CATEGORY_SLUGS.join(", ")})`],
       exitCode: 2
     };
   }
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
   const apiUrl = resolveApiUrl(opts.apiUrl);
+  if (opts.ai) {
+    return runAiSearch(opts, fetchImpl, apiUrl);
+  }
   const fetched = await getParsed(fetchImpl, `${apiUrl}/skills`, publicSkillListSchema);
   if (!fetched.ok) {
     return { lines: [`error: ${fetched.message}`], exitCode: 2 };
   }
   const query = (opts.query ?? "").trim().toLowerCase();
-  const matches = fetched.data.filter((skill) => {
-    if (opts.target && !skill.targets.includes(opts.target)) return false;
-    if (opts.category && (skill.category ?? null) !== opts.category) return false;
-    if (opts.packs && (skill.packSkills?.length ?? 0) === 0) return false;
-    return query === "" || matchesQuery(skill, query);
-  });
+  const matches = fetched.data.filter(
+    (skill) => matchesFilters(skill, opts) && (query === "" || matchesQuery(skill, query))
+  );
   if (opts.json) {
     return { lines: [JSON.stringify(matches, null, 2)], exitCode: 0 };
   }
@@ -17251,9 +17260,53 @@ async function runSearch(opts = {}) {
     lines: [
       ...renderRows(matches, opts.width, st),
       "",
-      st.dim(
-        `${matches.length} of ${fetched.data.length} skills - skillpass report <slug> shows the passport`
-      )
+      st.dim(`${matches.length} of ${fetched.data.length} skills - skillpass report <slug> shows the passport`)
+    ],
+    exitCode: 0
+  };
+}
+function matchesFilters(skill, opts) {
+  if (opts.target && !skill.targets.includes(opts.target)) return false;
+  if (opts.category && (skill.category ?? null) !== opts.category) return false;
+  if (opts.packs && (skill.packSkills?.length ?? 0) === 0) return false;
+  return true;
+}
+var AI_ERRORS = {
+  429: "AI search is rate limited (20 requests a minute per address); try again in a moment",
+  503: "AI search is not configured on this API",
+  502: "AI search is temporarily unavailable; try again shortly"
+};
+function aiErrorMessage(outcome) {
+  if (outcome.status !== void 0 && AI_ERRORS[outcome.status]) return AI_ERRORS[outcome.status];
+  if (outcome.status === 400 && outcome.apiError) return outcome.apiError;
+  return outcome.message;
+}
+async function runAiSearch(opts, fetchImpl, apiUrl) {
+  const query = (opts.query ?? "").trim();
+  if (query === "") {
+    return { lines: ["error: search --ai needs a query (describe what you need)"], exitCode: 2 };
+  }
+  const fetched = await getParsed(
+    fetchImpl,
+    `${apiUrl}/skills/search?q=${encodeURIComponent(query)}`,
+    publicSkillListSchema
+  );
+  if (!fetched.ok) {
+    return { lines: [`error: ${aiErrorMessage(fetched)}`], exitCode: 2 };
+  }
+  const matches = fetched.data.filter((skill) => matchesFilters(skill, opts));
+  if (opts.json) {
+    return { lines: [JSON.stringify(matches, null, 2)], exitCode: 0 };
+  }
+  if (matches.length === 0) {
+    return { lines: ["No skills match by meaning - try other words"], exitCode: 0 };
+  }
+  const st = opts.style ?? PLAIN;
+  return {
+    lines: [
+      ...renderRows(matches, opts.width, st),
+      "",
+      st.dim(`${matches.length} skills by meaning - skillpass report <slug> shows the passport`)
     ],
     exitCode: 0
   };
@@ -17266,7 +17319,7 @@ async function locate(slug, opts, fetchImpl, apiUrl) {
   const cwd = opts.cwd ?? process.cwd();
   let areas = knownAreas(cwd, opts.home);
   if (opts.target) {
-    areas = areas.filter((a) => a.tool === opts.target && a.global === (opts.global ?? false));
+    areas = areas.filter((a) => a.tools.includes(opts.target) && (opts.global ? a.global : a.project));
   }
   const hits = [];
   for (const area of areas) {
@@ -17337,9 +17390,7 @@ async function runUpdate(ref, opts = {}) {
   const hits = await locate(slug, opts, fetchImpl, apiUrl);
   const memberHit = hits.find((h) => h.packSlug !== void 0 && h.packSlug !== slug);
   if (memberHit?.packSlug !== void 0) {
-    push(
-      `error: ${slug} is part of the ${memberHit.packSlug} pack; run skillpass update ${memberHit.packSlug}`
-    );
+    push(`error: ${slug} is part of the ${memberHit.packSlug} pack; run skillpass update ${memberHit.packSlug}`);
     return done(2);
   }
   if (hits.length === 0) {
@@ -17411,9 +17462,7 @@ async function changesVsInstalled(fetchImpl, apiUrl, slug, installed, target, st
     publicPreflightSchema
   );
   if (!before.ok) {
-    return [
-      `Changes vs installed v${installed.installedVersion}: unavailable (that version is no longer published)`
-    ];
+    return [`Changes vs installed v${installed.installedVersion}: unavailable (that version is no longer published)`];
   }
   const { added, removed } = permissionChanges(before.data.permissions, target.permissions);
   if (added.length === 0 && removed.length === 0) {
@@ -17448,9 +17497,10 @@ async function runPackUpdate(slug, installed, detail, preflight, opts, fetchImpl
   );
   if (!confirmed) return done(2);
   const areaDir = installed.area.dir;
-  const { installs, skipped } = resolvePackMembers(detail.packMembers ?? [], installed.area.tool);
+  const tool = opts.target ?? installed.area.tools[0];
+  const { installs, skipped } = resolvePackMembers(detail.packMembers ?? [], installed.area.layout);
   if (installs.length === 0) {
-    push("", `error: none of the new version's skills support ${installed.area.tool}`);
+    push("", `error: none of the new version's skills support ${tool}`);
     return done(2);
   }
   const receipts = readReceipts(areaDir);
@@ -17479,7 +17529,7 @@ async function runPackUpdate(slug, installed, detail, preflight, opts, fetchImpl
     return done(2);
   }
   for (const name of skipped) {
-    push("", `note: ${name} does not support ${installed.area.tool}; skipped`);
+    push("", `note: ${name} does not support ${tool}; skipped`);
   }
   const done1 = [];
   try {
@@ -17560,11 +17610,11 @@ var USAGE = [
   "skillpass - validate AI agent skills locally and inspect hosted passports",
   "",
   "Usage:",
-  "  skillpass search [query] [--target <tool>] [--category <slug>] [--packs] [--json]",
+  "  skillpass search [query] [--ai] [--target <tool>] [--category <slug>] [--packs] [--json]",
   "                                             find skills in the directory",
   "  skillpass scan <path> [--json]              run the validator on a local skill package",
   "  skillpass report <slug>[@version] [--json]  fetch the hosted passport pre-flight",
-  "  skillpass add <slug>[@version] [--target <tool> [--global] | --dir <path>] [--yes]",
+  "  skillpass add <slug>[@version] [--target <tool>... [--global] | --dir <path>] [--yes]",
   "                                             install a skill through the pre-flight gate",
   "  skillpass remove <slug> [--target <tool> [--global] | --dir <path>]",
   "                                             remove an installed skill",
@@ -17575,11 +17625,15 @@ var USAGE = [
   "",
   "Flags:",
   "  --json    print machine-readable JSON instead of the readable report",
-  "  --target  install into a tool's skills folder: claude-code (.claude/skills),",
-  "            codex (.agents/skills)",
-  "  --global  with --target claude-code, install to ~/.claude/skills instead",
+  "  --target  a tool's skills folder: claude-code, cline, or agents (the shared",
+  "            .agents/skills read by codex, cursor, windsurf, github-copilot,",
+  "            gemini-cli, and opencode; those names work too). add takes it more",
+  "            than once to install into several tools",
+  "  --global  with --target, use the tool's user-level folder (~/.claude/skills,",
+  "            ~/.agents/skills, ~/.cline/skills)",
   "  --dir     install target directory (default ./<slug>)",
   "  --yes     skip the confirmation prompt for medium+ risk skills",
+  "  --ai      search by meaning: describe what you need (needs a query)",
   "  --category  search filter: a directory category slug",
   "  --packs   search filter: multi-skill packs only",
   "  --version print the CLI version",
@@ -17597,7 +17651,7 @@ var COMMAND_FLAGS = {
   list: [],
   outdated: [],
   update: ["--yes", "--target", "--global"],
-  search: ["--target", "--category", "--packs", "--json"]
+  search: ["--ai", "--target", "--category", "--packs", "--json"]
 };
 function parseCliArgs(argv) {
   const parsed = {
@@ -17608,6 +17662,7 @@ function parseCliArgs(argv) {
     yes: false,
     global: false,
     packs: false,
+    ai: false,
     seen: []
   };
   for (let i2 = 0; i2 < argv.length; i2++) {
@@ -17624,6 +17679,9 @@ function parseCliArgs(argv) {
     } else if (arg === "--packs") {
       parsed.packs = true;
       parsed.seen.push(arg);
+    } else if (arg === "--ai") {
+      parsed.ai = true;
+      parsed.seen.push(arg);
     } else if (arg === "--dir" || arg === "--target" || arg === "--category") {
       parsed.seen.push(arg);
       const value = argv[i2 + 1];
@@ -17634,7 +17692,7 @@ function parseCliArgs(argv) {
         if (arg === "--dir") {
           parsed.dir = value;
         } else if (arg === "--target") {
-          parsed.target = value;
+          parsed.targets = [.../* @__PURE__ */ new Set([...parsed.targets ?? [], value])];
         } else {
           parsed.category = value;
         }
@@ -17684,12 +17742,17 @@ async function run(argv) {
   if (disallowed) {
     return { lines: [`error: ${args.command} does not take ${disallowed}`, "", USAGE], exitCode: 2 };
   }
+  const target = args.targets?.[0];
+  if (args.command !== "add" && (args.targets?.length ?? 0) > 1) {
+    return { lines: [`error: ${args.command} takes one --target`, "", USAGE], exitCode: 2 };
+  }
   if (args.command === "search") {
     return runSearch({
       query: args.positional.join(" "),
-      target: args.target,
+      target,
       category: args.category,
       packs: args.packs,
+      ai: args.ai,
       json: args.json,
       width: process.stdout.isTTY ? process.stdout.columns : void 0,
       style: styler(Boolean(process.stdout.isTTY))
@@ -17707,7 +17770,7 @@ async function run(argv) {
     if (!slug) {
       return { lines: ["error: remove needs a skill slug", "", USAGE], exitCode: 2 };
     }
-    return runRemove(slug, { target: args.target, dir: args.dir, global: args.global });
+    return runRemove(slug, { target, dir: args.dir, global: args.global });
   }
   if (args.command === "list") {
     if (args.positional.length > 0) {
@@ -17723,7 +17786,7 @@ async function run(argv) {
     const tty = Boolean(process.stdin.isTTY);
     return runUpdate(ref, {
       yes: args.yes,
-      target: args.target,
+      target,
       global: args.global,
       style: styler(Boolean(process.stdout.isTTY)),
       confirmImpl: tty ? confirmViaTty : void 0,
@@ -17752,7 +17815,7 @@ async function run(argv) {
     return runAdd(ref, {
       yes: args.yes,
       dir: args.dir,
-      target: args.target,
+      target: args.targets,
       global: args.global,
       style: styler(Boolean(process.stdout.isTTY)),
       confirmImpl: tty ? confirmViaTty : void 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillpass",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Validation-first installer for AI agent skills: search the SkillPass directory, inspect a skill's passport, and install hash-verified skills and packs for Claude Code, Codex, and more.",
   "keywords": [
     "ai",