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

# Skills for agents

Create reusable instruction sets that teach agents specific tasks and share expertise across your team.

Skills are reusable instructions for tasks such as deployment, code review, or documentation checks. Store them with your code so teammates can review and reuse them.

## Key features

-   **Project and global scopes** - Keep project skills in a repository or global skills in your home directory
-   **Slash command invocation** - Ask for a task in natural language or invoke `/{skill-name}` with arguments
-   **Supporting files** - Include scripts, templates, and configuration alongside `SKILL.md`

## How Skills work

At the start of a [conversation](https://docs.warp.dev/agents/local-agents/interacting-with-agents/), the agent receives the names and descriptions of available skills. It loads a skill’s full instructions when the task calls for them.

Project discovery follows your working directory up to the Git repository root; skills from another project are not in scope. Use [Rules](https://docs.warp.dev/agents/capabilities/rules/) for persistent constraints and skills for task-specific instructions.

### Skill name conflicts

Same-name skills resolve differently by invocation:

-   **Natural language** - The agent sees all in-scope names, descriptions, and paths and chooses a skill.
-   **Slash commands** - The menu lists matches; choose by description.
-   **Background resolution** - Home-directory skills take priority, then project skills closer to the repository root.

### Example interactions

Ask “Check the docs for broken links” to let the agent choose a relevant skill, or invoke `/deploy` or `/add-feature-flag` directly.

### Identify skill sources in conversation data

The [Conversation API](https://docs.warp.dev/api) returns `read_skill` actions with these `input` fields:

| Input field | Skill source |
| --- | --- |
| `bundled_skill_id` | Warp-provided bundled reference. |
| `skill_path` | File-based or path-referenced bundled skill, including remote-host paths. |

To measure team-owned usage, exclude actions with `bundled_skill_id`, then count only paths under roots your team manages. A path alone does not prove ownership. See the [bundled ID catalog and availability limits](https://docs.warp.dev/factories/api-and-sdk/#skill-actions-in-conversation-data).

## Skill file format

Each skill is a Markdown file with YAML frontmatter: `name` identifies the skill, and `description` tells the agent when to use it.

### Basic structure

```markdown
---
name: your-skill-name
description: Brief description of what this skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for the agent.
You can use argument placeholders like $ARGUMENTS or $0 in the body (see [Skill arguments](#skill-arguments)).

## Examples
Show concrete examples of using this skill.
```

### Example skill file

An `add-feature-flag` skill can request the flag name and default, then update the repository’s configuration, helper, tests, and documentation.

## Skill arguments

Use argument placeholders to parameterize a skill’s instructions.

### Argument syntax

-   **`$ARGUMENTS`** - Full raw text after the skill name
-   **`$ARGUMENTS[N]`** - The Nth whitespace-separated argument, indexed from zero
-   **`$N`** - Shorthand for `$ARGUMENTS[N]`; `$0` is the first argument

### How argument substitution works

Text after the skill name is the argument string. Warp splits it on whitespace for indexed arguments and substitutes placeholders before sending the instructions to the agent. Without placeholders, it sends the extra text as a separate user message alongside the skill.

Note

If a placeholder references an argument index that wasn’t provided (e.g. `$2` when only two arguments were given), the placeholder is left as-is in the skill content.

### Example: Skill with arguments

For a skill named `explain-topic`, use this body:

```markdown
Explain $0 for an audience of $1 professionals.
Use a $2 tone.
Full request: $ARGUMENTS
```

Invoking this skill with:

```plaintext
/explain-topic bears engineering fun
```

Substitutes `bears`, `engineering`, and `fun` for `$0`, `$1`, and `$2`; `$ARGUMENTS` becomes `bears engineering fun`.

### Example: Skill without arguments

If `greet` contains only “Greet the user warmly in an Australian style,” `/greet say it in French` sends the skill followed by “say it in French” as a separate message.

## Skill locations

Choose project scope for shared repository workflows or home-directory scope for personal workflows across projects.

### Project skills

Store skills at the project root for repository-wide access, or in a subdirectory for work scoped to that directory.

Store them in any of these directories:

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

Each skill needs its own subdirectory containing `SKILL.md`. Reference supporting files in its instructions:

Warp scans all supported directory names, including when the repository uses several coding tools.

### Root directory skills (global)

Use the same supported directories under your home directory, such as `~/.agents/skills/` (recommended) or `~/.warp/skills/`. These skills are available across projects:

### Project vs Root directory skills

Use project skills for team deployments, migrations, and repository-specific checks. Use home-directory skills for personal Git workflows or cross-project automation.

### Cloud agents

[Cloud agents](https://docs.warp.dev/platform/) discover skills from repositories configured in their [environment](https://docs.warp.dev/factories/environments/). Add the repository containing your skill to the environment. For browsing and refreshing repository skills, see [Skills in the web app](https://docs.warp.dev/platform/oz-web-app/#skills).

### Extra directories for cloud runs

To load skills outside a repository, set `WARP_SKILL_DIRS` in the environment’s Docker image before startup:

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

-   **Directory layout** - Each entry names a parent directory whose direct children are skill folders containing `SKILL.md`. Missing or non-directory entries are skipped.
-   **Path resolution** - Separate entries with commas; surrounding whitespace and empty entries are ignored. A leading `~` expands to the home directory. Relative paths resolve against the run’s base working directory, not later directory changes.

The Warp Agent treats these as home-directory skills, in scope throughout the run. Repository skills with the same name remain separate; see [skill name conflicts](#skill-name-conflicts).

The Warp Agent reads these directories directly. Claude Code and Codex runs publish the skills into their native skill directories before launch. The first configured directory wins when two supplied folders have the same name. In a sandbox, conflicting existing entries are backed up. Outside a sandbox, existing entries remain untouched: a conflicting skill uses a `warp-` name prefix, or is skipped if that name is also occupied. See [agent harnesses](https://docs.warp.dev/factories/harnesses/) for runtime-specific configuration.

## Creating skills

### Step 1: Choose a location

Choose a [project or home-directory location](#skill-locations).

### Step 2: Create the directory structure

Create a subdirectory for your skill with a descriptive name:

```bash
mkdir -p .agents/skills/my-new-skill
```

### Step 3: Write the skill file

Create `SKILL.md` in your skill directory:

```bash
touch .agents/skills/my-new-skill/SKILL.md
```

### Step 4: Add content

Copy the [basic structure](#basic-structure) into `SKILL.md`. Set its name and description, then write the instructions, constraints, and expected results.

## Skills with supporting files

Keep scripts, templates, and configuration alongside `SKILL.md`:

Reference supporting files using relative paths in `SKILL.md`:

```plaintext
## Running the check

From the project root:

python3 .agents/skills/check-broken-links/check_links.py --internal-only
```

## Managing skills

### Viewing available skills

Ask “What skills do I have?” to list the in-scope project and home-directory skills.

### Editing skills

Use [`/open-skill`](https://docs.warp.dev/agents/capabilities/slash-commands/) to browse skills, inspect their directories, and open a skill in the editor.

### Best practices

Use clear descriptions, exact paths and commands, and concrete examples. Keep each skill focused, use names such as `run-migrations`, and version-control team skills.

## Pre-built skills

Copy or adapt examples from the public [warpdotdev/oz-skills collection](https://github.com/warpdotdev/oz-skills).

To browse suggested skills in the browser, see [Skills in the web app](https://docs.warp.dev/platform/oz-web-app/#skills).

## Suggested skills from Agent Memory

Promoting recurring patterns from [Agent Memory](https://docs.warp.dev/agents/agent-memory/) into reviewable skill drafts is in design as part of the research preview. See the Agent Memory page for a current status.

## Invoking skills with a prompt

Add context after the slash command, such as `/deploy push the latest changes to staging` or `/code-review focus on error handling`. See [skill arguments](#skill-arguments) for substitution behavior.

## Running agents from skills

Skills can be used with both local and [cloud agents](https://docs.warp.dev/platform/) to create reusable, automated workflows. When running an agent via the CLI, web app, or API, you can specify a skill to provide the base instructions for the agent.

### CLI

Use `--skill` with `oz agent run` for a local task or `oz agent run-cloud` for a cloud run. The skill supplies the base instructions; `--prompt` adds context for this run. See [Skills via the CLI](https://docs.warp.dev/agents/cli/oz-cli/skills/) for repository and path specifications and examples.

### Web app

Use the [Oz web app](https://docs.warp.dev/platform/oz-web-app/#running-a-skill) to select a skill, environment, and prompt from the browser.

### API and SDK

Set `config.skill_spec` when [creating a run from a skill](https://docs.warp.dev/factories/api-and-sdk/#running-a-skill). The Agent and run endpoints support standalone tasks; a factory is not required.

### Running skills on a schedule

Use a skill for recurring maintenance such as dependency upgrades, documentation checks, or issue triage. See [creating a skill-based schedule](https://docs.warp.dev/platform/triggers/scheduled-agents/#scheduling-a-skill) for the CLI example and [Scheduled Agents quickstart](https://docs.warp.dev/platform/triggers/scheduled-agents-quickstart/) for browser setup.

For factory-scoped instructions, see [factory skills](https://docs.warp.dev/factories/factory-skills/).

## Related pages

-   [Rules for agents](https://docs.warp.dev/agents/capabilities/rules/) - Set persistent guidelines and constraints
-   [Model Context Protocol (MCP)](https://docs.warp.dev/agents/capabilities/mcp/) - Connect tools and data sources
-   [Profiles & Permissions](https://docs.warp.dev/agents/capabilities/agent-profiles-permissions/) - Control permissions and autonomy
-   [Integrations quickstart](https://docs.warp.dev/platform/integrations/quickstart/) - Trigger cloud agents from team tools