Custom agent Markdown link does not load referenced .instructions.md file

## Summary

A custom `.agent.md` file contains a Markdown link to a `.instructions.md` file, but the referenced instructions are not added to the chat context when the custom agent is selected directly.

The same `.instructions.md` file loads successfully when:

1. it uses `applyTo: "**"`, or
2. the same Markdown reference is placed in a `.prompt.md` file.

The setting `"chat.includeReferencedInstructions": true` is enabled.

The issue was reproduced both in the original workspace and in a separate clean workspace containing only the minimal files required for reproduction.

This suggests that the problem is specific to resolving Markdown references originating from an active custom agent, rather than a general `.instructions.md` discovery or parsing problem.

## Environment

- VS Code: `1.137.0`
- OS: Windows 11 x64
- Setting enabled:

```json
"chat.includeReferencedInstructions": true
```

## Minimal reproduction

Create a new empty workspace with this structure:

```text
.github/
├── agents/
│ └── reference-test.agent.md
└── instructions/
└── reference-test.instructions.md
```

### 1. Create the custom agent

Create:

```text
.github/agents/reference-test.agent.md
```

with:

```md
---
name: Reference Test
description: Minimal test for referenced instruction loading.
---

Follow the [Reference Test Instructions](../instructions/reference-test.instructions.md).
```

### 2. Create the referenced instruction file

Create:

```text
.github/instructions/reference-test.instructions.md
```

with:

```md
---
name: Reference Test Instructions
description: Minimal instruction-reference test.
---

If the user sends exactly `PROBE_9C27`, respond exactly:

`AGENT_REFERENCE_INSTRUCTIONS_ACTIVE`
```

Do **not** add an `applyTo` property.

### 3. Enable referenced instructions

Ensure this setting is enabled:

```json
"chat.includeReferencedInstructions": true
```

### 4. Reload VS Code

Run:

```text
Developer: Reload Window
```

### 5. Execute the test

1. Start a new Chat.
2. Select the `Reference Test` custom agent directly.
3. Send:

```text
PROBE_9C27
```

## Expected behavior

The Markdown link inside `reference-test.agent.md` should cause the referenced `.instructions.md` file to be added to the request context.

The agent should respond exactly:

```text
AGENT_REFERENCE_INSTRUCTIONS_ACTIVE
```

The Custom Instructions diagnostics should also show the referenced instruction file, for example:

```text
Custom Instructions
context included: [1] reference-test.instructions.md
agents: [1] Reference Test
```

## Actual behavior

The custom agent itself is loaded, but the referenced `.instructions.md` file is not included.

The expected response:

```text
AGENT_REFERENCE_INSTRUCTIONS_ACTIVE
```

is not produced.

The diagnostics show the active custom agent but no referenced instruction:

```text
Custom Instructions
context included: [0]
agents: [1] Reference Test
```

This indicates that the custom agent is discovered correctly, but its Markdown reference to the `.instructions.md` file is not resolved into the request context.

---

## Control experiment 1 — `applyTo`

Add the following property to the frontmatter of `reference-test.instructions.md`:

```yaml
applyTo: "**"
```

Reload VS Code and repeat exactly the same probe.

### Result

The instruction file is now included:

```text
Custom Instructions
context included: [1] reference-test.instructions.md
```

and the probe succeeds:

```text
AGENT_REFERENCE_INSTRUCTIONS_ACTIVE
```

This confirms that:

- the `.instructions.md` file is valid;
- VS Code discovers the file;
- the file location is supported;
- the instruction itself works when it is actually loaded.

However, `applyTo: "**"` is not a suitable workaround for agent-specific instructions because it makes the instruction applicable workspace-wide and can affect unrelated chat sessions.

---

## Control experiment 2 — `.prompt.md` reference

Remove `applyTo: "**"` again.

Create:

```text
.github/prompts/reference-test.prompt.md
```

with:

```md
---
name: reference-test
description: Reference loading test.
agent: 'Reference Test'
---

Follow the [Reference Test Instructions](../instructions/reference-test.instructions.md).

PROBE_9C27
```

Invoke this prompt file.

### Result

The same referenced instruction is now included:

```text
Custom Instructions
context included: [1] reference-test.instructions.md
agents: [1] Reference Test
```

and the probe succeeds:

```text
AGENT_REFERENCE_INSTRUCTIONS_ACTIVE
```

This shows that the same Markdown reference and the same `.instructions.md` file work when the reference originates from a `.prompt.md` file.

---

## Reproduction matrix

| Configuration | Result |
|---|---|
| `.agent.md` → Markdown reference to `.instructions.md` | FAIL |
| `.instructions.md` with `applyTo: "**"` | PASS |
| `.prompt.md` → Markdown reference to the same `.instructions.md` | PASS |

The direct `.agent.md` reference failure was also reproduced in a separate clean workspace containing only the minimal custom agent and instruction file.

---

## Investigation performed

Several possible configuration causes were checked before concluding that this appears to be specific to the custom-agent reference-loading path.

### 1. Instruction file discovery was verified

The same `.instructions.md` file loads successfully with:

```yaml
applyTo: "**"
```

Therefore the file is discoverable by VS Code.

### 2. Instruction file parsing was verified

When the instruction file is actually included, the probe executes correctly.

Therefore the instruction content itself is valid.

### 3. Markdown path resolution was verified through `.prompt.md`

The same relative Markdown reference:

```md
[Reference Test Instructions](../instructions/reference-test.instructions.md)
```

works when used from a `.prompt.md` launcher.

Therefore the referenced file and relative path are valid.

### 4. `chat.includeReferencedInstructions` was verified

The setting is explicitly enabled:

```json
"chat.includeReferencedInstructions": true
```

Referenced instructions are successfully included from the `.prompt.md` case, confirming that referenced-instruction loading is active.

### 5. Workspace-specific configuration was ruled out

The failure was reproduced in a separate clean workspace containing only the minimal reproduction files.

This indicates that the behavior is not caused by the original project's configuration or file structure.

### 6. Stale custom-agent state was ruled out

`Developer: Reload Window` was used before validating the behavior.

The direct `.agent.md` reference still failed after reload.

### 7. A separate malformed Markdown/YAML issue was previously found and fixed

During the investigation, an unrelated escaping problem in an earlier instruction file was found and corrected.

After correcting the Markdown/YAML, `applyTo: "**"` worked correctly, while the direct `.agent.md` reference still failed.

Therefore malformed YAML/Markdown was a separate issue and does not explain the remaining direct-reference failure.

---

## Implementation investigation

The installed VS Code build was also inspected to understand why the three configurations above behave differently.

The observed implementation behavior appears consistent with the runtime results.

The custom agent body appears to be collected as agent/mode instructions.

Referenced-instruction traversal, however, appears to be seeded from prompt/instruction context entries that are already known to the instruction collector.

The custom agent's mode-instruction body does not appear to be used as a seed for that referenced-instruction traversal.

Conceptually, the failing path appears to behave like this:

```text
custom .agent.md
↓
custom agent body is loaded
↓
body becomes agent/mode instructions
↓
Markdown link exists inside the agent body
↓
agent body is not used as a seed for referenced-instruction traversal
↓
referenced .instructions.md is not loaded
```

The working `.prompt.md` path appears to behave differently:

```text
.prompt.md
↓
prompt/instruction context entry
↓
referenced-instruction traversal
↓
Markdown link is resolved
↓
.instructions.md is loaded
```

This implementation difference would explain all three experimental results:

```text
.agent.md -> .instructions.md reference FAIL
.instructions.md with applyTo: "**" PASS
.prompt.md -> .instructions.md reference PASS
```

It would also explain why:

```json
"chat.includeReferencedInstructions": true
```

works for the `.prompt.md` case but does not make the direct custom-agent reference work.

### Suspected root cause

The most likely root cause is therefore that Markdown references contained in the active custom agent body are not participating in the same referenced-instruction traversal that processes references originating from prompt/instruction context files.

In other words, the custom agent itself is loaded correctly, but references contained inside its body appear not to become traversal inputs for referenced instruction resolution.

This is an implementation hypothesis based on:

- the minimal reproduction;
- the clean-workspace reproduction;
- the two successful control experiments;
- runtime Custom Instructions diagnostics;
- inspection of the installed implementation.

I am not treating this as a confirmed root cause until it is verified by the VS Code maintainers.

---

## Current workaround

A scoped `.prompt.md` file can be used as a launcher that:

1. selects the custom agent, and
2. references the external `.instructions.md` file.

Conceptually:

```text
.prompt.md
├── selects custom agent
└── references .instructions.md
```

This successfully loads both the custom agent and its external instructions without using workspace-wide:

```yaml
applyTo: "**"
```

The workaround is currently reliable, but it introduces an additional launcher layer that should not be necessary if direct Markdown references from custom agents work as expected.

---

## Why this matters

External `.instructions.md` files are useful for keeping large custom-agent policies modular, reusable, maintainable, and scoped to a specific agent.

The current alternatives have significant drawbacks:

- `applyTo: "**"` causes agent-specific instructions to affect unrelated requests;
- copying the complete policy directly into `.agent.md` removes modularity and reuse;
- using an additional `.prompt.md` launcher works, but adds an extra execution layer solely to make the referenced instruction load.

A direct:

```text
.agent.md
↓
.instructions.md
```

Markdown-reference workflow is therefore important for maintaining isolated and reusable custom-agent configurations.