@drunkcoding/agents-and-skills 0.0.33 → 0.0.35

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "tech-graph",
       "source": "./plugins/tech-graph",
       "description": "6-step wizard for technical diagrams (SVG/PNG) via fireworks-tech-graph",
-      "version": "0.0.33",
+      "version": "0.0.35",
       "category": "diagram",
       "keywords": [
         "diagram",
@@ -26,7 +26,7 @@
       "name": "html-effectiveness",
       "source": "./plugins/html-effectiveness",
       "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
-      "version": "0.0.33",
+      "version": "0.0.35",
       "category": "reports",
       "keywords": [
         "html",
@@ -41,7 +41,7 @@
       "name": "plugin-validator",
       "source": "./plugins/plugin-validator",
       "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
-      "version": "0.0.33",
+      "version": "0.0.35",
       "category": "tooling",
       "keywords": [
         "validation",
@@ -57,7 +57,7 @@
       "name": "team-share",
       "source": "./plugins/team-share",
       "description": "Onboard your team with an interactive setup menu: install CodeGraph, build the Understand-Anything knowledge graph, and share Claude Code settings — run any combination, all idempotent.",
-      "version": "0.0.33",
+      "version": "0.0.35",
       "category": "tooling",
       "keywords": [
         "onboarding",
@@ -73,7 +73,7 @@
       "name": "multica-tool",
       "source": "./plugins/multica-tool",
       "description": "Export, import, and sync Multica skills, agents, and squads between workspaces.",
-      "version": "0.0.33",
+      "version": "0.0.35",
       "category": "workflow",
       "keywords": [
         "multica",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "Personal collection of Claude Code skills and agents, installable via `npx skills`.",
   "keywords": [
     "claude-code",

package/plugins/html-effectiveness/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "html-effectiveness",
   "displayName": "HTML Effectiveness Reports",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
   "author": {
     "name": "Steven Hoang"

package/plugins/multica-tool/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "multica-tool",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "Export, import, and sync Multica skills, agents, and squads between workspaces via the multica CLI."
 }

package/plugins/multica-tool/scripts/lib.mjs

@@ -84,7 +84,7 @@ export function getAgent(cli, id) {
 
 export function getSquad(cli, id) {
   const s = cli.json(["squad", "get", id]);
-  return { id: s.id, name: s.name, description: s.description, leaderId: s.leader_id };
+  return { id: s.id, name: s.name, description: s.description, instructions: s.instructions, leaderId: s.leader_id };
 }
 
 export const getSquadMembers = (cli, id) =>

package/plugins/multica-tool/scripts/multica-export.mjs

@@ -1,5 +1,6 @@
 import * as nodeFs from "node:fs";
-import { slugify, getSkill, getAgent, getSquad, getSquadMembers, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+import { dirname } from "node:path";
+import { slugify, getSkill, getAgent, getSquad, getSquadMembers, listRuntimes, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
 
 const nonEmpty = (v) => v && typeof v === "object" && Object.keys(v).length > 0;
 
@@ -23,8 +24,8 @@ export function buildManifest({ scope, sourceWorkspaceId, skills, agents, squad
     scope,
     sourceWorkspaceId,
     skills: [...seenSkills.values()].map((s) => ({ name: s.name, dir: `skills/${slugify(s.name)}`, sourceId: s.sourceId })),
-    agents: [...seenAgents.values()].map((a) => ({ name: a.name, file: `agents/${slugify(a.name)}.json`, sourceRuntimeId: a.sourceRuntimeId, skillNames: a.skillNames, hadSecrets: !!a.hadSecrets })),
-    squads: squad ? [{ name: squad.name, file: `squads/${slugify(squad.name)}.json`, description: squad.description ?? "", leaderName: squad.leaderName, members: squad.members }] : [],
+    agents: [...seenAgents.values()].map((a) => ({ name: a.name, file: `agents/${slugify(a.name)}.json`, sourceRuntimeId: a.sourceRuntimeId, sourceRuntimeProvider: a.sourceRuntimeProvider ?? null, skillNames: a.skillNames, hadSecrets: !!a.hadSecrets })),
+    squads: squad ? [{ name: squad.name, file: `squads/${slugify(squad.name)}.json`, description: squad.description ?? "", instructions: squad.instructions ?? "", leaderName: squad.leaderName, members: squad.members }] : [],
   };
 }
 
@@ -36,9 +37,10 @@ function collectSkill(cli, id, skills) {
 
 // Keyed by agent id (so squad leaderId/memberId resolve to names). Stores the
 // normalized agent, its redaction result, and its skill names.
-function collectAgent(cli, id, agentsById, skills) {
+function collectAgent(cli, id, agentsById, skills, providerById) {
   if (agentsById.has(id)) return agentsById.get(id);
   const a = getAgent(cli, id);
+  a.sourceRuntimeProvider = providerById.get(a.runtimeId) ?? null;
   const skillNames = a.skills.map((sk) => collectSkill(cli, sk.id, skills));
   const red = redactAgent(a);
   const entry = { raw: a, red, skillNames };
@@ -50,18 +52,23 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
   const skills = new Map();       // name -> normalized skill
   const agentsById = new Map();   // id   -> { raw, red, skillNames }
   let squad = null;
+  // Lazy + memoized: only fetched when an agent is actually collected (skips
+  // the extra CLI call on skill-only exports).
+  let providerById = null;
+  const getProviderById = () => providerById ??= new Map(listRuntimes(cli).map((r) => [r.id, r.provider]));
 
   if (scope === "skill") collectSkill(cli, ids.skillId, skills);
-  if (scope === "agent") collectAgent(cli, ids.agentId, agentsById, skills);
+  if (scope === "agent") collectAgent(cli, ids.agentId, agentsById, skills, getProviderById());
   if (scope === "squad") {
     const sq = getSquad(cli, ids.squadId);
     const members = getSquadMembers(cli, ids.squadId).filter((m) => m.memberType === "agent");
-    for (const m of members) collectAgent(cli, m.memberId, agentsById, skills);
-    if (!agentsById.has(sq.leaderId)) collectAgent(cli, sq.leaderId, agentsById, skills);
+    for (const m of members) collectAgent(cli, m.memberId, agentsById, skills, getProviderById());
+    if (!agentsById.has(sq.leaderId)) collectAgent(cli, sq.leaderId, agentsById, skills, getProviderById());
     const nameOf = (id) => agentsById.get(id)?.raw.name;
     squad = {
       name: sq.name,
       description: sq.description,
+      instructions: sq.instructions,
       leaderName: nameOf(sq.leaderId),
       members: members.map((m) => ({ agentName: nameOf(m.memberId), role: m.role })),
     };
@@ -70,7 +77,7 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
   const manifest = buildManifest({
     scope, sourceWorkspaceId,
     skills: [...skills.values()].map((s) => ({ name: s.name, sourceId: s.id })),
-    agents: [...agentsById.values()].map((a) => ({ name: a.raw.name, sourceRuntimeId: a.raw.runtimeId, skillNames: a.skillNames, hadSecrets: a.red.hadSecrets })),
+    agents: [...agentsById.values()].map((a) => ({ name: a.raw.name, sourceRuntimeId: a.raw.runtimeId, sourceRuntimeProvider: a.raw.sourceRuntimeProvider, skillNames: a.skillNames, hadSecrets: a.red.hadSecrets })),
     squad,
   });
 
@@ -83,7 +90,11 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(`${dir}/SKILL.md`, s.content ?? "");
     fs.writeFileSync(`${dir}/config.json`, JSON.stringify(s.config ?? {}, null, 2));
-    for (const f of s.files ?? []) fs.writeFileSync(`${dir}/${f.path}`, f.content ?? "");
+    for (const f of s.files ?? []) {
+      const target = `${dir}/${f.path}`;
+      fs.mkdirSync(dirname(target), { recursive: true }); // f.path may be nested, e.g. scripts/foo.sh
+      fs.writeFileSync(target, f.content ?? "");
+    }
   }
   // Index agent entries by name for the manifest writing loop.
   const agentByName = new Map([...agentsById.values()].map((a) => [a.raw.name, a]));

package/plugins/multica-tool/scripts/multica-import.mjs

@@ -1,5 +1,25 @@
 import * as nodeFs from "node:fs";
-import { listSkills, listAgents, listSquads, findByName, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+import { listSkills, listAgents, listSquads, listRuntimes, getSquadMembers, findByName, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+
+// Relative paths of every file under root (recursing into subdirs like scripts/).
+function walkSkillFiles(fs, root, rel = "") {
+  const out = [];
+  for (const ent of fs.readdirSync(rel ? `${root}/${rel}` : root, { withFileTypes: true })) {
+    const r = rel ? `${rel}/${ent.name}` : ent.name;
+    if (ent.isDirectory()) out.push(...walkSkillFiles(fs, root, r));
+    else out.push(r);
+  }
+  return out;
+}
+
+// Pull `description:` out of a SKILL.md YAML frontmatter block.
+// ponytail: single-line values only (the skill frontmatter convention); folded/multi-line YAML not handled.
+function frontmatterDescription(text) {
+  const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!block) return "";
+  const line = block[1].split(/\r?\n/).find((l) => /^description\s*:/.test(l));
+  return line ? line.replace(/^description\s*:/, "").trim().replace(/^["']|["']$/g, "") : "";
+}
 
 export function importSkills({ cli, manifest, dir, fs = nodeFs }) {
   const idMap = new Map();
@@ -12,19 +32,24 @@ export function importSkills({ cli, manifest, dir, fs = nodeFs }) {
     const configPath = `${sdir}/config.json`;
     const config = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "{}";
     const match = findByName(existing, s.name);
+    // Fall back to the SKILL.md frontmatter description when the manifest carries none.
+    const fmDesc = frontmatterDescription(fs.readFileSync(contentPath, "utf8"));
     let id;
     if (match) {
-      cli.run(["skill", "update", match.id, "--content-file", contentPath, "--config", config]);
+      // Only fill description when the existing skill has none — don't clobber a set one.
+      const desc = !match.description && fmDesc ? ["--description", fmDesc] : [];
+      cli.run(["skill", "update", match.id, "--content-file", contentPath, "--config", config, ...desc]);
       id = match.id; updated++;
     } else {
-      const out = cli.run(["skill", "create", "--name", s.name, "--content-file", contentPath, "--config", config]);
+      const desc = fmDesc ? ["--description", fmDesc] : [];
+      const out = cli.run(["skill", "create", "--name", s.name, "--content-file", contentPath, "--config", config, ...desc]);
       id = JSON.parse(out).id; created++;
     }
     idMap.set(s.name, id);
-    // upsert extra files (everything except SKILL.md and config.json)
-    for (const f of fs.readdirSync(sdir)) {
-      if (f === "SKILL.md" || f === "config.json") continue;
-      cli.run(["skill", "files", "upsert", id, "--path", f, "--content-file", `${sdir}/${f}`]);
+    // upsert extra files (everything except SKILL.md and config.json), by relative path
+    for (const rel of walkSkillFiles(fs, sdir)) {
+      if (rel === "SKILL.md" || rel === "config.json") continue;
+      cli.run(["skill", "files", "upsert", id, "--path", rel, "--content-file", `${sdir}/${rel}`]);
     }
   }
   return { idMap, created, updated };
@@ -70,16 +95,21 @@ export function importSquad({ cli, squad, agentIdMap }) {
   const leaderId = agentIdMap.get(squad.leaderName);
   const match = findByName(existing, squad.name);
   let id, created = 0, updated = 0;
+  const instr = squad.instructions ? ["--instructions", squad.instructions] : [];
   if (match) {
-    cli.run(["squad", "update", match.id, "--leader", leaderId, "--description", squad.description ?? ""]);
+    cli.run(["squad", "update", match.id, "--leader", leaderId, "--description", squad.description ?? "", ...instr]);
     id = match.id; updated++;
   } else {
-    const out = cli.run(["squad", "create", "--name", squad.name, "--leader", leaderId, "--description", squad.description ?? ""]);
+    const out = cli.run(["squad", "create", "--name", squad.name, "--leader", leaderId, "--description", squad.description ?? "", ...instr]);
     id = JSON.parse(out).id; created++;
   }
+  // Add non-leader members, skipping any already present so re-runs are idempotent.
+  const present = new Set(getSquadMembers(cli, id).map((m) => m.memberId));
   for (const m of squad.members) {
     if (m.agentName === squad.leaderName) continue;
-    cli.run(["squad", "member", "add", id, "--member-id", agentIdMap.get(m.agentName), "--role", m.role, "--type", "agent"]);
+    const memberId = agentIdMap.get(m.agentName);
+    if (present.has(memberId)) continue;
+    cli.run(["squad", "member", "add", id, "--member-id", memberId, "--role", m.role, "--type", "agent"]);
   }
   return { newId: id, created, updated };
 }
@@ -88,13 +118,50 @@ export function collectSourceRuntimes(manifest) {
   return [...new Set((manifest.agents ?? []).map((a) => a.sourceRuntimeId).filter(Boolean))];
 }
 
+// sourceRuntimeId -> provider (e.g. "claude", "opencode"), from whichever agent recorded it.
+function collectRuntimeProviders(manifest) {
+  const map = new Map();
+  for (const a of manifest.agents ?? []) {
+    if (a.sourceRuntimeId && a.sourceRuntimeProvider && !map.has(a.sourceRuntimeId)) {
+      map.set(a.sourceRuntimeId, a.sourceRuntimeProvider);
+    }
+  }
+  return map;
+}
+
+// Starts from the explicit --runtime-map (always wins), then auto-resolves any
+// remaining source runtime by provider — only when exactly one destination
+// runtime shares that provider. Ambiguous (0 or 2+ matches) stays unresolved.
+export function resolveRuntimeMap({ cli, manifest, runtimeMap }) {
+  const effective = new Map(runtimeMap);
+  const missing = collectSourceRuntimes(manifest).filter((r) => !effective.has(r));
+  if (!missing.length) return { effective, unresolved: [] };
+
+  const providers = collectRuntimeProviders(manifest);
+  const resolvable = missing.filter((r) => providers.has(r));
+  const destRuntimes = resolvable.length ? listRuntimes(cli) : [];
+  const unresolved = [];
+  for (const srcId of missing) {
+    const provider = providers.get(srcId);
+    const matches = provider ? destRuntimes.filter((r) => r.provider === provider) : [];
+    if (matches.length === 1) effective.set(srcId, matches[0].id);
+    else unresolved.push({ srcId, provider, matchCount: matches.length });
+  }
+  return { effective, unresolved };
+}
+
 export function importBundle({ cli, dir, runtimeMap, fs = nodeFs }) {
   const manifest = JSON.parse(fs.readFileSync(`${dir}/manifest.json`, "utf8"));
-  const missing = collectSourceRuntimes(manifest).filter((r) => !runtimeMap.has(r));
-  if (missing.length) throw new Error(`Unmapped runtimes: ${missing.join(", ")} — aborting before any write`);
+  const { effective, unresolved } = resolveRuntimeMap({ cli, manifest, runtimeMap });
+  if (unresolved.length) {
+    const detail = unresolved.map(({ srcId, provider, matchCount }) => provider
+      ? `${srcId} (provider "${provider}": ${matchCount} matching runtimes in destination, expected exactly 1)`
+      : `${srcId} (no provider recorded)`).join(", ");
+    throw new Error(`Unmapped runtimes: ${detail} — pass --runtime-map, aborting before any write`);
+  }
 
   const skillRes = importSkills({ cli, manifest, dir, fs });
-  const agentRes = importAgents({ cli, manifest, dir, skillIdMap: skillRes.idMap, runtimeMap, fs });
+  const agentRes = importAgents({ cli, manifest, dir, skillIdMap: skillRes.idMap, runtimeMap: effective, fs });
   let squadRes = { newId: null, created: 0, updated: 0 };
   if (manifest.squads?.length) squadRes = importSquad({ cli, squad: manifest.squads[0], agentIdMap: agentRes.idMap });
 

package/plugins/multica-tool/skills/import/SKILL.md

@@ -12,25 +12,24 @@ Import a local Multica bundle (produced by the export skill) into a target works
 
 Ask the user to confirm the name of the target workspace if not already stated. You will need the exact workspace name as registered in Multica.
 
-## Step 2 — Plan pass: read the bundle and collect unmapped runtimes
+## Step 2 — Run the import (auto-mapping first)
 
-Read the manifest to discover which source runtimes are referenced:
+Each exported agent record carries its source runtime's `provider` (e.g. `claude`, `opencode`) alongside its ID. The import script auto-maps a source runtime to the target workspace's runtime when there is **exactly one** runtime of that provider there — no manual mapping needed in the common case. Try the import without `--runtime-map` first:
 
 ```bash
-cat <folder>/manifest.json
+node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
+  --dir <folder> \
+  --workspace <workspace-name>
 ```
 
-Collect each distinct `sourceRuntimeId` from the `agents` array.
-
-List runtimes available in the target workspace:
+If it aborts with `Unmapped runtimes: ...` (0 or 2+ runtimes share that provider in the target workspace, or the bundle predates provider capture), resolve manually:
 
 ```bash
-multica runtime list --output json
+cat <folder>/manifest.json                 # note each distinct sourceRuntimeId
+multica runtime list --output json         # list target workspace runtimes
 ```
 
-For each distinct `sourceRuntimeId`, ask the user to pick a matching target runtime by name or ID. Build a mapping in the form `srcId=dstId`. If any source runtime has no mapping selected, abort and explain which IDs remain unmapped — do not write any resources.
-
-## Step 3 — Run the import
+Ask the user to pick a matching target runtime by name or ID for each unmapped `sourceRuntimeId`, then re-run with an explicit map (explicit entries always take precedence over auto-mapping):
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
@@ -39,7 +38,7 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
   --runtime-map <srcId1=dstId1,srcId2=dstId2,...>
 ```
 
-## Step 4 — Report results
+## Step 3 — Report results
 
 Parse the JSON output and report:
 

package/plugins/multica-tool/skills/sync/SKILL.md

@@ -18,29 +18,32 @@ sync <type> <name> from <src-ws> to <dest-ws>
 
 Where `<type>` is `skill`, `agent`, or `squad`; `<name>` is the resource name; `<src-ws>` and `<dest-ws>` are workspace names registered in Multica.
 
-## Step 2 — Build the runtime map
+## Step 2 — Run the sync (auto-mapping first)
 
-List runtimes available in the destination workspace:
+For agents and squads, each exported agent record carries its source runtime's `provider` (e.g. `claude`, `opencode`) alongside its ID. The sync script auto-maps a source runtime to the destination workspace's runtime when there is **exactly one** runtime of that provider there — no manual mapping needed in the common case. For skills (which have no runtime dependency), an empty runtime map is always acceptable. Try the sync without `--runtime-map` first:
 
 ```bash
-multica runtime list --output json
+node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-sync.mjs" \
+  <type> <name> from <src-ws> <dest-ws>
 ```
 
-Using the source workspace, fetch the resource to discover which `sourceRuntimeId` values are referenced (for agents and squads). For each distinct `sourceRuntimeId`, ask the user to select a matching target runtime by name or ID. Build a mapping in the form `srcId=dstId`. If any source runtime has no mapping, abort before running the sync.
+If it aborts with `Unmapped runtimes: ...` (0 or 2+ runtimes share that provider in the destination workspace), resolve manually:
 
-For skills (which have no runtime dependency), an empty runtime map is acceptable.
+```bash
+multica runtime list --workspace-id <dest-ws-id> --output json   # list destination workspace runtimes
+```
 
-## Step 3 — Run the sync
+Ask the user to select a matching target runtime by name or ID for each unmapped `sourceRuntimeId`, then re-run with an explicit map (explicit entries always take precedence over auto-mapping):
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-sync.mjs" \
   <type> <name> from <src-ws> <dest-ws> \
-  [--runtime-map <srcId1=dstId1,srcId2=dstId2,...>]
+  --runtime-map <srcId1=dstId1,srcId2=dstId2,...>
 ```
 
 The script exports to a temporary directory, imports into the destination workspace, then cleans up the temporary files automatically.
 
-## Step 4 — Report results
+## Step 3 — Report results
 
 Parse the JSON output and report:
 

package/plugins/plugin-validator/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plugin-validator",
   "displayName": "Plugin Validator",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
   "author": {
     "name": "Steven Hoang"

package/plugins/team-share/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-share",
   "displayName": "Team Share",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "Onboard your team with an interactive setup menu: install CodeGraph, build the Understand-Anything knowledge graph, and share Claude Code settings — run any combination, all idempotent.",
   "author": {
     "name": "Steven Hoang"

package/plugins/tech-graph/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-graph",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "Step-by-step wizard for generating technical diagrams as SVG+PNG.",
   "author": {
     "name": "steven"