---
title: Skills API
description: "API endpoints for the agent skills marketplace"
---

# Skills API

Use skill endpoints to extend your agents with specialized capabilities.

## Base URL

```
https://agentbot.sh/api/skills
```

## List skills

```http
GET /api/skills
```

Returns all available skills in the marketplace. No authentication required for basic listing. When a valid session is present and `agentId` is provided, the response includes which skills are already installed for that user and agent.

### Query parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `category` | string | Filter by category. Use `all` or omit for all skills. Options: `streaming`, `events`, `payments`, `finance`, `productivity`, `communication`, `development`, `channels`, `music`, `creative`, `marketing`, `ai` |
| `featured` | string | Set to `true` to return only featured skills |
| `search` | string | Case-insensitive search across skill names and descriptions |
| `agentId` | string | Agent identifier or managed runtime `openclawInstanceId`. When provided with an authenticated session, the response includes an `installedSkillIds` array indicating which skills are already installed on this agent. |

### Response

```json
{
  "skills": [
    {
      "id": "dj-streaming",
      "name": "baseFM DJ Streaming",
      "description": "Create baseFM streams, fetch live DJs, and generate ffmpeg broadcaster commands for agent DJs.",
      "category": "streaming",
      "author": "Agentbot",
      "downloads": 150,
      "rating": 5.0,
      "featured": true,
      "code": "",
      "scan": {
        "trustTier": "trusted",
        "riskLevel": "low",
        "installAllowed": true,
        "reasons": [],
        "warnings": [],
        "requiresManualReview": false
      }
    }
  ],
  "categories": [
    "streaming",
    "events",
    "payments",
    "finance",
    "productivity",
    "communication",
    "development",
    "channels",
    "music",
    "creative",
    "marketing",
    "ai"
  ],
  "featured": [],
  "installedSkillIds": ["dj-streaming", "guestlist"]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `skills` | array | List of skill objects matching the query filters |
| `skills[].code` | string | Skill handler code or configuration. Empty string for platform-authored skills without custom code. |
| `skills[].scan` | object | Marketplace safety scan result for the skill. See [scan object](#scan-object) for field details. |
| `categories` | string[] | All distinct skill categories in the marketplace |
| `featured` | array | Subset of `skills` where `featured` is `true`. Each entry includes the same `scan` object. |
| `installedSkillIds` | string[] | IDs of skills installed and enabled for the authenticated user and the specified `agentId`. Returns an empty array when no session is present or `agentId` is omitted. |

## Install skill

```http
POST /api/skills
```

Requires session authentication. Installs a skill on an agent.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `skillId` | string | Yes | ID of the skill to install |
| `agentId` | string | Yes | ID of the agent to install the skill on. This can be either a database agent ID or a managed runtime's `openclawInstanceId`. |

### Managed runtime resolution

When `agentId` does not match an existing agent row in the database, the endpoint checks whether it corresponds to the authenticated user's managed OpenClaw runtime (`openclawInstanceId`). If it does, a backing agent row is automatically created in the database before the skill is installed. This allows you to install skills on managed runtimes that have not yet been explicitly registered as agents.

The auto-created agent uses the following defaults:

| Field | Value |
|-------|-------|
| `name` | `Managed OpenClaw Runtime` |
| `model` | `openclaw` |
| `status` | `running` |

<Note>The agent row is created via an upsert, so subsequent skill installations on the same managed runtime reuse the existing row. The same resolution logic applies to the [uninstall endpoint](#uninstall-skill).</Note>

### Response

When the skill is installed and deployed to the gateway successfully:

```json
{
  "success": true,
  "installed": {
    "id": "inst_123",
    "skillId": "dj-streaming",
    "agentId": "agent_456",
    "installedAt": "2026-03-20T00:00:00Z"
  },
  "runtimeHydrated": false,
  "deployed": true,
  "message": "Skill installed successfully."
}
```

When the skill is saved but the agent is offline or the gateway is unreachable:

```json
{
  "success": true,
  "installed": {
    "id": "inst_123",
    "skillId": "dj-streaming",
    "agentId": "agent_456",
    "installedAt": "2026-03-20T00:00:00Z"
  },
  "runtimeHydrated": false,
  "deployed": false,
  "deployWarning": "Gateway unreachable - skill saved to database and will sync automatically",
  "message": "Skill saved to the database and will sync to the runtime automatically."
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Always `true` when the skill is saved to the database |
| `installed` | object | The installation record |
| `installed.id` | string | Unique installation identifier |
| `installed.skillId` | string | ID of the installed skill |
| `installed.agentId` | string | ID of the agent the skill was installed on |
| `installed.installedAt` | string | ISO 8601 timestamp of the installation |
| `runtimeHydrated` | boolean | `true` when the `agentId` resolved to a managed OpenClaw runtime and a backing agent row was auto-created. `false` when the agent already existed in the database. See [managed runtime resolution](#managed-runtime-resolution). |
| `deployed` | boolean | Whether the skill was successfully deployed to the gateway. `false` when the agent is offline or the gateway is unreachable. |
| `deployWarning` | string \| undefined | Present only when `deployed` is `false`. Describes why the deployment did not complete. The skill is still saved and will sync automatically when the agent comes back online. |
| `message` | string | Human-readable summary of the install outcome. Varies based on whether the runtime was hydrated and whether the gateway deploy succeeded. |

### Errors

| Code | Description |
|------|-------------|
| 400 | Missing `skillId` or `agentId` |
| 400 | Skill blocked by marketplace safety checks. The response includes a `scan` object with the reasons for the block. See [scan object](#scan-object). |
| 401 | Unauthorized |
| 404 | Agent not found or skill not found |
| 500 | Internal error |

When a skill is blocked by safety checks, the response looks like this:

```json
{
  "error": "Skill blocked by marketplace safety checks",
  "scan": {
    "trustTier": "blocked",
    "riskLevel": "blocked",
    "installAllowed": false,
    "reasons": ["Dynamic code execution via eval detected"],
    "warnings": [],
    "requiresManualReview": true
  }
}
```

<Note>When a skill is installed, the agent's complete state (including the newly installed skill) is automatically synced to the OpenClaw gateway. If the gateway is unreachable, the response returns `"deployed": false` with a `deployWarning` message — the skill is still recorded in the database and will sync automatically when the agent comes back online. You can also retry the sync manually using the [agent sync endpoint](/api-reference/agents#sync-agent-to-gateway).</Note>

## Create skill

```http
POST /api/skills/create
```

Requires session authentication. Creates a new custom skill in the marketplace. The skill becomes available to all users once created.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Display name of the skill. Maximum 80 characters. Must be unique across the marketplace. |
| `description` | string | Yes | Summary of the skill's capabilities. Maximum 600 characters. |
| `category` | string | No | Category for the skill. Maximum 40 characters. Defaults to `custom` when omitted. |
| `code` | string | No | Skill handler code or configuration. Maximum 2000 characters. |
| `sourceUrl` | string | No | URL to the skill's source code repository or homepage. Maximum 300 characters. Providing a source URL improves the skill's trust tier during safety scanning. |

### Response

```json
{
  "success": true,
  "skill": {
    "id": "clx9abc123",
    "name": "My Custom Skill",
    "description": "Analyzes track mix quality",
    "category": "custom",
    "code": "",
    "author": "user@example.com",
    "downloads": 0,
    "rating": 0,
    "featured": false,
    "mcpEnabled": false,
    "mcpConfig": null,
    "createdAt": "2026-04-02T12:00:00.000Z",
    "updatedAt": "2026-04-02T12:00:00.000Z"
  },
  "scan": {
    "trustTier": "review",
    "riskLevel": "medium",
    "installAllowed": true,
    "reasons": [],
    "warnings": ["Source URL missing"],
    "requiresManualReview": true
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `skill.id` | string | Unique identifier for the created skill |
| `skill.name` | string | Display name |
| `skill.description` | string | Skill description |
| `skill.category` | string | Category (defaults to `custom`) |
| `skill.code` | string | Skill handler code |
| `skill.author` | string | Set to the authenticated user's display name or email |
| `skill.downloads` | number | Download count, starts at `0` |
| `skill.rating` | number | Rating score, starts at `0` |
| `skill.featured` | boolean | Always `false` for user-created skills |
| `skill.mcpEnabled` | boolean | Whether the skill has a bundled MCP server. Always `false` for user-created skills. |
| `skill.mcpConfig` | object \| null | MCP server configuration. Always `null` for user-created skills. |
| `skill.createdAt` | string | ISO 8601 creation timestamp |
| `skill.updatedAt` | string | ISO 8601 last-updated timestamp |
| `scan` | object | Marketplace safety scan result. See [scan object](#scan-object). Skills that fail the safety scan are rejected before creation. |

### Errors

| Code | Description |
|------|-------------|
| 400 | Missing `name` or `description`, or a skill with the same name already exists |
| 400 | Skill blocked by marketplace safety checks. The response includes a `scan` object with the reasons for the block. See [scan object](#scan-object). |
| 401 | Unauthorized |
| 500 | Internal error |

## Uninstall skill

```http
DELETE /api/skills
```

Requires session authentication. Removes a skill from an agent.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `skillId` | string | Yes | ID of the skill to uninstall |
| `agentId` | string | Yes | ID of the agent to uninstall the skill from. Accepts a managed runtime's `openclawInstanceId` — see [managed runtime resolution](#managed-runtime-resolution) above. |

### Response

```json
{
  "success": true,
  "runtimeHydrated": false,
  "message": "Skill removed successfully."
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Always `true` when the skill is removed from the database |
| `runtimeHydrated` | boolean | `true` when the `agentId` resolved to a managed OpenClaw runtime. See [managed runtime resolution](#managed-runtime-resolution). |
| `message` | string | Human-readable summary of the uninstall outcome. Varies based on whether the runtime was hydrated. |

### Errors

| Code | Description |
|------|-------------|
| 400 | Missing `skillId` or `agentId` |
| 401 | Unauthorized |
| 404 | Agent not found |
| 500 | Internal error |

<Note>The uninstall endpoint returns `{ "success": true }` even when no matching installation exists. It does not return a `404` error for missing skill installations, though it does return `404` if the agent itself cannot be found.</Note>

<Note>When a skill is uninstalled, the updated agent state is automatically synced to the OpenClaw gateway. If the sync fails, the skill is still removed from the database — you can retry the sync manually using the [agent sync endpoint](/api-reference/agents#sync-agent-to-gateway).</Note>

## Verify skill

```http
POST /api/skills/verify
```

Runs a marketplace safety scan on a skill without creating or installing it. Use this endpoint to check whether a skill would pass safety checks before submitting it to the marketplace.

No authentication required.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Display name of the skill |
| `description` | string | No | Skill description |
| `code` | string | No | Skill handler code or configuration |
| `author` | string | No | Author name |
| `featured` | boolean | No | Whether the skill is featured |
| `sourceUrl` | string | No | URL to the skill's source repository |

### Response

```json
{
  "scan": {
    "trustTier": "verified",
    "riskLevel": "low",
    "installAllowed": true,
    "reasons": [],
    "warnings": ["Network access present"],
    "requiresManualReview": false
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `scan` | object | The safety scan result. See [scan object](#scan-object). |

### Errors

| Code | Description |
|------|-------------|
| 500 | Internal error |

## Scan object

Every skill listed, created, or verified includes a `scan` object from the marketplace safety scanner. The scanner performs static analysis on skill code to detect potentially dangerous patterns.

| Field | Type | Description |
|-------|------|-------------|
| `trustTier` | string | One of `trusted`, `verified`, `review`, or `blocked`. See [trust tiers](#trust-tiers). |
| `riskLevel` | string | One of `low`, `medium`, `high`, or `blocked` |
| `installAllowed` | boolean | Whether the skill can be installed. `false` when the skill is blocked. |
| `reasons` | string[] | List of reasons the skill was blocked. Empty when `trustTier` is not `blocked`. |
| `warnings` | string[] | Informational warnings about patterns found in the skill code (for example, network access or filesystem access). These do not prevent installation. |
| `requiresManualReview` | boolean | Whether the skill should be reviewed by a human before being promoted or sold |

### Trust tiers

| Tier | Description |
|------|-------------|
| `trusted` | Reserved for platform-authored skills and manually approved partners. Auto-install allowed and eligible for featured placement. |
| `verified` | User-created skills with a source URL that pass static checks with minimal warnings. Install allowed, visible trust badge, eligible for paid distribution. |
| `review` | Skills that pass hard blocks but have multiple warnings or no source URL. Discoverable and installable, but not promoted or eligible for paid distribution until reviewed. |
| `blocked` | Skills that match dangerous code patterns (shell injection, eval, process execution, environment variable scraping, destructive commands, or direct IP endpoints). Cannot be created or installed. |

### Blocked patterns

The following patterns in skill code cause a skill to be blocked:

- Piped shell execution (`curl ... | bash`)
- Dynamic code execution (`eval()`, `Function()`)
- Process execution imports or calls (`child_process`, `exec`, `spawn`)
- Destructive filesystem commands (`rm -rf`)
- Direct environment variable access (`process.env`)
- Direct IP-based remote endpoints

## Available skills

### Streaming

| Skill | Endpoint | Description |
|-------|----------|-------------|
| baseFM DJ Streaming | `/dj-streaming` | Create baseFM streams, fetch live DJs, and generate ffmpeg broadcaster commands for autonomous agent DJs |

### Events

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Guestlist Manager | `/guestlist` | Manage event guestlists, RSVPs, check-ins, and capacity limits |
| Event Ticketing | `/event-ticketing` | Sell tickets with USDC payments on Base via x402 protocol |
| Event Scheduler | `/event-scheduler` | Schedule events across Telegram, Discord, WhatsApp, and email with recurring support |
| Venue Finder | `/venue-finder` | Find venues worldwide with capacity and price filters |
| Festival Finder | `/festival-finder` | Discover festivals globally, compare lineups, and get recommendations |

### Payments

| Skill | Endpoint | Description |
|-------|----------|-------------|
| USDC Payments | `/usdc-payments` | Accept USDC payments on Base, generate payment links, and track transactions |
| Booking Settlement | `/booking-settlement` | Escrow and split execution for booking payments with auto-release on gig completion |
| Instant Split | `/instant-split` | Execute royalty splits instantly in USDC on Base with configurable thresholds |

### Finance

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Community Treasury | `/treasury` | Track spending, reimbursements, and multi-sig treasury management |
| Royalty Tracker | `/royalty-tracker` | Track streaming royalties across platforms in USDC |
| Crypto Price Alerts | `/crypto-price-alerts` | Monitor crypto prices and send alerts via Telegram or Discord when thresholds are hit |
| DeFi Portfolio | `/defi-portfolio` | Track wallet holdings, LP positions, and yield farming across Base and Ethereum |
| Invoice Generator | `/invoice-generator` | Create and send invoices in USDC with payment tracking and reminders |

### Productivity

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Google Calendar | `/google-calendar` | Schedule events, manage availability, and set reminders with full Google Calendar sync. See the [Calendar API](/api-reference/calendar) for detailed endpoint documentation. |
| File Manager | `/file-manager` | Upload, download, and organize files with local storage integration |
| Google Workspace | `/google-workspace` | Gmail, Calendar, Drive, and Sheets integration |
| Notion | `/notion` | Sync with Notion databases, pages, and workflows |
| CRM Helper | `/crm-helper` | Track leads, follow-ups, and customer interactions across channels |
| Meeting Notes | `/meeting-notes` | Auto-generate meeting notes from Zoom and Google Meet transcripts |

### Communication

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Email | `/email` | Send and receive emails with newsletter support |

### Development

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Webhooks | `/webhook` | Connect to any API with HTTP requests, webhooks, and integrations |
| Browser Automation | `/browser` | Browse websites, fill forms, and scrape data autonomously |
| Chat SDK | `/chat-sdk` | Multi-platform bot SDK for building on Slack, Teams, Discord, Google Chat, GitHub, and Linear with a single TypeScript SDK |
| Sentry CLI | `/sentry-cli` | Production error monitoring with issue management, log streaming, distributed tracing, and Sentry API access |
| Docker Containers | `/docker-containers` | Best practices for agent container isolation, persistent state, secret management, health checks, and resource limits |
| Stateful Agents | `/stateful-agents` | Persistent state management with Prisma, real-time agent coordination, scheduled tasks, and Drizzle ORM migrations |
| Deploy CLI | `/deploy-cli` | CLI reference for agent provisioning, secrets management, log streaming, and deployment troubleshooting |
| Code Review | `/code-review` | Review agent code against production best practices covering security, state management, error handling, and anti-pattern detection |

### Channels

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Telegram | `/telegram` | Connect via Telegram with bot commands, messages, and groups |
| Discord | `/discord` | Connect via Discord with slash commands, embeds, and voice channels |
| WhatsApp | `/whatsapp` | Connect via WhatsApp with message templates, media, and status updates |
| WhatsApp Business | `/whatsapp-business` | Full WhatsApp Business API with automated replies, labels, and catalogs |
| Slack | `/slack` | Post to channels, create threads, and handle slash commands |

### Music

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Track Archaeologist | `/track-archaeologist` | Deep catalog search via BlockDB similarity search |
| Setlist Oracle | `/setlist-oracle` | BPM, key, and energy analysis to build DJ sets with Camelot mixing |
| Demo Submitter | `/demo-submitter` | Submit demos to Base FM for airplay consideration |
| Spotify Analytics | `/spotify-analytics` | Track streams, followers, and playlist placements with a cross-platform analytics dashboard |
| SoundCloud Manager | `/soundcloud-manager` | Upload tracks, manage likes, track reposts, and analyze audience demographics |
| Bandcamp Sync | `/bandcamp-sync` | Sync releases, track sales, and manage merchandise across Bandcamp |

### Creative

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Visual Synthesizer | `/visual-synthesizer` | Generate release artwork and social media assets using Stable Diffusion XL |
| AI Image Generator | `/ai-image-generator` | Generate images via Stable Diffusion, DALL-E, or Midjourney with batch processing |
| Video Editor | `/video-editor` | Auto-edit video clips with transitions, captions, and background music |
| Podcast Producer | `/podcast-producer` | Auto-edit podcasts, remove filler words, and add intro/outro music |
| Video Generator | `/video-generator` | Generate videos via xAI Grok, Runway, or Wan for social media and marketing |
| Music Generator | `/music-generator` | Create original music with Google Lyria or MiniMax with async generation and follow-up delivery |
| ComfyUI Workflows | `/comfyui-workflows` | Run ComfyUI workflows locally or on Comfy Cloud for image, video, and music generation |

### Marketing

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Groupie Manager | `/groupie-manager` | Fan segmentation, lifecycle tracking, and automated merch drop campaigns |
| Content Calendar | `/content-calendar` | Plan and schedule social media posts across all platforms |
| SEO Analyzer | `/seo-analyzer` | Analyze website SEO, suggest keywords, and audit backlinks |
| Affiliate Tracker | `/affiliate-tracker` | Track affiliate links, clicks, and conversions across networks |

### AI

| Skill | Endpoint | Description |
|-------|----------|-------------|
| Qwen AI | `/qwen-ai` | Use Qwen models for chat, reasoning, and tool calling with fast inference |
| Fireworks AI | `/fireworks-ai` | Access Fireworks AI models for generation and reasoning with high-throughput inference |
| Bedrock Mantle | `/bedrock-mantle` | Use Amazon Bedrock Mantle models with automatic inference profile discovery |

## Production availability

The following skill routes are demo-only and are disabled in production by default:

- Booking Settlement (`/booking-settlement`)
- Demo Submitter (`/demo-submitter`)
- Event Scheduler (`/event-scheduler`)
- Event Ticketing (`/event-ticketing`)
- Festival Finder (`/festival-finder`)
- Groupie Manager (`/groupie-manager`)
- Instant Split (`/instant-split`)
- Royalty Tracker (`/royalty-tracker`)
- Setlist Oracle (`/setlist-oracle`)
- Track Archaeologist (`/track-archaeologist`)
- Venue Finder (`/venue-finder`)

When called in production without the `ENABLE_DEMO_SKILLS` environment variable set to `true`, these routes return `501` with the following response:

```json
{
  "error": "disabled_in_production",
  "message": "{skill-name} is a demo route and is disabled in production."
}
```

To enable demo skill routes in production, set the `ENABLE_DEMO_SKILLS=true` environment variable. In non-production environments, all skill routes are available without this flag.

## Use a skill

```http
POST /api/skills/{skill-name}
```

### Visual Synthesizer

```json
{
  "prompt": "dark techno album cover",
  "style": "industrial"
}
```

### Track Archaeologist

```json
{
  "action": "search",
  "bpm": 128,
  "genre": "techno",
  "mood": "dark"
}
```

### Setlist Oracle

```json
{
  "action": "build",
  "genre": "house",
  "duration": 120
}
```

### Groupie Manager

```json
{
  "action": "segment"
}
```

### Royalty Tracker

```json
{
  "action": "total"
}
```

### Demo Submitter

```json
{
  "action": "submit",
  "title": "My Track",
  "artist": "My Name"
}
```

### Event Ticketing

```json
{
  "action": "purchase",
  "eventId": "e1",
  "email": "fan@example.com",
  "tier": "vip"
}
```

### Event Scheduler

```json
{
  "action": "schedule",
  "title": "Newsletter",
  "date": "2026-03-20",
  "time": "18:00",
  "channels": ["telegram", "email"]
}
```

### Venue Finder

```json
{
  "action": "search",
  "city": "London",
  "type": "underground",
  "capacity": 200,
  "maxPrice": 500
}
```

### Festival Finder

```json
{
  "action": "search",
  "genre": "techno",
  "country": "UK",
  "maxPrice": 350
}
```

### Booking Settlement

Manage booking escrow, fund releases, and settlement simulations.

**Actions:** `list`, `get`, `create_escrow`, `release_funds`, `simulate_settlement`

```json
{
  "action": "create_escrow",
  "bookingId": "bk_1"
}
```

```json
{
  "action": "release_funds",
  "bookingId": "bk_1"
}
```

```json
{
  "action": "simulate_settlement",
  "booking": {
    "guarantee": 500,
    "backend": 200,
    "deposit": 100
  }
}
```

### Instant Split

Execute royalty splits instantly in USDC on Base.

**Actions:** `list_pending`, `create_split_rule`, `execute_split`, `get_balance`, `simulate`

```json
{
  "action": "execute_split",
  "splitId": "split_1"
}
```

```json
{
  "action": "create_split_rule",
  "splits": {
    "recipientAddress": "0x...",
    "percentage": 50,
    "role": "artist",
    "name": "Artist"
  },
  "threshold": 50
}
```

```json
{
  "action": "simulate",
  "streams": 100000,
  "rate": 0.003
}
```

## Response format

```json
{
  "success": true
}
```

<Note>Each skill returns additional data specific to its function alongside the `success` field.</Note>

## Errors

| Code | Description |
|------|-------------|
| 400 | Invalid request parameters |
| 404 | Skill not found |
| 500 | Internal error |
| 501 | Demo skill route is disabled in production. Set `ENABLE_DEMO_SKILLS=true` to enable. See [production availability](#production-availability). |
