clawskills-mcp 0.3.6 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 An MCP (Model Context Protocol) server that exposes [ClawSkills](https://github.com/Shanksg/clawskills) API integration skill docs to AI agents.
 
-ClawSkills currently contains 14 structured Markdown skill docs for SaaS APIs such as Salesforce, HubSpot, GitHub, Jira, Stripe, Notion, Slack, and Linear. Each skill tracks its own API version and `Last validated` date, while `clawskills-mcp` has its own npm version for the server itself.
+ClawSkills currently contains 14 structured Markdown skill docs plus workflow playbooks for cross-tool automations. Each skill tracks its own API version and `Last validated` date, while `clawskills-mcp` has its own npm version for the server itself.
 
 ---
 
@@ -46,6 +46,9 @@ docker run --rm -i clawskills-mcp
 | `list_skills` | List all available skill slugs with descriptions |
 | `get_skill` | Fetch a full skill doc or a specific section |
 | `search_skills` | Full-text search across all skill docs |
+| `list_playbooks` | List all available cross-tool workflow playbooks |
+| `get_playbook` | Fetch a full playbook by slug |
+| `search_playbooks` | Full-text search across all workflow playbooks |
 
 ### `list_skills`
 
@@ -71,17 +74,36 @@ Examples:
 
 Returns matching excerpts (±3 lines of context) grouped by skill, capped at 5 matches per skill.
 
+### `list_playbooks`
+
+No arguments. Returns all available playbooks.
+
+### `get_playbook`
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | yes | Playbook slug: `zendesk-jira-bug-escalation`, `hubspot-asana-onboarding`, etc. Fuzzy matched. |
+
+### `search_playbooks`
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `query` | string | yes | Search string, e.g. `"idempotency"`, `"rollback"`, `"closed won"` |
+
+Returns matching excerpts (±3 lines of context) grouped by playbook, capped at 5 matches per playbook.
+
 ---
 
 ## Configuration
 
-Skills are bundled inside the npm package — no `SKILLS_DIR` configuration needed for the standard `npx` setup.
+Skills and playbooks are bundled inside the npm package — no extra configuration is needed for the standard `npx` setup.
 
-`SKILLS_DIR` is available if you want to point the server at a custom or local skills directory (e.g. your own forks of the docs):
+`SKILLS_DIR` and `PLAYBOOKS_DIR` are available if you want to point the server at custom or local content directories:
 
 | Env var | Default | Description |
 |---------|---------|-------------|
 | `SKILLS_DIR` | bundled `skills/` inside the package | Absolute path to a directory of `{slug}/skill.md` files |
+| `PLAYBOOKS_DIR` | bundled `playbooks/` inside the package | Absolute path to a directory of `{slug}.md` playbook files |
 
 ```json
 {
@@ -90,7 +112,8 @@ Skills are bundled inside the npm package — no `SKILLS_DIR` configuration need
       "command": "npx",
       "args": ["-y", "clawskills-mcp"],
       "env": {
-        "SKILLS_DIR": "/path/to/your/skills"
+        "SKILLS_DIR": "/path/to/your/skills",
+        "PLAYBOOKS_DIR": "/path/to/your/playbooks"
       }
     }
   }

package/dist/index.js

@@ -25,6 +25,19 @@ function resolveSkillsDir() {
     }
     return candidates[0];
 }
+function resolvePlaybooksDir() {
+    if (process.env.PLAYBOOKS_DIR)
+        return process.env.PLAYBOOKS_DIR;
+    const candidates = [
+        path.resolve(__dirname, "../../playbooks"),
+        path.resolve(__dirname, "../playbooks"),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return candidates[0];
+}
 function resolvePackageVersion() {
     const packageJsonPath = path.resolve(__dirname, "../package.json");
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
@@ -49,6 +62,23 @@ function loadSkills(skillsDir) {
     process.stderr.write(`[clawskills-mcp] Loaded ${skills.size} skills: ${[...skills.keys()].join(", ")}\n`);
     return skills;
 }
+function loadPlaybooks(playbooksDir) {
+    const playbooks = new Map();
+    if (!fs.existsSync(playbooksDir)) {
+        process.stderr.write(`[clawskills-mcp] Playbooks directory not found: ${playbooksDir}\n`);
+        return playbooks;
+    }
+    const entries = fs.readdirSync(playbooksDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md") || entry.name === "INDEX.md")
+            continue;
+        const slug = entry.name.replace(/\.md$/, "");
+        const content = fs.readFileSync(path.join(playbooksDir, entry.name), "utf-8");
+        playbooks.set(slug, content);
+    }
+    process.stderr.write(`[clawskills-mcp] Loaded ${playbooks.size} playbooks: ${[...playbooks.keys()].join(", ")}\n`);
+    return playbooks;
+}
 // ---------------------------------------------------------------------------
 // Section extraction
 // ---------------------------------------------------------------------------
@@ -115,12 +145,15 @@ function findSkill(skills, name) {
     }
     return undefined;
 }
-function searchSkills(skills, query) {
+function findPlaybook(playbooks, name) {
+    return findSkill(playbooks, name);
+}
+function searchDocuments(documents, query) {
     const results = [];
     const lowerQuery = query.toLowerCase();
     const CONTEXT_LINES = 3;
     const MAX_PER_SKILL = 5;
-    for (const [slug, content] of skills.entries()) {
+    for (const [name, content] of documents.entries()) {
         const lines = content.split("\n");
         const excerpts = [];
         const usedRanges = [];
@@ -140,11 +173,17 @@ function searchSkills(skills, query) {
                 break;
         }
         if (excerpts.length > 0) {
-            results.push({ skill: slug, excerpts });
+            results.push({ name, excerpts });
         }
     }
     return results;
 }
+function searchSkills(skills, query) {
+    return searchDocuments(skills, query);
+}
+function searchPlaybooks(playbooks, query) {
+    return searchDocuments(playbooks, query);
+}
 // ---------------------------------------------------------------------------
 // Skill summary (first meaningful line)
 // ---------------------------------------------------------------------------
@@ -159,13 +198,15 @@ function skillSummary(content) {
 // ---------------------------------------------------------------------------
 // Exports for testing
 // ---------------------------------------------------------------------------
-export { resolveSkillsDir, resolvePackageVersion, loadSkills, extractSection, findSkill, searchSkills, skillSummary };
+export { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, skillSummary, };
 // ---------------------------------------------------------------------------
 // MCP Server setup
 // ---------------------------------------------------------------------------
 const SKILLS_DIR = resolveSkillsDir();
+const PLAYBOOKS_DIR = resolvePlaybooksDir();
 const PACKAGE_VERSION = resolvePackageVersion();
 const skills = loadSkills(SKILLS_DIR);
+const playbooks = loadPlaybooks(PLAYBOOKS_DIR);
 const server = new Server({ name: "clawskills-mcp", version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
 // List tools
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -201,11 +242,40 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["query"],
             },
         },
+        {
+            name: "list_playbooks",
+            description: "List all available ClawSkills workflow playbooks.",
+            inputSchema: { type: "object", properties: {}, required: [] },
+        },
+        {
+            name: "get_playbook",
+            description: "Retrieve a ClawSkills workflow playbook by name (slug).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Playbook slug, e.g. 'zendesk-jira-bug-escalation'" },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "search_playbooks",
+            description: "Search across workflow playbooks for a query string and return matching excerpts with context.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search query, e.g. 'idempotency', 'rollback', 'customer impact'" },
+                },
+                required: ["query"],
+            },
+        },
     ],
 }));
 // Call tools
 const GetSkillSchema = z.object({ name: z.string(), section: z.string().optional() });
+const GetPlaybookSchema = z.object({ name: z.string() });
 const SearchSkillsSchema = z.object({ query: z.string() });
+const SearchPlaybooksSchema = z.object({ query: z.string() });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     if (name === "list_skills") {
@@ -218,6 +288,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         });
         return { content: [{ type: "text", text: `Available skills (${skills.size}):\n\n${lines.join("\n")}` }] };
     }
+    if (name === "list_playbooks") {
+        if (playbooks.size === 0) {
+            return { content: [{ type: "text", text: "No playbooks loaded. Check PLAYBOOKS_DIR." }] };
+        }
+        const lines = [...playbooks.entries()].map(([slug, content]) => `• **${slug}** — ${skillSummary(content)}`);
+        return { content: [{ type: "text", text: `Available playbooks (${playbooks.size}):\n\n${lines.join("\n")}` }] };
+    }
     if (name === "get_skill") {
         const parsed = GetSkillSchema.safeParse(args);
         if (!parsed.success) {
@@ -256,13 +333,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return { content: [{ type: "text", text: `No results found for "${query}".` }] };
         }
         const output = results
-            .map(({ skill, excerpts }) => {
+            .map(({ name: skill, excerpts }) => {
             const blocks = excerpts.map((e, i) => `--- match ${i + 1} ---\n${e}`).join("\n\n");
             return `### ${skill}\n\n${blocks}`;
         })
             .join("\n\n---\n\n");
         return { content: [{ type: "text", text: `Search results for "${query}":\n\n${output}` }] };
     }
+    if (name === "get_playbook") {
+        const parsed = GetPlaybookSchema.safeParse(args);
+        if (!parsed.success) {
+            return { content: [{ type: "text", text: `Invalid arguments: ${parsed.error.message}` }], isError: true };
+        }
+        const slug = findPlaybook(playbooks, parsed.data.name);
+        if (!slug) {
+            const available = [...playbooks.keys()].join(", ");
+            return {
+                content: [{ type: "text", text: `Playbook "${parsed.data.name}" not found. Available playbooks: ${available}` }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: playbooks.get(slug) }] };
+    }
+    if (name === "search_playbooks") {
+        const parsed = SearchPlaybooksSchema.safeParse(args);
+        if (!parsed.success) {
+            return { content: [{ type: "text", text: `Invalid arguments: ${parsed.error.message}` }], isError: true };
+        }
+        const { query } = parsed.data;
+        const results = searchPlaybooks(playbooks, query);
+        if (results.length === 0) {
+            return { content: [{ type: "text", text: `No playbook results found for "${query}".` }] };
+        }
+        const output = results
+            .map(({ name: playbook, excerpts }) => {
+            const blocks = excerpts.map((e, i) => `--- match ${i + 1} ---\n${e}`).join("\n\n");
+            return `### ${playbook}\n\n${blocks}`;
+        })
+            .join("\n\n---\n\n");
+        return { content: [{ type: "text", text: `Playbook search results for "${query}":\n\n${output}` }] };
+    }
     return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
 });
 // ---------------------------------------------------------------------------

package/dist/index.test.js

@@ -3,9 +3,10 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { fileURLToPath } from "url";
-import { resolveSkillsDir, resolvePackageVersion, loadSkills, extractSection, findSkill, searchSkills, skillSummary } from "./index.js";
+import { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, skillSummary, } from "./index.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REAL_SKILLS_DIR = path.resolve(__dirname, "../../skills");
+const REAL_PLAYBOOKS_DIR = path.resolve(__dirname, "../../playbooks");
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -18,6 +19,13 @@ function makeTempSkillsDir(skills) {
     }
     return dir;
 }
+function makeTempPlaybooksDir(playbooks) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clawskills-playbooks-test-"));
+    for (const [slug, content] of Object.entries(playbooks)) {
+        fs.writeFileSync(path.join(dir, `${slug}.md`), content, "utf-8");
+    }
+    return dir;
+}
 const SAMPLE_CONTENT = `# GitHub Skill
 
 A skill doc for GitHub API.
@@ -44,11 +52,17 @@ Scopes: repo, read:user, etc.
 POST /repos/{owner}/{repo}/issues
 `;
 let tempDir;
+let tempPlaybooksDir;
 beforeAll(() => {
     tempDir = makeTempSkillsDir({ github: SAMPLE_CONTENT, salesforce: "# Salesforce\nCRM platform.\n## Overview\nSalesforce is a CRM." });
+    tempPlaybooksDir = makeTempPlaybooksDir({
+        "zendesk-jira": "# Zendesk -> Jira\n\nEscalate bugs from support into engineering.\n\n## Idempotency\n\nUse zendesk:{ticket_id}.",
+        "hubspot-asana": "# HubSpot -> Asana\n\nCreate onboarding work from closed won deals.",
+    });
 });
 afterAll(() => {
     fs.rmSync(tempDir, { recursive: true, force: true });
+    fs.rmSync(tempPlaybooksDir, { recursive: true, force: true });
 });
 // ---------------------------------------------------------------------------
 // loadSkills
@@ -86,6 +100,12 @@ describe("resolveSkillsDir", () => {
         expect(loadSkills(resolveSkillsDir()).has("stripe")).toBe(true);
     });
 });
+describe("resolvePlaybooksDir", () => {
+    it("prefers the canonical repo-root playbooks directory", () => {
+        expect(path.basename(resolvePlaybooksDir())).toBe("playbooks");
+        expect(loadPlaybooks(resolvePlaybooksDir()).has("zendesk-jira-bug-escalation")).toBe(true);
+    });
+});
 describe("resolvePackageVersion", () => {
     it("matches package.json", () => {
         const packageJsonPath = path.resolve(__dirname, "../package.json");
@@ -94,6 +114,20 @@ describe("resolvePackageVersion", () => {
     });
 });
 // ---------------------------------------------------------------------------
+// loadPlaybooks
+// ---------------------------------------------------------------------------
+describe("loadPlaybooks", () => {
+    it("loads markdown files from a directory", () => {
+        const playbooks = loadPlaybooks(tempPlaybooksDir);
+        expect(playbooks.size).toBe(2);
+        expect(playbooks.has("zendesk-jira")).toBe(true);
+    });
+    it("returns empty map for missing directory", () => {
+        const playbooks = loadPlaybooks("/nonexistent/playbooks/path");
+        expect(playbooks.size).toBe(0);
+    });
+});
+// ---------------------------------------------------------------------------
 // findSkill
 // ---------------------------------------------------------------------------
 describe("findSkill", () => {
@@ -119,6 +153,18 @@ describe("findSkill", () => {
         expect(findSkill(skills, "zzznomatch")).toBeUndefined();
     });
 });
+describe("findPlaybook", () => {
+    let playbooks;
+    beforeAll(() => {
+        playbooks = loadPlaybooks(tempPlaybooksDir);
+    });
+    it("returns key for exact match", () => {
+        expect(findPlaybook(playbooks, "zendesk-jira")).toBe("zendesk-jira");
+    });
+    it("matches normalized input", () => {
+        expect(findPlaybook(playbooks, "zendesk jira")).toBe("zendesk-jira");
+    });
+});
 // ---------------------------------------------------------------------------
 // extractSection
 // ---------------------------------------------------------------------------
@@ -153,7 +199,7 @@ describe("searchSkills", () => {
     it("returns results for a matching query", () => {
         const results = searchSkills(skills, "Personal Access Token");
         expect(results.length).toBeGreaterThan(0);
-        expect(results[0].skill).toBe("github");
+        expect(results[0].name).toBe("github");
         expect(results[0].excerpts.length).toBeGreaterThan(0);
     });
     it("is case-insensitive", () => {
@@ -172,6 +218,17 @@ describe("searchSkills", () => {
         expect(results[0].excerpts.length).toBeLessThanOrEqual(5);
     });
 });
+describe("searchPlaybooks", () => {
+    let playbooks;
+    beforeAll(() => {
+        playbooks = loadPlaybooks(tempPlaybooksDir);
+    });
+    it("returns results for a matching query", () => {
+        const results = searchPlaybooks(playbooks, "idempotency");
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].name).toBe("zendesk-jira");
+    });
+});
 // ---------------------------------------------------------------------------
 // skillSummary
 // ---------------------------------------------------------------------------
@@ -234,3 +291,25 @@ describe("real skills", () => {
         }
     });
 });
+describe("real playbooks", () => {
+    let playbooks;
+    beforeAll(() => {
+        playbooks = loadPlaybooks(REAL_PLAYBOOKS_DIR);
+    });
+    it("loads all expected playbooks", () => {
+        const knownPlaybooks = [
+            "hubspot-asana-onboarding",
+            "salesforce-hubspot-lead-sync",
+            "zendesk-jira-bug-escalation",
+        ];
+        for (const slug of knownPlaybooks) {
+            expect(playbooks.has(slug), `Missing playbook: ${slug}`).toBe(true);
+        }
+    });
+    it("every playbook has a non-empty summary line", () => {
+        for (const [slug, content] of playbooks.entries()) {
+            const summary = skillSummary(content);
+            expect(summary, `${slug}: empty summary`).not.toBe("");
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawskills-mcp",
-  "version": "0.3.6",
+  "version": "0.5.0",
   "description": "MCP server exposing ClawSkills API integration skill docs to AI agents",
   "license": "MIT",
   "author": "ClawSkills Contributors",
@@ -30,12 +30,14 @@
   },
   "files": [
     "dist/",
-    "skills/"
+    "skills/",
+    "playbooks/"
   ],
   "scripts": {
     "sync:skills": "node scripts/sync-skills.mjs",
     "check:skills": "node scripts/check-skills.mjs",
     "check:freshness": "node scripts/check-skills.mjs --freshness",
+    "check:docs": "node scripts/check-docs.mjs",
     "prepack": "npm run sync:skills",
     "build": "npm run sync:skills && tsc",
     "start": "node dist/index.js",

package/playbooks/INDEX.md

@@ -0,0 +1,32 @@
+# Playbooks Index
+
+Workflow playbooks are end-to-end guides for multi-system automations. They complement the per-tool `skill.md` files by defining the orchestration layer: trigger, source of truth, field mapping, idempotency, failure policy, and operational checks.
+
+## Available playbooks
+
+| Playbook | Systems | Primary use case |
+|----------|---------|------------------|
+| [Zendesk Ticket -> Jira Bug escalation](./zendesk-jira-bug-escalation.md) | Zendesk, Jira | Escalate support-confirmed defects into engineering workflow |
+| [HubSpot Deal Won -> Asana onboarding kickoff](./hubspot-asana-onboarding.md) | HubSpot, Asana | Start implementation or onboarding work when a deal closes |
+| [Salesforce Lead -> HubSpot Contact sync](./salesforce-hubspot-lead-sync.md) | Salesforce, HubSpot | Mirror new/updated leads into marketing automation without duplicates |
+
+## Playbook template
+
+Each playbook should define:
+- Business trigger
+- Systems involved
+- Source of truth
+- Sequence of operations
+- Field mapping
+- Idempotency and dedup keys
+- Retry / partial-failure policy
+- Reconciliation / rollback guidance
+- Observability checks
+
+## Next candidates
+
+- Slack incident -> Jira issue
+- GitHub PR -> Slack notification
+- Zendesk -> Salesforce case sync
+- Stripe payment failed -> HubSpot task
+- Notion request -> Asana task

package/playbooks/hubspot-asana-onboarding.md

@@ -0,0 +1,76 @@
+# HubSpot Deal Won -> Asana Onboarding Kickoff
+
+## Goal
+
+Create onboarding or implementation work in Asana as soon as a HubSpot Deal is marked closed won.
+
+## Systems involved
+
+- HubSpot: sales pipeline, deal state, customer/account context
+- Asana: delivery execution, onboarding tasks, project coordination
+
+## Trigger
+
+- HubSpot webhook `deal.propertyChange` where `dealstage` moves into the closed-won stage
+
+## Source of truth
+
+- Commercial state and customer/account metadata: HubSpot
+- Delivery execution and task/project state: Asana
+- Workflow linkage: integration database or HubSpot custom property storing the Asana `gid`
+
+## Sequence
+
+1. Receive the HubSpot webhook and verify it corresponds to the target pipeline/stage.
+2. Fetch the Deal, associated Company, and primary Contact.
+3. Check whether an Asana task/project already exists for the Deal ID.
+4. Create the onboarding project or kickoff task in Asana.
+5. Populate notes and custom fields with customer, owner, ARR, plan, and target launch details.
+6. Persist the Asana `gid` back to HubSpot or your integration store.
+7. Notify the implementation owner or CSM if required.
+
+## Field mapping
+
+| HubSpot | Asana |
+|---------|-------|
+| `dealId` | external mapping / custom field |
+| `dealname` | task/project name |
+| associated company name | notes / title suffix |
+| deal owner | assignee |
+| close date | kickoff anchor or due date |
+| ARR / amount | custom field |
+| onboarding tier | custom field / template choice |
+
+## Idempotency
+
+- Dedup key: HubSpot Deal ID
+- Webhook delivery is at-least-once, so check your mapping store before creation
+- If using project templates, ensure only one project is generated per Deal ID
+
+## Retry and partial failure policy
+
+- Retry transient Asana failures with bounded backoff
+- If Asana create succeeds but write-back to HubSpot fails, recover by searching the mapping store on the next run
+- Validation errors should move the record into a manual review queue with the Deal ID and failing field
+
+## Reconciliation
+
+- Daily job: compare all closed-won deals in the last 30 days against Asana kickoff artifacts
+- Backfill missing Asana `gid` values into HubSpot
+- Flag onboarding projects with no matching active deal
+
+## Rollback guidance
+
+- If a Deal reopens or is marked closed-lost shortly after creation, archive or cancel the Asana project/task rather than deleting it
+- Preserve the linkage so repeated stage churn does not create duplicates
+
+## Observability
+
+- Count created onboarding projects/tasks per day
+- Alert on webhook processing failures and duplicate prevention hits
+- Track time from closed won to Asana kickoff creation
+
+## Related skills
+
+- [`skills/hubspot/skill.md`](../skills/hubspot/skill.md)
+- [`skills/asana/skill.md`](../skills/asana/skill.md)

package/playbooks/salesforce-hubspot-lead-sync.md

@@ -0,0 +1,78 @@
+# Salesforce Lead -> HubSpot Contact Sync
+
+## Goal
+
+Mirror new or updated Salesforce Leads into HubSpot Contacts so marketing and lifecycle workflows stay current without creating duplicates.
+
+## Systems involved
+
+- Salesforce: CRM of record for lead capture and sales qualification
+- HubSpot: marketing automation, nurture, lifecycle segmentation
+
+## Trigger
+
+- Scheduled incremental sync using Salesforce `LastModifiedDate`
+- Optional near-real-time trigger from Salesforce CDC or platform events
+
+## Source of truth
+
+- Lead identity and sales-owned fields: Salesforce
+- Marketing engagement and automation state: HubSpot
+- Identity dedup anchor: email, with explicit mapping store as a secondary safeguard
+
+## Sequence
+
+1. Query Salesforce Leads modified since the last sync watermark, with a small overlap window.
+2. Skip converted Leads and Leads with no email.
+3. Search HubSpot Contacts by email.
+4. If a Contact exists, update it with mapped fields.
+5. If no Contact exists, create one and persist the mapping.
+6. Record sync outcome per Lead so failed rows can be retried independently.
+7. Advance the watermark only after all rows are processed or quarantined.
+
+## Field mapping
+
+| Salesforce Lead | HubSpot Contact |
+|-----------------|-----------------|
+| `Lead.Id` | custom property `salesforce_lead_id` or integration DB |
+| `Email` | `email` |
+| `FirstName` | `firstname` |
+| `LastName` | `lastname` |
+| `Company` | `company` |
+| `Phone` | `phone` |
+| `LeadSource` | custom source property |
+| `Status` | derived `lifecyclestage` mapping |
+
+## Idempotency
+
+- Primary dedup key: normalized email
+- Secondary correlation key: Salesforce Lead ID
+- Do not use HubSpot batch create blindly for unknown contacts; search first
+
+## Retry and partial failure policy
+
+- Retry transient HubSpot rate-limit and availability errors per shard
+- Quarantine `400` validation failures with Lead ID, email, and failing field names
+- If one row fails, continue the rest of the batch and surface a remediation report
+
+## Reconciliation
+
+- Daily compare: Salesforce Leads updated in the last 24 hours vs HubSpot Contacts carrying `salesforce_lead_id`
+- Repair records where the ID mapping is missing but email matches
+- Flag email collisions where multiple Salesforce Leads compete for one HubSpot Contact
+
+## Rollback guidance
+
+- Avoid destructive deletes across systems
+- If a bad sync overwrites HubSpot fields, restore from HubSpot history or your sync audit log and re-run the corrected mapping
+
+## Observability
+
+- Track processed, created, updated, quarantined, and retried rows per run
+- Alert on spikes in duplicate resolution or validation failures
+- Monitor watermark lag so the sync does not silently fall behind
+
+## Related skills
+
+- [`skills/salesforce/skill.md`](../skills/salesforce/skill.md)
+- [`skills/hubspot/skill.md`](../skills/hubspot/skill.md)

package/playbooks/zendesk-jira-bug-escalation.md

@@ -0,0 +1,79 @@
+# Zendesk Ticket -> Jira Bug Escalation
+
+## Goal
+
+Escalate a Zendesk support ticket into Jira when support determines the issue is a product defect that engineering must track and resolve.
+
+## Systems involved
+
+- Zendesk: intake, customer communication, support triage
+- Jira: engineering backlog, bug lifecycle, fix tracking
+
+## Trigger
+
+Any of:
+- Zendesk ticket gets tag `engineering`
+- Custom field `issue_type` changes to `bug`
+- Ticket priority becomes `urgent` and product area is set
+
+## Source of truth
+
+- Customer communication and ticket state: Zendesk
+- Engineering execution state: Jira
+- Escalation linkage: integration database or mirrored external ID field
+
+## Sequence
+
+1. Receive the Zendesk webhook or consume the ticket via Incremental Export.
+2. Build a deterministic correlation key: `zendesk:{ticket_id}`.
+3. Search Jira for an existing issue with that correlation key in a custom field or label.
+4. If no issue exists, create a Jira Bug with summary, reproduction notes, impact, and Zendesk URL.
+5. If an issue already exists, update priority, labels, assignee, and current reproduction context.
+6. Write the Jira issue key back to Zendesk as an internal note or custom field.
+7. Optionally mirror selected Jira status changes back to Zendesk after state mapping is finalized.
+
+## Field mapping
+
+| Zendesk | Jira |
+|---------|------|
+| `ticket.id` | custom external ID / label |
+| `subject` | `summary` |
+| latest public comment | `description` |
+| `priority` | `priority` |
+| `tags` | `labels` |
+| requester org / account | custom customer field or component |
+| product area custom field | component / label |
+
+## Idempotency
+
+- Dedup key: `zendesk:{ticket_id}`
+- Before create, always search Jira by dedup key
+- Zendesk webhooks are at-least-once delivery, so the create path must be safe to replay
+
+## Retry and partial failure policy
+
+- Retry transient Jira failures (`429`, `503`) with bounded exponential backoff
+- Do not retry `400` field validation errors blindly; quarantine and surface them
+- If Jira create succeeds but Zendesk write-back fails, reconcile by searching Jira with the dedup key on the next run
+
+## Reconciliation
+
+- Daily job: compare Zendesk tickets tagged `engineering` against Jira bugs with the dedup key
+- Repair missing backlinks in Zendesk
+- Flag Jira issues missing an active Zendesk ticket counterpart
+
+## Rollback guidance
+
+- If a Jira issue was created in error, transition it to a closed/cancelled state instead of deleting it
+- Remove the escalation tag or set a custom field in Zendesk to prevent automatic recreation
+
+## Observability
+
+- Count escalations per day
+- Alert on create failures, write-back failures, or rising duplicate-detection rates
+- Track mean time from Zendesk escalation to Jira issue creation
+
+## Related skills
+
+- [`skills/zendesk/skill.md`](../skills/zendesk/skill.md)
+- [`skills/jira/skill.md`](../skills/jira/skill.md)

package/skills/INDEX.md

@@ -3,6 +3,7 @@
 A curated library of integration skill documents for the most common SaaS platforms used in go-to-market and operations workflows. Each skill doc teaches an agent or automation builder how to reliably use that platform's API for high-value, production-grade workflows.
 
 → See [ROADMAP.md](./ROADMAP.md) for the prioritized build plan, phased milestones, and governance model.
+→ Cross-tool workflow guides now live in [`../playbooks/INDEX.md`](../playbooks/INDEX.md).
 
 ---
 

package/skills/ROADMAP.md

@@ -12,14 +12,14 @@ This skill set enables end-to-end automation and integration across the most com
 
 ---
 
-## Current state (as of 2026-03-10)
+## Current state (as of 2026-03-12)
 
 ### What's shipped
 
 | Layer | Status |
 |-------|--------|
 | **14 skill docs** — Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, Linear | ✅ Live |
-| **MCP server** — `clawskills-mcp` v0.3.4 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
+| **MCP server** — `clawskills-mcp` v0.4.0 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
 | **CI pipeline** — build + test on every push/PR via `ci.yml` | ✅ Live |
 | **Release automation** — `release.yml` workflow_dispatch → bump, tag, npm publish via OIDC | ✅ Live |
 | **Test suite** — Vitest unit tests + real-skills validation (required sections, ≥5 KB, all 14 tools) | ✅ Live |
@@ -83,7 +83,7 @@ The repo now needs tighter alignment between the canonical `skills/` directory,
 | Channel | Status | Next action |
 |---------|--------|-------------|
 | GitHub (public) | Ready to flip | Make repo public |
-| npm (`clawskills-mcp`) | ✅ Live — v0.3.4 | Maintain via `release.yml` |
+| npm (`clawskills-mcp`) | ✅ Live — v0.4.0 | Maintain via `release.yml` |
 | MCP registry listings | Not submitted | Submit to glama.ai, mcp.so, smithery.ai after public launch |
 | Docs website | Planned | Mintlify — fastest path to SEO-friendly browsable docs |
 | Lane A vs B | TBD | Revisit after first traction signals from public launch |
@@ -108,6 +108,43 @@ Each recipe lives as a `## Cross-tool recipe` appendix section in the relevant p
 
 ---
 
+### Priority 5 — Workflow playbooks and retrieval UX
+
+The next product layer is workflow-first guidance, not only tool-by-tool references. This means shipping opinionated playbooks that show how multiple systems fit together operationally, then exposing them cleanly through MCP.
+
+**Backlog:**
+- Add a `playbooks/` directory with high-value cross-tool workflows
+- Ship 3 flagship playbooks first:
+  - Zendesk Ticket -> Jira Bug escalation
+  - HubSpot Deal Won -> Asana onboarding kickoff
+  - Salesforce Lead -> HubSpot Contact sync
+- Expand to additional high-frequency workflows:
+  - Slack incident -> Jira issue
+  - GitHub PR -> Slack notification
+  - Zendesk -> Salesforce case sync
+  - Stripe payment failed -> HubSpot task
+  - Notion request -> Asana task
+- Standardize each playbook format:
+  - business trigger
+  - systems involved
+  - source-of-truth decision
+  - field mapping
+  - idempotency strategy
+  - retry and partial-failure policy
+  - reconciliation and rollback guidance
+  - observability / alerting checks
+- Expose playbooks through MCP after the doc layer stabilizes:
+  - `list_playbooks`
+  - `get_playbook`
+  - search/ranking that prefers recipes and playbooks over generic mentions
+
+**Acceptance criteria:**
+- [ ] At least 3 production-grade playbooks checked into the repo
+- [ ] README and INDEX reference the playbooks layer
+- [ ] MCP server plan defined for playbook retrieval and discovery
+
+---
+
 ## Prioritization framework
 
 Each skill/recipe is scored on five dimensions (1–5 each):

package/skills/asana/skill.md

@@ -685,6 +685,32 @@ curl -X POST \
 
 ---
 
+### Cross-tool recipe: HubSpot Deal Won -> Asana project kickoff
+
+**Goal:** Start onboarding or implementation work in Asana when a HubSpot Deal reaches `closedwon`.
+
+**Flow:**
+1. Receive a HubSpot webhook for `deal.propertyChange`.
+2. Confirm the new `dealstage` maps to closed-won in the target pipeline.
+3. Fetch the Deal, associated Company, and primary Contact from HubSpot.
+4. Create the Asana task or project in the correct team or project template.
+5. Store the Asana `task_gid` or `project_gid` back in HubSpot or in your integration DB.
+
+**Suggested Asana fields:**
+
+| Asana field | Source |
+|---|---|
+| `name` | `Onboard {dealname}` |
+| `notes` | Deal URL, customer, ARR, owner, launch context |
+| `assignee` | mapped CSM or implementation owner |
+| `due_on` | kickoff or target launch date |
+| `custom_fields` | plan, ARR, onboarding tier, deal ID |
+
+**Operational guardrails:**
+- Prevent duplicates by checking your mapping store before creating a new Asana record.
+- If you use a project template, create the project once and then create the kickoff task inside it.
+- HubSpot webhooks are at-least-once delivery; your creation path must be idempotent.
+
 ## Query patterns & filtering
 
 ### Task search

package/skills/hubspot/skill.md

@@ -390,6 +390,67 @@ GET https://api.hubapi.com/crm/v3/imports/{importId}
 # importStatus: STARTED → PROCESSING → DONE
 ```
 
+**When to use Imports vs batch endpoints:**
+- Use `batch/create` or `batch/update` for API-driven writes where you already have structured JSON and need immediate responses.
+- Use Imports for backfills, CSV-based migrations, or cases where users export flat files from another system.
+
+**Partial failure handling:**
+- Imports can finish with row-level failures even when the job completes successfully.
+- Always inspect the import summary and error rows before marking the source batch as complete.
+- Treat duplicate email collisions as data-quality events, not transient API failures.
+
+**Batch write guardrails:**
+- Max 100 inputs per batch request.
+- For large syncs, shard into batches of 100 and apply a short concurrency limit so you do not burst into 429s.
+- Search first when deduplicating by email; batch create is not idempotent.
+
+---
+
+### Cross-tool recipe: Salesforce Lead -> HubSpot Contact sync
+
+**Goal:** Mirror new or updated Salesforce Leads into HubSpot Contacts for marketing and lifecycle automation.
+
+**HubSpot-side pattern:**
+1. Search Contacts by `email`.
+2. If found, `PATCH /crm/v3/objects/contacts/{id}` with mapped fields.
+3. If not found, `POST /crm/v3/objects/contacts`.
+4. Optionally stamp a custom property like `salesforce_lead_id` so future reconciliations do not depend solely on email.
+
+**Recommended property mapping:**
+
+| HubSpot Contact | Source from Salesforce |
+|---|---|
+| `email` | `Lead.Email` |
+| `firstname` | `Lead.FirstName` |
+| `lastname` | `Lead.LastName` |
+| `company` | `Lead.Company` |
+| `phone` | `Lead.Phone` |
+| `lifecyclestage` | derived mapping from lead status |
+
+**Failure policy:**
+- `400` validation errors: quarantine the record with the source Lead ID and failing field names.
+- `409` or duplicate conflicts: re-run a search by email, then update the winning Contact instead of creating a second record.
+- `429`: respect `Retry-After` and retry the shard, not the full sync job.
+
+---
+
+### Cross-tool recipe: HubSpot Deal Won -> Asana project kickoff
+
+**Goal:** When a Deal enters `closedwon`, create onboarding work in Asana.
+
+**Flow:**
+1. Subscribe to `deal.propertyChange` for `dealstage`.
+2. Filter for the pipeline stage representing "closed won".
+3. Fetch the Deal plus associated Company and primary Contact.
+4. Create the Asana task or project with the customer name, ARR, owner, and launch date.
+5. Store the resulting Asana `gid` in HubSpot or in your integration DB.
+
+**Minimum payload to send to Asana:**
+- `name`: `Onboard {dealname}`
+- `notes`: include the HubSpot deal URL, company, close date, and owner
+- `due_on`: derived from kickoff SLA or launch date
+- `custom_fields`: ARR, segment, onboarding tier, source deal ID
+
 ---
 
 ## Query patterns & filtering

package/skills/jira/skill.md

@@ -462,6 +462,36 @@ The `expand=transitions.fields` parameter returns the fields required for each t
 
 ---
 
+### Cross-tool recipe: Zendesk Ticket -> Jira Bug escalation
+
+**Goal:** Create or update a Jira Bug when a Zendesk ticket meets escalation criteria.
+
+**Escalation trigger examples:**
+- Zendesk ticket priority becomes `urgent`
+- Tag includes `engineering`
+- Custom field indicates product defect
+
+**Flow:**
+1. Receive the Zendesk webhook or poll Incremental Export.
+2. Build a deterministic external key, for example `zendesk:{ticket_id}`.
+3. Search Jira for an existing issue with that external key in a custom field or label.
+4. If found, update severity, assignee, and status. If not found, create a Bug with the Zendesk URL in the description.
+5. Post the Jira issue key back to Zendesk as an internal note or custom field.
+
+**Minimum field mapping:**
+
+| Zendesk | Jira |
+|---|---|
+| `subject` | `summary` |
+| `description` / latest public comment | `description` (ADF) |
+| `priority` | `priority` |
+| `ticket id` | custom external ID field |
+| `tags` | `labels` |
+
+**Status sync recommendation:**
+- One-way sync into Jira is safer initially.
+- Add reverse Jira -> Zendesk status updates only after you define an explicit state map and conflict rules.
+
 ## Query patterns & filtering
 
 ### JQL incremental sync

package/skills/salesforce/skill.md

@@ -378,10 +378,28 @@ curl -s "$BASE/services/data/v66.0/jobs/ingest/$JOB_ID" \
 # Step 5 — retrieve failed records
 curl -s "$BASE/services/data/v66.0/jobs/ingest/$JOB_ID/failedResults" \
   -H "Authorization: Bearer $TOKEN"
+
+# Step 6 — retrieve successful and unprocessed records for reconciliation
+curl -s "$BASE/services/data/v66.0/jobs/ingest/$JOB_ID/successfulResults" \
+  -H "Authorization: Bearer $TOKEN"
+
+curl -s "$BASE/services/data/v66.0/jobs/ingest/$JOB_ID/unprocessedRecords" \
+  -H "Authorization: Bearer $TOKEN"
 ```
 
 **When to use Bulk API v2:** >1,000 records. For <1,000 records, REST is simpler and faster.
 
+**CSV and job design tips:**
+- Keep one object type per job. Do not mix Leads and Contacts in the same ingest file.
+- Include only columns you intend to write. Extra CSV columns are treated as field references and can fail the row.
+- Shard very large backfills into multiple jobs so a single failure does not block the full dataset.
+- Reconcile with all three result streams: `successfulResults`, `failedResults`, and `unprocessedRecords`.
+
+**Partial-failure policy:**
+- Retry only `unprocessedRecords` automatically.
+- Send `failedResults` to a remediation queue with the Salesforce error message and original source key.
+- Do not advance the upstream source cursor until every row is either successful or quarantined.
+
 ---
 
 ### Recipe 8: Register a Change Data Capture (CDC) subscription
@@ -410,6 +428,33 @@ def handler(event):
 
 ---
 
+### Cross-tool recipe: Salesforce Lead -> HubSpot Contact sync
+
+**Goal:** Create or update a HubSpot Contact whenever a Salesforce Lead is created or updated, deduplicating by email.
+
+**Flow:**
+1. Query Salesforce Leads modified since the last sync boundary using `LastModifiedDate`.
+2. Skip records with blank `Email` or `IsConverted = true`.
+3. In HubSpot, search by `email` first. If found, `PATCH` the Contact. If not, create it.
+4. Store the mapping `Lead.Id -> HubSpot contact id` in your integration DB, but treat `email` as the primary dedup key.
+5. Write a sync marker back to Salesforce only after the HubSpot write succeeds.
+
+**Field mapping (minimum viable):**
+
+| Salesforce Lead | HubSpot Contact |
+|---|---|
+| `Email` | `email` |
+| `FirstName` | `firstname` |
+| `LastName` | `lastname` |
+| `Company` | `company` |
+| `Phone` | `phone` |
+| `LeadSource` | `lead_source` or custom property |
+
+**Operational guardrails:**
+- Prefer a watermark sync (`LastModifiedDate >= cursor`) plus a small overlap window to avoid missed updates.
+- Do not use Bulk API v2 for near-real-time sync unless you are processing a large backfill.
+- If HubSpot rejects one record, quarantine that record and continue the rest of the sync batch.
+
 ## Query patterns & filtering
 
 ### SOQL reference patterns

package/skills/zendesk/skill.md

@@ -493,6 +493,11 @@ curl -u "agent@example.com/token:TOKEN" \
 
 **Validation**: Poll job status to `completed`. Spot-check 5 random ticket IDs from the batch to confirm `assignee_id` updated correctly.
 
+**Operational notes:**
+- Use `update_many` for homogeneous changes like tags, assignee, or status across a known set of ticket IDs.
+- Keep request batches at 100 IDs max and persist the returned `job_status_id`.
+- If the job partially succeeds, re-run only the failed IDs after inspecting the job result.
+
 ---
 
 ### Recipe 8: Manage agent permissions and group membership
@@ -542,6 +547,39 @@ curl -u "admin@example.com/token:TOKEN" \
 
 ---
 
+### Cross-tool recipe: Zendesk Ticket -> Jira Bug escalation
+
+**Goal**: Escalate a Zendesk ticket into Jira when support confirms the issue is a product defect.
+
+**Trigger examples**:
+- Agent adds tag `engineering`
+- Ticket priority changes to `urgent`
+- Custom field `issue_type` becomes `bug`
+
+**Flow**:
+1. Capture the Zendesk event via webhook or Incremental Export.
+2. Build a stable external key such as `zendesk:{ticket_id}`.
+3. Search Jira for an existing issue using that key in a custom field or label.
+4. If no issue exists, create a Jira Bug with the Zendesk URL, customer impact, and reproduction details.
+5. Write the Jira issue key back to Zendesk as an internal note or custom field so agents can track engineering progress.
+
+**Minimum field mapping**:
+
+| Zendesk ticket field | Jira field |
+|---|---|
+| `subject` | `summary` |
+| latest public comment | `description` |
+| `priority` | `priority` |
+| `tags` | `labels` |
+| `id` | external ID field / label |
+
+**Operational guardrails**:
+- Make the create path idempotent; webhooks can be retried.
+- Keep status sync one-way at first. Bi-directional sync needs an explicit state map and conflict resolution policy.
+- Post only sanitized customer context into Jira if Zendesk comments may include PII.
+
+---
+
 ## Query patterns & filtering
 
 ### Search API
@@ -602,6 +640,13 @@ GET /api/v2/incremental/tickets.json?start_time=1708300800
 - Also available for users and organizations: `/api/v2/incremental/users.json`, `/api/v2/incremental/organizations.json`.
 - Events include `deleted` tickets — check `status` field.
 
+**Production sync pattern:**
+1. Start with `start_time` at least 5 minutes in the past.
+2. Continue following the returned window until you have drained the stream for the current run.
+3. Persist the returned `end_time`, not your request timestamp.
+4. Re-run with a small overlap window to protect against delayed indexing and consumer crashes.
+5. Deduplicate by ticket `id` and latest `updated_at` in your sink.
+
 ### Sorting
 
 Search API: `&sort_by=created_at&sort_order=asc` (or `desc`).
@@ -648,6 +693,13 @@ def zendesk_request(method, url, **kwargs):
     raise Exception("Exceeded retry budget")
 ```
 
+### Bulk update and export guardrails
+
+- `update_many` is efficient for operational changes across up to 100 tickets, but it is not a substitute for a full sync.
+- Poll the returned job status before assuming the bulk update succeeded.
+- For analytics or warehouse sync, use Incremental Export rather than paginating Search or list endpoints.
+- Keep writes and reads separate: use `update_many` for operational changes, Incremental Export for system-of-record ingestion.
+
 ### Retry vs fail-fast
 
 | HTTP Status | Action |