# Jido Action

> Build and maintain composable Jido actions with validated inputs, explicit outputs, predictable errors, and AI-tool compatibility. Use when defining actions, schemas, action chains, or action execution behavior.

- Skill: `agentjido/jido-action` (Agent Skill)
- Install (CLI): `npx skillmds@latest add agentjido/jido-action`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agentjido/jido-action/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: agentjido (https://skillmd.com/u/agentjido)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agentjido/jido-action

---


# Jido Action

## Purpose

Create focused Jido actions that are easy to validate, compose, test, and
expose to agents or tools.

## When To Use

Use this skill for:

- New `use Jido.Action` modules
- Action schema or output schema changes
- `run/2` behavior changes
- Action chains or closures
- Converting actions into AI-callable tools
- Debugging action validation or execution

Invoke `jido-core` first for shared ecosystem context.

## Requirements

- Inspect local action modules before writing new patterns.
- Preserve the repo's current schema style unless migration is requested.
- Prefer pure, deterministic action behavior.
- Return explicit success or error tuples.

## Workflow

### 1. Inspect action conventions

Search before editing:

```bash
rg "use Jido.Action|def run\\(" lib test
```

Record:

- Schema style
- Return shape
- Error conventions
- Context usage
- Tests for validation and execution

### 2. Define the action contract

Before coding, identify:

- Action name and description
- Required and optional params
- Output shape
- Error cases
- Context fields read by `run/2`
- Whether the action is safe to expose as an AI tool

Keep actions narrow. Split multi-step workflows into action chains or separate
actions when that improves testing and reuse.

### 3. Validate inputs and outputs

Use the repo-supported schema mechanism. For new code, prefer Zoi when the repo
already uses or supports it. Otherwise preserve the existing schema style.

Validation should reject invalid input before behavior executes. Output schemas
should be used for externally consumed or tool-facing actions when supported.

### 4. Implement `run/2`

`run/2` should:

- Accept validated params
- Read only documented context keys
- Return `{:ok, result}` or `{:error, reason}`
- Keep external side effects out unless the action's purpose is explicitly an
  adapter boundary
- Avoid raising for normal validation or domain failures

### 5. Tool compatibility

When exposing an action to AI tools:

- Ensure name and description are clear to a model
- Ensure params have useful docs
- Avoid ambiguous atoms or internal-only data structures at the tool boundary
- Add tests for generated tool schema when the repo supports that behavior

### 6. Validate

Run focused action tests first:

```bash
mix test path/to/action_test.exs
```

Then run the repo-standard test or quality command.

## Output Expectations

Report:

- Action contract changed
- Validation behavior changed
- Error cases covered
- Tool-facing behavior, if any
- Tests run

## Guardrails

- Do not use actions as unstructured service objects.
- Do not silently swallow errors.
- Do not depend on process dictionary state.
- Do not expose unsafe filesystem, network, or code-evaluation behavior as a
  model tool.
- Do not change return shapes without updating callers and tests.