Related Pages

Related topics: Skills & Cross-Tool Playbooks, MCP Server (clawskills-mcp), Freshness Pipeline, Governance & Operations

ClawSkills Overview & Architecture

Purpose & Scope

ClawSkills is a curated library of integration skill documents that teach AI agents, automation builders, and LLMs how to reliably use the APIs of common SaaS platforms used in go-to-market and operations workflows. Each skill doc is a structured Markdown file that contains working code examples, rate limit rules, error playbooks, and platform-specific version details. The repository is designed so that an agent can be given a skill doc as context and produce production-grade integration code without further research Source: [README.md:1-30].

The project ships 14 structured Markdown skill docs covering tools such as Monday.com, Salesforce, Jira, Microsoft Dynamics 365, HubSpot, ServiceNow, Zendesk, Slack, GitHub, Notion, Linear, Figma, Asana, and Stripe, plus workflow playbooks for cross-tool automations Source: [skills/INDEX.md:30-60]. Each skill tracks its own API version and Last validated date, while the MCP server has its own npm version for the server layer itself Source: [mcp-server/README.md:3-8].

Repository Structure & Layers

The repository is organized into three distinct layers, each with a separate versioning and update cadence:

The top-level README.md describes the layout: skill docs live under skills/ organized per platform, cross-tool workflows live under playbooks/, and an INDEX.md in each folder acts as the entry point Source: [README.md:13-30]. The skills/INDEX.md file acts as the master catalog and references a ROADMAP.md for the phased build plan and governance model Source: [skills/INDEX.md:1-5].

The playbooks/ layer captures cross-tool workflows end to end — trigger, system sequence, field mapping, idempotency, failure policy, and operational guardrails — and is referenced from skills/INDEX.md via a relative link Source: [skills/INDEX.md:5-8, README.md:50-60].

MCP Server Architecture

The MCP server is a TypeScript package (clawskills-mcp) published to npm that exposes the skill library as Model Context Protocol tools usable from Claude Desktop, Claude Code, or any MCP-compatible client Source: [mcp-server/README.md:1-15]. The recommended install is zero-config via npx -y clawskills-mcp, with a Docker fallback built from mcp-server/Dockerfile Source: [mcp-server/README.md:25-40].

The package is an ESM module that ships a single binary (clawskills-mcp → dist/index.js) and bundles both the skills/ and playbooks/ directories at publish time, so the server is self-contained Source: [mcp-server/package.json:1-25, mcp-server/package.json:25-35]. Build scripts include sync:skills (synchronizes bundled docs from the repo into the package), check:skills, check:freshness, and check:docs, all of which run as part of npm run build via the prepack hook Source: [mcp-server/package.json:30-50].

The server exposes tools for AI agents to discover and read the docs at runtime, including list_skills, get_skill, search_skills, and list_playbooks Source: [mcp-server/README.md:45-55]. A Vitest test suite validates the loader logic against fixture skills and playbooks, including idempotency-key conventions such as zendesk:{ticket_id} used in cross-tool workflows Source: [mcp-server/src/index.test.ts:1-50].

flowchart LR
    A[Author edits<br/>skills/<tool>/skill.md] --> B[git push to main]
    B --> C[mcp-server sync-skills script]
    C --> D[Bundled skills/<br/>in npm package]
    D --> E[npx clawskills-mcp]
    E --> F[MCP client<br/>Claude Desktop / Code]
    F --> G[Agent reads skill<br/>via list_skills / get_skill]
    G --> H[Agent writes<br/>integration code]

Skill Doc Anatomy

Every skill doc follows a consistent template so that an agent can rely on section ordering regardless of the platform. The README enumerates the required sections:

• Best-fit use cases — high-signal scenarios where the tool excels
• Key concepts & data model — objects, fields, relationships, IDs
• Authentication & permissions — auth flows with curl examples and least-privilege scopes
• Common workflows (recipes) — 6–12 step-by-step recipes with request/response examples
• Query patterns & filtering — pagination, incremental sync, dedup
• Reliability: rate limits, retries, idempotency — verified limits and Python backoff code
• Error handling & troubleshooting — "if you see X, do Y" playbooks
• Security & compliance — PII, audit trails, token guidance
• Testing checklist — sandbox QA checklist
• Sources — official documentation links

Source: README.md:30-50

Concrete examples from individual skill docs illustrate the pattern: skills/notion/skill.md pins the API version header to Notion-Version: 2025-09-03 and documents the multi-source database migration introduced in that version Source: [skills/notion/skill.md:60-80, skills/notion/skill.md:120-140]. skills/linear/skill.md lists core GraphQL objects (Issue, Project, Cycle, Label, Comment, Webhook) and their field types in a single reference table Source: [skills/linear/skill.md:1-30]. skills/slack/skill.md and skills/figma/skill.md document webhook + Block Kit / dev-resources recipes respectively Source: [skills/slack/skill.md:30-55, skills/figma/skill.md:90-120].

Validation & Freshness Pipeline

Because vendor APIs change frequently — Monday.com releases a new GraphQL version every quarter and Notion ships dated version headers — each skill tracks a Last validated date and the project maintains a freshness check that re-validates docs against live sources Source: [README.md:60-70, skills/ROADMAP.md:1-30]. The npm package exposes this as npm run check:freshness, wired into check:skills.mjs --freshness Source: [mcp-server/package.json:35-45].

A known limitation surfaced by the community (tracked in issue #12) is that several vendor changelog pages are rendered client-side and return only headers or CSS errors when fetched with plain HTTP clients such as curl, the GitHub Actions WebFetch action, or cron jobs. After the 2026-05-11 re-validation pass, this broke the freshness pipeline for affected vendors. The proposed mitigation is a headless-browser fallback (e.g., Playwright or Puppeteer) for JS-rendered changelog pages, layered behind the existing plain-HTTP fetcher so it only triggers when needed.

See Also

• Skills Index — full tool catalog and top workflows per tool
• Skills Roadmap — phased build plan, governance, and packaging milestones
• Playbooks Index — cross-tool workflow recipes
• MCP Server README — install, run, and tool reference for clawskills-mcp

Related Pages

Related topics: ClawSkills Overview & Architecture, MCP Server (clawskills-mcp)

Skills & Cross-Tool Playbooks

ClawSkills is organized as a two-layer knowledge product. The Skills layer documents one SaaS platform at a time (auth, data model, recipes, error handling), while the Cross-Tool Playbooks layer orchestrates those same tools end-to-end for a single business outcome. Together they let an AI agent or automation builder go from "I want to mirror Salesforce leads into HubSpot" to working, validated code without re-deriving the integration details from scratch. Source: README.md

Layer 1: Per-Tool Skills

Each tool gets its own skills/<tool>/skill.md file. The repository ships 14 of them, covering the most common GTM and operations platforms (Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Slack, Figma, Notion, Linear, etc.). Source: README.md

Every skill doc follows the same template so an agent can navigate them predictably:

• Best-fit use cases — when this tool is the right choice
• Key concepts & data model — objects, fields, relationships, IDs
• Authentication & permissions — auth flows with working curl examples and least-privilege scopes
• Common workflows (recipes) — 6–12 step-by-step recipes with request/response examples
• Query patterns & filtering — pagination, incremental sync, dedup
• Reliability — verified rate limits, retry/backoff code in Python
• Error handling & troubleshooting — "if you see X, do Y" playbook
• Security & compliance — PII, audit trails, token guidance
• Testing checklist — a QA checklist you can run against a sandbox
• Sources — links to the official docs the skill was validated against

Source: README.md

Concrete examples from real skill files:

• The Notion skill pins API version 2025-09-03 in every request header and documents the multi-source database migration, including the data_source_id parent change. Source: skills/notion/skill.md
• The Linear skill centers on GraphQL and maps the priority integer scale (0=None … 4=Low) plus the dual id / identifier field convention. Source: skills/linear/skill.md
• The Slack skill provides a recipes table that maps each business outcome (runbook page, deploy summary, CRM sync, reaction-to-ticket) to the right combination of Block Kit, thread, and webhook event. Source: skills/slack/skill.md
• The Figma skill ships 10 recipes that span the full asset pipeline — webhook → export → upload — including HMAC verification and dev-resource handoff. Source: skills/figma/skill.md

The skills/INDEX.md is the discovery entry point: a tools-covered table, an auth-method quick reference (e.g. Salesforce OAuth 2.0 JWT Bearer, HubSpot Private App Token, Dynamics 365 Azure AD Client Credentials), and per-tool "top 10 workflows" lists that double as a high-signal index. Source: skills/INDEX.md

Layer 2: Cross-Tool Playbooks

A playbook is the orchestration layer. While a skill answers *"how do I call this API"*, a playbook answers *"how do these systems work together for a real business outcome"*. Each playbook defines:

• Business trigger
• Systems involved and the source-of-truth decision
• Sequence of operations
• Field mapping between systems
• Idempotency and dedup keys
• Retry and partial-failure policy
• Reconciliation and rollback guidance
• Observability / alerting checks

Source: skills/ROADMAP.md and playbooks/INDEX.md

The flagship playbooks shipped today are:

Source: playbooks/INDEX.md

The roadmap explicitly treats the playbook layer as the next product priority: the goal is to add high-frequency workflows (GitHub PR → Slack, Stripe payment-failed → HubSpot, Notion request → Asana) and to expose them through MCP once the doc layer stabilizes. Source: skills/ROADMAP.md

Access Patterns

The repo supports three consumption patterns, in increasing order of integration:

1. Direct file read — load the relevant skill.md into the prompt context. The README recommends including the full doc for code generation, and only the "Error handling" or "Reliability" section for narrow tasks. Source: README.md
2. RAG / vector indexing — chunk every skill.md with MarkdownHeaderTextSplitter and store in Chroma or LlamaIndex so the agent retrieves only the passages it needs. Source: README.md
3. MCP server — clawskills-mcp exposes the skills and playbooks as structured tools (list_skills, get_skill, search_skills, list_playbooks, get_playbook, search_playbooks, search_clawskills) that Claude Desktop / Claude Code can call directly. The server is versioned independently from the docs because it tracks the tooling layer, not the underlying SaaS APIs. Source: mcp-server/README.md

Freshness, Validation, and Known Gaps

Each skill doc carries its own Last validated date and pinned API version. A quarterly freshness pipeline is responsible for flagging docs older than 90 days and re-validating them against live vendor changelogs. Source: skills/ROADMAP.md

A known limitation surfaced by the 2026-05-11 re-validation pass: several vendor changelog pages are rendered client-side and return only headers or CSS errors when fetched with curl, WebFetch, or GitHub Actions cron jobs. This breaks the freshness pipeline. The proposed fix — tracked in issue #12 — is to add a headless-browser fallback (e.g. Playwright/Chromium) that activates only when the plain HTTP client receives an empty body, and to record the strategy used per vendor so the next pass can skip vendors already known to be JS-rendered. Until that lands, consumers should treat freshness warnings on those specific vendors as advisory rather than blocking.

See Also

• skills/INDEX.md — full tools-covered table and top-workflow index
• skills/ROADMAP.md — phased build plan, prioritization formula, governance model
• playbooks/INDEX.md — flagship cross-tool playbooks
• mcp-server/README.md — MCP tool reference for Claude integration
• Issue #12 — headless-browser fallback for JS-rendered changelogs

Related Pages

Related topics: ClawSkills Overview & Architecture, Skills & Cross-Tool Playbooks, Freshness Pipeline, Governance & Operations

MCP Server (clawskills-mcp)

Overview

clawskills-mcp is the Model Context Protocol (MCP) server component of the ClawSkills repository. It exposes the project's structured Markdown skill documents and cross-tool workflow playbooks as discoverable tools to AI agents such as Claude Desktop, Claude Code, and any other MCP-compatible client. The server itself versions independently of the underlying SaaS APIs it documents — at the time of writing, the npm package is at 0.6.0 while the skills bundle covers 14 platforms plus a playbooks layer. Source: mcp-server/package.json:3-4.

The core purpose is to make the integration knowledge base — auth patterns, rate-limit handling, error codes, and step-by-step recipes — consumable in-context by an LLM. Rather than copy-pasting recipes into prompts, agents can call get_skill or search_skills to retrieve the exact, version-pinned documentation at the moment it is needed. Source: mcp-server/README.md:1-7.

Architecture

The server is a single-process TypeScript application. At startup it reads Markdown files from the bundled skills/ and playbooks/ directories, indexes them in memory, and registers a set of tools against the MCP Server instance declared in mcp-server/src/index.ts:1-30. The package type is ESM, the binary entry is dist/index.js, and the published tarball ships dist/, skills/, and playbooks/ so the documents travel with the server. Source: mcp-server/package.json:24-32.

flowchart LR
    A[MCP Client<br/>Claude Desktop / Claude Code] -->|JSON-RPC| B(clawskills-mcp<br/>Node process)
    B --> C[skills/<br/>14 platform docs]
    B --> D[playbooks/<br/>cross-tool workflows]
    B -->|list_skills<br/>get_skill<br/>search_skills<br/>list_playbooks| A
    E[Repo maintainer] -->|sync:skills| F[sync-skills.mjs]
    F -->|copies & validates| C
    F -->|copies & validates| D

The flow shows the read path (client ↔ server ↔ bundled docs) and the build-time path (sync-skills.mjs populates the bundle before publish). Source: mcp-server/package.json:34-42.

Installation & Configuration

Three deployment paths are supported. The recommended path for Claude Desktop and Claude Code is npx -y clawskills-mcp — no install is required; the client launches the binary on demand. The MCP config entry registers the server under the name clawskills and points its command at npx. Source: mcp-server/README.md:11-32.

{
  "mcpServers": {
    "clawskills": {
      "command": "npx",
      "args": ["-y", "clawskills-mcp"]
    }
  }
}

For containerized environments, a Dockerfile is provided at the repo root and is invoked as docker build -t clawskills-mcp -f mcp-server/Dockerfile .. The image exposes the server over stdio (docker run --rm -i) so it can be wired into any MCP-aware orchestrator. Source: mcp-server/README.md:34-40.

The package.json scripts cover the developer lifecycle: sync:skills re-bundles the docs into mcp-server/skills/, check:skills and check:freshness validate them, check:docs runs a documentation linter, build performs sync:skills plus a TypeScript compile, and prepack enforces a sync before npm publish. Source: mcp-server/package.json:34-42.

Exposed Tools

The server registers a small, focused tool surface. ListToolsRequestSchema returns four tools whose inputSchema is declared inline in mcp-server/src/index.ts:14-50. The README confirms this shape, and the partial list_playbooks entry visible in mcp-server/README.md:46-52 suggests a fourth tool for browsing the cross-tool recipes stored under playbooks/.

The get_skill tool accepts an optional section argument with documented aliases such as auth, rate-limits, errors, pagination, recipes, gotchas, webhooks, overview, and fields. This lets an agent request a narrow slice — for example, only the rate-limit handling section — when context budget is tight. Source: mcp-server/src/index.ts:25-40.

Skill Synchronization Pipeline

scripts/sync-skills.mjs is the bridge between the repo's canonical skill docs at skills/<tool>/skill.md and the bundle that ships inside the npm package. prepack runs this script automatically, and the build script runs it before tsc, ensuring the published artifact always carries a current copy of every doc. Source: mcp-server/package.json:36-42.

The validation step is check:skills, with a separate check:freshness mode intended to confirm that the Last validated: date in each doc header is still recent. This freshness check is the seam where a known limitation surfaces — see the next section.

Community Context — Freshness Pipeline Limitations

A tracked issue, Shanksg/clawskills#12, reports that several vendor changelog pages (the very pages the freshness pipeline reads to decide whether a doc needs re-validation) are rendered client-side. Plain HTTP fetches via curl, WebFetch, and the GitHub Actions cron return only headers and CSS errors, so check:freshness cannot determine whether a skill is stale. The proposed fix is a headless-browser fallback that would execute JavaScript and recover the rendered DOM before diffing. This is directly relevant to clawskills-mcp because every get_skill call implicitly trusts the freshness claim in the document it returns; a stale skill surfaced through search_skills would mislead the calling agent. Source: mcp-server/package.json:38-39, skills/ROADMAP.md:1-20.

Until the headless fallback lands, operators running the freshness check on a schedule should treat any skill whose vendor publishes a JS-rendered changelog as needing manual re-validation, and pin API versions explicitly when integrating — exactly the pattern the skills themselves recommend. Source: README.md:1-30, skills/INDEX.md:1-20.

See Also

• README.md — top-level project overview and RAG integration patterns
• skills/INDEX.md — full catalog of skill docs, top workflows, and quick-reference auth tables
• skills/ROADMAP.md — phased build plan, including the freshness pipeline work tracked in issue #12
• Issue #12: Freshness pipeline headless-browser fallback — open community discussion motivating the limitation above

Related Pages

Related topics: ClawSkills Overview & Architecture, Skills & Cross-Tool Playbooks, MCP Server (clawskills-mcp)

Freshness Pipeline, Governance & Operations

Purpose & Scope

ClawSkills is a curated library of integration skill documents for SaaS platforms, with a published Model Context Protocol (MCP) server on top. Because vendor APIs change continuously, the project maintains an explicit freshness pipeline that re-validates every skill against the live vendor documentation, plus a governance model that separates documentation versioning from server-tooling versioning.

The high-level role of this subsystem is threefold:

1. Detect staleness in any skill.md whose underlying API has changed since its Last validated: date.
2. Sync content so the in-repo skill docs match the vendor's current published reference.
3. Govern releases so that documentation refreshes and MCP server tooling ship on independent cadences.

Source: README.md ("Keeping skills current" and the "Releases are automated" notes).

Freshness Validation Pipeline

The pipeline is implemented as a sequence of Node scripts in mcp-server/scripts/:

• check-skills.mjs — structural linter. Walks every skills/<tool>/skill.md, asserts all 11 required sections are present, and validates that the document header contains a Last validated: date and a pinned API version. It is the same validator invoked from CI by npm test (Source: README.md, "Contributing" section).
• check-docs.mjs — link and reference auditor. Ensures every cited ## Sources block resolves to a real, official vendor URL and that no skill claims behavior that is not backed by a source link.
• sync-skills.mjs — the diff engine. Compares the current skill.md against the latest vendor changelog/API reference, surfaces the diff at the section level, and writes back updated snippets after a maintainer review.

The end-to-end flow looks like this:

flowchart LR
    A[Vendor API docs / changelog] --> B[check-docs.mjs<br/>link audit]
    B --> C[check-skills.mjs<br/>structural lint]
    C --> D[Human review<br/>of diff]
    D --> E[sync-skills.mjs<br/>apply updates]
    E --> F[Update Last validated:<br/>date in header]
    F --> G[git commit + PR]
    G --> H[CI: npm test]
    H -->|pass| I[Merge to main]
    I --> J[GitHub Actions:<br/>Release workflow]

Source: mcp-server/README.md (MCP server packaging and CI surface) and skills/ROADMAP.md (Priority 1: Freshness).

Known limitation: JS-rendered changelogs

Issue #12 — *Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs* — documents that several vendor changelog pages (confirmed during the 2026-05-11 re-validation pass) are rendered client-side. Plain curl, WebFetch, and the existing GitHub Actions cron jobs return only headers or CSS errors, which breaks the freshness pipeline. The agreed remediation is to add a headless-browser fallback (e.g., Playwright/Puppeteer) behind sync-skills.mjs so SPAs render fully before diffing. Until that lands, those vendors are validated manually and their Last validated: dates are pinned with a "manual review" note.

Governance Model

ClawSkills deliberately splits versioning responsibility so that a doc refresh does not force a server release, and vice versa.

Source: README.md ("Each skill tracks its own platform version and Last validated date in the document header. The MCP package has a separate npm version…") and mcp-server/README.md ("ClawSkills currently contains 14 structured Markdown skill docs… while clawskills-mcp has its own npm version for the server itself").

Release process

Releases are automated end-to-end:

1. A PR that touches any skill.md, playbooks/, or mcp-server/ source is opened.
2. CI runs npm test, which executes check-skills.mjs to enforce the 11-section template.
3. On merge to main, a maintainer triggers the Release workflow in GitHub Actions, picking patch / minor / major.
4. The MCP server is published to npm; skill docs are versioned implicitly by their header date.

Source: README.md ("Releases are automated: merge to main, then go to GitHub Actions → Release → Run workflow → pick patch / minor / major.").

Known Issues & Operational Guardrails

• Monday.com — new API version is released every quarter. The current pinned version is 2026-01; downstream consumers must always send the API-Version header explicitly (Source: README.md).
• Figma — the legacy files:read scope is deprecated; consumers must migrate to granular scopes such as file_content:read and file_comments:write. Rate limits were updated in Nov 2025 and now vary by plan and seat type (Source: README.md).
• Notion — version 2025-09-03 introduced multi-source databases. Single-source databases (the vast majority) are unaffected, but multi-source databases require data_source_id in the parent object (Source: skills/notion/skill.md).
• Freshness tooling — JS-rendered vendor pages currently break sync-skills.mjs; tracked in #12.

These guardrails are the operational surface that the freshness pipeline surfaces into the docs so that downstream agent builders do not silently regress.

See Also

• Skills Index — full list of supported tools and workflows.
• Roadmap — phased milestones, including the freshness work and Phase 5 cross-tool orchestration.
• MCP Server README — install, tools, and packaging for clawskills-mcp.
• Contributing guide — template structure and the 11 required sections every skill must ship.

Doramagic Pitfall Log

Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Shanksg/clawskills/issues/12

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Shanksg/clawskills

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Shanksg/clawskills

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Shanksg/clawskills

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Shanksg/clawskills

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Shanksg/clawskills

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Shanksg/clawskills

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Shanksg/clawskills

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using clawskills with real data or production workflows.

• Freshness pipeline: add headless-browser fallback for JS-rendered vendor - github / github_issue
• Configuration risk requires verification - GitHub / issue