Skills: reusable prompts for AI agents

Skills are Markdown instruction files that customize Warp’s AI agent. Create project or home-scoped skills and invoke them by name with oz agent run.

A Skill is a Markdown file that contains instructions for Warp’s AI agent. When you apply a skill to an agent run, those instructions are prepended to the agent’s system prompt, shaping how it thinks, what it focuses on, and how it formats its responses. Skills are a lightweight, version-controllable way to capture team conventions, project-specific workflows, or expert-level prompting patterns — and share them across agents and teammates.

Where Warp loads skills from

Warp scans a set of well-known directories for skills, both in your home directory (available in every project) and in your repository root (scoped to that project). Skills are stored as SKILL.md files inside named subdirectories.

The full set of supported locations, in precedence order (highest first):

Provider	Home directory path	Project directory path
Agents	~/.agents/skills/<skill-name>/SKILL.md	.agents/skills/<skill-name>/SKILL.md
Warp	Warp managed skills directory	.warp/skills/<skill-name>/SKILL.md
Claude	~/.claude/skills/<skill-name>/SKILL.md	.claude/skills/<skill-name>/SKILL.md
Codex	~/.codex/skills/<skill-name>/SKILL.md	.codex/skills/<skill-name>/SKILL.md
Cursor	~/.cursor/skills/<skill-name>/SKILL.md	.cursor/skills/<skill-name>/SKILL.md
Gemini	~/.gemini/skills/<skill-name>/SKILL.md	.gemini/skills/<skill-name>/SKILL.md
Copilot	~/.copilot/skills/<skill-name>/SKILL.md	.copilot/skills/<skill-name>/SKILL.md
GitHub	~/.github/skills/<skill-name>/SKILL.md	.github/skills/<skill-name>/SKILL.md
OpenCode	~/.opencode/skills/<skill-name>/SKILL.md	.opencode/skills/<skill-name>/SKILL.md

If the same skill content appears in multiple locations (for example, when a package manager symlinks skills across providers), Warp deduplicates them and keeps the copy from the highest-priority provider.

Commit project-scoped skills to your repository so every contributor automatically gets the same agent behavior when working in that project.

Anatomy of a SKILL.md file

A skill file is a Markdown document with an optional YAML front matter block at the top.

SKILL.md example

---
name: "conventional-commits"
description: "Write all commit messages using the Conventional Commits specification."
---

Always format commit messages as:

  type(scope): subject

Where type is one of: feat, fix, docs, style, refactor, perf, test, chore.
The subject must be lowercase and must not end with a period.

If the change is a breaking change, append ! after the type and add a BREAKING CHANGE: footer.

Front matter field	Required	Description
name	No	Human-readable name for the skill. Falls back to the directory name if omitted.
description	No	Short description shown in the skills list. Falls back to the first paragraph of the file body.

The body of the file is sent verbatim to the agent as part of its system prompt. Write it as you would write a prompt: clear, specific, and in the imperative.

Creating a custom skill

1. Choose a location

   Decide whether the skill applies to a specific project (put it in .agents/skills/ or .warp/skills/ at your repo root) or to all your projects (put it in ~/.agents/skills/ or ~/.warp/skills/).

2. Create the skill directory and file

   The skill’s directory name becomes its identifier — the name you use to invoke it.

   mkdir -p .warp/skills/no-console-logs
   touch .warp/skills/no-console-logs/SKILL.md
   
3. Write the instructions

   Open SKILL.md and write the instructions you want the agent to follow.

   ---
   name: "no-console-logs"
   description: "Remove all console.log statements before committing."
   ---
   
   Before completing any task that involves JavaScript or TypeScript files:
   1. Search for any `console.log`, `console.warn`, and `console.debug` calls in the files you modified.
   2. Remove them unless they are inside a file explicitly named `logger.ts` or similar.
   3. Mention in your summary how many console statements you removed.
   
4. Verify the skill is detected

   Run oz agent list to confirm Warp has picked up your new skill. Skills associated with your repositories and environments will appear in the output.

   oz agent list
   

Using skills with oz agent run

Pass the --skill flag to oz agent run to apply a skill to a cloud agent run. The skill name is the directory name (or the name field in front matter if set).

# Apply a single skill
oz agent run --skill conventional-commits "Commit the staged changes"

# Apply multiple skills
oz agent run --skill conventional-commits --skill no-console-logs "Fix the auth bug and commit"

# Qualify the skill name with a repo path for unambiguous resolution
oz agent run --skill my-org/my-repo:conventional-commits "..."

Skill arguments

Skills support argument substitution. Use $ARGUMENTS in your skill body to insert the agent’s prompt verbatim, or use positional placeholders $1, $2, etc. for structured argument passing.

---
name: "fix-issue"
description: "Triage and fix a GitHub issue by number."
---

Look up GitHub issue #$1 using the GitHub MCP server.
Read the issue description and any linked code.
Implement a fix, write a test, and open a draft PR with the title "fix: $ARGUMENTS".

Invoke it with:

oz agent run --skill fix-issue 1234

The agent receives the skill body with $1 replaced by 1234 and $ARGUMENTS replaced by the full prompt string 1234.

Bundled skills

Warp ships a set of built-in skills that are always available. These cover common workflows like fetching PR review comments (PRCommentsSkill) and are activated automatically when their prerequisites are met (for example, when a specific MCP server is running). Bundled skills are read-only and cannot be modified, but you can override them by creating a project-scoped skill with the same name.

Next steps

Rules

Constrain agent behavior at the project level with AI rules.

MCP servers

Pair skills with MCP tools to give the agent specialized capabilities.

Agent Mode

Use skills interactively in your local terminal session.

Cloud agents

Run skill-powered agents headlessly in the cloud.