Document user-home references in prompt files

[ntrogh]

Product change

• Source: Fix user home paths in prompt files vscode#333942
• Merged: 2026-09-02 UTC

Prompt syntax now resolves ~ and ~/ file references against the environment user home. The behavior is consistent for validation, link navigation, and referenced-instruction collection, including Markdown links and #file: references.

Why the docs need an update

The prompt file documentation currently explains only workspace-relative Markdown links. It does not describe home-relative references, leaving users without guidance for portable references to personal files.

Suggested documentation

• docs/agent-customization/prompt-files.md: document home-relative Markdown links and #file: references alongside relative workspace references.
• docs/agent-customization/custom-instructions.md, docs/agent-customization/custom-agents.md, and docs/agent-customization/agent-skills.md: keep any shared file-reference guidance consistent where the same prompt syntax applies.

Details to verify

• Both ~ and paths beginning with ~/ resolve against the environment user home.
• Use Unix-style / separators so prompt and skill files remain portable across operating systems.

Acceptance criteria

• The prompt file reference section distinguishes workspace-relative and home-relative paths and includes a valid home-relative example.
• The docs cover both Markdown link navigation and #file: references without implying that ~ is relative to the prompt file.
• Related customization pages do not give conflicting path guidance.