# Run Agent

> Execute a universal CLOD agent definition and orchestrate referenced skills.

- Skill: `spillwavesolutions/run-agent` (Agent Skill)
- Install (CLI): `npx skillmds@latest add spillwavesolutions/run-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spillwavesolutions/run-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: spillwavesolutions (https://skillmd.com/u/spillwavesolutions)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/spillwavesolutions/run-agent

---


## Inputs

- **agent_path** (path, required) -- Path to the CLOD agent markdown file.
- **args** (map, optional) -- Key-value arguments passed to the agent.
- **execution_mode** (enum: `sequential` | `parallel`, default: `sequential`) -- Whether to run skills sequentially or in parallel.
- **max_parallel** (integer, default: 4) -- Maximum number of parallel skill invocations.
- **timeout_secs** (integer, default: 900) -- Timeout for the entire agent run in seconds.
- **working_dir** (path, optional) -- Working directory for skill execution.
- **env** (map, optional) -- Environment variables to set during execution.
- **log_path** (path, optional) -- Path for JSONL event log output.

## Outputs

- **result** (markdown) -- The final result of the agent run.
- **steps** (array) -- Structured trace with timestamps, skill id, status, and output excerpt per step.
- **errors** (array) -- Any errors encountered during execution.

## Constraints

- Skills must be resolved from `./skills` relative to the repo root.
- Must not mutate git state unless explicit in agent policy.
- Timeout must be enforced per agent run.

## Contract
- Parse `agent_path` as CLOD agent markdown.
- Validate required skills exist; fail fast if missing.
- Respect `execution_mode` or `parallelism` hints inside the agent document.
- Invoke skills in-order (or concurrently) passing `args` as needed.
- On failure, surface error and allow caller to trigger fallback agent/model.
- Emit structured trace in `steps` with timestamps, skill id, status, and output excerpt.

Execution Rules
1) Load agent and normalize into internal plan.
2) For each step: resolve skill, prepare inputs, invoke via platform-native mechanism.
3) If step marked `parallel`, request platform-native fan-out up to `max_parallel`; when the platform lacks native parallelism, run sequentially.
4) Collect results; if any required step fails, mark run failed.
5) If `log_path` provided, append JSONL events for observability.

Invocation guidance by platform
- Routing: cron frontmatter `agent` selects the adapter (codex | gemini | opencode | claude | copilot).
- Codex: call this skill directly with `agent_path` + `args`. Parallel blocks are honored only when the user/agent explicitly requests parallel work; the adapter may spawn background shell tasks when safe, otherwise runs sequentially.
- Gemini: supports explicit multi-agent/parallel requests (e.g., “run X and Y in parallel” or orchestrator commands). The adapter maps CLOD `parallel` blocks to Gemini’s native fan-out when available.
- OpenCode: accepts explicit instructions to run multiple background agents. The adapter will fan out steps marked `parallel`; otherwise it executes in order.
- Claude: uses native agent execution when `agent: claude`; this skill is bypassed.