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

Reusable instructions - Define a task once and reuse its instructions across conversations
Project and global scopes - Keep team workflows in a repository or personal skills in your home directory
Automatic discovery - The agent sees available skill names and descriptions and loads instructions when relevant
Simple markdown format - Write each skill in a SKILL.md file with YAML frontmatter
Supporting files - Include scripts, templates, and configuration alongside the skill
Slash command invocation - Invoke /{skill-name} directly instead of asking the agent to choose a skill
Parameterized skills - Pass arguments to adapt a skill’s instructions to the current task

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

Describe the task in natural language to let the agent choose an available skill:

“Use the deploy skill to push to staging.”
“Check the docs for broken links.”
“Draft documentation for the new API endpoint based on this PR.”

If you know the skill name, 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

This example assumes a project with flags in config/feature_flags.yaml, helpers in src/utils/flags.ts, and flag documentation in docs/FEATURE_FLAGS.md. Adapt those paths to your repository.

---
name: add-feature-flag
description: Add a feature flag to the codebase with configuration, a helper, and documentation
---

# Add a feature flag

## Instructions
1. Ask the user for the feature flag name and default value.
2. Add the flag definition to `config/feature_flags.yaml`.
3. Create a helper function in `src/utils/flags.ts`.
4. Update `docs/FEATURE_FLAGS.md`.

## Configuration format
Use this shape for each flag, replacing the name, description, and owner:

```yaml
feature_name:
  default: false
  description: "What this flag controls"
  owner: "team-name"
```

## Examples
* "Add a feature flag for the new checkout flow."
* "Create a flag to enable dark mode for beta users."

For example, /add-feature-flag add a checkout flag, disabled by default invokes the skill and supplies context for the new flag. The agent follows the repository paths and format specified in the skill rather than inferring them.

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

This complete skill uses indexed arguments for the topic, audience, and tone:

---
name: explain-topic
description: Explain a topic for a specific audience in a given tone
---

# Explain a topic

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

Invoking this skill with:

/explain-topic bears engineering fun

Warp substitutes the arguments before sending these instructions to the agent:

Explain bears for an audience of engineering professionals.
Use a fun tone.
Full request: bears engineering fun

Example: Skill without arguments

This skill has no argument placeholders:

---
name: greet
description: Greet the user warmly in an Australian style
---

# Greet

Greet the user warmly in an Australian style.

Invoking /greet say it in French sends the skill instructions followed by “say it in French” as a separate user message. You can add context without changing the skill file, even when it has no placeholders.

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