clawskills-mcp 0.3.5 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawskills-mcp",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "MCP server exposing ClawSkills API integration skill docs to AI agents",
   "license": "MIT",
   "author": "ClawSkills Contributors",
@@ -33,8 +33,12 @@
     "skills/"
   ],
   "scripts": {
-    "prepack": "rm -rf ./skills && cp -r ../skills ./skills",
-    "build": "tsc",
+    "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",
     "dev": "ts-node src/index.ts",
     "test": "vitest run",

package/skills/ROADMAP.md

@@ -19,7 +19,7 @@ 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.3.4 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
+| **MCP server** — `clawskills-mcp` v0.3.6 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.3.6 | 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 |

package/skills/asana/skill.md

@@ -1,5 +1,9 @@
 # Asana Skill
 
+> **Last validated:** 2026-02-19 | **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.
+
 ## What this skill enables
 
 - Automatically create, assign, and structure tasks from any external intake channel (forms, emails, Slack messages, webhook events) so work is captured without manual entry.
@@ -681,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 |