@drunkcoding/agents-and-skills 0.0.35 → 0.0.37

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.35",
+      "version": "0.0.37",
       "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.35",
+      "version": "0.0.37",
       "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.35",
+      "version": "0.0.37",
       "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.35",
+      "version": "0.0.37",
       "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.35",
+      "version": "0.0.37",
       "category": "workflow",
       "keywords": [
         "multica",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.35",
+  "version": "0.0.37",
   "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.35",
+  "version": "0.0.37",
   "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.35",
+  "version": "0.0.37",
   "description": "Export, import, and sync Multica skills, agents, and squads between workspaces via the multica CLI."
 }

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

@@ -8,17 +8,17 @@ export function slugify(name) {
   return s || "unnamed";
 }
 
-export function realExec(args) {
-  return spawnSync("multica", args, { encoding: "utf8" });
+export function realExec(args, opts = {}) {
+  return spawnSync("multica", args, { encoding: "utf8", ...opts });
 }
 
 export function makeCli(exec, { workspaceId } = {}) {
-  function run(args) {
+  function run(args, opts) {
     let full = args;
     if (workspaceId) {
       full = [...args, "--workspace-id", workspaceId];
     }
-    const res = exec(full);
+    const res = exec(full, opts);
     if (res.status !== 0) throw new Error(res.stderr?.trim() || `multica exited ${res.status}`);
     return res.stdout;
   }
@@ -78,10 +78,18 @@ export function getAgent(cli, id) {
     runtimeId: a.runtime_id,
     hasCustomEnv: a.has_custom_env,
     mcpConfig: a.mcp_config,
+    mcpConfigRedacted: !!a.mcp_config_redacted,
     skills: (a.skills ?? []).map((sk) => ({ id: sk.id, name: sk.name })),
   };
 }
 
+// Custom env is never included in `agent get` — only `has_custom_env`/`custom_env_key_count`.
+// Reading actual values requires this dedicated, audited, owner/admin-only command.
+export function getAgentCustomEnv(cli, id) {
+  const r = cli.json(["agent", "env", "get", id]);
+  return r.custom_env ?? {};
+}
+
 export function getSquad(cli, id) {
   const s = cli.json(["squad", "get", id]);
   return { id: s.id, name: s.name, description: s.description, instructions: s.instructions, leaderId: s.leader_id };

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

@@ -1,15 +1,32 @@
 import * as nodeFs from "node:fs";
 import { dirname } from "node:path";
-import { slugify, getSkill, getAgent, getSquad, getSquadMembers, listRuntimes, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+import { slugify, getSkill, getAgent, getAgentCustomEnv, getSquad, getSquadMembers, listRuntimes, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
 
 const nonEmpty = (v) => v && typeof v === "object" && Object.keys(v).length > 0;
 
 export function redactAgent(a) {
-  // a is a normalized (camelCase) agent from getAgent.
-  const { id, hasCustomEnv, mcpConfig, skills, runtimeId, ...rest } = a;
-  const hadSecrets = !!hasCustomEnv || nonEmpty(mcpConfig);
+  // a is a normalized (camelCase) agent from getAgent, with `customEnv`/
+  // `customEnvFetchFailed` attached by the caller (collectAgent) — getAgent
+  // itself never fetches custom_env, since it requires a separate audited call.
+  const { id, hasCustomEnv, mcpConfigRedacted, customEnvFetchFailed, mcpConfig, customEnv, skills, runtimeId, ...rest } = a;
+  const mcpUsable = !mcpConfigRedacted && nonEmpty(mcpConfig);
+  const envUsable = !customEnvFetchFailed && nonEmpty(customEnv);
+  // mcpConfigRedacted / customEnvFetchFailed alone still flag hadSecrets even
+  // when unusable — the user should know something was present at the source
+  // but couldn't be captured, not just silently see an empty bundle.
+  const hadSecrets = mcpUsable || envUsable || !!mcpConfigRedacted || !!customEnvFetchFailed;
   return {
-    record: { ...rest, sourceRuntimeId: runtimeId, skillNames: [], hadSecrets },
+    // sourceId lets import-time mention rewriting map stale `mention://agent/<id>`
+    // links (in this or another agent's/squad's instructions) to the new id.
+    record: {
+      ...rest,
+      sourceId: id,
+      sourceRuntimeId: runtimeId,
+      skillNames: [],
+      mcpConfig: mcpUsable ? mcpConfig : null,
+      customEnv: envUsable ? customEnv : null,
+      hadSecrets,
+    },
     hadSecrets,
   };
 }
@@ -24,7 +41,7 @@ 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, sourceRuntimeProvider: a.sourceRuntimeProvider ?? null, skillNames: a.skillNames, hadSecrets: !!a.hadSecrets })),
+    agents: [...seenAgents.values()].map((a) => ({ name: a.name, file: `agents/${slugify(a.name)}.json`, sourceId: a.sourceId, 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 }] : [],
   };
 }
@@ -41,6 +58,15 @@ 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;
+  a.customEnv = {};
+  a.customEnvFetchFailed = false;
+  if (a.hasCustomEnv) {
+    try {
+      a.customEnv = getAgentCustomEnv(cli, id);
+    } catch {
+      a.customEnvFetchFailed = true; // e.g. insufficient permission — non-fatal, warned via hadSecrets
+    }
+  }
   const skillNames = a.skills.map((sk) => collectSkill(cli, sk.id, skills));
   const red = redactAgent(a);
   const entry = { raw: a, red, skillNames };
@@ -77,7 +103,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, sourceRuntimeProvider: a.raw.sourceRuntimeProvider, skillNames: a.skillNames, hadSecrets: a.red.hadSecrets })),
+    agents: [...agentsById.values()].map((a) => ({ name: a.raw.name, sourceId: a.raw.id, sourceRuntimeId: a.raw.runtimeId, sourceRuntimeProvider: a.raw.sourceRuntimeProvider, skillNames: a.skillNames, hadSecrets: a.red.hadSecrets })),
     squad,
   });
 

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

@@ -57,6 +57,8 @@ export function importSkills({ cli, manifest, dir, fs = nodeFs }) {
 
 export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs = nodeFs }) {
   const idMap = new Map();
+  const sourceIdMap = new Map(); // source agent id -> new agent id, for mention rewriting
+  const secretsApplyFailures = [];
   let created = 0, updated = 0;
   const existing = listAgents(cli);
 
@@ -69,6 +71,7 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       "--visibility", rec.visibility ?? "private",
       "--max-concurrent-tasks", String(rec.maxConcurrentTasks ?? 6),
     ];
+    if (rec.description) common.push("--description", rec.description);
     if (rec.instructions) common.push("--instructions", rec.instructions);
     if (rec.model) common.push("--model", rec.model);
     if (rec.thinkingLevel) common.push("--thinking-level", rec.thinkingLevel);
@@ -84,18 +87,77 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       id = JSON.parse(out).id; created++;
     }
     idMap.set(rec.name, id);
+    if (rec.sourceId) sourceIdMap.set(rec.sourceId, id);
     const skillIds = (rec.skillNames ?? []).map((n) => skillIdMap.get(n)).filter(Boolean);
     cli.run(["agent", "skills", "set", id, "--skill-ids", skillIds.join(",")]);
+
+    // mcp_config/custom_env carry real secrets. Each is applied via its OWN
+    // follow-up call, never bundled into the create/update call above — that
+    // keeps a rejected secret from failing the whole agent create/update, and
+    // sidesteps the fact that only one stdin payload can be read per process
+    // anyway. `agent update --mcp-config-stdin` works on a freshly-created id
+    // too, so no create/update branching is needed here.
+    const hasMcpConfig = rec.mcpConfig && Object.keys(rec.mcpConfig).length > 0;
+    if (hasMcpConfig) {
+      try {
+        cli.run(["agent", "update", id, "--mcp-config-stdin"], { input: JSON.stringify(rec.mcpConfig) });
+      } catch {
+        secretsApplyFailures.push(rec.name);
+      }
+    }
+    // custom_env has no flag on `agent update` at all — `agent env set` is the
+    // only way to set it on an existing agent, so it's always a follow-up call.
+    const hasCustomEnv = rec.customEnv && Object.keys(rec.customEnv).length > 0;
+    if (hasCustomEnv) {
+      try {
+        cli.run(["agent", "env", "set", id, "--custom-env-stdin"], { input: JSON.stringify(rec.customEnv) });
+      } catch {
+        secretsApplyFailures.push(rec.name);
+      }
+    }
   }
-  return { idMap, created, updated };
+  return { idMap, sourceIdMap, created, updated, secretsApplyFailures };
+}
+
+// Rewrites `mention://agent/<id>` links (e.g. `[@dev-backend](mention://agent/<id>)`)
+// from a source-workspace agent id to its id in the destination workspace.
+// Mentions with no entry in idMap (agent outside this bundle) are left as-is.
+const MENTION_RE = /mention:\/\/agent\/([^)\s]+)/g;
+
+export function rewriteMentions(text, idMap) {
+  if (!text) return text;
+  return text.replace(MENTION_RE, (full, oldId) => {
+    const newId = idMap.get(oldId);
+    return newId ? `mention://agent/${newId}` : full;
+  });
+}
+
+// Second pass over agent instructions: an agent's instructions may @mention a
+// sibling agent from the same bundle by its SOURCE id, which is only knowable
+// once every agent in the bundle has been created/updated (idMap complete) —
+// so this must run after the importAgents loop above, not inside it.
+export function rewriteAgentMentions({ cli, manifest, dir, agentIdMap, sourceIdMap, fs = nodeFs }) {
+  let updated = 0;
+  for (const a of manifest.agents) {
+    const rec = JSON.parse(fs.readFileSync(`${dir}/${a.file}`, "utf8"));
+    if (!rec.instructions) continue;
+    const rewritten = rewriteMentions(rec.instructions, sourceIdMap);
+    if (rewritten === rec.instructions) continue;
+    cli.run(["agent", "update", agentIdMap.get(rec.name), "--instructions", rewritten]);
+    updated++;
+  }
+  return { updated };
 }
 
-export function importSquad({ cli, squad, agentIdMap }) {
+export function importSquad({ cli, squad, agentIdMap, sourceIdMap }) {
   const existing = listSquads(cli);
   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] : [];
+  // Squad instructions commonly list @mentions of teammate agents by their
+  // SOURCE id — rewrite to the destination ids before the squad is created.
+  const instructions = sourceIdMap ? rewriteMentions(squad.instructions, sourceIdMap) : squad.instructions;
+  const instr = instructions ? ["--instructions", instructions] : [];
   if (match) {
     cli.run(["squad", "update", match.id, "--leader", leaderId, "--description", squad.description ?? "", ...instr]);
     id = match.id; updated++;
@@ -162,16 +224,20 @@ export function importBundle({ cli, dir, runtimeMap, fs = nodeFs }) {
 
   const skillRes = importSkills({ cli, manifest, dir, fs });
   const agentRes = importAgents({ cli, manifest, dir, skillIdMap: skillRes.idMap, runtimeMap: effective, fs });
+  // Runs after every agent exists so forward-referencing mentions resolve.
+  const mentionRes = rewriteAgentMentions({ cli, manifest, dir, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap, fs });
   let squadRes = { newId: null, created: 0, updated: 0 };
-  if (manifest.squads?.length) squadRes = importSquad({ cli, squad: manifest.squads[0], agentIdMap: agentRes.idMap });
+  if (manifest.squads?.length) squadRes = importSquad({ cli, squad: manifest.squads[0], agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap });
 
   return {
     created: { skills: skillRes.created, agents: agentRes.created, squads: squadRes.created },
     updated: { skills: skillRes.updated, agents: agentRes.updated, squads: squadRes.updated },
+    mentionsRewritten: mentionRes.updated,
     skillIdMap: Object.fromEntries(skillRes.idMap),
     agentIdMap: Object.fromEntries(agentRes.idMap),
     squadId: squadRes.newId,
     secretsReminder: (manifest.agents ?? []).filter((a) => a.hadSecrets).map((a) => a.name),
+    secretsApplyFailures: agentRes.secretsApplyFailures,
   };
 }
 

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

@@ -58,4 +58,4 @@ Parse the JSON output from the script and report:
 
 - Directory written to.
 - Count of skills, agents, and squads exported.
-- If `warnings` is non-empty, surface every agent name verbatim with this message: "WARNING: the following agents had custom environment variables or MCP config that were NOT exported — re-add secrets manually after import: `<agent-name>`."
+- If `warnings` is non-empty, surface every agent name verbatim with this message: "WARNING: the following agents' exported files contain custom environment variables or MCP config in PLAINTEXT — treat the export directory as sensitive (avoid committing it to a public repo, restrict file permissions, delete it once the import is done): `<agent-name>`."

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

@@ -38,6 +38,8 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
   --runtime-map <srcId1=dstId1,srcId2=dstId2,...>
 ```
 
+The import also rewrites any `mention://agent/<id>` link inside squad and agent instructions (e.g. `[@dev-backend](mention://agent/<id>)`) from the source agent's id to its new id in the target workspace — the CLI does this automatically for every agent captured in the bundle; no extra flag needed. Mentions pointing to an agent outside the bundle are left untouched.
+
 ## Step 3 — Report results
 
 Parse the JSON output and report:
@@ -45,4 +47,6 @@ Parse the JSON output and report:
 - Created and updated counts for skills, agents, and squads.
 - Name-to-ID maps for skills and agents (`skillIdMap`, `agentIdMap`).
 - Squad ID if a squad was imported.
-- If `secretsReminder` is non-empty, surface every agent name verbatim with: "WARNING: the following agents had custom environment variables or MCP config that were NOT exported — re-add secrets manually in the Multica UI: `<agent-name>`."
+- `mentionsRewritten`: how many agents had an agent-mention link rewritten to its new id.
+- If `secretsReminder` is non-empty, surface every agent name verbatim with: "WARNING: the following agents' bundle files contained custom environment variables or MCP config in PLAINTEXT — the source export directory should be treated as sensitive: `<agent-name>`."
+- If `secretsApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: mcp_config or custom_env failed to apply to the following agents during import (the agent itself was still created/updated) — set them manually in the Multica UI: `<agent-name>`."

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

@@ -50,4 +50,5 @@ Parse the JSON output and report:
 - Created and updated counts for skills, agents, and squads.
 - Name-to-ID maps (`skillIdMap`, `agentIdMap`).
 - Squad ID if a squad was synced.
-- If `secretsReminder` is non-empty, surface every agent name verbatim with: "WARNING: the following agents had custom environment variables or MCP config that were NOT exported — re-add secrets manually in the Multica UI: `<agent-name>`."
+- If `secretsReminder` is non-empty, surface every agent name verbatim with: "WARNING: the following agents' bundle files contained custom environment variables or MCP config in PLAINTEXT — the temporary export directory (already cleaned up) briefly held these secrets in plaintext: `<agent-name>`."
+- If `secretsApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: mcp_config or custom_env failed to apply to the following agents during sync (the agent itself was still created/updated) — set them manually in the Multica UI: `<agent-name>`."

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

@@ -1,7 +1,7 @@
 {
   "name": "plugin-validator",
   "displayName": "Plugin Validator",
-  "version": "0.0.35",
+  "version": "0.0.37",
   "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.35",
+  "version": "0.0.37",
   "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.35",
+  "version": "0.0.37",
   "description": "Step-by-step wizard for generating technical diagrams as SVG+PNG.",
   "author": {
     "name": "steven"