@clawpify/skills 1.0.5 → 1.0.7

package/dist/index.js

@@ -87,6 +87,54 @@ async function createAuthenticatedConfig() {
 ` + "  - SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET (OAuth client credentials)");
 }
 
+// src/skills.ts
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+async function loadSkills(customDir) {
+  const baseDir = customDir ?? join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const skillParts = [];
+  await collectMarkdown(baseDir, skillParts);
+  return skillParts.join(`
+
+---
+
+`);
+}
+async function loadSkillMetadata(customDir) {
+  const baseDir = customDir ?? join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const skillPath = join(baseDir, "SKILL.md");
+  return readFile(skillPath, "utf-8");
+}
+async function loadSkillReference(name, customDir) {
+  const baseDir = customDir ?? join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const refPath = join(baseDir, "references", name.endsWith(".md") ? name : `${name}.md`);
+  return readFile(refPath, "utf-8");
+}
+async function listSkillReferences(customDir) {
+  const baseDir = customDir ?? join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const refDir = join(baseDir, "references");
+  const entries = await readdir(refDir);
+  return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", ""));
+}
+async function collectMarkdown(dir, parts) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await collectMarkdown(fullPath, parts);
+    } else if (entry.name.endsWith(".md")) {
+      const content = await readFile(fullPath, "utf-8");
+      parts.push(content);
+    }
+  }
+}
+
 // src/agent.ts
 import Anthropic from "@anthropic-ai/sdk";
 var DEFAULT_SYSTEM_INSTRUCTION = "You're Clawpify. You help run a Shopify store. The merchant texts you to get stuff done";
@@ -108,6 +156,20 @@ var SHOPIFY_GRAPHQL_TOOL = {
     required: ["query"]
   }
 };
+var LOAD_SKILL_REFERENCE_TOOL = {
+  name: "load_skill_reference",
+  description: "Load a reference document for a specific domain. Available Shopify references: products, orders, customers, inventory, discounts, collections, fulfillments, refunds, draft-orders, gift-cards, webhooks, locations, marketing, markets, menus, metafields, pages, blogs, files, shipping, shop, subscriptions, translations, segments, bulk-operations. Available document references: docx, pdf, pdf-forms, pdf-reference, pptx, pptx-editing, pptx-creating, xlsx. Use this BEFORE writing queries or processing documents to get the correct syntax and workflow.",
+  input_schema: {
+    type: "object",
+    properties: {
+      reference: {
+        type: "string",
+        description: "Name of the reference to load (e.g. 'orders', 'products', 'docx', 'pdf', 'xlsx')"
+      }
+    },
+    required: ["reference"]
+  }
+};
 var DEFAULT_PRICING = {
   inputPerMillion: 3,
   outputPerMillion: 15,
@@ -187,8 +249,8 @@ class ShopifyAgent {
   }
   registerPlugin(plugin) {
     const name = plugin.tool.name;
-    if (name === "shopify_graphql") {
-      throw new Error(`Cannot register plugin with reserved tool name "shopify_graphql"`);
+    if (name === "shopify_graphql" || name === "load_skill_reference") {
+      throw new Error(`Cannot register plugin with reserved tool name "${name}"`);
     }
     if (this.plugins.has(name)) {
       throw new Error(`Plugin with tool name "${name}" is already registered`);
@@ -208,6 +270,7 @@ class ShopifyAgent {
   buildTools() {
     const allTools = [
       SHOPIFY_GRAPHQL_TOOL,
+      LOAD_SKILL_REFERENCE_TOOL,
       ...[...this.plugins.values()].map((p) => p.tool)
     ];
     if (allTools.length > 0) {
@@ -245,6 +308,17 @@ class ShopifyAgent {
         return { content: content2, isError: true };
       }
     }
+    if (name === "load_skill_reference") {
+      try {
+        const content2 = await loadSkillReference(input.reference);
+        await safeHook(this.hooks.onToolResult, name, content2, false);
+        return { content: content2, isError: false };
+      } catch (error) {
+        const content2 = `Error: ${error instanceof Error ? error.message : String(error)}`;
+        await safeHook(this.hooks.onToolResult, name, content2, true);
+        return { content: content2, isError: true };
+      }
+    }
     if (this.plugins.has(name)) {
       const plugin = this.plugins.get(name);
       try {
@@ -488,40 +562,11 @@ class InMemoryStore {
     this.store.delete(sessionId);
   }
 }
-
-// src/skills.ts
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-async function loadSkills(customDir) {
-  const baseDir = customDir ?? join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
-  const skillParts = [];
-  await collectMarkdown(baseDir, skillParts);
-  return skillParts.join(`
-
----
-
-`);
-}
-async function collectMarkdown(dir, parts) {
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      await collectMarkdown(fullPath, parts);
-    } else if (entry.name.endsWith(".md")) {
-      const content = await readFile(fullPath, "utf-8");
-      parts.push(content);
-    }
-  }
-}
 export {
   loadSkills,
+  loadSkillReference,
+  loadSkillMetadata,
+  listSkillReferences,
   getAccessToken,
   createShopifyClient,
   createAuthenticatedConfig,

package/dist/skills.d.ts

@@ -3,6 +3,23 @@
  * Works both locally and when installed as an npm package.
  *
  * Optionally provide a custom directory path to load skills from.
+ *
+ * @deprecated Use `loadSkillMetadata()` for the system prompt and
+ * `loadSkillReference(name)` to load individual references on demand.
  */
 export declare function loadSkills(customDir?: string): Promise<string>;
+/**
+ * Load only the SKILL.md metadata file (Level 1+2).
+ * Use this for the system prompt instead of `loadSkills()` to keep context small.
+ */
+export declare function loadSkillMetadata(customDir?: string): Promise<string>;
+/**
+ * Load a specific reference file on demand (Level 3).
+ * Returns the content of `clawpify/references/{name}.md`.
+ */
+export declare function loadSkillReference(name: string, customDir?: string): Promise<string>;
+/**
+ * List available reference file names (without the `.md` extension).
+ */
+export declare function listSkillReferences(customDir?: string): Promise<string[]>;
 //# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASpE"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASpE;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CAOnB"}

package/dist/skills.js

@@ -12,6 +12,22 @@ async function loadSkills(customDir) {
 
 `);
 }
+async function loadSkillMetadata(customDir) {
+  const baseDir = customDir ?? join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const skillPath = join(baseDir, "SKILL.md");
+  return readFile(skillPath, "utf-8");
+}
+async function loadSkillReference(name, customDir) {
+  const baseDir = customDir ?? join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const refPath = join(baseDir, "references", name.endsWith(".md") ? name : `${name}.md`);
+  return readFile(refPath, "utf-8");
+}
+async function listSkillReferences(customDir) {
+  const baseDir = customDir ?? join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const refDir = join(baseDir, "references");
+  const entries = await readdir(refDir);
+  return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", ""));
+}
 async function collectMarkdown(dir, parts) {
   let entries;
   try {
@@ -30,5 +46,8 @@ async function collectMarkdown(dir, parts) {
   }
 }
 export {
-  loadSkills
+  loadSkills,
+  loadSkillReference,
+  loadSkillMetadata,
+  listSkillReferences
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawpify/skills",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Shopify Agent SDK — query and manage Shopify stores via GraphQL Admin API with AI agents and MCP",
   "type": "module",
   "main": "./dist/index.js",

package/src/agent.ts

@@ -1,6 +1,7 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { ShopifyClient } from "./shopify";
 import type { MemoryStore } from "./memory";
+import { loadSkillReference } from "./skills";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -148,6 +149,23 @@ const SHOPIFY_GRAPHQL_TOOL: Anthropic.Tool = {
   },
 };
 
+const LOAD_SKILL_REFERENCE_TOOL: Anthropic.Tool = {
+  name: "load_skill_reference",
+  description:
+    "Load a reference document for a specific domain. Available Shopify references: products, orders, customers, inventory, discounts, collections, fulfillments, refunds, draft-orders, gift-cards, webhooks, locations, marketing, markets, menus, metafields, pages, blogs, files, shipping, shop, subscriptions, translations, segments, bulk-operations. Available document references: docx, pdf, pdf-forms, pdf-reference, pptx, pptx-editing, pptx-creating, xlsx. Use this BEFORE writing queries or processing documents to get the correct syntax and workflow.",
+  input_schema: {
+    type: "object" as const,
+    properties: {
+      reference: {
+        type: "string",
+        description:
+          "Name of the reference to load (e.g. 'orders', 'products', 'docx', 'pdf', 'xlsx')",
+      },
+    },
+    required: ["reference"],
+  },
+};
+
 /** Default pricing for claude-sonnet-4-5 (USD per million tokens). */
 const DEFAULT_PRICING: ModelPricing = {
   inputPerMillion: 3,
@@ -266,9 +284,9 @@ export class ShopifyAgent {
   /** Register a plugin at runtime. Throws if a tool with the same name already exists. */
   registerPlugin(plugin: AgentPlugin): void {
     const name = plugin.tool.name;
-    if (name === "shopify_graphql") {
+    if (name === "shopify_graphql" || name === "load_skill_reference") {
       throw new Error(
-        `Cannot register plugin with reserved tool name "shopify_graphql"`
+        `Cannot register plugin with reserved tool name "${name}"`
       );
     }
     if (this.plugins.has(name)) {
@@ -297,6 +315,7 @@ export class ShopifyAgent {
   private buildTools(): Anthropic.Tool[] {
     const allTools: Anthropic.Tool[] = [
       SHOPIFY_GRAPHQL_TOOL,
+      LOAD_SKILL_REFERENCE_TOOL,
       ...[...this.plugins.values()].map((p) => p.tool),
     ];
     if (allTools.length > 0) {
@@ -348,6 +367,18 @@ export class ShopifyAgent {
       }
     }
 
+    if (name === "load_skill_reference") {
+      try {
+        const content = await loadSkillReference(input.reference);
+        await safeHook(this.hooks.onToolResult, name, content, false);
+        return { content, isError: false };
+      } catch (error) {
+        const content = `Error: ${error instanceof Error ? error.message : String(error)}`;
+        await safeHook(this.hooks.onToolResult, name, content, true);
+        return { content, isError: true };
+      }
+    }
+
     if (this.plugins.has(name)) {
       const plugin = this.plugins.get(name)!;
       try {

package/src/index.ts

@@ -63,7 +63,12 @@ export { InMemoryStore } from "./memory";
 export type { MemoryStore } from "./memory";
 
 // Skills loader
-export { loadSkills } from "./skills";
+export {
+  loadSkills,
+  loadSkillMetadata,
+  loadSkillReference,
+  listSkillReferences,
+} from "./skills";
 
 // Re-export types for convenience
 export type { ShopifyClientConfig, GraphQLResponse } from "./shopify";

package/src/skills.ts

@@ -7,6 +7,9 @@ import { fileURLToPath } from "node:url";
  * Works both locally and when installed as an npm package.
  *
  * Optionally provide a custom directory path to load skills from.
+ *
+ * @deprecated Use `loadSkillMetadata()` for the system prompt and
+ * `loadSkillReference(name)` to load individual references on demand.
  */
 export async function loadSkills(customDir?: string): Promise<string> {
   const baseDir =
@@ -19,6 +22,53 @@ export async function loadSkills(customDir?: string): Promise<string> {
   return skillParts.join("\n\n---\n\n");
 }
 
+/**
+ * Load only the SKILL.md metadata file (Level 1+2).
+ * Use this for the system prompt instead of `loadSkills()` to keep context small.
+ */
+export async function loadSkillMetadata(
+  customDir?: string
+): Promise<string> {
+  const baseDir =
+    customDir ??
+    join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const skillPath = join(baseDir, "SKILL.md");
+  return readFile(skillPath, "utf-8");
+}
+
+/**
+ * Load a specific reference file on demand (Level 3).
+ * Returns the content of `clawpify/references/{name}.md`.
+ */
+export async function loadSkillReference(
+  name: string,
+  customDir?: string
+): Promise<string> {
+  const baseDir =
+    customDir ??
+    join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const refPath = join(
+    baseDir,
+    "references",
+    name.endsWith(".md") ? name : `${name}.md`
+  );
+  return readFile(refPath, "utf-8");
+}
+
+/**
+ * List available reference file names (without the `.md` extension).
+ */
+export async function listSkillReferences(
+  customDir?: string
+): Promise<string[]> {
+  const baseDir =
+    customDir ??
+    join(fileURLToPath(import.meta.url), "..", "..", "clawpify");
+  const refDir = join(baseDir, "references");
+  const entries = await readdir(refDir);
+  return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", ""));
+}
+
 async function collectMarkdown(
   dir: string,
   parts: string[]