From 9cacab110ce426aec288e5ff7428ae2926e0e134 Mon Sep 17 00:00:00 2001 From: Shaurya Saria Date: Mon, 24 Aug 2026 19:02:44 +0530 Subject: [PATCH] docs(contributing): document artifact path portability Relates to #2662 --- docs/contributing/custom-agents.md | 22 ++++++++++++++++++++++ docs/contributing/prompts.md | 24 ++++++++++++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/docs/contributing/custom-agents.md b/docs/contributing/custom-agents.md index 3ee1bb2ff0..0cdf5461bd 100644 --- a/docs/contributing/custom-agents.md +++ b/docs/contributing/custom-agents.md @@ -162,6 +162,28 @@ Agent files MUST: 3. Begin content directly after frontmatter 4. End with single newline character +## Path Portability + +Agent packages can be loaded from the repository or from a distributed +extension, so references to other artifacts must remain valid in either +context. + +* Refer to a skill, agent, subagent, or prompt by the `name:` value from its + frontmatter wrapped in backticks, not by a hard-coded path. +* Refer to an instruction file by its full `.instructions.md` filename + and name the specific section when only part applies. The filename is the + stable reference; hosts attach instructions through `applyTo` or semantic + matching. +* Refer to a prompt whose frontmatter omits `name:` by its + `.prompt.md` filename, because the host derives the slash command from + the filename stem. +* Reserve file paths for caller-defined tracking or evidence locations, + frontmatter wiring such as `agents:`, `agent:`, and `applyTo`, and resources + that belong to the artifact being authored. +* Never hard-code a skill's `.github/skills///SKILL.md` path or + a path into another skill's directory. Name the skill and let progressive + disclosure resolve it across repository, extension, and plugin distributions. + ## Frontmatter Requirements ### Required Fields diff --git a/docs/contributing/prompts.md b/docs/contributing/prompts.md index a64cf87e5c..55af9cf54e 100644 --- a/docs/contributing/prompts.md +++ b/docs/contributing/prompts.md @@ -59,6 +59,30 @@ Prompt files MUST: 3. Begin content directly after frontmatter 4. End with single newline character +## Path Portability + +Prompt packages can be loaded from the repository or from a distributed +extension, so references to other artifacts must remain valid in either +context. + +* Refer to a skill, agent, subagent, or prompt by the `name:` value from its + frontmatter wrapped in backticks, not by a hard-coded path. +* Refer to an instruction file by its full `.instructions.md` filename + and name the specific section when only part applies. The filename is the + stable reference; hosts attach instructions through `applyTo` or semantic + matching. +* Refer to a prompt whose frontmatter omits `name:` by its + `.prompt.md` filename, because the host derives the slash command from + the filename stem. +* Reserve file paths for caller-defined tracking or evidence locations, + frontmatter wiring such as `agents:`, `agent:`, and `applyTo`, and resources + that belong to the artifact being authored. +* Never hard-code a skill's `.github/skills///SKILL.md` path or + a path into another skill's directory. Name the skill and let progressive + disclosure resolve it across repository, extension, and plugin distributions. +* Use `#file:` only when the prompt must include another file's full contents; + otherwise, name the artifact or use a path relative to its own resources. + ## Frontmatter Requirements ### Required Fields