Skip to content

docs: document WARP_SKILL_DIRS for cloud agent runs #506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hongyi-chen merged 4 commits into from
Aug 14, 2026
+22 −0
Merged

docs: document WARP_SKILL_DIRS for cloud agent runs #506

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b221305
docs: document WARP_SKILL_DIRS for cloud agent runs
hongyi-chen Aug 12, 2026
9e8df72
Merge branch 'main' into docs/warp-skill-dirs-cloud-runs
hongyi-chen Aug 12, 2026
96b846f
docs: correct third-party harness support for WARP_SKILL_DIRS
warp-agent-staging[bot] Aug 14, 2026
3bcf192
Merge branch 'main' into docs/warp-skill-dirs-cloud-runs
hongyi-chen Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions src/content/docs/agents/capabilities/skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -292,6 +292,10 @@ Understanding when to use each level:
* Cross-project automation (git workflows, documentation templates)
* Professional standards you apply everywhere

### Extra directories for cloud runs

[Cloud agents](/platform/) discover skills from the repositories in their [environment](/platform/environments/). To index skills that live outside those repositories — for example, skills baked into a custom Docker image — set the `WARP_SKILL_DIRS` environment variable. See [extra skill directories in cloud runs](/platform/skills-as-agents/#extra-skill-directories-in-cloud-runs).

## Creating skills

### Step 1: Choose a location
Expand Down
18 changes: 18 additions & 0 deletions src/content/docs/platform/skills-as-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,24 @@ For cloud agent runs (`oz agent run-cloud`), skills are discovered from reposito
You can also list available skills programmatically using the `GET /agent` endpoint. See the [Oz API](/reference/api-and-sdk/) reference for details.
:::

### Extra skill directories in cloud runs

Skills that don't live in a cloned repository's standard skill directories can still be indexed. Set the `WARP_SKILL_DIRS` environment variable to a comma-separated list of skill directories, and a cloud run picks them up alongside the skills it discovers from your repositories. This is useful for skills baked into a custom Docker image, mounted from shared storage, or installed by a setup step outside a repo.

Set the variable in the environment's Docker image so it's present when the agent starts:

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

How the value is interpreted:

* **Directory layout** - Each entry is a skills directory whose direct children are skill folders containing a `SKILL.md`, the same layout as `.agents/skills/`. Point the variable at the parent directory, not at an individual skill folder.
* **Path resolution** - A leading `~` expands to the home directory. Relative entries resolve against the run's working directory rather than the agent process's current directory, so they stay stable even when setup steps change directories.

@hongyi-chen hongyi-chen Aug 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure if this one is necessary

@warp-agent-staging warp-agent-staging Bot Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kept this one — checked skill_manager.rs (add_skills_dirs_skills) and it's real, distinct behavior: WARP_SKILL_DIRS skills register at SkillScope::Home precedence, so they're always in scope for the run regardless of the current working directory, unlike repo skills which only apply while the agent is working in that repo. A same-named repo skill isn't shadowed either — both stay addressable, which is exactly the case the linked skill-name-conflicts section covers. Without this bullet a reader has no way to know WARP_SKILL_DIRS skills behave like personal skills rather than repo skills, so I think it earns its place. Let me know if you'd rather see it trimmed further or reworded.

* **Precedence** - Skills loaded this way are treated as personal (home) skills, so they stay in scope for the whole run regardless of which directory the agent is working in. Repository skills of the same name still appear separately, as described in [skill name conflicts](/agents/capabilities/skills/#skill-name-conflicts).

The Warp Agent harness reads `WARP_SKILL_DIRS` directly. For [third-party harnesses](/platform/harnesses/) such as Claude Code and Codex, a cloud run publishes each of these skills into that harness's own skill root before launch, so the harness discovers them through its native skill system.

---

## Running skill-based agents
Expand Down
Loading