@drunkcoding/agents-and-skills 0.0.44 → 0.0.45

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

package/package.json

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

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

@@ -5,6 +5,18 @@ import { slugify, getSkill, getAgent, getAgentCustomEnv, getSquad, getSquadMembe
 
 const nonEmpty = (v) => v && typeof v === "object" && Object.keys(v).length > 0;
 
+// Externalize a prose field to a sibling .md next to `jsonRel`
+// (e.g. agents/x.json + ".description.md" → agents/x.description.md), and record
+// the `<field>_file` pointer on `record`. Empty prose writes nothing and adds no
+// key — same sibling-file pattern as avatar_file, applied uniformly to every
+// resource's instructions/description so no prose is ever embedded in the JSON.
+function writeSidecar(fs, outDir, jsonRel, suffix, text, record, key) {
+  if (!text) return;
+  const rel = jsonRel.replace(/\.json$/, suffix);
+  fs.writeFileSync(`${outDir}/${rel}`, text);
+  record[key] = rel;
+}
+
 // An avatar_url is either an uploaded-image URL (http[s]://…) or an inline
 // "emoji:🦍" marker. Only image URLs carry bytes worth bundling; emoji markers
 // are just carried as strings in the record.
@@ -31,7 +43,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, instructions, archived_at, ...rest } = a;
+  const { id, has_custom_env, mcp_config_redacted, custom_env_fetch_failed, mcp_config, custom_env, skills, runtime_id, instructions, description, archived_at, ...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
@@ -51,9 +63,10 @@ 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 and description are written to sibling .md files by the caller
+    // (see avatar_file), never embedded in the JSON record.
     instructions: instructions ?? "",
+    description: description ?? "",
   };
 }
 
@@ -72,9 +85,11 @@ export function buildManifest({ scope, sourceWorkspaceId, skills, agents, squads
     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) => {
       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.
+      const entry = { name: squad.name, file, avatar_url: squad.avatar_url ?? null, leader_name: squad.leader_name, members: squad.members };
+      // Instructions and description go to sibling .md files (see squad write
+      // loop); only referenced when non-empty.
       if (squad.instructions) entry.instructions_file = file.replace(/\.json$/, ".md");
+      if (squad.description) entry.description_file = file.replace(/\.json$/, ".description.md");
       return entry;
     }),
     projects: [...seenProjects.values()].map((p) => ({
@@ -304,32 +319,34 @@ 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;
-    }
+    // Instructions and description each live in a sibling .md for reviewability.
+    writeSidecar(fs, outDir, entry.file, ".md", red.instructions, record, "instructions_file");
+    writeSidecar(fs, outDir, entry.file, ".description.md", red.description, record, "description_file");
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(record, null, 2));
   }
-  const squadInstrByName = new Map(squads.map((s) => [s.name, s.instructions ?? ""]));
+  const squadByName = new Map(squads.map((s) => [s.name, s]));
   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) ?? "");
-    }
+    const s = squadByName.get(entry.name);
+    if (entry.instructions_file) fs.writeFileSync(`${outDir}/${entry.instructions_file}`, s?.instructions ?? "");
+    if (entry.description_file) fs.writeFileSync(`${outDir}/${entry.description_file}`, s?.description ?? "");
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(entry, null, 2));
   }
   const projectByTitle = new Map(projects.map((p) => [p.title, p]));
   for (const entry of manifest.projects) {
     fs.mkdirSync(`${outDir}/projects`, { recursive: true });
-    fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(projectByTitle.get(entry.title), null, 2));
+    const record = { ...projectByTitle.get(entry.title) };
+    const desc = record.description; delete record.description;
+    writeSidecar(fs, outDir, entry.file, ".description.md", desc, record, "description_file");
+    fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(record, null, 2));
   }
   const autopilotByTitle = new Map(autopilots.map((a) => [a.title, a]));
   for (const entry of manifest.autopilots) {
     fs.mkdirSync(`${outDir}/autopilots`, { recursive: true });
-    fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(autopilotByTitle.get(entry.title), null, 2));
+    const record = { ...autopilotByTitle.get(entry.title) };
+    const desc = record.description; delete record.description;
+    writeSidecar(fs, outDir, entry.file, ".description.md", desc, record, "description_file");
+    fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(record, null, 2));
   }
   fs.writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2));
   return {

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

@@ -8,15 +8,18 @@ export function parseInclude(raw) {
   return set;
 }
 
-// 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");
+// A prose field (instructions/description) lives in a sibling .md referenced by
+// `<field>_file` (mirrors avatar_file). Legacy bundles carry no `<field>_file`
+// and keep the prose inline in the JSON — fall back to that so older exports
+// still import.
+function readSidecar(fs, dir, rec, fileKey, inlineKey) {
+  if (rec[fileKey] && fs.existsSync(`${dir}/${rec[fileKey]}`)) {
+    return fs.readFileSync(`${dir}/${rec[fileKey]}`, "utf8");
   }
-  return rec.instructions ?? "";
+  return rec[inlineKey] ?? "";
 }
+const readInstructions = (fs, dir, rec) => readSidecar(fs, dir, rec, "instructions_file", "instructions");
+const readDescription = (fs, dir, rec) => readSidecar(fs, dir, rec, "description_file", "description");
 
 // Relative paths of every file under root (recursing into subdirs like scripts/).
 function walkSkillFiles(fs, root, rel = "") {
@@ -100,7 +103,8 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       "--visibility", rec.visibility ?? "private",
       "--max-concurrent-tasks", String(rec.max_concurrent_tasks ?? 6),
     ];
-    if (rec.description) common.push("--description", rec.description);
+    const description = readDescription(fs, dir, rec);
+    if (description) common.push("--description", description);
     const instructions = readInstructions(fs, dir, rec);
     if (instructions) common.push("--instructions", instructions);
     if (rec.model) common.push("--model", rec.model);
@@ -269,7 +273,8 @@ export function importProjects({ cli, manifest, dir, agentIdMap, fs = nodeFs })
   for (const entry of manifest.projects ?? []) {
     const rec = JSON.parse(fs.readFileSync(`${dir}/${entry.file}`, "utf8"));
     const flags = ["--title", rec.title];
-    if (rec.description) flags.push("--description", rec.description);
+    const description = readDescription(fs, dir, rec);
+    if (description) flags.push("--description", description);
     if (rec.icon) flags.push("--icon", rec.icon);
     if (rec.status) flags.push("--status", rec.status);
     if (rec.due_date) flags.push("--due-date", rec.due_date);
@@ -347,7 +352,8 @@ export function importAutopilots({ cli, manifest, dir, agentIdMap, fs = nodeFs }
 
   for (const rec of recs) {
     const common = [];
-    if (rec.description) common.push("--description", rec.description);
+    const description = readDescription(fs, dir, rec);
+    if (description) common.push("--description", description);
     if (rec.issue_title_template) common.push("--issue-title-template", rec.issue_title_template);
     // priority is never present today — the multica CLI/API accepts it on write but
     // never returns it on read, so export can't capture the source's real value.
@@ -469,6 +475,7 @@ export function importBundle({ cli, dir, runtimeMap, include, fs = nodeFs }) {
   if (inc.has("squads")) {
     for (const squad of manifest.squads ?? []) {
       squad.instructions = readInstructions(fs, dir, squad);
+      squad.description = readDescription(fs, dir, squad);
       const r = importSquad({ cli, squad, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap });
       if (r.skipped) { squadsSkipped.push(squad.name); continue; }
       squadIdMap.set(squad.name, r.newId);

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

@@ -37,13 +37,7 @@ If the user specified an output directory, use it verbatim. Otherwise default to
 First resolve `<workspace-name>`:
 
 - If the user named a source workspace (the value you would pass as `--workspace <name>`), use that name.
-- Otherwise, read the current default workspace's name:
-
-```bash
-multica workspace get --output json
-```
-
-  and take its `.name`.
+- Otherwise, run `multica workspace get --output json` and take its `.name` (the current default workspace).
 
 Slugify the resolved name for filesystem safety — lowercase it, replace each run of non-`[a-z0-9]` characters with a single `-`, and trim leading/trailing `-` (the same rule the scripts use internally).
 
@@ -70,7 +64,12 @@ Pass `--scope all` (with no `--id`) to export the **entire workspace** — every
 
 Exporting a project (or `projects`/`all`) also **bundles the project's lead agent** so the bundle is self-contained; projects carry metadata only (title, description, icon, priority, status, dates, lead mapping) plus their attached resource records — never issues. On import, only `github_repo` resources are portable and recreated; other resource types are reported and skipped.
 
-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`.
+The script writes `manifest.json`, skill `SKILL.md` files, agent JSON files, and squad JSON files into `<dir>`. Every resource's prose fields are externalized to sibling Markdown files, never embedded in the JSON — so they are easy to read, diff, and edit:
+
+- **instructions** (system prompt / charter, agents and squads) → `<slug>.md`, referenced by an `instructions_file` key.
+- **description** (agents, squads, projects, autopilots) → `<slug>.description.md`, referenced by a `description_file` key.
+
+An empty field gets no file and no `*_file` key. Skills keep their own layout — the description lives in `SKILL.md` frontmatter and the body is the content.
 
 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

@@ -13,7 +13,7 @@ Import a local Multica bundle (produced by the export skill) into a target works
 You need the exact workspace name as registered in Multica for `--workspace` in the steps below.
 
 - If the user named a target workspace, use it.
-- If the user did **not** name one, default to the **basename of the import folder** — e.g. importing from `export/mx-workspace` defaults the target workspace to `mx-workspace`. State the inferred workspace name to the user before continuing.
+- If the user did **not** name one, default to the **basename of the import folder** — e.g. importing from `export/mx-workspace` defaults the target workspace to `mx-workspace`. State the inferred workspace name to the user before continuing. This default is reliable for whole-workspace bundles (`export/<workspace-name>`); a single-resource bundle nested under `export/<workspace-name>/<slug>-<type>` has the resource slug as its basename, not the workspace — name the target workspace explicitly in that case.
 
 No existence check is needed here: the Step 2 dry-run fails with `Unknown workspace "<name>"` if the inferred workspace is not present in the target account, at which point ask the user for the correct name.
 
@@ -70,7 +70,7 @@ If it instead aborts with `Unresolved autopilot assignees: ...`, that is not fix
 
 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.
+Prose fields are read back from each resource's sibling `.md` when a `*_file` key points at it — **instructions** from `<slug>.md` (agents, squads) and **description** from `<slug>.description.md` (agents, squads, projects, autopilots). Editing that Markdown is the supported way to review and enhance the prose before import. Older bundles that predate the split (prose inline in the JSON, no `*_file` key) 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.
 

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

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