@drunkcoding/agents-and-skills 0.0.39 → 0.0.40

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

package/package.json

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

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

@@ -31,7 +31,7 @@ export function redactAgent(a) {
   // a is a normalized agent from getAgent, with `custom_env`/
   // `custom_env_fetch_failed` attached by the caller (collectAgent) — getAgent
   // itself never fetches custom_env, since it requires a separate audited call.
-  const { id, has_custom_env, mcp_config_redacted, custom_env_fetch_failed, mcp_config, custom_env, skills, runtime_id, ...rest } = a;
+  const { id, has_custom_env, mcp_config_redacted, custom_env_fetch_failed, mcp_config, custom_env, skills, runtime_id, instructions, ...rest } = a;
   const mcpUsable = !mcp_config_redacted && nonEmpty(mcp_config);
   const envUsable = !custom_env_fetch_failed && nonEmpty(custom_env);
   // mcp_config_redacted / custom_env_fetch_failed alone still flag hadSecrets even
@@ -39,10 +39,10 @@ export function redactAgent(a) {
   // but couldn't be captured, not just silently see an empty bundle.
   const hadSecrets = mcpUsable || envUsable || !!mcp_config_redacted || !!custom_env_fetch_failed;
   return {
-    // source_id 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,
+      // source_id lets import-time mention rewriting map stale `mention://agent/<id>`
+      // links (in this or another agent's/squad's instructions) to the new id.
       source_id: id,
       source_runtime_id: runtime_id,
       skill_names: [],
@@ -51,6 +51,9 @@ export function redactAgent(a) {
       had_secrets: hadSecrets,
     },
     hadSecrets,
+    // instructions are written to a sibling .md by the caller (see avatar_file),
+    // never embedded in the JSON record.
+    instructions: instructions ?? "",
   };
 }
 
@@ -65,7 +68,13 @@ export function buildManifest({ scope, sourceWorkspaceId, skills, agents, squads
     source_workspace_id: sourceWorkspaceId,
     skills: [...seenSkills.values()].map((s) => ({ name: s.name, dir: `skills/${slugify(s.name)}`, source_id: s.source_id })),
     agents: [...seenAgents.values()].map((a) => ({ name: a.name, file: `agents/${slugify(a.name)}.json`, source_id: a.source_id, source_runtime_id: a.source_runtime_id, source_runtime_provider: a.source_runtime_provider ?? null, skill_names: a.skill_names, had_secrets: !!a.had_secrets })),
-    squads: (squads ?? []).map((squad) => ({ name: squad.name, file: `squads/${slugify(squad.name)}.json`, description: squad.description ?? "", instructions: squad.instructions ?? "", avatar_url: squad.avatar_url ?? null, leader_name: squad.leader_name, members: squad.members })),
+    squads: (squads ?? []).map((squad) => {
+      const file = `squads/${slugify(squad.name)}.json`;
+      const entry = { name: squad.name, file, description: squad.description ?? "", avatar_url: squad.avatar_url ?? null, leader_name: squad.leader_name, members: squad.members };
+      // Instructions go to a sibling .md (see squad write loop); only referenced when non-empty.
+      if (squad.instructions) entry.instructions_file = file.replace(/\.json$/, ".md");
+      return entry;
+    }),
   };
 }
 
@@ -170,10 +179,21 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
         record.avatar_file = rel;
       }
     }
+    // Instructions live in a sibling .md for reviewability (same sibling-file
+    // pattern as avatar_file); only written when non-empty.
+    if (red.instructions) {
+      const rel = entry.file.replace(/\.json$/, ".md");
+      fs.writeFileSync(`${outDir}/${rel}`, red.instructions);
+      record.instructions_file = rel;
+    }
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(record, null, 2));
   }
+  const squadInstrByName = new Map(squads.map((s) => [s.name, s.instructions ?? ""]));
   for (const entry of manifest.squads) {
     fs.mkdirSync(`${outDir}/squads`, { recursive: true });
+    if (entry.instructions_file) {
+      fs.writeFileSync(`${outDir}/${entry.instructions_file}`, squadInstrByName.get(entry.name) ?? "");
+    }
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(entry, null, 2));
   }
   fs.writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2));

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

@@ -1,6 +1,16 @@
 import * as nodeFs from "node:fs";
 import { listSkills, listAgents, listSquads, listRuntimes, listWorkspaceMembers, getSquadMembers, findByName, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
 
+// Instructions live in a sibling .md referenced by `instructions_file` (mirrors
+// avatar_file). Legacy bundles carry no instructions_file and keep instructions
+// inline in the JSON — fall back to that so older exports still import.
+function readInstructions(fs, dir, rec) {
+  if (rec.instructions_file && fs.existsSync(`${dir}/${rec.instructions_file}`)) {
+    return fs.readFileSync(`${dir}/${rec.instructions_file}`, "utf8");
+  }
+  return rec.instructions ?? "";
+}
+
 // Relative paths of every file under root (recursing into subdirs like scripts/).
 function walkSkillFiles(fs, root, rel = "") {
   const out = [];
@@ -82,7 +92,8 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       "--max-concurrent-tasks", String(rec.max_concurrent_tasks ?? 6),
     ];
     if (rec.description) common.push("--description", rec.description);
-    if (rec.instructions) common.push("--instructions", rec.instructions);
+    const instructions = readInstructions(fs, dir, rec);
+    if (instructions) common.push("--instructions", instructions);
     if (rec.model) common.push("--model", rec.model);
     if (rec.thinking_level) common.push("--thinking-level", rec.thinking_level);
     if (rec.runtime_config && Object.keys(rec.runtime_config).length) common.push("--runtime-config", JSON.stringify(rec.runtime_config));
@@ -184,9 +195,10 @@ export function rewriteAgentMentions({ cli, manifest, dir, agentIdMap, sourceIdM
   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;
+    const instructions = readInstructions(fs, dir, rec);
+    if (!instructions) continue;
+    const rewritten = rewriteMentions(instructions, sourceIdMap);
+    if (rewritten === instructions) continue;
     cli.run(["agent", "update", agentIdMap.get(rec.name), "--instructions", rewritten]);
     updated++;
   }
@@ -280,6 +292,7 @@ export function importBundle({ cli, dir, runtimeMap, fs = nodeFs }) {
   const squadIdMap = new Map();
   let squadsCreated = 0, squadsUpdated = 0;
   for (const squad of manifest.squads ?? []) {
+    squad.instructions = readInstructions(fs, dir, squad);
     const r = importSquad({ cli, squad, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap });
     squadIdMap.set(squad.name, r.newId);
     squadsCreated += r.created;

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

@@ -52,7 +52,7 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-export.mjs" \
 
 Pass `--scope all` (with no `--id`) to export the **entire workspace** — every skill, agent, and squad — into one flat, deduped bundle. A skill or agent shared across many agents/squads is written exactly once and referenced by name.
 
-The script writes `manifest.json`, skill SKILL.md files, agent JSON files, and squad JSON files into `<dir>`.
+The script writes `manifest.json`, skill `SKILL.md` files, agent JSON files, and squad JSON files into `<dir>`. Each agent's and squad's **instructions** (system prompt / charter) are written to a sibling Markdown file — `agents/<slug>.md`, `squads/<slug>.md` — referenced by an `instructions_file` key in the JSON, so the prose is easy to read, diff, and edit. Agents/squads with no instructions get no `.md`.
 
 Avatars are captured automatically: an agent's uploaded-image avatar is downloaded into the bundle (`agents/<slug>.avatar.<ext>`) and referenced by `avatar_file`; emoji avatars (agents and squads) and a squad's avatar are recorded as the `avatar_url` string.
 

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

@@ -40,6 +40,8 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
 
 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.
 
+Instructions are read back from each resource's sibling `.md` (`agents/<slug>.md`, `squads/<slug>.md`) when present — editing that Markdown is the supported way to review and enhance an agent's or squad's instructions before import. Older bundles that predate the split (instructions inline in the JSON, no `instructions_file`) still import unchanged.
+
 Avatars are restored automatically, but **only when the target resource has none** — an existing agent or squad that already carries an avatar is never overwritten. New agents get their bundled image re-uploaded; new squads get their `avatar_url` (emoji or URL) set. An agent whose source avatar was an emoji can't be restored (the CLI has no emoji setter for agents) and is reported as unsupported.
 
 ## Step 3 — Report results

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

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