Skills Docs — lacai

What is a skill

A skill is a small package that adds a new ability to the lacai AI. Once a user installs your skill, the AI knows how to use it in conversation.

Think of it like a plugin. You write a tool that does one specific thing well, like checking the weather, sending a Slack message, or looking up a stock price. The AI figures out when to use it and calls it automatically when the user asks.

You do not have to build a UI. You write the logic, declare what the tool does in plain words, and lacai handles the rest. The AI reads your description and decides when to call your tool.

Skills run server-side inside lacai. You do not ship JavaScript that runs in the user browser. You declare a handler URL and lacai calls it when needed.

How it works

The whole flow from install to execution in four steps.

1

You submit a skill bundle

A zip file with a manifest and your tool definitions. lacai scans it automatically for security issues.

2

It gets listed in the marketplace

After the scan passes, your skill shows up publicly. Users can browse and install it in one click.

3

The AI learns about it

When a user starts a chat or voice session, lacai merges your tool definitions into the AI context. The AI reads your descriptions and knows it can use your skill.

4

The user asks, the AI acts

User says "what is the weather in Lagos". The AI calls your tool, gets the result, and answers naturally. No extra setup for the user.

Quickstart

From zero to a working skill in about ten minutes.

Download a working example first

Before writing anything, download the GitHub skill. It is a real approved skill in the marketplace. Open the zip, read the manifest, and you will understand the structure immediately.

GitHub Skill — sample bundle Search public repos, get repo details, read latest releases. No auth required. Tier: Green.

Download zip

Create your project folder

Make a folder with at least two files inside it.

my-skill/
  manifest.json
  README.md

Write the manifest

The manifest is the most important file. It tells lacai everything about your skill.

{
  "slug": "weather",
  "name": "Weather",
  "version": "1.0.0",
  "author": "you",
  "description": "Get the current weather for any city",
  "auth_type": "secret",
  "secrets": [
    { "key": "api_key", "label": "OpenWeather API Key", "placeholder": "abc123..." }
  ],
  "permissions": [],
  "domains": ["api.openweathermap.org"],
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather and temperature for a city",
      "handler_url": "https://yourserver.com/weather",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name" }
        },
        "required": ["city"]
      }
    }
  ]
}

Zip it and submit

Zip the folder and upload it in your developer portal. The scan takes about 30 seconds. You will get an email when it is done.

Make sure your zip includes manifest.json at the root level, not inside a subfolder. The scanner looks for it there.

The manifest file

Every field explained.

Field	Type	What it does
slug	string	Unique ID for your skill. Lowercase, hyphens only. Cannot be changed after publishing.
name	string	Display name shown in the marketplace.
version	string	Semver like 1.0.0. Bump this when you submit an update.
author	string	Your name or your company.
description	string	One to two sentences shown in the marketplace card.
auth_type	string	How users authenticate. One of none, secret, or oauth.
secrets	array	Fields to ask the user for (API keys etc). Only used when auth_type is secret.
permissions	array	What your skill is allowed to do. Leave empty unless you need special access.
domains	array	The external URLs your tool calls. Any call to an unlisted domain is blocked automatically.
tools	array	The actual tool definitions the AI will use. See the next section.
homepage	string	Optional. A link to your docs or GitHub repo.
changelog	string	Optional. Short notes about what changed in this version.

Defining tools

Tools are the actions the AI can take. Write the description like you are explaining it to a person, not a machine.

The description field is the most important thing you will write. The AI reads it to decide whether to call your tool. A bad description means the AI will use your tool at the wrong time or not at all.

Good vs bad descriptions

Bad: "Fetches weather data from OpenWeatherMap API for a given location parameter"

Good: "Get the current weather and temperature for any city. Use this when the user asks about weather, temperature, or whether they need an umbrella."

Tool fields

Field	Type	What it does
name	string	Internal name. Lowercase, underscores. The AI uses this to call your tool.
description	string	Plain English description of what the tool does and when to use it.
handler_url	string	The URL lacai sends a POST request to when this tool is called. Must be in your domains list.
parameters	object	JSON Schema describing the arguments the AI should pass to your tool.
static_response	string	Optional. If set, lacai returns this string directly without calling handler_url. Useful for simple tools.

What lacai sends to your handler

When the AI calls your tool, lacai makes a POST request to your handler_url with this body.

{
  "city": "Lagos",          // the arguments the AI passed
  "_secrets": {
    "api_key": "abc123"    // the user stored API key, decrypted
  }
}

What your handler should return

{
  "result": "It is 28°C and sunny in Lagos."
}

Return a plain result the AI can read and repeat to the user. Keep it short and factual.

Auth and secrets

Three ways to handle authentication depending on what your skill needs.

No auth

Set auth_type to none and leave secrets empty. Good for public APIs that do not need a key.

API key or secret

Set auth_type to secret and list the fields you need in the secrets array. The user fills them in after installing your skill. lacai encrypts them and sends them to your handler with each call.

"secrets": [
  {
    "key": "api_key",
    "label": "OpenWeather API Key",
    "placeholder": "Paste your key here"
  }
]

OAuth

Set auth_type to oauth and add an oauth section to your manifest. lacai opens the auth URL for the user and stores the token automatically.

"oauth": {
  "auth_url":    "https://provider.com/oauth/authorize",
  "token_url":   "https://provider.com/oauth/token",
  "client_id":   "your-client-id",
  "client_secret":"your-client-secret",
  "scope":        "read write"
}

Secrets are encrypted with AES-256 and tied to each user. You never store them yourself. lacai injects them into your handler calls.

Bundling and submitting

How to package and send your skill for review.

What to include

Your zip must have manifest.json at the top level. Everything else is optional.

my-skill.zip
  manifest.json       required
  README.md           optional but nice
  package.json        include if you have npm deps
  index.js            only if your handler runs here

Size limit

Keep your bundle under 5MB. If you have large dependencies, trim them with npm install --omit=dev before zipping.

Submit

Go to your developer portal, fill in the form, and upload the zip. The scan runs automatically. You will get an email with the result.

Updates

Submit a new bundle with a higher version number. The scan runs again. If it passes, your marketplace listing updates automatically.

Security scan

Every submission goes through an automatic check before anyone can install it.

The scan looks for things that could harm users or the platform. It runs in under a minute in most cases.

What we check

1

Virus scan

The bundle is scanned with ClamAV. If any malware signatures are found, it is rejected immediately.

2

Code patterns

We scan every JS file for dangerous patterns. Things like eval, new Function, dynamic imports, child_process, and filesystem access are not allowed.

3

Dependency audit

If you have a package.json, we run npm audit. Critical vulnerabilities mean auto rejection. High severity means manual review.

4

Manifest check

We read your permissions and domains and assign a tier. This determines whether the skill auto-approves or goes to manual review.

Permission tiers

Your manifest permissions determine how your skill is treated in the review process.

Green — auto approved

One domain or fewer. No filesystem access. No panel or schedule permissions. These go live automatically if the scan passes.

Yellow — manual review

More than one domain, or uses the schedule or panel permission. A human at lacai reviews these before they go live. Usually takes 1 to 2 days.

Red — rejected

Filesystem permission is in your manifest. This is auto rejected. Skills do not need filesystem access and it poses too much risk.

Keep your domains list as short as possible. One API, one domain. This keeps your skill in the Green tier and gets it approved faster.

FAQ

How long does review take?

Green tier skills auto-approve in under a minute if the scan passes. Yellow tier usually takes one to two days. You get an email either way.

Can I update my skill after publishing?

Yes. Submit a new bundle with a higher version number. It goes through the same scan. When it passes, the listing updates.

Do users need to set up anything?

Just install the skill. If it needs an API key they enter it once. If it needs OAuth they click Connect once. After that the AI handles everything.

What happens to user secrets?

They are encrypted with AES-256 and stored on lacai servers. You never receive or store them yourself. They are decrypted and injected into your handler call each time.

My skill was rejected. Can I fix it and resubmit?

Yes. The rejection email tells you exactly what failed. Fix it, zip again, and submit. There is no limit on resubmissions.

Can skills call each other?

Not directly. Each skill runs independently. If you need combined functionality, build it into one skill or use the AI to chain the calls in conversation.