@systemdox/mcp-server 0.1.42 → 0.1.44

package/dist/index.js

@@ -99,6 +99,16 @@ var SystemDoxApiClient = class {
     this.cache.set(cacheKey, data);
     return data;
   }
+  /** A read that skips the cache: an install must take the version that is
+   * latest now, not the one cached before someone published another. */
+  async getFresh(path) {
+    const res = await this.fetchRaw(path);
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`SystemDox API error ${res.status}: ${body}`);
+    }
+    return await res.json();
+  }
   async post(path, body) {
     return this.mutate("POST", path, body);
   }
@@ -119,8 +129,8 @@ var SystemDoxApiClient = class {
       body: JSON.stringify(body)
     });
     if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`SystemDox API error ${res.status}: ${text}`);
+      const text2 = await res.text();
+      throw new Error(`SystemDox API error ${res.status}: ${text2}`);
     }
     return await res.json();
   }
@@ -285,12 +295,12 @@ function registerGetGuardrails(server2, apiClient2) {
       );
     }
     if (filtered.length === 0) {
-      const text2 = guardrails.length === 0 ? `No checks found. Add checks at ${configLink("/docs/guardrails", await workspaceBase(apiClient2))}` : `No checks found${lang ? ` for language "${lang}"` : ""}${category ? ` in category "${category}"` : ""}.`;
+      const text3 = guardrails.length === 0 ? `No checks found. Add checks at ${configLink("/docs/guardrails", await workspaceBase(apiClient2))}` : `No checks found${lang ? ` for language "${lang}"` : ""}${category ? ` in category "${category}"` : ""}.`;
       return {
-        content: [{ type: "text", text: text2 }]
+        content: [{ type: "text", text: text3 }]
       };
     }
-    const text = filtered.map(
+    const text2 = filtered.map(
       (g) => `## ${g.title} [${g.severity}]
 
 ${g.description}
@@ -314,7 +324,7 @@ ${g.fix}
           type: "text",
           text: `Found ${filtered.length} check(s):
 
-${text}`
+${text2}`
         }
       ]
     };
@@ -404,7 +414,7 @@ ${spec.taskContent}`);
           ]
         };
       }
-      const text = filtered.map(
+      const text2 = filtered.map(
         (s) => `- **${s.name}** (${s.draftId}) \u2014 ${s.status}, ${s.requirementCount} requirements` + (s.repoFullName ? `, repo: ${s.repoFullName}` : "")
       ).join("\n");
       return {
@@ -413,7 +423,7 @@ ${spec.taskContent}`);
             type: "text",
             text: `Found ${filtered.length} spec(s):
 
-${text}`
+${text2}`
           }
         ]
       };
@@ -466,18 +476,18 @@ function registerGetDocs(server2, apiClient2) {
             isError: true
           };
         }
-        let text2 = doc.content;
+        let text3 = doc.content;
         if (anchor && doc.section_resolved === false) {
-          text2 = `_Section "${anchor}" not found \u2014 returning the full document._
+          text3 = `_Section "${anchor}" not found \u2014 returning the full document._
 
-` + text2;
+` + text3;
         } else if (anchor && doc.heading) {
-          text2 = `## ${doc.heading}
+          text3 = `## ${doc.heading}
 
 ${doc.content}`;
         }
         return {
-          content: [{ type: "text", text: text2 }]
+          content: [{ type: "text", text: text3 }]
         };
       }
       const params = {};
@@ -501,7 +511,7 @@ ${doc.content}`;
           ]
         };
       }
-      const text = items.map((d) => {
+      const text2 = items.map((d) => {
         const sections = (d.outline ?? []).slice(0, 8);
         const sectionHint = sections.length > 0 ? `
   sections: ${sections.map((s) => s.anchor).join(", ")}` : "";
@@ -515,7 +525,7 @@ ${doc.content}`;
             type: "text",
             text: `Found ${items.length} document(s) (${response.total} total):
 
-${text}
+${text2}
 
 Use doc_id for full content, or doc_id + section to fetch one section.`
           }
@@ -850,13 +860,13 @@ var SEVERITY_SCORES = {
   low: 0.25
 };
 var CHARS_PER_TOKEN = 4;
-function estimateTokens(text) {
-  return Math.ceil(text.length / CHARS_PER_TOKEN);
+function estimateTokens(text2) {
+  return Math.ceil(text2.length / CHARS_PER_TOKEN);
 }
-function truncateToTokens(text, maxTokens) {
+function truncateToTokens(text2, maxTokens) {
   const maxChars = Math.max(0, maxTokens) * CHARS_PER_TOKEN;
-  if (text.length <= maxChars) return { text, truncated: false };
-  const head = text.slice(0, maxChars);
+  if (text2.length <= maxChars) return { text: text2, truncated: false };
+  const head = text2.slice(0, maxChars);
   const floor = Math.floor(maxChars * 0.75);
   const paragraph = head.lastIndexOf("\n\n");
   const line = head.lastIndexOf("\n");
@@ -901,7 +911,7 @@ function scoreSeverity(item) {
   if (!item.severity) return 0.5;
   return SEVERITY_SCORES[item.severity] ?? 0.5;
 }
-function extractKeywords(text) {
+function extractKeywords(text2) {
   const stopWords = /* @__PURE__ */ new Set([
     "the",
     "a",
@@ -986,7 +996,7 @@ function extractKeywords(text) {
     "implement",
     "create"
   ]);
-  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !stopWords.has(w));
+  return text2.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !stopWords.has(w));
 }
 function scoreItems(items, taskDescription, filePaths) {
   const languages = detectLanguages(filePaths);
@@ -1029,20 +1039,20 @@ var MAX_TAIL = 10;
 var TAIL_SHARE = 0.15;
 var TRUNCATION_NOTICE_TOKENS = 30;
 function formatGuardrail(g) {
-  let text = `## ${g.title} [${g.severity}]
+  let text2 = `## ${g.title} [${g.severity}]
 
 ${g.description}`;
-  if (g.pattern) text += `
+  if (g.pattern) text2 += `
 
 **Bad:** \`\`\`
 ${g.pattern}
 \`\`\``;
-  if (g.fix) text += `
+  if (g.fix) text2 += `
 
 **Good:** \`\`\`
 ${g.fix}
 \`\`\``;
-  return text;
+  return text2;
 }
 function formatSpecHeadline(s) {
   return `### ${s.name}
@@ -1064,19 +1074,19 @@ function formatRules(rules) {
     if (!byCategory.has(cat)) byCategory.set(cat, []);
     byCategory.get(cat).push(r);
   }
-  let text = "";
+  let text2 = "";
   for (const [cat, catRules] of byCategory) {
-    text += `### ${cat.charAt(0).toUpperCase() + cat.slice(1)}
+    text2 += `### ${cat.charAt(0).toUpperCase() + cat.slice(1)}
 `;
     for (const r of catRules) {
-      text += `- ${r.text}
+      text2 += `- ${r.text}
 `;
     }
-    text += "\n";
+    text2 += "\n";
   }
   return `## Project Rules (${rules.length})
 
-${text.trim()}`;
+${text2.trim()}`;
 }
 async function fetchSpecBody(api, draftId) {
   const spec = await api.get(
@@ -1413,13 +1423,13 @@ function registerGetContext(server2, apiClient2) {
       }
     },
     async ({ task_description, file_paths, max_tokens }) => {
-      const { text } = await buildContext(apiClient2, {
+      const { text: text2 } = await buildContext(apiClient2, {
         taskDescription: task_description,
         filePaths: file_paths,
         maxTokens: max_tokens
       });
       return {
-        content: [{ type: "text", text }]
+        content: [{ type: "text", text: text2 }]
       };
     }
   );
@@ -1667,9 +1677,9 @@ function registerGetProjectRules(server2, apiClient2) {
         );
       }
       if (filtered.length === 0) {
-        const text2 = rules.length === 0 ? `No project rules found. Add rules at ${configLink("/docs/rules", await workspaceBase(apiClient2))}` : `No project rules found${category ? ` in category "${category}"` : ""}.`;
+        const text3 = rules.length === 0 ? `No project rules found. Add rules at ${configLink("/docs/rules", await workspaceBase(apiClient2))}` : `No project rules found${category ? ` in category "${category}"` : ""}.`;
         return {
-          content: [{ type: "text", text: text2 }]
+          content: [{ type: "text", text: text3 }]
         };
       }
       const grouped = /* @__PURE__ */ new Map();
@@ -1678,25 +1688,25 @@ function registerGetProjectRules(server2, apiClient2) {
         if (!grouped.has(cat)) grouped.set(cat, []);
         grouped.get(cat).push(rule);
       }
-      let text = `Found ${filtered.length} project rule(s):
+      let text2 = `Found ${filtered.length} project rule(s):
 
 `;
       for (const [cat, catRules] of grouped) {
         const label = CATEGORY_LABELS[cat] ?? cat;
-        text += `## ${label}
+        text2 += `## ${label}
 
 `;
         for (const rule of catRules) {
-          text += `- ${rule.text}
+          text2 += `- ${rule.text}
 `;
         }
-        text += "\n";
+        text2 += "\n";
       }
       return {
         content: [
           {
             type: "text",
-            text
+            text: text2
           }
         ]
       };
@@ -1722,10 +1732,10 @@ function registerCreateProjectRule(server2, apiClient2) {
         readOnlyHint: false
       }
     },
-    async ({ text, category }) => {
+    async ({ text: text2, category }) => {
       const saved = await apiClient2.post(
         "/v1/standards/rules",
-        { text, category }
+        { text: text2, category }
       );
       apiClient2.invalidateCache("/v1/standards/rules");
       return {
@@ -1763,7 +1773,7 @@ function registerGetPromptTemplates(server2, apiClient2) {
           ]
         };
       }
-      const text = templates.map(
+      const text2 = templates.map(
         (t) => `## ${t.name}
 
 ` + (t.description ? `*${t.description}*
@@ -1778,7 +1788,7 @@ ${t.prompt}
             type: "text",
             text: `Found ${templates.length} prompt template(s):
 
-${text}`
+${text2}`
           }
         ]
       };
@@ -1825,9 +1835,345 @@ function registerCreatePromptTemplate(server2, apiClient2) {
   );
 }
 
+// src/tools/skills.ts
+import { z as z13 } from "zod";
+import { homedir as homedir2 } from "os";
+import { basename, resolve as resolve2 } from "path";
+
+// src/lib/skills.ts
+import { createHash } from "crypto";
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, relative, resolve, sep } from "path";
+var MANIFEST_FILE = ".systemdox-skill.json";
+var ENTRY_FILE = "SKILL.md";
+var MAX_FILES = 100;
+var MAX_FILE_BYTES = 256 * 1024;
+var MAX_TOTAL_BYTES = 1024 * 1024;
+var NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+var SKIPPED = /* @__PURE__ */ new Set([MANIFEST_FILE, ".git", "node_modules", "__pycache__", ".DS_Store"]);
+var SkillInstallRefused = class extends Error {
+  constructor(dest, edited) {
+    super(
+      `${dest} has local changes in ${edited.length} file(s): ${edited.join(", ")}. Nothing was written. Move your changes aside, or install again with overwrite.`
+    );
+    this.dest = dest;
+    this.edited = edited;
+  }
+  dest;
+  edited;
+};
+function sha256(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function isValidName(name) {
+  return name.length <= 64 && NAME_RE.test(name);
+}
+function isValidPath(path) {
+  return path.length > 0 && path.length <= 512 && !path.startsWith("/") && path.split("/").every((s) => SEGMENT_RE.test(s) && s !== "." && s !== "..");
+}
+function frontmatterName(skillMd) {
+  const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
+  if (!block) return void 0;
+  const line = /^name:[ \t]*(.+?)[ \t]*$/m.exec(block[1]);
+  return line ? line[1].replace(/^(['"])(.*)\1$/, "$2") : void 0;
+}
+function defaultSkillDir(name) {
+  return join(homedir(), ".claude", "skills", name);
+}
+async function walk(root, { skipHidden }, dir = root, out = { files: [], links: [], hidden: [] }) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (SKIPPED.has(entry.name) || entry.name.endsWith(".pyc")) continue;
+    const full = join(dir, entry.name);
+    const rel = relative(root, full).split(sep).join("/");
+    if (entry.isSymbolicLink()) out.links.push(rel);
+    else if (skipHidden && entry.name.startsWith(".")) out.hidden.push(rel);
+    else if (entry.isDirectory()) await walk(root, { skipHidden }, full, out);
+    else if (entry.isFile()) out.files.push(rel);
+  }
+  out.files.sort();
+  return out;
+}
+async function readSkillDirectory(directory) {
+  const root = resolve(directory);
+  if (!existsSync(join(root, ENTRY_FILE))) {
+    throw new Error(`${root} has no ${ENTRY_FILE}: a skill folder holds SKILL.md at its root`);
+  }
+  const walked = await walk(root, { skipHidden: true });
+  if (walked.links.length) {
+    throw new Error(`${walked.links.join(", ")}: links are not followed; copy the file into the skill folder`);
+  }
+  const paths = walked.files;
+  if (paths.length > MAX_FILES) {
+    throw new Error(`${root} holds ${paths.length} files: a skill holds at most ${MAX_FILES}`);
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const files = [];
+  let total = 0;
+  for (const path of paths) {
+    if (!isValidPath(path)) {
+      throw new Error(`${path}: file names may use letters, digits, ".", "_" and "-" only`);
+    }
+    const raw = await readFile(join(root, ...path.split("/")));
+    if (raw.includes(0)) throw new Error(`${path} is binary: a skill holds text files only`);
+    if (raw.length > MAX_FILE_BYTES) {
+      throw new Error(`${path} is ${raw.length} bytes: a file holds at most ${MAX_FILE_BYTES}`);
+    }
+    total += raw.length;
+    if (total > MAX_TOTAL_BYTES) {
+      throw new Error(`the files pass ${MAX_TOTAL_BYTES} bytes at ${path}`);
+    }
+    let content;
+    try {
+      content = decoder.decode(raw);
+    } catch {
+      throw new Error(`${path} is not UTF-8 text`);
+    }
+    files.push({ path, content });
+  }
+  const skillMd = files.find((f) => f.path === ENTRY_FILE);
+  const name = frontmatterName(skillMd.content);
+  if (!name) throw new Error(`${ENTRY_FILE} has no frontmatter name`);
+  return { name, files, skipped: walked.hidden };
+}
+function within(dest, path) {
+  if (!isValidPath(path)) throw new Error(`refusing to write ${JSON.stringify(path)}: not a skill path`);
+  const full = resolve(dest, ...path.split("/"));
+  if (!full.startsWith(resolve(dest) + sep)) throw new Error(`refusing to write outside ${dest}: ${path}`);
+  return full;
+}
+async function readManifest(dest) {
+  try {
+    return JSON.parse(await readFile(join(dest, MANIFEST_FILE), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function installSkill(version, dest, { overwrite = false } = {}) {
+  if (!isValidName(version.name)) throw new Error(`refusing to install ${JSON.stringify(version.name)}: not a skill name`);
+  const incoming = new Map(version.files.map((f) => [f.path, f]));
+  for (const f of version.files) within(dest, f.path);
+  if (existsSync(dest) && (await lstat(dest)).isSymbolicLink()) {
+    throw new Error(`${dest} is a link: install into a real folder`);
+  }
+  const walked = existsSync(dest) ? await walk(dest, { skipHidden: false }) : { files: [], links: [], hidden: [] };
+  if (walked.links.length) {
+    throw new Error(`${dest} holds links (${walked.links.join(", ")}): remove them, nothing was written`);
+  }
+  const present = walked.files;
+  const manifest = await readManifest(dest);
+  const known = Object.fromEntries(
+    Object.entries(manifest?.files ?? {}).filter(([p, h]) => isValidPath(p) && typeof h === "string")
+  );
+  const edited = [];
+  const untracked = [];
+  for (const path of present) {
+    const content = await readFile(join(dest, ...path.split("/")), "utf8");
+    if (Object.hasOwn(known, path)) {
+      if (sha256(content) !== known[path]) edited.push(path);
+    } else if (!incoming.has(path) || sha256(content) !== incoming.get(path).sha256) {
+      if (incoming.has(path) || !manifest) edited.push(path);
+      else untracked.push(path);
+    }
+  }
+  const blocking = edited.filter((p) => incoming.has(p) || !manifest);
+  if (blocking.length && !overwrite) throw new SkillInstallRefused(dest, blocking);
+  const written = [];
+  for (const f of version.files) {
+    const full = within(dest, f.path);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, f.content, "utf8");
+    written.push(f.path);
+  }
+  const removed = [];
+  const keptEdited = [];
+  for (const path of Object.keys(known)) {
+    if (incoming.has(path) || !present.includes(path)) continue;
+    if (edited.includes(path)) {
+      keptEdited.push(path);
+      continue;
+    }
+    await rm(within(dest, path));
+    removed.push(path);
+  }
+  const next = {
+    name: version.name,
+    version: version.version,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    files: Object.fromEntries(version.files.map((f) => [f.path, f.sha256]))
+  };
+  await writeFile(join(dest, MANIFEST_FILE), JSON.stringify(next, null, 2) + "\n", "utf8");
+  return {
+    dest,
+    version: version.version,
+    written,
+    removed,
+    keptUntracked: untracked.filter((p) => !incoming.has(p)),
+    keptEdited
+  };
+}
+function fenceFor(text2) {
+  const longest = Math.max(0, ...(text2.match(/`+/g) ?? []).map((r) => r.length));
+  return "`".repeat(Math.max(3, longest + 1));
+}
+function describeInstall(name, r) {
+  const lines = [
+    `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
+  ];
+  if (r.removed.length) lines.push(`Removed (no longer in the skill): ${r.removed.join(", ")}`);
+  if (r.keptEdited.length) {
+    lines.push(`Kept, edited here and no longer in the skill: ${r.keptEdited.join(", ")}`);
+  }
+  if (r.keptUntracked.length) lines.push(`Kept, added here: ${r.keptUntracked.join(", ")}`);
+  lines.push("Start a new Claude Code session to load it.");
+  return lines.join("\n");
+}
+
+// src/tools/skills.ts
+var SKILLS = "/v1/standards/skills";
+function expandHome(path) {
+  return path.replace(/^~(?=$|[\\/])/, homedir2());
+}
+function text(t) {
+  return { content: [{ type: "text", text: t }] };
+}
+function registerSkillTools(server2, apiClient2, { localFiles }) {
+  const fileSchema = z13.object({
+    path: z13.string().describe('Path inside the skill folder, forward slashes, e.g. "references/guide.md"'),
+    content: z13.string().describe("The file's full text, exactly as it is")
+  });
+  server2.registerTool(
+    "publish_skill",
+    {
+      title: "Publish Skill",
+      description: localFiles ? "Publish a Claude Code skill folder (SKILL.md plus its references and scripts) to SystemDox so it can be installed on any computer. Pass `directory` (e.g. ~/.claude/skills/<name>): the server reads the files itself, byte for byte. Publishing a name again makes a new version. Never retype the files into `files` when the folder is on this computer." : "Publish a Claude Code skill (SKILL.md plus its references and scripts) to SystemDox so it can be installed on any computer. Pass every file of the folder in `files`, exactly as it is. Publishing a name again makes a new version.",
+      inputSchema: {
+        ...localFiles ? {
+          directory: z13.string().optional().describe("The skill folder on this computer, holding SKILL.md at its root")
+        } : {},
+        files: z13.array(fileSchema).optional().describe(localFiles ? "Only when there is no folder to read" : "Every file of the skill folder"),
+        name: z13.string().optional().describe("The skill's name; defaults to SKILL.md's frontmatter name and must match it"),
+        spaceId: z13.string().optional().describe("Space for a NEW skill (default: your default space)"),
+        note: z13.string().max(500).optional().describe(`A short change note for this version, shown in the console's history (e.g. "Fix the GA4 step")`),
+        baseVersion: z13.number().int().positive().optional().describe(
+          "The version these files were edited from. When given, the publish is refused (SYD-K017) if someone published a newer version since, instead of replacing their changes"
+        )
+      },
+      annotations: { readOnlyHint: false }
+    },
+    async (args) => {
+      let files;
+      let name;
+      let skipped = [];
+      if (localFiles && args.directory) {
+        ({ name, files, skipped } = await readSkillDirectory(expandHome(args.directory)));
+      } else if (args.files?.length) {
+        files = args.files;
+        const entry = files.find((f) => f.path === ENTRY_FILE);
+        name = entry ? frontmatterName(entry.content) : void 0;
+      } else {
+        throw new Error(localFiles ? "Pass `directory` (or `files`)." : "Pass `files`.");
+      }
+      name = args.name ?? name;
+      if (!name) throw new Error(`${ENTRY_FILE} has no frontmatter name; pass \`name\`.`);
+      const saved = await apiClient2.post(
+        `${SKILLS}/${encodeURIComponent(name)}/versions`,
+        {
+          files,
+          ...args.spaceId ? { spaceId: args.spaceId } : {},
+          ...args.note ? { note: args.note } : {},
+          ...args.baseVersion ? { baseVersion: args.baseVersion } : {}
+        }
+      );
+      apiClient2.invalidateCache(SKILLS);
+      return text(
+        `Published **${saved.name}** version ${saved.version} (${saved.fileCount} file(s), ${saved.totalBytes} bytes).
+Install it anywhere with: npx -y @systemdox/mcp-server install-skill ${saved.name}` + (skipped.length ? `
+Left out (hidden files are never part of a skill): ${skipped.join(", ")}` : "")
+      );
+    }
+  );
+  server2.registerTool(
+    "list_skills",
+    {
+      title: "List Skills",
+      description: "List the Claude Code skills published to SystemDox that you can install: name, description, latest version. Use install_skill to install one.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true }
+    },
+    async () => {
+      const { skills } = await apiClient2.get(SKILLS);
+      if (!skills.length) {
+        return text(
+          `No skills published yet. Publish one with publish_skill; they appear at ${configLink("/docs/skills", await workspaceBase(apiClient2))}`
+        );
+      }
+      return text(
+        `${skills.length} skill(s):
+
+` + skills.map((s) => `- **${s.name}** (version ${s.latestVersion}, updated ${s.updatedAt.slice(0, 10)}): ${s.description}`).join("\n")
+      );
+    }
+  );
+  server2.registerTool(
+    "install_skill",
+    {
+      title: "Install Skill",
+      description: localFiles ? "Install a skill published to SystemDox onto this computer (default ~/.claude/skills/<name>/). Refuses, naming the files, when a file there was edited since it was installed, unless overwrite is true. Never runs anything." : "Fetch a skill published to SystemDox so you can install it: returns every file and the folder to write them into (default ~/.claude/skills/<name>/). Write each file exactly, then the manifest it shows.",
+      inputSchema: {
+        name: z13.string().describe("The skill's name"),
+        version: z13.number().int().positive().optional().describe("A version number (default: the latest)"),
+        target: z13.string().optional().describe("Folder to install into, e.g. a repo's .claude/skills/<name>"),
+        ...localFiles ? { overwrite: z13.boolean().optional().describe("Replace files edited since they were installed") } : {}
+      },
+      annotations: { readOnlyHint: !localFiles }
+    },
+    async (args) => {
+      const version = await apiClient2.getFresh(
+        `${SKILLS}/${encodeURIComponent(args.name)}/versions/${args.version ?? "latest"}`
+      );
+      if (localFiles) {
+        const dest2 = args.target ? expandHome(args.target) : defaultSkillDir(version.name);
+        if (basename(resolve2(dest2)) !== version.name) {
+          throw new Error(`target must be a folder named ${version.name} (e.g. .claude/skills/${version.name}); got ${dest2}`);
+        }
+        const result = await installSkill(version, dest2, { overwrite: args.overwrite });
+        return text(describeInstall(version.name, result));
+      }
+      const dest = args.target ?? `~/.claude/skills/${version.name}`;
+      const manifest = {
+        name: version.name,
+        version: version.version,
+        installedAt: "<now, ISO 8601>",
+        files: Object.fromEntries(version.files.map((f) => [f.path, f.sha256]))
+      };
+      const body = version.files.map((f) => {
+        const fence = fenceFor(f.content);
+        return `### ${f.path}
+
+${fence}
+${f.content}${f.content.endsWith("\n") ? "" : "\n"}${fence}`;
+      }).join("\n\n");
+      return text(
+        `Skill **${version.name}** version ${version.version}: write these ${version.files.length} file(s) into ${dest}/ exactly as shown (the content between the fences), creating folders as needed. If a file there differs from ${MANIFEST_FILE}'s hash for it, it was edited: ask before replacing it. Then write ${MANIFEST_FILE} with this content, and tell the user to start a new Claude Code session.
+
+### ${MANIFEST_FILE}
+
+\`\`\`json
+${JSON.stringify(manifest, null, 2)}
+\`\`\`
+
+${body}`
+      );
+    }
+  );
+}
+
 // src/server.ts
-var SERVER_VERSION = true ? "0.1.42" : "0.0.0-dev";
-function createServer(apiClient2) {
+var SERVER_VERSION = true ? "0.1.44" : "0.0.0-dev";
+function createServer(apiClient2, { localFiles = false } = {}) {
   const server2 = new McpServer({
     name: "systemdox-mcp-server",
     version: SERVER_VERSION
@@ -1846,13 +2192,14 @@ function createServer(apiClient2) {
   registerReportDecision(server2, apiClient2);
   registerCreateProjectRule(server2, apiClient2);
   registerCreatePromptTemplate(server2, apiClient2);
+  registerSkillTools(server2, apiClient2, { localFiles });
   return server2;
 }
 
 // src/index.ts
 var config = loadConfig();
 var apiClient = new SystemDoxApiClient(config);
-var server = createServer(apiClient);
+var server = createServer(apiClient, { localFiles: true });
 async function main() {
   await apiClient.validate();
   const transport = new StdioServerTransport();

package/dist/install-skill.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `systemdox-mcp-server install-skill <name>` — what the console's Install
+ * button copies (ADR-216 §2.3). Installs a published skill onto this computer
+ * with no model in the loop, through the same code and the same edit check as
+ * the stdio server's install_skill tool.
+ *
+ * Exit codes: 0 installed; 1 usage, no key, or the API refused; 2 refused
+ * because files in the folder were edited since they were installed.
+ */
+import { SystemDoxApiClient } from "./lib/api-client.js";
+export declare const INSTALL_USAGE = "Usage: systemdox-mcp-server install-skill <name> [--version <n>] [--target <dir>] [--overwrite]";
+export interface InstallArgs {
+    name: string;
+    version?: number;
+    target?: string;
+    overwrite: boolean;
+}
+export declare function parseInstallArgs(argv: string[]): InstallArgs;
+interface Io {
+    out: (line: string) => void;
+    err: (line: string) => void;
+    client?: Pick<SystemDoxApiClient, "getFresh">;
+}
+export declare function runInstallSkill(argv: string[], io: Io): Promise<number>;
+export {};