Agents > Capabilities

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, 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 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 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.

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

---
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.

Example: Skill with arguments

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

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

Invoking this skill with:

/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:

Directoryyour-project/
- Directory.agents/
  - Directoryskills/
    Directoryadd-feature-flag/
    SKILL.md
    Directoryrun-migrations/
    SKILL.md
- Directory.claude/
  - Directoryskills/
    Directoryreview-code/
    SKILL.md
- Directory.github/
  - Directoryskills/
    Directorycreate-release/
    SKILL.md

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:

Directory~/.agents/
- Directoryskills/
  - Directorygit-workflow/
    SKILL.md
  - Directorycode-review/
    SKILL.md

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 discover skills from repositories configured in their environment. Add the repository containing your skill to the environment. For browsing and refreshing repository skills, see Skills in the web app.

Extra directories for cloud runs

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

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.

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 for runtime-specific configuration.

Creating skills

Step 1: Choose a location

Choose a project or home-directory location.

Step 2: Create the directory structure

Create a subdirectory for your skill with a descriptive name:

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

Step 3: Write the skill file

Create SKILL.md in your skill directory:

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

Step 4: Add content

Copy the 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:

Directory.agents/skills/
- Directorycheck-broken-links/
  - SKILL.md
  - check_links.py Supporting script
  - config.yaml Configuration file

Reference supporting files using relative paths in SKILL.md:

## 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 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.

To browse suggested skills in the browser, see Skills in the web app.

Suggested skills from Agent Memory

Promoting recurring patterns from 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 for substitution behavior.

Running agents from skills

Skills can be used with both local and cloud agents 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 for repository and path specifications and examples.

Web app

Use the Oz web app to select a skill, environment, and prompt from the browser.

API and SDK

Set config.skill_spec when creating a run from 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 for the CLI example and Scheduled Agents quickstart for browser setup.

For factory-scoped instructions, see factory skills.

Rules for agents - Set persistent guidelines and constraints
Model Context Protocol (MCP) - Connect tools and data sources
Profiles & Permissions - Control permissions and autonomy
Integrations quickstart - Trigger cloud agents from team tools