Tools and skills reference

@flexkit/tools is a server-only package with no React or Studio dependency. Import defineTool, defineSkill and defineTools from it, default-export the result of defineTools from flexkit.tools.ts, and serve it with createToolsHandler.

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.

The returned tool also carries inputSchema, the JSON Schema (draft-07) published in the catalog. 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.

A rename changes sync identity and removes the prior skill’s attachments. See code-defined skills.

defineTools

defineTools({ tools?, skills? }) returns { tools, skills } and throws on duplicate tool or skill names. It is the shape createToolsHandler serves and flexkit dev loads from the default export of flexkit.tools.ts.

createToolsHandler

createToolsHandler(definition, options?) returns (request: Request) => Promise<Response>.

Option	Default
`secret`	`process.env.FLEXKIT_TOOLS_SECRET`
`previousSecret`	`process.env.FLEXKIT_TOOLS_SECRET_PREVIOUS`

GET answers a signed discovery request with { tools, skills }. POST verifies the signature, validates arguments against the tool’s Zod schema and returns { result }. The signature covers the request path, so register the exact URL the handler is mounted on. handleToolsRequest(definition, request, options?) is the same logic without the closure, for frameworks that pass extra arguments.

Local runtime

@flexkit/tools/dev exports startDevConnect, the Node runtime behind flexkit dev. Most projects never import it; it exists so other hosts, such as a desktop app, can register a local runtime the same way.

See custom tools for a complete example and security for authorization and failure handling.