Creating Skills

Create a SkillSet and deploy skills with any of these three methods:

• Dashboard — visual editor with built-in code validation
• MCP Server — programmatic access from AI coding assistants
• Developer API — REST API for automation and CI/CD

A SkillSet is a container for one or more skills — JavaScript functions the AI agent can call during conversations. Building one is a two-step process:

1. Create the SkillSet — name, description, visibility.
2. Create a version — add skills and configuration definitions, then deploy.

Each version is an immutable snapshot. Creating a new version automatically makes it the active one.

Plan the skill

Before writing code, answer four questions:

• What problem does it solve? (e.g. look up an order status)
• What inputs does it need? (e.g. order ID)
• What should it return? (e.g. status, delivery date, tracking URL)
• Does it need configuration? (e.g. API keys, endpoint URLs)

Example: order status skill

We'll build a skill that checks the status of a customer's order:

• Input — order ID (required), customer ID (optional)
• Output — status message, current status, estimated delivery
• Config — API endpoint URL, API key

Write the handler function

Every skill requires an async function handler(input) that receives:

Basic example

async function handler(input) {
  const { config, secrets, parameters } = input
  const { orderId } = parameters

  const res = await fetch(`${config.apiEndpoint}/orders/${orderId}`, {
    headers: { 'Authorization': `Bearer ${secrets.apiKey}` }
  })

  if (!res.ok) {
    return {
      prompt: `Failed to look up order ${orderId}: ${res.statusText}`
    }
  }

  const order = await res.json()

  return {
    prompt: `Order ${orderId} is currently ${order.status}. Estimated delivery: ${order.estimatedDelivery}.`,
    response: {
      text: `Order #${orderId}: ${order.status}`,
      buttons: [
        { label: "Track Package", payload: "TRACK_PACKAGE" },
        { label: "Request Return", payload: "REQUEST_RETURN" }
      ]
    }
  }
}

Rich response example (carousel)

async function handler(input) {
  const { config, secrets, parameters } = input

  const res = await fetch(`${config.apiEndpoint}/products?q=${parameters.query}`, {
    headers: { 'Authorization': `Bearer ${secrets.apiKey}` }
  })
  const { products } = await res.json()

  return {
    prompt: `Found ${products.length} products matching "${parameters.query}".`,
    response: {
      carousel: products.slice(0, 5).map(p => ({
        title: p.name,
        subtitle: `$${p.price}`,
        imageUrl: p.imageUrl,
        buttons: [
          { type: "web_url", title: "View", url: p.url },
          { type: "postback", title: "Add to Cart", payload: `ADD_${p.id}` }
        ]
      }))
    }
  }
}

Via Dashboard

The Dashboard provides a visual editor with code validation, schema editors, and AI-powered fix suggestions.

1. Create the SkillSet

1. Go to AI Settings → Skills.
2. Click Create New.
3. Fill in:
   • Name — display name (1–100 characters)
   • Slug — URL-friendly identifier, auto-generated from the name if you leave it blank. Lowercase letters, numbers, and underscores only, max 64 characters.
   • Tagline — short summary (max 200 characters)
   • Description — what the SkillSet does (1–1000 characters)
   • Visibility — PRIVATE (your organization only). Publishing to the public marketplace isn't available from the dashboard yet; use the MCP server or Developer API to create a PUBLIC SkillSet.
4. Optionally upload a logo.
5. Save.

2. Create a version with skills

1. Open your SkillSet and go to the code editor.

2. For each skill, fill in:

   Metadata

   • Name — display name (1–100 characters)
   • Slug — identifier (1–64 characters, ^[a-z0-9_]+$)
   • Description — what it does (1–500 characters)
   • Prompt — tell the AI agent when and how to use this skill (1–2000 characters)
   • Kind — EXECUTE (performs an action) or SEARCH (retrieves data)

   Code

   • Handler Code — your JavaScript handler function (max 50 KB)

   Schemas (JSON editors)

   • Parameters — JSON Schema for the inputs the AI agent should extract
   • Response — JSON Schema for the handler's output

   Optional

   • Buttons — quick-reply buttons (label max 50 chars, payload max 200 chars)

3. Add Configuration Definitions if your skill needs API keys or settings (see Configuration Types).

4. Fix any errors the live validator flags.

5. Enter a changelog message and publish.

3. Install and configure

1. Go to AI Settings → Skills.
2. Find your SkillSet and click Install.
3. Fill in the required configuration values (API key, endpoint, etc.).
4. Save.

4. Connect to a persona

1. Go to AI Settings → Personas and select a persona.
2. Open the Skills tab.
3. Enable the SkillSet.
4. Test in a conversation — try "check the status of order ORD-12345".

Via MCP Server

The Cloodot MCP server lets you manage SkillSets from any MCP-compatible client — Claude Code, Cursor, Windsurf, or any tool that speaks the Model Context Protocol.

Connect

Server URL — https://developers.cloodot.com/mcp

Authentication — OAuth 2.0. Your MCP client handles the OAuth flow automatically using the standard /.well-known/oauth-protected-resource endpoint.

Available tools

Each tool ships with full input schemas, so your MCP client surfaces required fields and validates inputs automatically. The same field limits from Skill definition limits apply.

Via Developer API

The Developer API is available at https://developers.cloodot.com. All endpoints require an API key sent via the x-api-key header.

For the complete API reference with request/response schemas, visit the interactive documentation at:

https://developers.cloodot.com/api/v1/reference

Quick start

Create a SkillSet:

curl -X POST https://developers.cloodot.com/api/v1/skillsets \
  -H "x-api-key: cloodot_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Management",
    "description": "Skills for checking order status and managing shipments",
    "visibility": "PRIVATE"
  }'

Create a version (auto-deploys):

curl -X POST https://developers.cloodot.com/api/v1/skillsets/SKILLSET_ID/versions \
  -H "x-api-key: cloodot_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "changeLog": "...", "skills": [...], "configDefinitions": [...] }'

Install and configure:

curl -X POST https://developers.cloodot.com/api/v1/skillsets/SKILLSET_ID/install \
  -H "x-api-key: cloodot_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X PUT https://developers.cloodot.com/api/v1/skillsets/SKILLSET_ID/config \
  -H "x-api-key: cloodot_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "apiEndpoint": "https://api.example.com", "apiKey": "sk-..." } }'

Available endpoints

ActionResponse reference

Every skill handler must return an ActionResponse object that matches this schema.

Schema

{
  prompt: string,              // Required
  message?: string,            // Optional
  data?: any,                  // Optional
  response?: {                 // Optional
    text?: string,
    buttons?: Array<{ label: string, payload: string }>,
    carousel?: Array<CarouselItem>,
    imageUrl?: string,
    documentUrl?: string
  }
}

Field reference

Carousel item schema

How fields are used

• prompt — fed back to the AI agent as tool output. The AI agent reads it to compose a natural-language reply to the user. Keep it informative and concise.
• message — sent as a direct assistant message, bypassing the AI agent.
• response.text — text content shown in the chat alongside the AI agent's reply.
• response.buttons — clickable quick-reply buttons below the message. Tapping one sends payload back as a new message.
• response.carousel — horizontally scrollable cards with optional image, title, subtitle, and action buttons.
• response.imageUrl / response.documentUrl — media attachments. Both must be HTTPS URLs.

Minimal return

return { prompt: "Order ORD-123 is shipped and arriving tomorrow." }

Full return

return {
  prompt: "Found 3 products matching the search.",
  response: {
    text: "Here are the top results:",
    buttons: [
      { label: "Show More", payload: "SHOW_MORE" }
    ],
    carousel: [
      {
        title: "Widget Pro",
        subtitle: "$29.99",
        imageUrl: "https://example.com/widget.png",
        buttons: [
          { type: "web_url", title: "View", url: "https://example.com/widget" },
          { type: "postback", title: "Buy Now", payload: "BUY_WIDGET_PRO" }
        ]
      }
    ],
    imageUrl: "https://example.com/promo-banner.png"
  }
}

Skill definition limits

Field limits when creating a skill version.

Skill fields

SkillSet fields

Version fields

Configuration types

Troubleshooting

Handler not found

Error — "handler function not found"

Define an async handler function in your skill code:

async function handler(input) {
  // ...
}

Configuration not available

Error — config.apiKey (or secrets.apiKey) is undefined

1. Confirm the configuration key is defined in configDefinitions.
2. Confirm the SkillSet is installed and configured with values.
3. Make sure the key in your config definition matches what you read in code.
4. Fields marked isSensitive arrive in input.secrets, not input.config.

Skill not appearing in conversations

1. Confirm the SkillSet version is deployed — creating a version auto-deploys.
2. Confirm the SkillSet is installed in your organization.
3. Confirm the persona has the SkillSet enabled.
4. Make sure the prompt field clearly describes when the AI agent should use the skill.

Invalid response

If your handler returns something that doesn't match the ActionResponse format (for example, missing prompt), execution fails. At minimum, always return { prompt: "..." }.

Next steps

• Skill Schema Reference — full schema and validation rules
• Skill Sets — organize and manage SkillSet collections
• AI Agent Configuration — connect skills to the AI agent