@cubis/foundry 0.3.61 → 0.3.63

package/dist/cli/init/execute.js

@@ -1,7 +1,7 @@
 function hasMcpSelection(selectedMcps, mcpId) {
     return selectedMcps.includes(mcpId);
 }
-export function buildInitExecutionPlan({ selections, dryRun, target, }) {
+export function buildInitExecutionPlan({ selections, dryRun, overwrite, target, }) {
     const planItems = [];
     const wantsPostman = hasMcpSelection(selections.selectedMcps, "postman");
     const wantsStitch = hasMcpSelection(selections.selectedMcps, "stitch");
@@ -20,6 +20,7 @@ export function buildInitExecutionPlan({ selections, dryRun, target, }) {
             skillProfile: selections.skillProfile,
             allSkills: selections.skillProfile === "full",
             dryRun,
+            overwrite,
             yes: true,
             target,
             postman: wantsPostman,

package/dist/cli/init/execute.js.map

@@ -1 +1 @@
-{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../../src/cli/init/execute.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../../src/cli/init/execute.ts"],"names":[],"mappings":"AAOA,SAAS,eAAe,CAAC,YAAyB,EAAE,KAAgB;IAClE,OAAO,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,EACrC,UAAU,EACV,MAAM,EACN,SAAS,EACT,MAAM,GAMP;IACC,MAAM,SAAS,GAA4B,EAAE,CAAC;IAC9C,MAAM,YAAY,GAAG,eAAe,CAAC,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IACzE,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACvE,MAAM,YAAY,GAAG,eAAe,CAAC,UAAU,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;IAE/E,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QAC5C,MAAM,eAAe,GAAG,QAAQ,KAAK,aAAa,CAAC;QACnD,MAAM,aAAa,GAAG,WAAW,IAAI,eAAe,CAAC;QACrD,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,IAAI,WAAW,IAAI,CAAC,eAAe,EAAE,CAAC;YACpC,QAAQ,CAAC,IAAI,CACX,+BAA+B,QAAQ,0CAA0C,CAClF,CAAC;QACJ,CAAC;QAED,MAAM,cAAc,GAA4B;YAC9C,QAAQ;YACR,KAAK,EAAE,UAAU,CAAC,WAAW;YAC7B,MAAM,EAAE,UAAU,CAAC,QAAQ;YAC3B,YAAY,EAAE,UAAU,CAAC,YAAY;YACrC,SAAS,EAAE,UAAU,CAAC,YAAY,KAAK,MAAM;YAC7C,MAAM;YACN,SAAS;YACT,GAAG,EAAE,IAAI;YACT,MAAM;YACN,OAAO,EAAE,YAAY;YACrB,MAAM,EAAE,aAAa;YACrB,2BAA2B,EAAE,KAAK;YAClC,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,UAAU,EAAE,YAAY;YACxB,WAAW,EAAE,YAAY,IAAI,aAAa;YAC1C,UAAU,EAAE,YAAY,IAAI,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO;YAC3E,WAAW,EAAE,OAAO;YACpB,aAAa,EACX,YAAY,IAAI,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK;YAClE,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;YAC9D,kBAAkB,EAAE,YAAY;gBAC9B,CAAC,CAAC,UAAU,CAAC,kBAAkB;gBAC/B,CAAC,CAAC,SAAS;YACb,cAAc,EAAE,IAAI;SACrB,CAAC;QAEF,SAAS,CAAC,IAAI,CAAC;YACb,QAAQ;YACR,cAAc;YACd,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,KAAK,EAAE,SAAS;KACjB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,UAAgC;IAChE,MAAM,eAAe,GAAG,UAAU,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACpE,OAAO;QACL,oBAAoB;QACpB,aAAa,UAAU,CAAC,QAAQ,EAAE;QAClC,gBAAgB,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACjD,oBAAoB,UAAU,CAAC,YAAY,EAAE;QAC7C,mBAAmB,UAAU,CAAC,WAAW,EAAE;QAC3C,gBAAgB,UAAU,CAAC,QAAQ,EAAE;QACrC,kBAAkB,UAAU,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE;QACzJ,qBAAqB,UAAU,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;QACzG,mBAAmB,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,gBAAgB,EAAE;QAChF,wBAAwB,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,kBAAkB,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,gBAAgB,EAAE;KAC/I,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/mcp/README.md

@@ -24,13 +24,13 @@ This server exposes built-in tools plus dynamic passthrough tools discovered fro
 
 | Domain      | Tools | Purpose                                                       |
 | ----------- | ----- | ------------------------------------------------------------- |
-| **Skills**               | 5        | Browse/search/get + budget reporting for skill definitions          |
+| **Skills**               | 7        | Browse/search/validate/get + targeted reference loading for skills  |
 | **Postman config**       | 3        | Read/write Postman MCP mode in `cbx_config.json`                   |
 | **Stitch config**        | 3        | Read/write Stitch active profile in `cbx_config.json`              |
 | **Postman passthrough**  | dynamic  | `postman.<tool_name>` for all discovered upstream Postman tools    |
 | **Stitch passthrough**   | dynamic  | `stitch.<tool_name>` for all discovered upstream Stitch tools       |
 
-The skill vault uses a **lazy content model**: startup only scans metadata (category/name/path). Full `SKILL.md` content is loaded on-demand via `skill_get` only.
+The skill vault uses a **lazy content model**: startup only scans metadata (category/name/path). Exact skill selection is validated via `skill_validate`, `skill_get` loads the core `SKILL.md`, and sidecar markdown is loaded only when needed via `skill_get_reference`.
 
 ## Architecture
 
@@ -67,7 +67,9 @@ mcp/
 │   │   ├── skillListCategories.ts
 │   │   ├── skillBrowseCategory.ts
 │   │   ├── skillSearch.ts
+│   │   ├── skillValidate.ts
 │   │   ├── skillGet.ts
+│   │   ├── skillGetReference.ts
 │   │   ├── skillBudgetReport.ts
 │   │   ├── postmanModes.ts    # Mode ↔ URL mapping
 │   │   ├── postmanGetMode.ts
@@ -269,6 +271,32 @@ Search skills by keyword.
 }
 ```
 
+#### `skill_validate`
+
+Validate an exact skill ID before loading it.
+
+**Input**:
+
+```json
+{ "id": "flutter-expert" }
+```
+
+**Output**:
+
+```json
+{
+  "id": "flutter-expert",
+  "exists": true,
+  "canonicalId": "flutter-expert",
+  "category": "mobile",
+  "description": "Flutter app architecture...",
+  "isWrapper": false,
+  "isAlias": false,
+  "replacementId": null,
+  "availableReferences": ["references/project-structure.md"]
+}
+```
+
 #### `skill_get`
 
 Get the full SKILL.md content for a specific skill.
@@ -276,12 +304,30 @@ Get the full SKILL.md content for a specific skill.
 **Input**:
 
 ```json
-{ "id": "nestjs-expert" }
+{ "id": "nestjs-expert", "includeReferences": false }
 ```
 
 **Output**: Full markdown content of the skill file (as `type: "text"` content block).
 `structuredContent.metrics` includes `loadedSkillEstimatedTokens` and estimated savings vs full catalog.
 
+By policy, agents should call `includeReferences: false` by default and fetch sidecar docs only when needed.
+
+#### `skill_get_reference`
+
+Get one validated markdown sidecar file for a skill.
+
+**Input**:
+
+```json
+{
+  "id": "flutter-expert",
+  "path": "references/project-structure.md"
+}
+```
+
+**Output**: Raw markdown content of the requested reference file (as `type: "text"` content block).
+`structuredContent` includes the resolved relative path and token metrics.
+
 #### `skill_budget_report`
 
 Consolidated Skill Log + Context Budget report for selected/loaded skill IDs.

package/mcp/dist/index.js

@@ -433,6 +433,36 @@ async function readFullSkillContent(skillPath) {
 }
 var MARKDOWN_LINK_RE = /\[[^\]]+\]\(([^)]+)\)/g;
 var MAX_REFERENCED_FILES = 25;
+function parseFrontmatter2(content) {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
+  if (!match) return { raw: "", body: content };
+  return { raw: match[1], body: content.slice(match[0].length) };
+}
+function parseMetadataFromFrontmatter(frontmatter) {
+  const lines = frontmatter.split(/\r?\n/);
+  const metadata = {};
+  let inMetadata = false;
+  for (const line of lines) {
+    if (/^metadata\s*:\s*$/.test(line)) {
+      inMetadata = true;
+      continue;
+    }
+    if (!inMetadata) continue;
+    if (!line.trim()) continue;
+    if (!/^\s+/.test(line)) break;
+    const kv = line.match(/^\s+([A-Za-z0-9_-]+)\s*:\s*(.+)\s*$/);
+    if (!kv) continue;
+    metadata[kv[1]] = kv[2].trim().replace(/^['"]|['"]$/g, "");
+  }
+  return metadata;
+}
+function parseSkillFrontmatter(content) {
+  const { raw } = parseFrontmatter2(content);
+  return {
+    description: parseDescriptionFromFrontmatter(content, Number.MAX_SAFE_INTEGER),
+    metadata: parseMetadataFromFrontmatter(raw)
+  };
+}
 function normalizeLinkTarget(rawTarget) {
   let target = String(rawTarget || "").trim();
   if (!target) return null;
@@ -519,6 +549,36 @@ async function collectSiblingMarkdownTargets(skillDir) {
   targets.sort((a, b) => a.localeCompare(b));
   return targets;
 }
+async function listReferencedMarkdownPaths(skillPath, skillContent) {
+  const source = skillContent ?? await readFullSkillContent(skillPath);
+  const skillDir = path3.dirname(skillPath);
+  const explicitTargets = collectReferencedMarkdownTargets(source);
+  const siblingTargets = await collectSiblingMarkdownTargets(skillDir);
+  const merged = /* @__PURE__ */ new Set([...explicitTargets, ...siblingTargets]);
+  return [...merged].sort((a, b) => a.localeCompare(b)).slice(0, MAX_REFERENCED_FILES);
+}
+async function readSkillReferenceFile(skillPath, relativePath) {
+  const normalized = String(relativePath || "").trim();
+  if (!normalized || !normalized.toLowerCase().endsWith(".md")) {
+    throw new Error("Reference path must be a non-empty relative markdown file.");
+  }
+  const available = await listReferencedMarkdownPaths(skillPath);
+  if (!available.includes(normalized)) {
+    throw new Error(
+      `Reference path "${normalized}" is not available for this skill.`
+    );
+  }
+  const skillDir = path3.dirname(skillPath);
+  const resolved = path3.resolve(skillDir, normalized);
+  const relative = path3.relative(skillDir, resolved);
+  if (relative.startsWith("..") || path3.isAbsolute(relative)) {
+    throw new Error(`Reference path "${normalized}" escapes the skill directory.`);
+  }
+  return {
+    relativePath: relative.split(path3.sep).join("/"),
+    content: await readFile(resolved, "utf8")
+  };
+}
 async function readSkillContentWithReferences(skillPath, includeReferences = true) {
   const skillContent = await readFullSkillContent(skillPath);
   if (!includeReferences) {
@@ -527,6 +587,10 @@ async function readSkillContentWithReferences(skillPath, includeReferences = tru
   const references = await readReferencedMarkdownFiles(skillPath, skillContent);
   return { skillContent, references };
 }
+async function readSkillFrontmatter(skillPath) {
+  const content = await readFullSkillContent(skillPath);
+  return parseSkillFrontmatter(content);
+}
 async function enrichWithDescriptions(skills, maxLength) {
   return Promise.all(
     skills.map(async (skill) => {
@@ -539,7 +603,7 @@ async function enrichWithDescriptions(skills, maxLength) {
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z13 } from "zod";
+import { z as z15 } from "zod";
 
 // src/tools/skillListCategories.ts
 import { z as z2 } from "zod";
@@ -709,13 +773,85 @@ async function handleSkillSearch(args, manifest, summaryMaxLength, charsPerToken
   };
 }
 
-// src/tools/skillGet.ts
+// src/tools/skillValidate.ts
 import { z as z5 } from "zod";
+var skillValidateName = "skill_validate";
+var skillValidateDescription = "Validate an exact skill ID before loading it. Returns alias metadata and discoverable reference markdown paths.";
+var skillValidateSchema = z5.object({
+  id: z5.string().describe("The exact skill ID (directory name) to validate")
+});
+function assertConcreteSkillId(id) {
+  if (id.startsWith("workflow-") || id.startsWith("agent-")) {
+    invalidInput(
+      `Skill id "${id}" appears to be a wrapper id. Use workflow/agent routing (for example $workflow-implement-track or $agent-backend-specialist) and call skill_get only for concrete skill ids.`
+    );
+  }
+}
+async function handleSkillValidate(args, manifest, charsPerToken) {
+  const { id } = args;
+  assertConcreteSkillId(id);
+  const skill = manifest.skills.find((entry) => entry.id === id);
+  if (!skill) {
+    const payload2 = {
+      id,
+      exists: false,
+      canonicalId: null,
+      category: null,
+      description: null,
+      isWrapper: false,
+      isAlias: false,
+      replacementId: null,
+      availableReferences: []
+    };
+    const text2 = JSON.stringify(payload2, null, 2);
+    const metrics2 = buildSkillToolMetrics({
+      charsPerToken,
+      fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+      responseEstimatedTokens: estimateTokensFromText(text2, charsPerToken),
+      responseCharacterCount: text2.length
+    });
+    return {
+      content: [{ type: "text", text: text2 }],
+      structuredContent: { ...payload2, metrics: metrics2 },
+      _meta: { metrics: metrics2 }
+    };
+  }
+  const frontmatter = await readSkillFrontmatter(skill.path);
+  const replacementId = frontmatter.metadata.replaced_by || frontmatter.metadata.alias_of || null;
+  const isAlias = Boolean(replacementId || frontmatter.metadata.deprecated);
+  const availableReferences = await listReferencedMarkdownPaths(skill.path);
+  const payload = {
+    id,
+    exists: true,
+    canonicalId: replacementId || skill.id,
+    category: skill.category,
+    description: frontmatter.description || skill.description || null,
+    isWrapper: false,
+    isAlias,
+    replacementId,
+    availableReferences
+  };
+  const text = JSON.stringify(payload, null, 2);
+  const metrics = buildSkillToolMetrics({
+    charsPerToken,
+    fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+    responseEstimatedTokens: estimateTokensFromText(text, charsPerToken),
+    responseCharacterCount: text.length
+  });
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: { ...payload, metrics },
+    _meta: { metrics }
+  };
+}
+
+// src/tools/skillGet.ts
+import { z as z6 } from "zod";
 var skillGetName = "skill_get";
 var skillGetDescription = "Get full content of a specific skill by ID. Returns SKILL.md content and optionally direct referenced markdown files.";
-var skillGetSchema = z5.object({
-  id: z5.string().describe("The skill ID (directory name) to retrieve"),
-  includeReferences: z5.boolean().optional().describe(
+var skillGetSchema = z6.object({
+  id: z6.string().describe("The skill ID (directory name) to retrieve"),
+  includeReferences: z6.boolean().optional().describe(
     "Whether to include direct local markdown references from SKILL.md (default: true)"
   )
 });
@@ -780,13 +916,63 @@ async function handleSkillGet(args, manifest, charsPerToken) {
   };
 }
 
+// src/tools/skillGetReference.ts
+import { z as z7 } from "zod";
+var skillGetReferenceName = "skill_get_reference";
+var skillGetReferenceDescription = "Get one validated markdown reference file for a skill by exact relative path.";
+var skillGetReferenceSchema = z7.object({
+  id: z7.string().describe("The exact skill ID (directory name)"),
+  path: z7.string().describe("Exact relative markdown reference path exposed by skill_validate")
+});
+function assertConcreteSkillId2(id) {
+  if (id.startsWith("workflow-") || id.startsWith("agent-")) {
+    invalidInput(
+      `Skill id "${id}" appears to be a wrapper id. Use workflow/agent routing (for example $workflow-implement-track or $agent-backend-specialist) and call skill_get only for concrete skill ids.`
+    );
+  }
+}
+async function handleSkillGetReference(args, manifest, charsPerToken) {
+  const { id, path: path8 } = args;
+  assertConcreteSkillId2(id);
+  const skill = manifest.skills.find((entry) => entry.id === id);
+  if (!skill) {
+    notFound("Skill", id);
+  }
+  let reference;
+  try {
+    reference = await readSkillReferenceFile(skill.path, path8);
+  } catch (error) {
+    invalidInput(error instanceof Error ? error.message : String(error));
+  }
+  const metrics = buildSkillToolMetrics({
+    charsPerToken,
+    fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+    responseEstimatedTokens: estimateTokensFromText(
+      reference.content,
+      charsPerToken
+    ),
+    responseCharacterCount: reference.content.length
+  });
+  return {
+    content: [{ type: "text", text: reference.content }],
+    structuredContent: {
+      skillId: id,
+      path: reference.relativePath,
+      metrics
+    },
+    _meta: {
+      metrics
+    }
+  };
+}
+
 // src/tools/skillBudgetReport.ts
-import { z as z6 } from "zod";
+import { z as z8 } from "zod";
 var skillBudgetReportName = "skill_budget_report";
 var skillBudgetReportDescription = "Report estimated context/token budget for selected and loaded skills compared to the full skill catalog.";
-var skillBudgetReportSchema = z6.object({
-  selectedSkillIds: z6.array(z6.string()).default([]).describe("Skill IDs selected after search/browse."),
-  loadedSkillIds: z6.array(z6.string()).default([]).describe("Skill IDs loaded via skill_get.")
+var skillBudgetReportSchema = z8.object({
+  selectedSkillIds: z8.array(z8.string()).default([]).describe("Skill IDs selected after search/browse."),
+  loadedSkillIds: z8.array(z8.string()).default([]).describe("Skill IDs loaded via skill_get.")
 });
 function uniqueStrings(values) {
   return [...new Set(values.map((value) => String(value)))];
@@ -876,7 +1062,7 @@ function handleSkillBudgetReport(args, manifest, charsPerToken) {
 }
 
 // src/tools/postmanGetMode.ts
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 
 // src/cbxConfig/paths.ts
 import path4 from "path";
@@ -1136,8 +1322,8 @@ function isValidMode(mode) {
 // src/tools/postmanGetMode.ts
 var postmanGetModeName = "postman_get_mode";
 var postmanGetModeDescription = "Get the current Postman MCP mode from cbx_config.json. Returns the friendly mode name and URL.";
-var postmanGetModeSchema = z7.object({
-  scope: z7.enum(["global", "project", "auto"]).optional().describe(
+var postmanGetModeSchema = z9.object({
+  scope: z9.enum(["global", "project", "auto"]).optional().describe(
     "Config scope to read. Default: auto (project if exists, else global)"
   )
 });
@@ -1192,12 +1378,12 @@ function handlePostmanGetMode(args) {
 }
 
 // src/tools/postmanSetMode.ts
-import { z as z8 } from "zod";
+import { z as z10 } from "zod";
 var postmanSetModeName = "postman_set_mode";
 var postmanSetModeDescription = "Set the Postman MCP mode in cbx_config.json. Modes: minimal, code, full.";
-var postmanSetModeSchema = z8.object({
-  mode: z8.enum(["minimal", "code", "full"]).describe("Postman MCP mode to set: minimal, code, or full"),
-  scope: z8.enum(["global", "project", "auto"]).optional().describe(
+var postmanSetModeSchema = z10.object({
+  mode: z10.enum(["minimal", "code", "full"]).describe("Postman MCP mode to set: minimal, code, or full"),
+  scope: z10.enum(["global", "project", "auto"]).optional().describe(
     "Config scope to write. Default: auto (project if exists, else global)"
   )
 });
@@ -1236,11 +1422,11 @@ function handlePostmanSetMode(args) {
 }
 
 // src/tools/postmanGetStatus.ts
-import { z as z9 } from "zod";
+import { z as z11 } from "zod";
 var postmanGetStatusName = "postman_get_status";
 var postmanGetStatusDescription = "Get full Postman configuration status including mode, URL, and workspace ID.";
-var postmanGetStatusSchema = z9.object({
-  scope: z9.enum(["global", "project", "auto"]).optional().describe(
+var postmanGetStatusSchema = z11.object({
+  scope: z11.enum(["global", "project", "auto"]).optional().describe(
     "Config scope to read. Default: auto (project if exists, else global)"
   )
 });
@@ -1280,11 +1466,11 @@ function handlePostmanGetStatus(args) {
 }
 
 // src/tools/stitchGetMode.ts
-import { z as z10 } from "zod";
+import { z as z12 } from "zod";
 var stitchGetModeName = "stitch_get_mode";
 var stitchGetModeDescription = "Get the active Stitch profile name and URL from cbx_config.json. Never exposes API keys.";
-var stitchGetModeSchema = z10.object({
-  scope: z10.enum(["global", "project", "auto"]).optional().describe(
+var stitchGetModeSchema = z12.object({
+  scope: z12.enum(["global", "project", "auto"]).optional().describe(
     "Config scope to read. Default: auto (project if exists, else global)"
   )
 });
@@ -1319,12 +1505,12 @@ function handleStitchGetMode(args) {
 }
 
 // src/tools/stitchSetProfile.ts
-import { z as z11 } from "zod";
+import { z as z13 } from "zod";
 var stitchSetProfileName = "stitch_set_profile";
 var stitchSetProfileDescription = "Set the active Stitch profile in cbx_config.json. The profile must already exist in the config.";
-var stitchSetProfileSchema = z11.object({
-  profileName: z11.string().min(1).describe("Name of the Stitch profile to activate"),
-  scope: z11.enum(["global", "project", "auto"]).optional().describe(
+var stitchSetProfileSchema = z13.object({
+  profileName: z13.string().min(1).describe("Name of the Stitch profile to activate"),
+  scope: z13.enum(["global", "project", "auto"]).optional().describe(
     "Config scope to write. Default: auto (project if exists, else global)"
   )
 });
@@ -1369,11 +1555,11 @@ function handleStitchSetProfile(args) {
 }
 
 // src/tools/stitchGetStatus.ts
-import { z as z12 } from "zod";
+import { z as z14 } from "zod";
 var stitchGetStatusName = "stitch_get_status";
 var stitchGetStatusDescription = "Get full Stitch configuration status including active profile, all profile names, and URLs. Never exposes API keys.";
-var stitchGetStatusSchema = z12.object({
-  scope: z12.enum(["global", "project", "auto"]).optional().describe(
+var stitchGetStatusSchema = z14.object({
+  scope: z14.enum(["global", "project", "auto"]).optional().describe(
     "Config scope to read. Default: auto (project if exists, else global)"
   )
 });
@@ -1458,6 +1644,17 @@ var TOOL_REGISTRY = [
       ctx.charsPerToken
     )
   },
+  {
+    name: skillValidateName,
+    description: skillValidateDescription,
+    schema: skillValidateSchema,
+    category: "skill",
+    createHandler: (ctx) => async (args) => handleSkillValidate(
+      args,
+      ctx.manifest,
+      ctx.charsPerToken
+    )
+  },
   {
     name: skillGetName,
     description: skillGetDescription,
@@ -1469,6 +1666,17 @@ var TOOL_REGISTRY = [
       ctx.charsPerToken
     )
   },
+  {
+    name: skillGetReferenceName,
+    description: skillGetReferenceDescription,
+    schema: skillGetReferenceSchema,
+    category: "skill",
+    createHandler: (ctx) => async (args) => handleSkillGetReference(
+      args,
+      ctx.manifest,
+      ctx.charsPerToken
+    )
+  },
   {
     name: skillBudgetReportName,
     description: skillBudgetReportDescription,
@@ -1850,7 +2058,7 @@ async function createServer({
     `Registered ${TOOL_REGISTRY.length} built-in tools from registry`
   );
   const upstreamCatalogs = await discoverUpstreamCatalogs(defaultConfigScope);
-  const dynamicSchema = z13.object({}).passthrough();
+  const dynamicSchema = z15.object({}).passthrough();
   const registeredDynamicToolNames = /* @__PURE__ */ new Set();
   for (const catalog of [upstreamCatalogs.postman, upstreamCatalogs.stitch]) {
     for (const tool of catalog.tools) {

package/mcp/src/tools/index.ts

@@ -40,6 +40,13 @@ export {
   handleSkillSearch,
 } from "./skillSearch.js";
 
+export {
+  skillValidateName,
+  skillValidateDescription,
+  skillValidateSchema,
+  handleSkillValidate,
+} from "./skillValidate.js";
+
 export {
   skillGetName,
   skillGetDescription,
@@ -47,6 +54,13 @@ export {
   handleSkillGet,
 } from "./skillGet.js";
 
+export {
+  skillGetReferenceName,
+  skillGetReferenceDescription,
+  skillGetReferenceSchema,
+  handleSkillGetReference,
+} from "./skillGetReference.js";
+
 export {
   skillBudgetReportName,
   skillBudgetReportDescription,

package/mcp/src/tools/registry.test.ts

@@ -38,7 +38,9 @@ describe("tool registry", () => {
     expect(names).toContain("skill_list_categories");
     expect(names).toContain("skill_browse_category");
     expect(names).toContain("skill_search");
+    expect(names).toContain("skill_validate");
     expect(names).toContain("skill_get");
+    expect(names).toContain("skill_get_reference");
     expect(names).toContain("skill_budget_report");
     expect(names).toContain("postman_get_mode");
     expect(names).toContain("postman_set_mode");
@@ -48,8 +50,8 @@ describe("tool registry", () => {
     expect(names).toContain("stitch_get_status");
   });
 
-  it("has exactly 11 built-in tools", () => {
-    expect(TOOL_REGISTRY).toHaveLength(11);
+  it("has exactly 13 built-in tools", () => {
+    expect(TOOL_REGISTRY).toHaveLength(13);
   });
 
   it("has no duplicate tool names", () => {
@@ -70,7 +72,7 @@ describe("tool registry", () => {
 
   it("filters by category", () => {
     const skillTools = getToolsByCategory("skill");
-    expect(skillTools).toHaveLength(5);
+    expect(skillTools).toHaveLength(7);
     expect(skillTools.every((t) => t.category === "skill")).toBe(true);
 
     const postmanTools = getToolsByCategory("postman");
@@ -103,11 +105,11 @@ describe("tool registry", () => {
 
   it("buildRegistrySummary produces correct structure", () => {
     const summary = buildRegistrySummary();
-    expect(summary.totalTools).toBe(11);
+    expect(summary.totalTools).toBe(13);
     expect(summary.categories).toHaveProperty("skill");
     expect(summary.categories).toHaveProperty("postman");
     expect(summary.categories).toHaveProperty("stitch");
-    expect(summary.categories.skill.tools).toHaveLength(5);
+    expect(summary.categories.skill.tools).toHaveLength(7);
     expect(summary.categories.postman.tools).toHaveLength(3);
     expect(summary.categories.stitch.tools).toHaveLength(3);
   });

package/mcp/src/tools/registry.ts

@@ -67,6 +67,13 @@ import {
   handleSkillSearch,
 } from "./skillSearch.js";
 
+import {
+  skillValidateName,
+  skillValidateDescription,
+  skillValidateSchema,
+  handleSkillValidate,
+} from "./skillValidate.js";
+
 import {
   skillGetName,
   skillGetDescription,
@@ -74,6 +81,13 @@ import {
   handleSkillGet,
 } from "./skillGet.js";
 
+import {
+  skillGetReferenceName,
+  skillGetReferenceDescription,
+  skillGetReferenceSchema,
+  handleSkillGetReference,
+} from "./skillGetReference.js";
+
 import {
   skillBudgetReportName,
   skillBudgetReportDescription,
@@ -175,6 +189,18 @@ export const TOOL_REGISTRY: readonly ToolRegistryEntry[] = [
         ctx.charsPerToken,
       ),
   },
+  {
+    name: skillValidateName,
+    description: skillValidateDescription,
+    schema: skillValidateSchema,
+    category: "skill",
+    createHandler: (ctx) => async (args) =>
+      handleSkillValidate(
+        args as z.infer<typeof skillValidateSchema>,
+        ctx.manifest,
+        ctx.charsPerToken,
+      ),
+  },
   {
     name: skillGetName,
     description: skillGetDescription,
@@ -187,6 +213,18 @@ export const TOOL_REGISTRY: readonly ToolRegistryEntry[] = [
         ctx.charsPerToken,
       ),
   },
+  {
+    name: skillGetReferenceName,
+    description: skillGetReferenceDescription,
+    schema: skillGetReferenceSchema,
+    category: "skill",
+    createHandler: (ctx) => async (args) =>
+      handleSkillGetReference(
+        args as z.infer<typeof skillGetReferenceSchema>,
+        ctx.manifest,
+        ctx.charsPerToken,
+      ),
+  },
   {
     name: skillBudgetReportName,
     description: skillBudgetReportDescription,