Related Pages

Related topics: Installation Guide, Skills Library Overview, MCP Server Architecture

Home - ClawSkills Overview

What is ClawSkills?

ClawSkills is an open-source, community-driven collection of integration skill documentation for 14 popular developer tools and SaaS platforms. It provides AI-augmented developers with comprehensive, verified API reference materials delivered as a Model Context Protocol (MCP) server.

The project serves as a centralized knowledge base containing authentication patterns, rate limits, error handling, and production-ready code recipes for each integrated tool.

Sources: README.md:1

Architecture

MCP Server Architecture

ClawSkills operates as an MCP server that AI assistants like Claude can connect to for retrieving skill documentation on demand.

graph TD
    A[Claude / Claude Code] -->|MCP Protocol| B[clawskills-mcp Server]
    B --> C[Skill Files Repository]
    C --> D[skills/*.md]
    C --> E[skills/INDEX.md]
    B --> F[list_skills Tool]
    B --> G[get_skill Tool]
    B --> H[search_skills Tool]

Skill Document Structure

Each skill document follows a standardized 11-section template ensuring consistency across all integrations.

graph TD
    A[Skill Document] --> B[Metadata & Headers]
    A --> C[Overview]
    A --> D[Authentication & Permissions]
    A --> E[Core Endpoints]
    A --> F[Common Workflows / Recipes]
    A --> G[Error Handling]
    A --> H[Rate Limits]
    A --> I[Webhooks]
    A --> J[Reliability Patterns]
    A --> K[QA Checklist]
    A --> L[Sources]

Sources: README.md:24

Supported Tools

The project currently covers 14 widely-used enterprise tools.

Sources: skills/INDEX.md

Available MCP Tools

The ClawSkills MCP server exposes three tools for AI assistants:

list_skills

Returns a list of all available skill documents in the repository.

get_skill

Retrieves a complete skill document or a specific section. Supports partial retrieval of:

• auth — Authentication and permissions
• rate-limits — Rate limiting information
• recipes — Common workflow patterns
• errors — Error handling patterns

search_skills

Performs full-text search across all skill documents to find relevant content.

Sources: README.md:45-50

Installation

Quick Start (npx)

npx -y clawskills-mcp

Permanent Installation

npm install -g clawskills-mcp

Claude Desktop Configuration

Add to your Claude Desktop or Claude Code configuration file:

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

Sources: README.md:38-43

Development Phases

The project follows a structured 5-phase development roadmap:

Sources: skills/ROADMAP.md:1-30

CI/CD Pipeline

The project includes automated quality assurance:

Release Automation

Releases are fully automated via GitHub Actions:

1. Merge to main branch
2. Navigate to GitHub Actions → Release workflow
3. Run workflow with desired version bump (patch/minor/major)

Testing Pipeline

The CI pipeline (ci.yml) runs on every push and pull request:

• Build verification
• Unit tests with Vitest
• Real-skills validation (all 14 tools must have required sections)
• Minimum file size requirements (≥5 KB per skill)

Sources: skills/ROADMAP.md:18-22

Contributing Guidelines

Adding a New Skill

1. Create a branch: git checkout -b skill/<toolname>
2. Follow the template: Use any existing skill.md as reference — all 11 sections required
3. Verify documentation: Test all endpoints, rate limits, and auth flows against official vendor documentation
4. Add validation date: Include Last validated: date in the doc header
5. Update indices: Modify skills/INDEX.md and README.md
6. Add sources: Link to official sources in the ## Sources section
7. Open PR: CI automatically runs npm test for validation

Sources: README.md:10-18

Rate Limit Management

Each skill document includes platform-specific rate limiting patterns. Key patterns observed across tools:

Sources: skills/linear/skill.md:100-105, skills/dynamics365/skill.md:150-155, skills/ROADMAP.md:8

Authentication Patterns

Common authentication methods across supported tools:

graph TD
    A[Authentication Methods] --> B[OAuth 2.0]
    A --> C[API Keys / PAT]
    A --> D[Bearer Tokens]
    A --> E[Webhook Signatures]
    
    B --> B1[Authorization Code Flow]
    B --> B2[Client Credentials]
    
    C --> C1[Linear API Keys]
    C --> C2[Figma PAT]
    C --> C3[ServiceNow Basic Auth]

Sources: skills/linear/skill.md:1-15, skills/figma/skill.md:40-60

Best Practices

For AI Tool Integration

1. Reference specific sections: Load only the relevant authentication or endpoint section
2. Use full skill as context: For complex workflows, load the complete skill document as system prompt
3. Follow documented patterns: Always use the exact auth patterns, rate limit handling, and error codes specified in the skill docs

Example: Loading Skill as Context

import anthropic

with open("skills/jira/skill.md") as f:
    jira_skill = f.read()

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=jira_skill,
    messages=[{"role": "user", "content": "Write code to..."}]
)

Sources: README.md:60-72

Project Status

ClawSkills is production-ready with the following characteristics:

Sources: skills/ROADMAP.md:22-25

Next Development Phase

Priority 1 — Freshness and Accuracy Pipeline

The project maintainers are focused on keeping documentation accurate as vendor APIs evolve. A pipeline to automatically validate and update skill documents against official API changes is planned.

Sources: skills/ROADMAP.md:33-36

Related Pages

Related topics: Home - ClawSkills Overview, Quick Start Guide, MCP Server Architecture

Installation Guide

Overview

This guide covers all installation methods for clawskills, a skill documentation library providing integration guides for 14 enterprise tools including Jira, Salesforce, Figma, Slack, Linear, and others. The repository can be used as a standalone skill reference or as an MCP (Model Context Protocol) server that AI assistants like Claude can query dynamically.

Architecture Overview

graph TD
    A[clawskills Repository] --> B[MCP Server]
    A --> C[Static Skill Docs]
    B --> D[Claude Desktop]
    B --> E[Claude Code]
    B --> F[Custom AI Apps]
    
    G[MCP Tools] --> H[list_skills]
    G --> I[get_skill]
    G --> J[search_skills]
    
    B --> G

Installation Methods

Method 1: NPX (Temporary Use)

Execute the MCP server without installation using npx:

npx -y clawskills-mcp

This method is useful for:

• One-time testing
• CI/CD pipelines
• Temporary integrations

Sources: README.md:1

Method 2: Global NPM Installation

Install the package globally for persistent access:

npm install -g clawskills-mcp

Prerequisites:

• Node.js 18.x or higher
• npm 9.x or higher

Sources: mcp-server/README.md

Method 3: Docker Deployment

Deploy the MCP server as a containerized service:

docker build -t clawskills-mcp ./mcp-server
docker run -p 3000:3000 clawskills-mcp

Docker Configuration:

Sources: mcp-server/Dockerfile

MCP Client Configuration

Claude Desktop Configuration

Add the clawskills MCP server to your Claude Desktop configuration file:

File Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration Template:

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

Alternative: Using Global Installation Path

If installed globally, reference the installed binary:

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

Sources: README.md:1

Claude Code Configuration

For Claude Code, add the same configuration to your Claude Code settings file:

File Location: ~/.claude/settings.json or project .claude/CLAUDE.md

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

Sources: README.md:1

Available MCP Tools

Once connected, the following three tools are available:

Tool Usage Example:

# Example: List all available skills
result = list_skills()

# Example: Get specific skill documentation
result = get_skill(skill_name="jira", section="auth")

# Example: Search for specific content
result = search_skills(query="webhook signature verification")

Sources: README.md:1

Environment Configuration

Package.json Dependencies

The MCP server requires the following runtime dependencies:

Sources: mcp-server/package.json

Runtime Environment Variables

Verification

Test the Installation

Verify the MCP server is correctly installed and accessible:

# Test npx execution
npx -y clawskills-mcp --version

# Test Docker container
docker run clawskills-mcp --health-check

Verify MCP Connection

After configuring Claude Desktop:

1. Restart Claude Desktop
2. Check for the clawskills server in the MCP servers list
3. Send a test query: list_skills

Integration with Claude Code

Project-Level Integration

Create a .claude/CLAUDE.md file in your project to define when to use skill docs:

# Integration Skills

When writing code that integrates with any of the following tools, always read the
corresponding skill doc before writing code:

- Monday.com → @skills/monday/skill.md
- Salesforce → @skills/salesforce/skill.md
- Jira → @skills/jira/skill.md
- Dynamics 365 → @skills/dynamics365/skill.md
- HubSpot → @skills/hubspot/skill.md
- ServiceNow → @skills/servicenow/skill.md
- Zendesk → @skills/zendesk/skill.md
- Asana → @skills/asana/skill.md
- GitHub → @skills/github/skill.md
- Figma → @skills/figma/skill.md
- Slack → @skills/slack/skill.md
- Stripe → @skills/stripe/skill.md
- Notion → @skills/notion/skill.md
- Linear → @skills/linear/skill.md

Follow the auth patterns, rate limit handling, and error codes exactly as documented.
Always pin API version headers where specified.

Sources: README.md:1

Troubleshooting

Common Issues

Health Check Endpoint

When running in Docker or as a standalone server:

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600
}

Next Steps

After installation, proceed to:

1. Authentication Setup — Configure credentials for your target tools
2. Skill Selection — Identify relevant skills for your integration
3. Recipe Implementation — Follow the workflow recipes in each skill doc
4. Rate Limit Planning — Review rate limiting for your use case

Sources: skills/ROADMAP.md:1

Related Pages

Related topics: Installation Guide, MCP Tools Reference, AI Tool Integration Guide

Quick Start Guide

Overview

ClawSkills is a comprehensive skill documentation library for integrating AI tools with popular SaaS platforms. It provides standardized documentation covering authentication patterns, rate limits, API workflows, error handling, and cross-tool orchestration recipes for 14 supported tools.

Sources: README.md:1

Supported Tools

Sources: README.md:18-31

Installation

Option 1: Quick Run (npx)

npx -y clawskills-mcp

Sources: README.md:64

Option 2: Global Installation

npm install -g clawskills-mcp

Sources: README.md:68

MCP Server Configuration

Add ClawSkills to your Claude Desktop or Claude Code configuration:

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

Sources: README.md:73-80

Available Tools

The MCP server exposes three tools for accessing skill documentation:

Sources: mcp-server/src/index.ts

Authentication Patterns

Personal Access Tokens (PAT)

Recommended for server-to-server integrations:

# Figma example
curl https://api.figma.com/v1/me \
  -H "X-Figma-Token: YOUR_PAT"

Sources: skills/figma/skill.md

OAuth 2.0

Recommended for user-facing applications:

# Linear OAuth flow
GET https://api.linear.app/oauth/token
  ?client_id=...
  &client_secret=...
  &redirect_uri=...
  &grant_type=authorization_code

Sources: skills/linear/skill.md

API Token + Basic Auth

Common for Jira Cloud integrations:

AUTH="Basic $(echo -n 'email:api_token' | base64)"
curl -H "Authorization: $AUTH" "$BASE/rest/api/3/issue/PROJ-42"

Sources: skills/jira/skill.md

Usage with Claude

Method 1: Reference Skill Sections

Paste relevant skill documentation into your conversation:

[paste the "Authentication & permissions" section from skills/salesforce/skill.md]

Write a Python function that exchanges a JWT for an access token
and caches it until 5 minutes before expiry.

Sources: README.md:91-97

Method 2: Load Skill as System Context

import anthropic

with open("skills/jira/skill.md") as f:
    jira_skill = f.read()

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=f"Follow the auth patterns, rate limit handling, and error codes exactly as documented in:\n{jira_skill}",
    messages=[
        {"role": "user", "content": "Create a Jira issue for a new bug report"}
    ]
)

Sources: README.md:107-123

Integration Agent Pattern

For multi-tool workflows, use the integration agent pattern:

import anthropic

client = anthropic.Anthropic()

def run_integration_agent(task: str, tools_needed: list[str]) -> str:
    """Route a cross-tool integration task to Claude with relevant skills."""
    
    # Load required skill docs
    skills_context = []
    for tool in tools_needed:
        try:
            with open(f"skills/{tool}/skill.md") as f:
                skills_context.append(f"# {tool.upper()} Skill\n{f.read()}")
        except FileNotFoundError:
            pass
    
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=2048,
        system="You are an integration specialist. Follow the skill documentation exactly.",
        messages=[
            {"role": "system", "content": "\n\n---\n\n".join(skills_context)},
            {"role": "user", "content": task}
        ]
    )
    return response.content[0].text

# Example
result = run_integration_agent(
    task="Write a Python script that syncs Zendesk tickets (status=open, priority=urgent) to Jira bugs.",
    tools_needed=["zendesk", "jira"]
)

Sources: README.md:42-58

Project Instruction Integration

For Claude Code users, add skill references to your project instruction file:

# Integration Skills

When writing code that integrates with any of the following tools, always read the
corresponding skill doc before writing code:

- Monday.com → @skills/monday/skill.md
- Salesforce → @skills/salesforce/skill.md
- Jira → @skills/jira/skill.md
- Dynamics 365 → @skills/dynamics365/skill.md
- HubSpot → @skills/hubspot/skill.md
- ServiceNow → @skills/servicenow/skill.md
- Zendesk → @skills/zendesk/skill.md
- Asana → @skills/asana/skill.md
- GitHub → @skills/github/skill.md
- Figma → @skills/figma/skill.md
- Slack → @skills/slack/skill.md
- Stripe → @skills/stripe/skill.md
- Notion → @skills/notion/skill.md
- Linear → @skills/linear/skill.md

Follow the auth patterns, rate limit handling, and error codes exactly as documented.
Always pin API version headers where specified.

Sources: README.md:126-148

Cross-Tool Workflow Example

The Slack-Jira incident playbook demonstrates multi-tool integration:

graph TD
    A[Slack Alert Received] --> B{Existing Jira Issue?}
    B -->|No| C[Create Jira Issue]
    B -->|Yes| D[Update Existing Issue]
    C --> E[Post Link to Slack Thread]
    D --> E
    E --> F{Optional: Status Sync}
    F -->|Enabled| G[Mirror Jira Status → Slack]

Sources: playbooks/slack-jira-incident.md

Key workflow steps:

1. Detect incident trigger in Slack channel
2. Extract correlation key from message context
3. Resolve Slack message permalink
4. Search Jira for existing issue with correlation key
5. Create or update Jira issue with Slack context
6. Reply in Slack thread with Jira link

Rate Limit Handling

Each skill documents specific rate limits. General patterns:

Always implement retry logic with Retry-After header respect:

def make_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            wait_time = int(response.headers.get("Retry-After", 60))
            time.sleep(wait_time)
            continue
        return response
    raise Exception("Max retries exceeded")

Skill Document Structure

Each skill follows an 11-section template:

Sources: README.md:33-35

Contributing New Skills

1. Create branch: git checkout -b skill/<toolname>
2. Follow the template structure in any existing skill.md
3. Verify all endpoints, rate limits, and auth flows against official docs
4. Add Last validated: date to doc header
5. Update skills/INDEX.md and README.md
6. Open PR — CI runs npm test to validate skill loads with all required sections

Sources: README.md:33-45

Release Process

Releases are automated:

1. Merge PR to main
2. Navigate to GitHub Actions → Release → Run workflow
3. Select version bump: patch / minor / major

Sources: README.md:51-53

Roadmap

Sources: skills/ROADMAP.md

Related Pages

Related topics: Skill Document Structure, Playbooks Index, Home - ClawSkills Overview

Skills Library Overview

1. Introduction

The ClawSkills repository is a comprehensive library of integration skill documentation for connecting AI assistants with popular enterprise tools and SaaS platforms. It provides standardized, production-ready documentation that covers authentication flows, API endpoints, rate limits, error handling, and common workflow recipes for 14 different tools.

Sources: README.md:1-30

1.1 Purpose and Scope

The library serves as a unified reference for developers building integrations with external services. Each skill document follows a consistent 11-section structure that ensures complete coverage of:

• Authentication mechanisms (API keys, OAuth 2.0, JWT)
• Rate limiting policies and retry strategies
• Core API operations (CRUD operations)
• Common workflow patterns (recipes)
• Error codes and troubleshooting
• Webhook configurations for event-driven architectures

1.2 Supported Tools

The library currently includes comprehensive documentation for 14 enterprise tools:

Sources: README.md:80-95

Related Pages

Related topics: Skills Library Overview, Contributing Guide, Playbooks Index

Skill Document Structure

Overview

The Skill Document Structure is the standardized, self-contained Markdown format used to document every tool integration in the clawskills repository. Each skill doc captures everything an AI agent needs to reliably call an external API — authentication flows, rate limits, error codes, common recipes, and webhook patterns — without requiring external research. Sources: README.md:1-10

The repository currently covers 14 tools: Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, and Linear. Sources: README.md:60-61

The skill system serves two primary consumers:

1. AI agents (Claude Code, Copilot, LangChain/LlamaIndex RAG pipelines) — query skill docs to write integration code correctly on the first attempt.
2. Human developers — use skill docs as a reference when building or debugging cross-tool workflows.

Design Principles

Related Pages

Related topics: Skills Library Overview, Skill Document Structure, AI Tool Integration Guide

Playbooks Index

Overview

Playbooks in ClawSkills are comprehensive, multi-step workflow guides that orchestrate integrations across two or more tools. Unlike individual skill documents that focus on single-tool API capabilities, playbooks provide end-to-end automation patterns for common cross-system business scenarios.

The Playbooks Index serves as the central directory and documentation hub for all available cross-tool workflows, enabling AI assistants and developers to implement sophisticated integrations without requiring deep expertise in each underlying API.

Architecture

Relationship Between Components

graph TD
    subgraph "ClawSkills Core"
        A[Skills Index] --> B[Individual Skill Docs]
        C[Playbooks Index] --> D[Cross-Tool Playbooks]
    end
    
    subgraph "MCP Server"
        E[get_skill] --> B
        F[get_playbook] --> D
        G[list_playbooks] --> C
    end
    
    H[AI Assistant] --> E
    H --> F
    H --> G

Playbook Structure Pattern

Each playbook follows a standardized template containing:

Available Playbooks

1. Zendesk → Jira Bug Escalation

Slug: zendesk-jira-bug-escalation

Purpose: Automatically creates a Jira bug issue when a Zendesk ticket meets escalation criteria.

Trigger Conditions:

• Ticket status changes to solved with low satisfaction score
• Specific tag patterns (e.g., bug, escalate)
• Agent-assigned priority flag

Key Features:

• Bidirectional comment mirroring
• Attachment transfer from Zendesk to Jira
• Correlation key generation for idempotent handling
• Custom field mapping for project/issuetype selection

Sources: playbooks/zendesk-jira-bug-escalation.md

2. HubSpot → Asana Onboarding

Slug: hubspot-asana-onboarding

Purpose: Creates a structured onboarding task hierarchy in Asana when a new contact is added to a HubSpot list.

Workflow:

1. Detect new contact in target HubSpot list
2. Create parent Onboarding Project in Asana
3. Generate task checklist based on onboarding template
4. Assign tasks to team members via Asana sections
5. Post initial status update to Slack (if configured)

Task Template Structure:

graph LR
    A[New Contact] --> B[Create Project]
    B --> C[Kickoff Meeting]
    B --> D[Setup Tasks]
    B --> E[Training Tasks]
    C --> F[Send Welcome Email]
    D --> G[Create Accounts]
    D --> H[Configure Access]
    E --> I[Training Scheduled]
    E --> J[Materials Sent]

Sources: playbooks/hubspot-asana-onboarding.md

3. Salesforce → HubSpot Lead Sync

Slug: salesforce-hubspot-lead-sync

Purpose: Bidirectional synchronization of lead data between Salesforce CRM and HubSpot Marketing Platform.

Sync Directions:

• Lead Creation: Salesforce → HubSpot (when Lead status = "Open")
• Status Updates: HubSpot → Salesforce (when Contact lifecycle stage changes)
• Deal Association: Bidirectional (deal closed in either system updates the other)

Field Mapping:

Sources: playbooks/salesforce-hubspot-lead-sync.md

4. Slack → Jira Incident Management

Slug: slack-jira-incident

Purpose: Streamlined incident creation and tracking using Slack as the front-end interface and Jira as the backend issue tracker.

Trigger Events:

• reaction_added emoji on flagged messages
• /incident slash command invocation
• Specific channel message patterns (configurable)

Workflow Sequence:

sequenceDiagram
    participant S as Slack User
    participant SL as Slack API
    participant BM as Bot/Server
    participant J as Jira Cloud
    
    S->>SL: Adds 🚨 reaction
    SL->>BM: reaction_added event
    BM->>SL: getPermalink()
    BM->>J: Search existing issue
    alt No existing issue
        BM->>J: Create incident issue
        BM->>SL: Post issue link to thread
    else Existing issue found
        BM->>SL: Post existing link
    end

Correlation Key Format: slack:{team_id}:{channel_id}:{ts}

Sources: playbooks/slack-jira-incident.md

MCP Server Integration

The ClawSkills MCP server exposes playbook operations through three primary tools:

Tool Definitions

Usage Example

// List all available playbooks
const playbooks = await client.list_playbooks({});
// Returns: ["hubspot-asana-onboarding", "salesforce-hubspot-lead-sync", "zendesk-jira-bug-escalation", "slack-jira-incident"]

// Fetch specific playbook
const playbook = await client.get_playbook({
    name: "slack-jira-incident"
});

// Search for specific patterns
const results = await client.search_playbooks({
    query: "idempotency"
});

Search Behavior

• Full-text search across all playbook content
• Returns up to 5 matches per playbook
• Includes ±3 lines of context around each match
• Supports queries like "idempotency", "rollback", "closed won"

Sources: mcp-server/README.md

Test Coverage

The Playbooks system is validated through automated tests:

describe("real playbooks", () => {
  let playbooks: Map<string, string>;

  beforeAll(() => {
    playbooks = loadPlaybooks(REAL_PLAYBOOKS_DIR);
  });

  it("loads all expected playbooks", () => {
    const knownPlaybooks = [
      "hubspot-asana-onboarding",
      "salesforce-hubspot-lead-sync",
      "zendesk-jira-bug-escalation",
    ];
    // Verification logic
  });

  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("");
    }
  });
});

Validation Requirements:

• All expected playbooks must load successfully
• Each playbook must contain a non-empty summary line
• Minimum file size threshold (5000 bytes) prevents truncated documentation

Sources: mcp-server/src/index.test.ts:1-50

Roadmap and Future Development

Phase 5 — Cross-Tool Orchestration (In Progress)

The Playbooks system represents the culmination of the ClawSkills documentation strategy:

Sources: skills/ROADMAP.md

Adding New Playbooks

To contribute a new playbook:

1. Create a branch: git checkout -b playbook/<playbook-name>
2. Follow the playbook template structure
3. Include all required sections (trigger, flow, mapping, error handling)
4. Update playbooks/INDEX.md with the new entry
5. Open a PR — CI validates playbook loads and has required sections

Playbook Naming Convention:

• Filename: <primary-tool>-<secondary-tool>-<scenario>.md
• Slug: Same as filename without extension
• Frontmatter: Include title, description, and tools array

Related Pages

Related topics: MCP Tools Reference, Installation Guide

MCP Server Architecture

Overview

The clawskills-mcp is a Model Context Protocol (MCP) server that exposes the ClawSkills API integration documentation to AI agents. It provides a bridge between AI assistants (such as Claude) and the structured skill documentation for 14 different API integrations.

Sources: mcp-server/README.md

Core Purpose

The server serves as an interface layer that allows AI agents to query, search, and retrieve API integration knowledge without requiring manual documentation lookup. This enables AI-assisted coding tasks to incorporate accurate API specifications, authentication patterns, and workflow recipes on demand.

graph TD
    A[AI Agent] -->|MCP Protocol| B[clawskills-mcp Server]
    B -->|list_skills| C[Skill Index]
    B -->|get_skill| C
    B -->|search_skills| D[Full-text Search]
    B -->|list_playbooks| E[Cross-Tool Playbooks]
    C -->|Returns| A
    D -->|Returns| A
    E -->|Returns| A
    
    F[skills/\*.md] --> C
    G[playbooks/\*.md] --> E

Sources: README.md:50-80

Architecture Components

Component Overview

Directory Structure

clawskills/
├── mcp-server/
│   ├── src/
│   │   └── index.ts          # Main MCP server implementation
│   ├── package.json          # Dependencies and scripts
│   ├── tsconfig.json          # TypeScript configuration
│   ├── vitest.config.ts       # Test configuration
│   ├── Dockerfile             # Container deployment
│   └── README.md              # Server-specific documentation
├── skills/
│   ├── INDEX.md               # Master skill index
│   ├── jira/skill.md
│   ├── slack/skill.md
│   ├── figma/skill.md
│   ├── notion/skill.md
│   ├── linear/skill.md
│   └── ... (9 more skills)
├── playbooks/
│   ├── slack-jira-incident.md
│   └── ... (additional workflows)
└── README.md                  # Main project documentation

Sources: mcp-server/README.md:1-10

MCP Tools Interface

The server exposes four primary tools that AI agents can invoke:

Tool Specifications

Parameter Details

#### get_skill Parameters

#### search_skills Parameters

Sources: README.md:60-75

Deployment Models

npx (Recommended for Claude Desktop/Code)

No installation required. The server is fetched and executed on demand.

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

Configuration File Locations:

Sources: mcp-server/README.md:20-40

Docker Deployment

For server-side or containerized environments:

# Build the image
docker build -t clawskills-mcp -f mcp-server/Dockerfile .

# Run the container
docker run --rm -i clawskills-mcp

Sources: mcp-server/README.md:50-55

Content Repository

Skill Documentation Structure

Each skill follows a standardized 11-section template:

1. Overview — Tool description and key capabilities
2. Authentication & permissions — Auth flows, token management, scopes
3. Base URL & versioning — API endpoint structure
4. Rate limits — Request quotas and throttling patterns
5. Common workflows (recipes) — Code examples for typical operations
6. Error codes — Error handling patterns
7. Webhooks — Event-driven integration patterns
8. Pagination — Large dataset retrieval
9. Filtering & sorting — Query parameter conventions
10. Sources — Official documentation links
11. Testing checklist — Verification procedures

Supported Integrations

Sources: README.md:30-45

Build and Development

TypeScript Configuration

The server is implemented in TypeScript for type safety:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Sources: mcp-server/tsconfig.json

Testing Infrastructure

The project uses Vitest for unit testing and validation:

// vitest.config.ts structure
{
  test: {
    environment: "node",
    include: ["**/*.test.ts"],
    coverage: {
      provider: "v8",
      reporter: ["text", "json", "html"]
    }
  }
}

Sources: mcp-server/vitest.config.ts

CI/CD Pipeline

The project includes automated workflows:

Release Process:

1. Merge changes to main branch
2. Navigate to GitHub Actions → Release
3. Run workflow with desired version bump (patch, minor, major)
4. Server automatically publishes via OIDC authentication

Sources: skills/ROADMAP.md:60-70

Data Flow

Query Execution Flow

sequenceDiagram
    participant AI as AI Agent
    participant MCP as MCP Server
    participant FS as File System
    participant MD as Markdown Files
    
    AI->>MCP: list_skills()
    MCP->>FS: Read INDEX.md
    FS-->>MCP: Return skill list
    MCP-->>AI: Skill slugs with descriptions
    
    AI->>MCP: get_skill("jira", "auth")
    MCP->>FS: Read skills/jira/skill.md
    FS-->>MCP: Return markdown content
    MCP-->>AI: Authentication section content
    
    AI->>MCP: search_skills("webhook")
    MCP->>FS: Search all *.md files
    FS-->>MCP: Matching results
    MCP-->>AI: Search results with context

Content Resolution

Version Management

Semantic Versioning

The MCP server maintains its own npm version separate from the skill documentation:

Documentation Versioning

Individual skill docs track their own API version and Last validated date:

Related Pages

Related topics: MCP Server Architecture, Quick Start Guide, AI Tool Integration Guide

MCP Tools Reference

Overview

The clawskills-mcp is a Model Context Protocol (MCP) server that provides AI assistants (specifically Claude) access to the ClawSkills library of integration skill documentation. This server acts as a bridge between AI coding assistants and the comprehensive API documentation for 14+ third-party tools including Jira, GitHub, Salesforce, Linear, and others.

The MCP server exposes three primary tools that enable AI assistants to query, retrieve, and search through skill documentation in real-time, allowing them to write accurate integration code without requiring manual lookup of API documentation.

Sources: README.md:1

Architecture

System Components

graph TD
    A[Claude AI Assistant] -->|MCP Protocol| B[clawskills-mcp Server]
    B --> C[Skill Documentation Files]
    B --> D[Index Registry]
    C --> E[skills/*.md]
    F[Claude Desktop/Claude Code] --> A
    G[Claude API App] --> A

Tool Interaction Flow

sequenceDiagram
    participant C as Claude Assistant
    participant MCP as clawskills-mcp Server
    participant FS as File System
    
    C->>MCP: list_skills
    MCP->>FS: Read INDEX.md
    FS-->>MCP: Return skill list
    MCP-->>C: Skill names & descriptions
    
    C->>MCP: get_skill(skill_name, section?)
    MCP->>FS: Read skills/{skill}/skill.md
    FS-->>MCP: Return skill document
    MCP-->>C: Full skill or section content
    
    C->>MCP: search_skills(query)
    MCP->>FS: Read all skill files
    FS-->>MCP: Search results
    MCP-->>C: Matching skill sections

Available MCP Tools

1. list_skills

Returns a list of all available skill documentation files in the ClawSkills library.

Parameters: None required

Returns: Array of skill names with brief descriptions

Sources: mcp-server/src/index.ts

2. get_skill

Retrieves the complete content of a skill document or a specific section within it.

Parameters:

Returns: Full skill documentation or specified section content

Sources: mcp-server/src/index.ts

3. search_skills

Performs full-text search across all skill documents.

Parameters:

Returns: Matching skill sections with context

Sources: mcp-server/src/index.ts

Installation

Prerequisites

• Node.js 18+ (for npx usage)
• npm 8+ (for global installation)

Quick Start (Temporary)

npx -y clawskills-mcp

Permanent Installation

npm install -g clawskills-mcp

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

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

Sources: README.md:1

Claude Code Configuration

For Claude Code projects, add the MCP server to your project's MCP settings:

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

Supported Skills

The MCP server provides access to documentation for the following integrations:

Sources: README.md:1, skills/ROADMAP.md:1

Usage Patterns

Pattern 1: Direct Reference in Prompts

Paste skill documentation directly into your conversation:

Using the above Figma authentication section, write a Python function 
that exchanges a JWT for an access token and caches it until 5 minutes before expiry.

Pattern 2: Integration Agent Workflow

def run_integration_agent(task: str, tools_needed: list[str]) -> str:
    """
    Use MCP tools to fetch skill docs, then write integration code.
    """
    # Fetch relevant skills via MCP
    skills = []
    for tool in tools_needed:
        skill_doc = get_skill(tool)
        skills.append(skill_doc)
    
    # Construct prompt with skill context
    prompt = f"""
    Task: {task}
    
    Integration documentation:
    {skills}
    
    Write the integration code following these patterns.
    """
    
    # Send to Claude for code generation
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=2048,
        messages=[{"role": "user", "content": prompt}]
    )
    return response.content[0].text

Pattern 3: Project Instruction Integration

Add to your .claude/CLAUDE.md to configure Claude Code with skill awareness:

# Integration Skills

When writing code that integrates with any of the following tools, always read the 
corresponding skill doc before writing code:

- Monday.com → @skills/monday/skill.md
- Salesforce → @skills/salesforce/skill.md
- Jira → @skills/jira/skill.md
- Dynamics 365 → @skills/dynamics365/skill.md
- HubSpot → @skills/hubspot/skill.md
- ServiceNow → @skills/servicenow/skill.md
- Zendesk → @skills/zendesk/skill.md
- Asana → @skills/asana/skill.md
- GitHub → @skills/github/skill.md
- Figma → @skills/figma/skill.md
- Slack → @skills/slack/skill.md
- Stripe → @skills/stripe/skill.md
- Notion → @skills/notion/skill.md
- Linear → @skills/linear/skill.md

Follow the auth patterns, rate limit handling, and error codes exactly as documented.
Always pin API version headers where specified.

Sources: README.md:1

Skill Document Structure

Each skill document follows a standardized template with 11 required sections:

Sources: README.md:1, skills/ROADMAP.md:1

Best Practices

When Using MCP Tools

1. Specify exact tools needed: Rather than loading all skills, request only the tools relevant to your current task to minimize complexity
2. Use section filtering: When you only need authentication info, specify section: "auth" to get targeted content
3. Combine search with targeted retrieval: Use search_skills to find relevant content, then get_skill for complete context

When Writing Integration Code

1. Follow documented auth patterns: Each skill specifies the recommended authentication method (PAT, OAuth, API Key)
2. Implement rate limit handling: Respect the documented rate limits and use Retry-After headers
3. Pin API version headers: Use the exact version headers specified (e.g., Notion-Version: 2025-09-03)
4. Handle errors consistently: Use the documented error codes and retry strategies

Troubleshooting

Connection Issues

Debug Logging

Log the following for troubleshooting:

• Tool name called
• Parameters passed
• Response status and timing

Do NOT log:

• Token values or credentials
• Full request/response bodies (may contain PII)

Future Enhancements

The ClawSkills project roadmap includes improvements to the MCP server:

Sources: skills/ROADMAP.md:1

See Also

• CLAUDE.md Integration Guide - Detailed integration patterns
• Skills Index - Complete list of available skills
• Slack-Jira Incident Playbook - Cross-tool workflow example
• ROADMAP.md - Project roadmap and status

Related Pages

Related topics: Quick Start Guide, MCP Tools Reference, Playbooks Index

AI Tool Integration Guide

Overview

The clawskills project is a comprehensive library of skill documentation designed to enable AI assistants (such as Claude) to integrate with third-party tools and services through a standardized, machine-readable format. Each skill document provides authentication patterns, API endpoints, rate limits, error handling, and reusable code recipes for a specific vendor API. Sources: README.md

Purpose and Scope

The project serves two primary audiences:

1. AI Development Platforms — Developers building AI agents can reference skill docs to understand how their AI assistant should interact with external services
2. Integration Developers — Teams implementing integrations can use these docs as authoritative references for correct API usage, authentication flows, and error handling

Each skill file follows a strict template with 11 required sections, ensuring consistency across all 14 currently supported tools. Sources: skills/ROADMAP.md

Supported Tools

The library currently covers 14 primary tools with complete documentation:

Related Pages

Related topics: Skill Document Structure, Skills Library Overview

Contributing Guide

This project maintains a comprehensive library of integration skill documentation for 14 major SaaS platforms. The contributing guide establishes the standardized process for adding new skills and updating existing documentation to ensure consistency, accuracy, and reliability across the entire codebase.

Overview

The clawskills repository contains self-contained skill documentation files (.md) that provide AI assistants with accurate API integration knowledge. Each skill doc follows a strict 11-section template and is validated through automated CI pipelines before publication.

Supported Platforms: Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, Linear

Contribution Workflow

graph TD
    A[Create Branch: skill/<toolname>] --> B[Follow 11-Section Template]
    B --> C[Verify Endpoints Against Vendor Docs]
    C --> D[Add Last Validated Date]
    D --> E[Update skills/INDEX.md]
    E --> F[Update README.md]
    F --> G[Open Pull Request]
    G --> H[CI Pipeline: npm test]
    H --> I{All Tests Pass?}
    I --|Yes| J[Merge to main]
    I --|No| K[Fix Validation Errors]
    K --> H
    J --> L[Release Automation]

Branch Naming Convention

All skill contributions must be created from a feature branch following this naming pattern:

git checkout -b skill/<toolname>

Replace <toolname> with the lowercase, hyphenated name of the platform (e.g., skill/zendesk, skill/jira).

Sources: README.md:1-10

Skill Template Structure

Every skill document must contain all 11 required sections. Use an existing skill file (e.g., skills/jira/skill.md) as your reference template.

Required Sections

Document Quality Requirements

// Minimum file size: 5KB
// Source: mcp-server/src/index.test.ts
const MIN_FILE_SIZE = 5000; // bytes

// Every skill must have:
const REQUIRED_SECTIONS = [
  'overview',
  'authentication',
  'common-workflows',
  'error-codes',
  'rate-limits',
  'reliability',
  'security',
  'scopes',
  'sources',
  'qa-checklist'
];

Sources: mcp-server/src/index.test.ts:21-30

Verification Process

Before committing your skill document, perform the following verification steps:

Endpoint Verification Checklist

1. Review official vendor documentation for all endpoints referenced in the skill
2. Verify rate limits against current vendor documentation (note: rate limits are updated periodically)
3. Test authentication flows locally if possible, or document the exact OAuth/ PAT flow
4. Validate JSON examples against actual API responses
5. Check for deprecated endpoints — for example, Figma's files:read scope is deprecated as of November 2025

Required Metadata

Each skill document must include a Last validated: date in the doc header:

Doramagic Pitfall Log

Doramagic extracted 8 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs

• Severity: medium
• Finding: Installation risk is backed by a source signal: Freshness pipeline: add headless-browser fallback for JS-rendered vendor changelogs. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Shanksg/clawskills/issues/12

2. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:1161910025 | https://github.com/Shanksg/clawskills | host_targets=mcp_host, claude

3. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1161910025 | https://github.com/Shanksg/clawskills | README/documentation is current enough for a first validation pass.

4. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | last_activity_observed missing

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium

6. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1161910025 | https://github.com/Shanksg/clawskills | no_demo; severity=medium

7. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | issue_or_pr_quality=unknown

8. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1161910025 | https://github.com/Shanksg/clawskills | release_recency=unknown

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 needs validation - GitHub / issue