From b22130596559475264d528e255aafe0db8eda614 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 12 Aug 2026 17:15:59 +0000 Subject: [PATCH 1/2] docs: document WARP_SKILL_DIRS for cloud agent runs Documents the WARP_SKILL_DIRS environment variable that indexes extra skill directories at personal-skill precedence during cloud runs, and links to it from the skill locations section. Co-Authored-By: Warp Agent --- .../docs/agents/capabilities/skills.mdx | 4 ++++ .../docs/platform/skills-as-agents.mdx | 19 +++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/src/content/docs/agents/capabilities/skills.mdx b/src/content/docs/agents/capabilities/skills.mdx index 6c30edcd..8e3b6db0 100644 --- a/src/content/docs/agents/capabilities/skills.mdx +++ b/src/content/docs/agents/capabilities/skills.mdx @@ -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 diff --git a/src/content/docs/platform/skills-as-agents.mdx b/src/content/docs/platform/skills-as-agents.mdx index e82edecf..d7dfa186 100644 --- a/src/content/docs/platform/skills-as-agents.mdx +++ b/src/content/docs/platform/skills-as-agents.mdx @@ -54,6 +54,25 @@ 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. +* **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). +* **Invalid entries** - Paths that are missing or aren't directories are skipped with a warning in the run log, and an unset or empty value does nothing. + +This variable applies to cloud runs on the Warp Agent harness. [Third-party harnesses](/platform/harnesses/) such as Claude Code and Codex use their own skill systems and ignore it. + --- ## Running skill-based agents From 96b846f58e593a5bf4c9fd8b0fdfa77c15f22592 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Fri, 14 Aug 2026 17:20:47 +0000 Subject: [PATCH 2/2] docs: correct third-party harness support for WARP_SKILL_DIRS Claude Code and Codex cloud runs publish WARP_SKILL_DIRS skills into their own skill roots before launch, so these harnesses discover them natively rather than ignoring the variable. Also trims the redundant Invalid entries bullet per review feedback. Co-Authored-By: Warp --- src/content/docs/platform/skills-as-agents.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/platform/skills-as-agents.mdx b/src/content/docs/platform/skills-as-agents.mdx index d7dfa186..ce131df7 100644 --- a/src/content/docs/platform/skills-as-agents.mdx +++ b/src/content/docs/platform/skills-as-agents.mdx @@ -69,9 +69,8 @@ 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. * **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). -* **Invalid entries** - Paths that are missing or aren't directories are skipped with a warning in the run log, and an unset or empty value does nothing. -This variable applies to cloud runs on the Warp Agent harness. [Third-party harnesses](/platform/harnesses/) such as Claude Code and Codex use their own skill systems and ignore it. +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. ---