> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt > Use this file to discover all available pages before exploring further. # 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.md` | `.agents/skills//SKILL.md` | | **Warp** | Warp managed skills directory | `.warp/skills//SKILL.md` | | **Claude** | `~/.claude/skills//SKILL.md` | `.claude/skills//SKILL.md` | | **Codex** | `~/.codex/skills//SKILL.md` | `.codex/skills//SKILL.md` | | **Cursor** | `~/.cursor/skills//SKILL.md` | `.cursor/skills//SKILL.md` | | **Gemini** | `~/.gemini/skills//SKILL.md` | `.gemini/skills//SKILL.md` | | **Copilot** | `~/.copilot/skills//SKILL.md` | `.copilot/skills//SKILL.md` | | **GitHub** | `~/.github/skills//SKILL.md` | `.github/skills//SKILL.md` | | **OpenCode** | `~/.opencode/skills//SKILL.md` | `.opencode/skills//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. ```text SKILL.md example theme={null} --- 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 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/`). The skill's directory name becomes its identifier — the name you use to invoke it. ```bash theme={null} mkdir -p .warp/skills/no-console-logs touch .warp/skills/no-console-logs/SKILL.md ``` Open `SKILL.md` and write the instructions you want the agent to follow. ```markdown theme={null} --- 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. ``` 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. ```bash theme={null} 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). ```bash theme={null} # 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. ```markdown theme={null} --- 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: ```bash theme={null} 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 Constrain agent behavior at the project level with AI rules. Pair skills with MCP tools to give the agent specialized capabilities. Use skills interactively in your local terminal session. Run skill-powered agents headlessly in the cloud.