> 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](/agent-platform/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](/agent-platform/cloud-agents/environments/).

**Discovery workflow:**

1.  **Create a skill** in your repository (see [Creating skills](/agent-platform/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.

* * *

## Running skill-based agents

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

### Oz web app

The [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev) provides a visual interface for running skill-based agents. 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](/agent-platform/cloud-agents/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](/agent-platform/cloud-agents/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](/agent-platform/cloud-agents/oz-web-app/) using the **New schedule** action.

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

* * *

## Suggested Skills

The [Oz web app](/agent-platform/cloud-agents/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](/agent-platform/capabilities/skills/) — How to create skills and skill file format
-   [Environments](/agent-platform/cloud-agents/environments/) — Configure repositories and runtime context for cloud agents
-   [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) — Run agents automatically on a cron schedule
-   [Oz Web App](/agent-platform/cloud-agents/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