Create AtlasClaw Provider

Guide for creating new providers that integrate external systems with the AtlasClaw AI Agent.

Quick Start Checklist

Provider Creation Progress:
- [ ] 1. Gather requirements (system type, auth method, capabilities)
- [ ] 2. Create provider directory structure
- [ ] 3. Write PROVIDER.md with LLM context fields
- [ ] 4. Create skills for each capability
- [ ] 5. Add configuration to atlasclaw.json
- [ ] 6. Test provider loading and skill execution

Phase 1: Gather Requirements

Before creating a provider, determine:

Question	Example Answer
Provider type	servicenow, github, datadog
Display name	ServiceNow, GitHub, Datadog
Authentication method	Basic Auth, API Token, OAuth 2.0, Cookie
Base URL pattern	https://instance.service-now.com
Key capabilities	CRUD incidents, manage users, query metrics
Target keywords	incident, ticket, alert, deployment

Phase 2: Directory Structure

Create provider at: {workspace}/providers/{provider-name}/

providers/{provider-name}/
├── PROVIDER.md           # Required - provider metadata and documentation
├── README.md             # Optional - human documentation
├── skills/               # Required - at least one skill
│   └── {skill-name}/
│       ├── SKILL.md      # Required - skill metadata
│       └── scripts/      # Required for executable skills
│           └── handler.py
└── references/           # Optional - API docs, mappings
    └── api_mapping.md

Phase 3: PROVIDER.md Template

---
# === Required Fields ===
provider_type: {provider-name}        # Must match directory name
display_name: {Display Name}
version: "1.0.0"

# === LLM Context Fields (for Skill Discovery) ===
keywords:
  - keyword1                          # Domain-specific terms users might say
  - keyword2
  - keyword3

capabilities:
  - Capability description 1
  - Capability description 2

use_when:
  - User intent scenario 1
  - User intent scenario 2

avoid_when:
  - Scenario when other provider is better (suggest alternative)
---

# {Display Name} Provider

Brief description of what this provider integrates with.

## Connection Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `base_url` | string | Yes | API base URL |
| `username` | string | Conditional | Username for auth |
| `password` | string | Conditional | Password or token |
| `api_key` | string | Conditional | API key if applicable |

## Authentication Modes

| Mode | Parameters | Notes |
|------|------------|-------|
| Basic Auth | `username` + `password` | Standard HTTP Basic |
| API Token | `api_key` | Bearer token auth |

## Configuration Example

```json
{
  "service_providers": {
    "{provider-name}": {
      "default": {
        "base_url": "${PROVIDER_URL}",
        "api_key": "${PROVIDER_API_KEY}"
      }
    }
  }
}

Environment Variables

PROVIDER_URL=https://api.example.com
PROVIDER_API_KEY=your-api-key

Provided Skills

Skill	Description
{provider}-{action}	Brief description

## Phase 4: SKILL.md Template

```yaml
---
name: "{provider}-{action}"
description: "Brief description. Trigger when user wants to {action}."
category: "provider:{provider-name}"
provider_type: "{provider-name}"
instance_required: "true"

# === LLM Context Fields ===
triggers:
  - action phrase 1
  - action phrase 2

use_when:
  - User intent scenario 1
  - User intent scenario 2

avoid_when:
  - Scenario when other skill is better

examples:
  - "Example user input 1"
  - "Example user input 2"

related:
  - related-skill-1
  - related-skill-2

# === Tool Registration ===
tool_name: "{provider}_{action}"
tool_entrypoint: "scripts/handler.py:handler"
---

# {provider}-{action}

## Purpose

What this skill does and when to use it.

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | Yes | Description |
| param2 | integer | No | Description (default: 10) |

## Usage Examples

**Example 1**: Basic usage
```bash
python scripts/handler.py --param1 "value"

Error Handling

Error	Cause	Resolution
AUTH_FAILED	Invalid credentials	Check API key

## Phase 5: Handler Template

Create `scripts/handler.py`:

```python
# -*- coding: utf-8 -*-
"""
{Skill Name} Handler

Implements the {action} functionality for {Provider} provider.
"""
from __future__ import annotations

import argparse
import json
import os
import sys
from typing import Any, Optional

import requests


def get_provider_config() -> dict[str, Any]:
    """Load provider configuration from atlasclaw.json."""
    config_path = os.environ.get("ATLASCLAW_CONFIG", "atlasclaw.json")
    with open(config_path, "r", encoding="utf-8") as f:
        config = json.load(f)
    
    provider_config = config.get("service_providers", {}).get("{provider-name}", {})
    instance = os.environ.get("PROVIDER_INSTANCE", "default")
    return provider_config.get(instance, {})


def handler(params: dict[str, Any]) -> dict[str, Any]:
    """
    Main handler function.
    
    Args:
        params: Input parameters
        
    Returns:
        Result dictionary with success, message, and data
    """
    config = get_provider_config()
    base_url = config.get("base_url", "").rstrip("/")
    api_key = config.get("api_key", "")
    
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    try:
        # Implement API call here
        response = requests.get(
            f"{base_url}/api/endpoint",
            headers=headers,
            timeout=30
        )
        response.raise_for_status()
        
        return {
            "success": True,
            "message": "Operation completed successfully",
            "data": response.json()
        }
    except requests.RequestException as e:
        return {
            "success": False,
            "message": f"API request failed: {str(e)}",
            "error": {"code": "API_ERROR", "details": str(e)}
        }


def main():
    """CLI entry point."""
    parser = argparse.ArgumentParser(description="{Skill description}")
    parser.add_argument("--param1", required=True, help="Parameter 1")
    parser.add_argument("--param2", type=int, default=10, help="Parameter 2")
    
    args = parser.parse_args()
    
    result = handler({
        "param1": args.param1,
        "param2": args.param2
    })
    
    print(json.dumps(result, indent=2))
    sys.exit(0 if result["success"] else 1)


if __name__ == "__main__":
    main()

Phase 6: Configuration

Add to atlasclaw.json:

{
  "service_providers": {
    "{provider-name}": {
      "default": {
        "base_url": "${PROVIDER_URL}",
        "api_key": "${PROVIDER_API_KEY}"
      },
      "production": {
        "base_url": "${PROVIDER_PROD_URL}",
        "api_key": "${PROVIDER_PROD_API_KEY}"
      }
    }
  }
}

Add to .env:

PROVIDER_URL=https://api.example.com
PROVIDER_API_KEY=your-api-key

Phase 7: Verification

1. Restart service (or wait for hot reload)
2. Check logs for provider loading:

   [AtlasClaw] Provider loaded: {provider-name}
   [AtlasClaw] Skills loaded: X from {provider-name}
   

3. Test via API:

   curl http://localhost:8000/api/skills | grep {provider-name}
   

LLM Context Best Practices

Keywords

• Use domain-specific terms users naturally say
• Avoid generic terms like "create", "update", "manage"
• Include abbreviations and synonyms

use_when

• Describe user intent, not technical actions
• Focus on business scenarios
• Include common phrasings

avoid_when

• Critical for disambiguation between similar providers
• Always suggest the correct alternative
• Include commonly confused scenarios

Common Provider Types

Type	Examples	Typical Keywords
ITSM	ServiceNow, Jira	incident, ticket, issue, sprint
Monitoring	Datadog, Prometheus	alert, metric, dashboard
Communication	Slack, Teams	message, channel, notification
Version Control	GitHub, GitLab	repository, PR, merge, commit
CRM	Salesforce	lead, opportunity, account
Cloud	AWS, Azure	instance, resource, deployment

Additional Resources

• PROVIDER_GUIDE.md - Full documentation
• SKILL_GUIDE.md - Skill development guide
• Jira Provider - Reference implementation