---
title: 'Tools and skills reference'
description: 'Use the public server-side extension definitions.'
---

# Tools and skills reference

> **Release requirement:** This guide uses Studio extension APIs that are not present in npm `@flexkit/studio@0.0.31`. See [package availability](/docs/reference/compatibility#package-availability) before using the example.

Import `defineTool` and `defineSkill` from `@flexkit/studio/tools`. Register their returned values with the framework handler's `tools` and `skills` options.

## defineTool

| Property      | Contract                                                        |
| ------------- | --------------------------------------------------------------- |
| `name`        | CamelCase identifier; must not begin with `custom_`.            |
| `description` | Nonempty description, trimmed by the helper.                    |
| `input`       | Zod schema used to validate invocation arguments.               |
| `execute`     | Receives validated input and actor; returns a value or promise. |

A Chat actor has `kind: 'chat'`, `userId`, `role`, and `spaceCodes`. An automation actor has `kind: 'automation'`, `automationId`, nullable `spaceId`, and `spaceCodes`. Authorize business actions explicitly based on the appropriate actor branch.

## defineSkill

| Property      | Contract                                        |
| ------------- | ----------------------------------------------- |
| `name`        | Nonempty sync identity, up to 120 characters.   |
| `description` | Nonempty summary, up to 500 characters.         |
| `content`     | Nonempty instructions, up to 50,000 characters. |
| `space`       | Optional nonempty deployed space code.          |

Names must be unique within registered skills. A rename changes sync identity and removes the prior skill's attachments. See [code-defined skills](/docs/ai/skills/define-in-code).

## Endpoint and secrets

The adapter exposes signed GET discovery and POST invocation at `/api/flexkit/tools`. Configure `FLEXKIT_TOOLS_SECRET` and optionally the previous secret during rotation. These are server secrets, not Studio public configuration.

See [custom tools](/docs/automations/custom-tools) for a complete example and [security](/docs/automations/custom-tools/security-and-deployment) for authorization and failure handling.


---

[View full sitemap](/docs/sitemap.md)