clawskills-mcp 0.5.0 → 0.7.0

package/README.md

@@ -49,6 +49,9 @@ docker run --rm -i clawskills-mcp
 | `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 |
+| `search_clawskills` | Unified search across both skills and playbooks |
+
+For most user queries, start with `search_clawskills`. It biases toward playbooks for workflow-shaped searches like `closed won onboarding`, `zendesk jira escalation`, or `lead sync`.
 
 ### `list_skills`
 
@@ -92,6 +95,14 @@ No arguments. Returns all available playbooks.
 
 Returns matching excerpts (±3 lines of context) grouped by playbook, capped at 5 matches per playbook.
 
+### `search_clawskills`
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `query` | string | yes | Search string, e.g. `"closed won onboarding"`, `"zendesk jira escalation"`, `"lead sync"` |
+
+Returns combined results across skills and playbooks. Workflow-oriented queries rank playbooks ahead of generic skill matches.
+
 ---
 
 ## Configuration

package/dist/index.js

@@ -148,9 +148,55 @@ function findSkill(skills, name) {
 function findPlaybook(playbooks, name) {
     return findSkill(playbooks, name);
 }
+function parseFrontmatter(content) {
+    if (!content.startsWith("---\n"))
+        return {};
+    const end = content.indexOf("\n---\n", 4);
+    if (end === -1)
+        return {};
+    const block = content.slice(4, end);
+    const metadata = {};
+    let currentKey = null;
+    for (const rawLine of block.split("\n")) {
+        const line = rawLine.trimEnd();
+        const keyMatch = line.match(/^([a-zA-Z0-9_]+):\s*(.*)$/);
+        if (keyMatch) {
+            const [, key, value] = keyMatch;
+            if (value === "") {
+                metadata[key] = [];
+                currentKey = key;
+            }
+            else {
+                metadata[key] = value.trim();
+                currentKey = null;
+            }
+            continue;
+        }
+        const listMatch = line.match(/^\s*-\s+(.*)$/);
+        if (listMatch && currentKey) {
+            const current = metadata[currentKey];
+            if (Array.isArray(current)) {
+                current.push(listMatch[1].trim());
+            }
+        }
+    }
+    return metadata;
+}
+function getPlaybookMetadata(content) {
+    const frontmatter = parseFrontmatter(content);
+    const systems = Array.isArray(frontmatter.systems) ? frontmatter.systems : [];
+    const tags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
+    return {
+        title: typeof frontmatter.title === "string" ? frontmatter.title : undefined,
+        systems,
+        tags,
+        triggerType: typeof frontmatter.trigger_type === "string" ? frontmatter.trigger_type : undefined,
+    };
+}
 function searchDocuments(documents, query) {
     const results = [];
     const lowerQuery = query.toLowerCase();
+    const queryTerms = lowerQuery.split(/[^a-z0-9]+/).filter(Boolean);
     const CONTEXT_LINES = 3;
     const MAX_PER_SKILL = 5;
     for (const [name, content] of documents.entries()) {
@@ -158,7 +204,10 @@ function searchDocuments(documents, query) {
         const excerpts = [];
         const usedRanges = [];
         for (let i = 0; i < lines.length; i++) {
-            if (!lines[i].toLowerCase().includes(lowerQuery))
+            const lowerLine = lines[i].toLowerCase();
+            const matchesExact = lowerLine.includes(lowerQuery);
+            const matchesTerm = queryTerms.some((term) => lowerLine.includes(term));
+            if (!matchesExact && !matchesTerm)
                 continue;
             const start = Math.max(0, i - CONTEXT_LINES);
             const end = Math.min(lines.length - 1, i + CONTEXT_LINES);
@@ -184,13 +233,59 @@ function searchSkills(skills, query) {
 function searchPlaybooks(playbooks, query) {
     return searchDocuments(playbooks, query);
 }
+function searchClawskills(skills, playbooks, query) {
+    const normalizedQuery = query.toLowerCase();
+    const queryTerms = normalizedQuery.split(/[^a-z0-9]+/).filter(Boolean);
+    const workflowHints = new Set([
+        "sync", "onboarding", "closed", "won", "handoff", "escalate",
+        "escalation", "workflow", "playbook", "incident", "notify",
+    ]);
+    const workflowShaped = queryTerms.some((term) => workflowHints.has(term));
+    const skillResults = searchSkills(skills, query).map((result) => ({
+        ...result,
+        contentType: "skill",
+        score: result.excerpts.length * 10 + (workflowShaped ? 0 : 5),
+    }));
+    const playbookResults = searchPlaybooks(playbooks, query).map((result) => {
+        const metadata = getPlaybookMetadata(playbooks.get(result.name));
+        const metadataText = [metadata.title, ...metadata.systems, ...metadata.tags, metadata.triggerType]
+            .filter(Boolean)
+            .join(" ")
+            .toLowerCase();
+        const metadataMatches = queryTerms.filter((term) => metadataText.includes(term)).length;
+        return {
+            ...result,
+            contentType: "playbook",
+            score: result.excerpts.length * 10 + metadataMatches * 5 + (workflowShaped ? 15 : 0),
+        };
+    });
+    return [...playbookResults, ...skillResults]
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .slice(0, 12);
+}
 // ---------------------------------------------------------------------------
 // Skill summary (first meaningful line)
 // ---------------------------------------------------------------------------
+// Playbooks open with a YAML frontmatter block; skills open with an H1 followed
+// by a blockquote. Without the frontmatter handling below, every playbook
+// summary came out as the literal "---" delimiter.
 function skillSummary(content) {
-    for (const line of content.split("\n")) {
-        const trimmed = line.trim();
-        if (trimmed && !trimmed.startsWith("#"))
+    const lines = content.split("\n");
+    let start = 0;
+    if (lines[0]?.trim() === "---") {
+        const closing = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+        if (closing !== -1) {
+            for (const line of lines.slice(1, closing)) {
+                const title = line.match(/^title:\s*(.+)$/);
+                if (title)
+                    return title[1].trim().replace(/^["']|["']$/g, "");
+            }
+            start = closing + 1;
+        }
+    }
+    for (const line of lines.slice(start)) {
+        const trimmed = line.trim().replace(/^>\s*/, "");
+        if (trimmed && trimmed !== "---" && !trimmed.startsWith("#"))
             return trimmed;
     }
     return "";
@@ -198,7 +293,7 @@ function skillSummary(content) {
 // ---------------------------------------------------------------------------
 // Exports for testing
 // ---------------------------------------------------------------------------
-export { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, skillSummary, };
+export { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, searchClawskills, getPlaybookMetadata, skillSummary, };
 // ---------------------------------------------------------------------------
 // MCP Server setup
 // ---------------------------------------------------------------------------
@@ -269,6 +364,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["query"],
             },
         },
+        {
+            name: "search_clawskills",
+            description: "Search across both skills and playbooks. For workflow-shaped queries, playbooks are ranked ahead of generic skill matches.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search query, e.g. 'closed won onboarding', 'zendesk jira escalation', 'lead sync'" },
+                },
+                required: ["query"],
+            },
+        },
     ],
 }));
 // Call tools
@@ -276,6 +382,7 @@ 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() });
+const SearchClawskillsSchema = z.object({ query: z.string() });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     if (name === "list_skills") {
@@ -373,6 +480,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             .join("\n\n---\n\n");
         return { content: [{ type: "text", text: `Playbook search results for "${query}":\n\n${output}` }] };
     }
+    if (name === "search_clawskills") {
+        const parsed = SearchClawskillsSchema.safeParse(args);
+        if (!parsed.success) {
+            return { content: [{ type: "text", text: `Invalid arguments: ${parsed.error.message}` }], isError: true };
+        }
+        const { query } = parsed.data;
+        const results = searchClawskills(skills, playbooks, query);
+        if (results.length === 0) {
+            return { content: [{ type: "text", text: `No results found for "${query}".` }] };
+        }
+        const output = results
+            .map(({ name: itemName, contentType, excerpts }) => {
+            const blocks = excerpts.map((e, i) => `--- match ${i + 1} ---\n${e}`).join("\n\n");
+            return `### [${contentType}] ${itemName}\n\n${blocks}`;
+        })
+            .join("\n\n---\n\n");
+        return { content: [{ type: "text", text: `Unified search results for "${query}":\n\n${output}` }] };
+    }
     return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
 });
 // ---------------------------------------------------------------------------

package/dist/index.test.js

@@ -3,7 +3,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { fileURLToPath } from "url";
-import { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, skillSummary, } from "./index.js";
+import { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, searchClawskills, getPlaybookMetadata, 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");
@@ -56,8 +56,8 @@ 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.",
+        "zendesk-jira": "---\ntitle: Zendesk -> Jira\nsystems:\n  - zendesk\n  - jira\ntags:\n  - support\n  - escalation\ntrigger_type: webhook\n---\n# Zendesk -> Jira\n\nEscalate bugs from support into engineering.\n\n## Idempotency\n\nUse zendesk:{ticket_id}.",
+        "hubspot-asana": "---\ntitle: HubSpot -> Asana\nsystems:\n  - hubspot\n  - asana\ntags:\n  - onboarding\n  - handoff\ntrigger_type: webhook\n---\n# HubSpot -> Asana\n\nCreate onboarding work from closed won deals.",
     });
 });
 afterAll(() => {
@@ -229,6 +229,32 @@ describe("searchPlaybooks", () => {
         expect(results[0].name).toBe("zendesk-jira");
     });
 });
+describe("getPlaybookMetadata", () => {
+    it("parses frontmatter metadata from playbooks", () => {
+        const playbooks = loadPlaybooks(tempPlaybooksDir);
+        const metadata = getPlaybookMetadata(playbooks.get("zendesk-jira"));
+        expect(metadata.systems).toContain("zendesk");
+        expect(metadata.tags).toContain("escalation");
+        expect(metadata.triggerType).toBe("webhook");
+    });
+});
+describe("searchClawskills", () => {
+    it("prefers playbooks for workflow-shaped queries", () => {
+        const skills = new Map([["hubspot", "HubSpot CRM API.\nUse for contacts and deals."]]);
+        const playbooks = loadPlaybooks(tempPlaybooksDir);
+        const results = searchClawskills(skills, playbooks, "closed won onboarding");
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].contentType).toBe("playbook");
+        expect(results[0].name).toBe("hubspot-asana");
+    });
+    it("still returns skill hits for non-workflow queries", () => {
+        const skills = loadSkills(tempDir);
+        const playbooks = loadPlaybooks(tempPlaybooksDir);
+        const results = searchClawskills(skills, playbooks, "Personal Access Token");
+        expect(results.length).toBeGreaterThan(0);
+        expect(results.some((result) => result.contentType === "skill" && result.name === "github")).toBe(true);
+    });
+});
 // ---------------------------------------------------------------------------
 // skillSummary
 // ---------------------------------------------------------------------------
@@ -245,6 +271,25 @@ describe("skillSummary", () => {
         const summary = skillSummary("# Title\n## Subtitle\n");
         expect(summary).toBe("");
     });
+    it("uses the frontmatter title instead of the --- delimiter", () => {
+        const summary = skillSummary("---\ntitle: Slack Incident -> Jira Issue\nsystems:\n  - slack\n---\n\n# Heading\n\nBody text.");
+        expect(summary).toBe("Slack Incident -> Jira Issue");
+    });
+    it("falls through past frontmatter that has no title", () => {
+        const summary = skillSummary("---\nsystems:\n  - slack\n---\n\n# Heading\n\nBody text.");
+        expect(summary).toBe("Body text.");
+    });
+    it("strips the blockquote marker from skill headers", () => {
+        const summary = skillSummary("# Jira Skill\n\n> **Last validated:** 2026-08-02\n");
+        expect(summary).toBe("**Last validated:** 2026-08-02");
+    });
+    it("gives every real playbook a summary that is not the --- delimiter", () => {
+        for (const [slug, content] of loadPlaybooks(REAL_PLAYBOOKS_DIR)) {
+            const summary = skillSummary(content);
+            expect(summary, `${slug} has no usable summary`).not.toBe("");
+            expect(summary, `${slug} summary is the frontmatter delimiter`).not.toBe("---");
+        }
+    });
 });
 // ---------------------------------------------------------------------------
 // Real skills validation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawskills-mcp",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "MCP server exposing ClawSkills API integration skill docs to AI agents",
   "license": "MIT",
   "author": "ClawSkills Contributors",
@@ -50,11 +50,11 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.0.0",
     "typescript": "^5.6.0",
     "vitest": "^2.0.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   }
 }

package/playbooks/INDEX.md

@@ -9,6 +9,7 @@ Workflow playbooks are end-to-end guides for multi-system automations. They comp
 | [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 |
+| [Slack Incident -> Jira Issue](./slack-jira-incident.md) | Slack, Jira | Convert in-chat incident escalations into tracked engineering work items |
 
 ## Playbook template
 
@@ -25,7 +26,6 @@ Each playbook should define:
 
 ## Next candidates
 
-- Slack incident -> Jira issue
 - GitHub PR -> Slack notification
 - Zendesk -> Salesforce case sync
 - Stripe payment failed -> HubSpot task

package/playbooks/hubspot-asana-onboarding.md

@@ -1,3 +1,17 @@
+---
+title: HubSpot Deal Won -> Asana Onboarding Kickoff
+systems:
+  - hubspot
+  - asana
+tags:
+  - crm
+  - onboarding
+  - handoff
+  - delivery
+  - revops
+trigger_type: webhook
+---
+
 # HubSpot Deal Won -> Asana Onboarding Kickoff
 
 ## Goal

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

@@ -1,3 +1,17 @@
+---
+title: Salesforce Lead -> HubSpot Contact Sync
+systems:
+  - salesforce
+  - hubspot
+tags:
+  - crm
+  - sync
+  - marketing
+  - lead
+  - revops
+trigger_type: scheduled_sync
+---
+
 # Salesforce Lead -> HubSpot Contact Sync
 
 ## Goal

package/playbooks/slack-jira-incident.md

@@ -0,0 +1,113 @@
+---
+title: Slack Incident -> Jira Issue
+systems:
+  - slack
+  - jira
+tags:
+  - incident
+  - support
+  - engineering
+  - escalation
+  - on-call
+trigger_type: webhook_event
+---
+
+# Slack Incident -> Jira Issue
+
+## Goal
+
+Capture an incident discussion happening in Slack as a tracked Jira issue, so engineering, on-call, and leadership can follow resolution outside the noisy chat surface. The Slack message remains the conversation record; Jira becomes the accountable work item.
+
+## Systems involved
+
+- Slack: incident detection, real-time discussion, customer-impact reports
+- Jira: durable tracking, engineering ownership, link to postmortem
+- (Optional) PagerDuty or Opsgenie: paging — usually upstream of this playbook, not driven by it
+
+## Trigger
+
+Any of:
+- A Slack message receives a designated reaction emoji (e.g. `:jira:` or `:rotating_light:`) — fired via Slack `reaction_added` event
+- A Slack slash command (e.g. `/incident <summary>`) invoked in any channel
+- A message posted in a channel matching `incident-*` with a designated keyword prefix
+
+Reaction-based triggers are the most reliable and lowest-friction; slash commands are best when summary capture must be deliberate.
+
+## Source of truth
+
+- Incident discussion / customer-impact reports: Slack (channel + thread)
+- Engineering execution state, severity, owner, resolution: Jira
+- Linkage: Slack permalink in Jira description; Jira key replied to the Slack thread
+
+## Sequence
+
+1. Receive the inbound request — either a **Slack Events API event** (`reaction_added` or `message`) delivered as JSON with the event wrapped under an `event` object, OR a **Slash Command HTTP request** (separate endpoint, form-encoded body with `channel_id`, `user_id`, `text`, `trigger_id` at the top level — no `event` wrapper and no `event_id`). Both are signed by Slack; verify the request with `X-Slack-Signature` and `X-Slack-Request-Timestamp` (5-minute window).
+2. **Ack with HTTP 200 immediately after signature verification — on every delivery, not just retries.** Slack Events API enforces a 3-second response budget on first delivery and on retries; missing it causes Slack to redeliver the event and creates avoidable duplicate work. Hand the remaining steps off to an async worker / queue. If a retry header is present (`X-Slack-Retry-Num`), treat it as an expected duplicate signal — still ack 200 and let the dedupe step catch it. (Slash Command requests don't carry retries but still benefit from immediate ack so the user sees a fast response.)
+3. Build a deterministic correlation key: `slack:{team_id}:{channel_id}:{ts}`. The `{ts}` source depends on the trigger:
+   - **`reaction_added`:** `event.item.ts` — the timestamp of the message that was reacted to.
+   - **`message`:** `event.ts` — the original message timestamp; for replies posted into a thread, prefer `event.thread_ts` so the key anchors to the parent message and all in-thread activity collapses to one issue.
+   - **Slash Command:** no inbound `message_ts` exists. Either (a) require the command be invoked from inside a thread and use `thread_ts` from the command payload, or (b — recommended default) the async worker first posts a bot anchor message via `chat.postMessage` and uses that posted message's `ts`. Option (b) requires no user training and gives the thread reply a natural place to land.
+4. Fetch the originating message and thread context via `conversations.history` (with `latest=ts`, `inclusive=true`, `limit=1`) and `conversations.replies` for thread.
+5. Resolve `permalink` for the message via `chat.getPermalink`.
+6. Search Jira for an existing issue carrying that correlation key (label or custom field). If found, skip creation and reuse the Jira key.
+7. If no existing issue, create a Jira issue (`POST /rest/api/3/issue`) with:
+   - `summary` derived from the message text (first sentence, truncated to ~120 chars).
+   - `description` containing the Slack permalink, the message text, and up to N thread replies for context.
+   - `priority`, `issuetype`, `project`, `components` derived from per-channel config or sensible defaults.
+   - A label `slack-incident` plus the correlation key as a label or custom-field value.
+8. Reply in the Slack thread via `chat.postMessage` with the Jira issue link, key, and current assignee.
+9. (Optional) Pin the bot reply if the channel is an incident channel.
+10. (Optional) Mirror selected Jira status transitions back to Slack via `chat.postMessage` once a status mapping is finalized.
+
+## Field mapping
+
+| Slack | Jira |
+|-------|------|
+| Correlation source (varies by trigger): `reaction_added` → `event.item.channel` + `event.item.ts`; `message` → `event.channel` + `event.ts` (use `event.thread_ts` for in-thread replies); Slash Command → command payload `channel_id` + `ts` of the bot's anchor message (or `thread_ts` if invoked inside a thread) | correlation key `slack:{team_id}:{channel_id}:{ts}` stored in label / custom field |
+| message text (first sentence) | `summary` |
+| message text + thread replies + permalink | `description` — Jira Cloud REST v3 requires **ADF (Atlassian Document Format) JSON**; convert Slack text + thread replies into an ADF document (see `skills/jira/skill.md` § ADF) |
+| reactor user / slash command invoker | `reporter` (after Slack-user -> Atlassian-account-id mapping) |
+| channel name or category | `components` or labels |
+| keyword/severity from text | `priority` (P1/P2/P3) |
+| message permalink | external link field or `description` |
+
+## Idempotency
+
+- **Dedup key:** `slack:{team_id}:{channel_id}:{ts}` (same format as the correlation key in Sequence step 3) stored as a Jira label and/or a custom field for searchability.
+- Slack delivers Events API events at least once. Dedupe at the edge using the **payload field `event_id`** (present in the JSON wrapper, not an HTTP header). Slash command requests have **no `event_id`** — dedupe those by correlation key alone. Always re-dedupe by correlation key immediately before the Jira create call.
+- If multiple users react with the trigger emoji on the same message, only the first reaction creates the issue; subsequent reactions are noops (or append a reactor list to the Jira issue).
+- Slash command invocations must check correlation by `channel_id + thread_ts` first to avoid duplicating during incidents.
+
+## Retry and partial failure policy
+
+- **Slack rate limits** are per-method tier (Tier 1: 1+/min, Tier 4: 100+/min). On `429`, respect the `Retry-After` header — do not retry sooner.
+- **Jira rate limits** use cost-based throttling. On `429` or `503`, use bounded exponential backoff (base 1s, max 60s, max 5 attempts).
+- Do not blindly retry Jira `400` validation errors — log, surface to operators, and quarantine the event.
+- If Jira create succeeds but the Slack thread reply fails, do not retry Jira create. Reconcile by searching Jira for the correlation key and posting the thread reply on the next event or reconciliation pass.
+- Slack event endpoints must return 200 within 3 seconds. Push work to a queue if create + reply exceeds that budget.
+
+## Reconciliation
+
+- Hourly or daily job: scan recent messages in channels matching `incident-*` for trigger reactions/keywords and confirm a Jira issue with the matching correlation key exists. Create any missing issues.
+- Reverse pass: list Jira issues with label `slack-incident` updated in the last 24h; verify each has at least one Slack thread reply with the Jira link. Repair missing replies.
+- Drift check: confirm Jira issues marked `Done` have a corresponding Slack thread reply announcing closure (if status mirroring is enabled).
+
+## Rollback guidance
+
+- If a Jira issue was created in error, transition it to a closed/cancelled state (`Won't Do`, `Cancelled`) rather than deleting it — preserves the dedup key so an accidental re-reaction does not recreate it.
+- Remove the trigger reaction in Slack via `reactions.remove` (cosmetic) and add a `:white_check_mark:` reply explaining the cancellation.
+- Add the correlation key to a deny-list table to prevent re-creation if reactions get added again.
+
+## Observability
+
+- Time from reaction to Jira issue creation (target: < 5s p95).
+- Daily count of incidents created, by channel and by reactor.
+- Duplicate-detection rate (events that would have created duplicates but were short-circuited).
+- Failed Slack signature verifications (anomalous — investigate).
+- Failed Jira creates, broken down by HTTP status and error code.
+- Lag between Jira closure and Slack-thread closure message.
+
+## Related skills
+
+- [`skills/slack/skill.md`](../skills/slack/skill.md)
+- [`skills/jira/skill.md`](../skills/jira/skill.md)

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

@@ -1,3 +1,17 @@
+---
+title: Zendesk Ticket -> Jira Bug Escalation
+systems:
+  - zendesk
+  - jira
+tags:
+  - support
+  - engineering
+  - escalation
+  - incident
+  - handoff
+trigger_type: webhook_or_incremental_sync
+---
+
 # Zendesk Ticket -> Jira Bug Escalation
 
 ## Goal

package/skills/ROADMAP.md

@@ -19,9 +19,9 @@ This skill set enables end-to-end automation and integration across the most com
 | 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.4.0 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
+| **MCP server** — `clawskills-mcp` v0.7.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 |
+| **Release automation** — `prepare-release.yml` workflow_dispatch → release PR; `release.yml` on merge → npm publish via OIDC + tag | ✅ Live |
 | **Test suite** — Vitest unit tests + real-skills validation (required sections, ≥5 KB, all 14 tools) | ✅ Live |
 | **Public repo readiness** — MIT license, `.gitignore`, full `package.json` metadata | ✅ Ready |
 
@@ -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.4.0 | Maintain via `release.yml` |
+| npm (`clawskills-mcp`) | ✅ Live — v0.7.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 |
@@ -175,18 +175,19 @@ Each skill/recipe is scored on five dimensions (1–5 each):
 - **Freshness pipeline:** Weekly cron checks `Last validated:` dates (see Priority 2 above).
 - **Live smoke tests:** Optional phase B — weekly auth + read tests against sandboxes.
 - **Breaking change monitoring:** Subscribe to each vendor's developer changelog:
-  - Monday: https://developer.monday.com/changelog
-  - Salesforce: https://help.salesforce.com/s/articleView?id=release-notes.salesforce_release_notes.htm
+  - Monday: https://developer.monday.com/api-reference/docs/api-versioning (versioning table) + https://developer.monday.com/changelog (entries)
+  - Salesforce: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/rest_rns.htm — ⚠️ JS-rendered: the content body is injected client-side, so plain HTTP fetchers (curl, wget, GitHub Actions cron jobs without a JS engine) return only the page shell. Read it in a real browser, or use a headless-browser tool (Playwright/Puppeteer) — see https://github.com/Shanksg/clawskills/issues/12.
+    - **Workaround (found 2026-08-02):** https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_versions.htm **is** plain-fetchable and lists the highest published API version with its release name. That covers "did a new version ship?" — the most common freshness question — without a browser. Only the delta review still needs one.
   - Jira: https://developer.atlassian.com/cloud/jira/platform/changelog/
-  - Dynamics 365: https://learn.microsoft.com/en-us/dynamics365/release-plans/
+  - Dynamics 365: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/web-api-versions (Web API version differences) + https://learn.microsoft.com/en-us/dynamics365/released-versions/microsoft-dataverse (weekly release notes)
   - HubSpot: https://developers.hubspot.com/changelog
-  - ServiceNow: https://developer.servicenow.com/dev.do
-  - Zendesk: https://developer.zendesk.com/api-reference/ticketing/introduction/#api-changelog
-  - Asana: https://developers.asana.com/docs/changelog
-  - GitHub: https://github.blog/changelog/
-  - Figma: https://www.figma.com/developers/api#changelog
-  - Slack: https://api.slack.com/changelog
-  - Stripe: https://stripe.com/docs/changelog
+  - ServiceNow: https://www.servicenow.com/docs/bundle/australia-release-notes/page/release-notes/family-release-notes.html (current named release — rotate this URL on each new release; https://www.servicenow.com/docs/r/release-notes/available-versions.html lists which family is current)
+  - Zendesk: https://developer.zendesk.com/api-reference/changelog/changelog/
+  - Asana: https://forum.asana.com/c/forum-en/api/api-change-log/204 — Asana hosts their dated API changelog as a forum category (individual entries are threads under it); the developer-portal page just redirects here
+  - GitHub: https://github.blog/changelog/ (entries) + https://docs.github.com/en/rest/about-the-rest-api/breaking-changes (per-version breaking-change list — the fetchable source of truth for REST API versions)
+  - Figma: https://developers.figma.com/docs/rest-api/changelog/ (moved from `figma.com/developers/api#changelog`, which now redirects)
+  - Slack: https://docs.slack.dev/changelog (moved from `api.slack.com/changelog`, which now redirects)
+  - Stripe: https://docs.stripe.com/changelog (moved from `stripe.com/docs/changelog`, which now redirects)
   - Notion: https://developers.notion.com/page/changelog
   - Linear: https://linear.app/changelog
 
@@ -202,7 +203,11 @@ Each skill/recipe is scored on five dimensions (1–5 each):
 - PRs to `skill.md` files require: (a) reference to official doc, (b) tested curl/pseudocode example, (c) updated `Last validated:` date.
 - Branch convention: `skill/<toolname>` → PR → merge to main.
 - CI runs `npm test` on every PR — validates skill loads and has all required sections.
-- Releases: merge to main, then GitHub Actions → **Release** → Run workflow → pick `patch / minor / major`.
+- Releases (two stages — `main` is protected, so nothing can be pushed to it directly):
+  1. GitHub Actions → **Prepare Release** → Run workflow → pick `patch / minor / major`. Opens a `release/vX.Y.Z` PR with the version bump; publishes nothing.
+  2. Merge that PR. **Release** publishes to npm via OIDC and tags `vX.Y.Z`.
+
+  > `release.yml` must keep that exact filename — npm's trusted publisher config pins it. Renaming it breaks publishing with a 404.
 
 ---
 

package/skills/asana/skill.md

@@ -1,8 +1,25 @@
 # Asana Skill
 
-> **Last validated:** 2026-02-19 | **API:** Asana REST API 1.0
+> **Last validated:** 2026-08-02 | **API:** Asana REST API 1.0
 > **REST base URL:** `https://app.asana.com/api/1.0`
 > **Assumed product:** Asana cloud. Enterprise controls, SCIM, and admin APIs may require additional scopes and plan-specific access.
+>
+> **⚠️ Changes since 2026-02-19:**
+> - **Out of Office API (2026-04-27):** new endpoints replace the legacy `vacation_dates` field, which is now **deprecated** on the user object. Migrate any code that reads/writes `vacation_dates`.
+> - **RBAC Role API (2026-02-27):** new CRUD endpoints for managing custom roles on Enterprise plans.
+> - **Timesheet Approval Status API (2026-03-20)** and **Categories for Time Tracking Entries (2026-04-01):** new time-tracking primitives — useful for ops/finance workflows.
+> - **Project portfolio + advanced project search APIs (2026-03-23):** new endpoints for portfolio settings and advanced project filtering.
+> - **Custom Types in Memberships (2026-03-31):** memberships endpoints now support custom-type filters.
+> - **Goals API (2026-04-06):** goals now expose privacy settings, default access levels, and stories.
+> - **Enhanced filtering on the Search API (2026-04-06):** custom task types now usable as filter dimensions.
+>
+> **⚠️ Changes since 2026-05:**
+> - **Granular RBAC permissions (2026-07-02):** finer-grained role-based access control, extending the Role API above.
+> - **AI Studio Usage API (2026-07-02):** new endpoint for tracking AI Studio consumption.
+> - **`sort_by=relevance` on project search (2026-06-04):** relevance ordering now available alongside the existing sort options.
+> - **AI teammates / agent API support announced (2026-05-28)** — not yet GA; no action required, but expect new actor types on tasks and stories.
+>
+> **Source:** https://forum.asana.com/c/forum-en/api/api-change-log/204
 
 ## What this skill enables
 

package/skills/dynamics365/skill.md

@@ -1,8 +1,11 @@
 # Microsoft Dynamics 365 Skill
 
-> **Last validated:** 2026-02-19 | **API:** Dataverse Web API (OData v4) v9.2
+> **Last validated:** 2026-08-02 | **API:** Dataverse Web API (OData v4) v9.2
 > **Base URL:** `https://{org-name}.crm.dynamics.com/api/data/v9.2/`
 > **Assumed product:** Dynamics 365 Sales. Other apps (Customer Service, Field Service) share the same Web API pattern.
+>
+> **Note:** Re-confirmed on 2026-08-02: v9.0, v9.1, and v9.2 still have identical Web API behavior with no breaking changes. No v9.3 or v10 announced. The 2026 release waves are PowerApps/Copilot features, not Web API surface changes. Microsoft's own guidance is to pin the version that was current when you wrote the code and test before moving up, rather than tracking the newest automatically.
+> **Source:** https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/web-api-versions (page revision 2026-03-27)
 
 ---