> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Skills as Agents

Run agents based on skills for consistent, repeatable workflows. Use skills with local or cloud agents from the CLI, Oz web app, API, or on a schedule.

You can start an agent from a [skill](/agents/capabilities/skills/)—a reusable set of instructions that defines what the agent should do. When you run an agent based on a skill, the skill provides the base prompt and behavior, while you supply additional context for that specific run.

Skills work with both **local agents** (running on your machine) and **cloud agents** (running in Warp’s infrastructure).

This is useful when you want:

-   **Consistent behavior** — The same skill produces the same workflow every time, regardless of who triggers it or where it runs.
-   **Repeatable automation** — Run skills on schedules for maintenance tasks like code cleanup, dependency updates, or issue triage.
-   **Shareable workflows** — Skills live in repositories, so your team can version, review, and collaborate on agent behavior.

* * *

## How Skills become available

Skill discovery depends on whether you’re running a local or cloud agent.

### Local agents

For local agent runs (`oz agent run`), skills are automatically discovered from your current repository. Warp scans these directories in order of precedence:

-   **`.warp/skills/`**
-   **`.agents/skills/`**
-   **`.claude/skills/`**
-   **`.codex/skills/`**
-   **`.cursor/skills/`**
-   **`.gemini/skills/`**
-   **`.copilot/skills/`**
-   **`.factory/skills/`**
-   **`.github/skills/`**
-   **`.opencode/skills/`**

You can also specify a skill from any accessible repository using the fully qualified format: `owner/repo:skill-name`.

### Cloud agents

For cloud agent runs (`oz agent run-cloud`), skills are discovered from repositories configured in your [environments](/platform/environments/).

**Discovery workflow:**

1.  **Create a skill** in your repository (see [Creating skills](/agents/capabilities/skills/#creating-skills))
2.  **Add the repository** to an environment
3.  **The skill appears** in the Agents list in the Oz web app

Note

You can also list available skills programmatically using the `GET /agent` endpoint. See the [Oz API](/reference/api-and-sdk/) reference for details.

### Extra skill directories in cloud runs

Skills that don’t live in a cloned repository’s standard skill directories can still be indexed. Set the `WARP_SKILL_DIRS` environment variable to a comma-separated list of skill directories, and a cloud run picks them up alongside the skills it discovers from your repositories. This is useful for skills baked into a custom Docker image, mounted from shared storage, or installed by a setup step outside a repo.

Set the variable in the environment’s Docker image so it’s present when the agent starts:

```
ENV WARP_SKILL_DIRS="/opt/team-skills,tooling/skills"
```

How the value is interpreted:

-   **Directory layout** - Each entry is a skills directory whose direct children are skill folders containing a `SKILL.md`, the same layout as `.agents/skills/`. Point the variable at the parent directory, not at an individual skill folder.
-   **Path resolution** - A leading `~` expands to the home directory. Relative entries resolve against the run’s working directory rather than the agent process’s current directory, so they stay stable even when setup steps change directories.
-   **Precedence** - Skills loaded this way are treated as personal (home) skills, so they stay in scope for the whole run regardless of which directory the agent is working in. Repository skills of the same name still appear separately, as described in [skill name conflicts](/agents/capabilities/skills/#skill-name-conflicts).
-   **Invalid entries** - Paths that are missing or aren’t directories are skipped with a warning in the run log, and an unset or empty value does nothing.

This variable applies to cloud runs on the Warp Agent harness. [Third-party harnesses](/platform/harnesses/) such as Claude Code and Codex use their own skill systems and ignore it.

* * *

## Running skill-based agents

You can start an agent from a skill using multiple entry points.

### Oz web app

Use the [Oz web app](/platform/oz-web-app/) to run skill-based agents from a visual interface. From the web app, you can:

-   Browse all skills available from your environments on the **Agents** page
-   View suggested agents from Warp’s public [oz-skills repository](https://github.com/warpdotdev/oz-skills)
-   Start a new run by selecting a skill, environment, and prompt
-   Create scheduled agents that run skills on a cron schedule

For a complete walkthrough of the web app interface, see [Oz Web App](/platform/oz-web-app/).

### CLI

Use the `--skill` flag with the Oz CLI:

```
# Run locally with a skilloz agent run --skill "owner/repo:skill-name" --prompt "additional context"
# Run in the cloud with a skilloz agent run-cloud \  --environment <ENV_ID> \  --skill "owner/repo:skill-name" \  --prompt "additional context"
```

For full CLI documentation, see [Using skills](/reference/cli/#using-skills) in the CLI reference.

### API & SDK

Use the `skill_spec` parameter when creating a run:

```
{  "prompt": "additional context for this run",  "config": {    "environment_id": "<ENV_ID>",    "skill_spec": "owner/repo:skill-name"  }}
```

For full API documentation, see [Agent configuration](/reference/api-and-sdk/#agent-configuration) in the API reference.

* * *

## Running skills on a schedule

One of the most powerful uses for skill-based agents is running them on a schedule. [Scheduled agents](/platform/triggers/scheduled-agents/) execute automatically at specified times, making them ideal for:

-   **Dead code cleanup** — Weekly scans for unused code or stale feature flags
-   **Dependency updates** — Daily or weekly checks for security updates
-   **Issue triage** — Regular categorization and prioritization of open issues
-   **Documentation refresh** — Periodic updates to keep docs in sync with code

**Creating a scheduled skill-based agent:**

```
oz schedule create \  --name "Weekly Code Cleanup" \  --cron "0 10 * * 1" \  --environment <ENV_ID> \  --prompt "Scan for dead code and unused feature flags. Open a PR with removals."
```

You can also create schedules from the [Oz web app](/platform/oz-web-app/) using the **New schedule** action.

For full scheduling documentation, see [Scheduled Agents](/platform/triggers/scheduled-agents/).

* * *

## Suggested Skills

The [Oz web app](/platform/oz-web-app/) displays suggested agents from the public [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. These are pre-built skills that demonstrate common use cases and can be used as starting points for your own workflows.

Suggested skills appear on the Agents page under the **Suggested** filter.

* * *

## Related resources

-   [Skills](/agents/capabilities/skills/) — How to create skills and skill file format
-   [Environments](/platform/environments/) — Configure repositories and runtime context for cloud agents
-   [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule
-   [Oz Web App](/platform/oz-web-app/) — Visual interface for managing cloud agents
-   [Oz CLI](/reference/cli/) — Command-line interface for running agents
-   [Oz API & SDK](/reference/api-and-sdk/) — Programmatic access to cloud agents