docs: document WARP_SKILL_DIRS for cloud agent runs - #506
Open
guyscherzer8 wants to merge 2 commits into
Open
Conversation
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 <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
hongyi-chen
marked this pull request as ready for review
August 12, 2026 17:48
Contributor
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
hongyi-chen
approved these changes
Aug 12, 2026
hongyi-chen
reviewed
Aug 12, 2026
| * **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. |
Collaborator
There was a problem hiding this comment.
we can remove this last point
hongyi-chen
reviewed
Aug 12, 2026
| 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. |
Collaborator
There was a problem hiding this comment.
not sure if this one is necessary
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR documents WARP_SKILL_DIRS for cloud agent runs and links the skill locations page to the new section. The new section is mostly aligned with the implementation, but it includes one factual contradiction about third-party harness support.
Concerns
- The docs say Claude Code and Codex ignore
WARP_SKILL_DIRS, but the implementation publishes those skill directories into each harness's native skill root before launch. - No security findings.
- No approved or repository spec context was available for spec-drift validation.
Verdict
Found: 1 critical, 0 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| * **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. |
Contributor
There was a problem hiding this comment.
🚨 [CRITICAL] This says third-party harnesses ignore WARP_SKILL_DIRS, but the implementation publishes these directories into Claude Code and Codex skill roots, so users would be told not to use a supported path.
Suggested change
| 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. Claude Code and Codex cloud runs publish these skills into each harness's own skill root before launch so those harnesses can discover them through their native skill systems. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Documents
WARP_SKILL_DIRS, the environment variable a cloud agent run reads to index extra skill directories at personal-skill precedence. It shipped in the 2026.08.07 release notes (as "SKILLS_DIRS") but had no docs coverage, and the release note used a different name than the code.platform/skills-as-agents.mdx— new "Extra skill directories in cloud runs" section covering the value format, directory layout,~and relative-path resolution against the run's working directory, home-tier precedence, invalid-entry handling, and the fact that third-party harnesses ignore it.agents/capabilities/skills.mdx— pointer from "Skill locations" to that section.Source
warp:crates/ai/src/skills/read_skills.rs(WARP_SKILL_DIRS,parse_skills_dirs_env,resolve_skills_dirs,read_skills_for_skills_dirs)warp:app/src/ai/agent_sdk/driver.rs(load_skills_dirs, called only forHarnessKind::Oz)Reviewers
Resolved from the warp
.github/STAKEHOLDERSfor the source files above: @bnavetta, @ianhodge, @warpdotdev/oss-maintainers. Reviewer assignment could not be applied automatically because the available token lacks theread:orgscope.Validation
npm run buildpasses; the missing_docs audit no longer reports this changelog item as unverified.Found by
The
missing_docsdrift-watch audit (changelog cross-check).Conversation: https://staging.warp.dev/conversation/1bda9ae7-44b1-43c5-bb7a-d22ccf8b6c16
Run: https://oz.staging.warp.dev/runs/019ff6ea-bc3c-7336-b1f5-9f1f5b89cd84
This PR was generated with Oz.