# Actions

How to create and run agent actions.

- Repository: https://github.com/BuilderIO/agent-native (7579 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add BuilderIO/agent-native --skill actions -g -a claude-code -y`
Codex: `npx skills add BuilderIO/agent-native --skill actions -g -a codex -y`
Cursor: `npx skills add BuilderIO/agent-native --skill actions -g -a cursor -y`
Gemini CLI: `npx skills add BuilderIO/agent-native --skill actions -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add BuilderIO/agent-native`

## Description

How to create and run agent actions. Actions are the single source of truth for app operations, the agent calls them as tools and frontend code calls them through client hooks. Use when creating a new action, adding an API integration, or wiring up frontend data fetching.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Agent Actions

## Rule

Actions in `actions/` are the **single source of truth** for app operations. The agent calls them as tools, the frontend calls them through `useActionQuery` / `useActionMutation`, and the framework owns the HTTP transport behind those hooks, no duplicate `/api/` routes.

Before creating any custom route for app data, check `actions/` and the action table in `AGENTS.md`. An action already exists? Call it directly. Missing? Create or update a `defineAction`. **Stop trigger:** about to add a file under `server/routes/api/` (or middleware to guard one)? Check it against the exception list in *Custom `/api/` Routes* below first, even if you already started the route.

## Keep Actions Deterministic

An action may call a provider API, validate data, and persist records without being an AI feature, keep it deterministic, focused, and independently useful to the agent. Don't put LLM calls or a second model runtime in app actions.

The sanctioned model-backed exception is `@agent-native/core/decisions` for capability-aware classification and scoring, and it returns a result without performing or authorizing the selected action.

When a workflow is research, analysis, generation, recommendation, or synthesis, or spans several provider calls and writes, route it to the AgentSidebar via `sendToAgentChat({ openSidebar: true })` and let the agent orchestrate focused actions instead of hiding an AI-shaped workflow behind one opaque `generate-*`/`create-*` action just because its implementation happens to be deterministic.

## How to Create an Action

**One action per file, default-exported. The filename is the action name** (kebab-case): `actions/list-meals.ts` is the `list-meals` action. Don't put several `defineAction`s as named exports in one file, the registry keys actions by filename and only the default export is registered, so extra named exports never become callable and won't match `.generated/action-types.d.ts`.

The rest: https://github.com/BuilderIO/agent-native/blob/HEAD/.agents/skills/actions/SKILL.md