How to reference other mds in the md of Subagents by using @?

I think this feature in Claude Code is not well implemented

For example

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on @docs/Development-Guide.md

Provide constructive feedback without making direct changes.

This issue might be a duplicate of existing issues. Please check:

Automatically load @ referenced files in AGENTS.md into context #2225: Automatically load @ referenced files in AGENTS.md into context - discusses the same @ reference functionality for markdown files that OpenCode currently doesn't support but should
The Manual Instructions in AGENTS.md seems to only work for relative referecnes in the current project #1490: The Manual Instructions in AGENTS.md seems to only work for relative references in the current project - mentions issues with @ file references not working as expected relative to the file they're referenced from

Feel free to ignore if none of these address your specific case.

Not AGENTS.md / CLAUDE.md, Claude Code currently cannot implement referencing other md files with @ in Subagent. Is there any hope for opencode to achieve this?

@Cyberbolt

@Cyberbolt yeah I think we want all our md parsing to be consistent so currently we only read and inject files from an "@" for the commands but we want to do it for AGENTS.md and maybe agent definitions too that makes sense

@Cyberbolt yeah I think we want all our md parsing to be consistent so currently we only read and inject files from an "@" for the commands but we want to do it for AGENTS.md and agent definitions too that makes sense

Is my understanding correct? Currently, @ is useful for AGENTS.md and commands, but not for Subagents. @ is included in the form of files in AGENTS.md and commands, and the LLM reads them when needed.

Yeah currently we only resolve the @ reference for commands but we should do it for the other things too

@rekram1-node

@rekram1-node I see this issue was raised on August 25th, and currently opencode still does not support referencing via @ in AGENTS.md and Subagents. I think this is a very practical feature. May I ask how much engineering effort would be required to add it, or would you accept a PR?

Yeah currently we only resolve the @ reference for commands but we should do it for the other things too

Won't that behavior break the pattern/use case documented here, where files are only read when the context indicates that is appropriate. In this case when I am dealing with Rust code the @docs/typescript-guidelines.md will not be read:

https://opencode.ai/docs/rules/#manual-instructions-in-agentsmd

How to reference other mds in the md of Subagents by using @? #2965

@Cyberbolt

That documentation was added solely because we don't currently resolve the @ references. We will soon tho.

In regards to @Cyberbolt, there are a few small things I discussed w/ dax that I wanna include so I will probably do that this weekend / Monday. If you really want to you can start one and then I will do commits to it afterwards if needed.

Note that we wanna wanna do @ resolves for:

AGENTS.md
commands (already supported, it also resolves @agent references but the other 2 probably shouldn't)
agent definitions

We have a config markdown parser namespace

We also support the !`...` notations for commands, potentially should support those for others as well.

That documentation was added solely because we don't currently resolve the @ references.

Ack, and the current behavior is desirable (as outlined).
Will you consider placing the new (or old) behavior behind a config variable?
Say import_at? that lives in the md file, and can also be set via global and local config files?

We could make it configurable, would it not make sense ot just remove those @ prefixes if they link to large files? The idea behind resolving them was to be consistent with both other tools (claude code, codex, etc) and commands.

We could make it configurable ...

Thanks for considering this possibility.

That would be great. The current behavior is desirable in orchestration workflow scenarios.

... would it not make sense ot just remove those @ prefixes if they link to large files?

Not really. These (Agent, Subagent, Command) files are categorically distinct from project/other files, so the @ abstraction is useful in preserving that distinction. And the config variable allows use cases that otherwise are either not possible or are hacky.

The idea behind resolving them was to be consistent with both other tools (claude code, codex, etc) and commands.

Agreed, familiarity for legacy users migrating is important. If this is a core long-term goal of the project, I suggest adding a compat_claude, compat_codex, etc., config variables and collecting, and setting, the various related variables behind that.

I'd also argue against forcing (no config variable) the behaviors of these abstractions (Agent, Command) to be the same. Generally the point of introducing an abstraction is to solve a problem. Forcing the abstractions to be clones defeats that purpose.
Naturally adding the import_at config variable to Commands improves the flexibility of that abstraction, and users whose use case is not thwarted by redundant/identical abstractions will be unimpeded.

Note for the team – I’m not sure whether this will actually work with our current tooling, but I wanted to share an idea that feels intuitive.

We could reference auxiliary markdown files using the @ prefix, e.g. @AGENTS_BROWSER_TESTER.md for a file at the project root or @subfolder/AGENTS_BROWSER_TESTER.md for one inside a subdirectory. Some of these AGENTS_*.md files also reference other AGENTS_*.md files in the same way, creating nested includes.

Just passing this along for consideration-

@taqtiqa-mark

@taqtiqa-mark I think the team wants almost everything to be customizable generally, but I just wanna understand your case better

Not really. These (Agent, Subagent, Command) files are categorically distinct from project/other files, so the @ abstraction is useful in preserving that distinction. And the config variable allows use cases that otherwise are either not possible or are hacky.

When would you want to @ reference a file otherwise? Like what does the @ do for you in any other circumstance?

Ofc if you do @email or something that doesn't exist then it would remain the same, but if you @ reference files in a prompt, shouldn't the behavior be consistent?

When would you want to @ reference a file otherwise?

I am not sure that I would.
IIUC, @ indicates file location in the config folder hierarchy - the abstraction I referenced. So @ indicates something located in a global, local, OPENCODE_CONFIG folder.
If you meant: what context other than Agent/Subagent files would I expect @ point to a file in the config folder hierarchy? Then I would expect that to be true in Agent, Subagent, Rules, Command and Tool files as well as instruction files. With the convention that *.md files can have yaml front matter setting import_at, and otherwise the default set in the config file chain applies when using *.txt, etc., files. So @email, first looks for $OPENSOURCE_CONFIG/<context>/email.md (possibly setting import_at) then $OPENSOURCE_CONFIG/<context>/email (not able to set import_at, but using the setting from $OPENSOURCE_CONFIG/opencode.jsonc ). Where <context> is agents, commands, tools or rules.

Like what does the @ do for you in any other circumstance?

In all circumstances (Rules, Agents, Commands, Tools) I'd expect/hope the @ does the same thing (subject to the variable setting of import_at)

.... if you @ reference files in a prompt, shouldn't the behavior be consistent?

Yes it should be consistent within the context (Rules, Commands, Tools, Agents/Subagents): Files in the config hierarchy.

The `folder/file/location.conv` should be understood to be referring to files in project hierarchy. Here, naturally, `./.../.../files` does not mean import this file automatically, and immediately. But if you did want to be consistent then adding import_backticks would seem natural?

Apologies if that is not clear. On reflection I should have used AI to generate some Gherkin feature files :) ... I may still do.

for the @ thing we only resolve it if you have a file or agent that it references, otherwise it stays as is so I wouldnt say u need to take extra care not to use and you would rarely ever need to escape it

as for @@, why introduce a new standard? almost every coding agent supports @ syntax for this type of stuff making it @@ would break workflows no?

for the @ thing we only resolve it if you have a file or agent that it references,

Correct, and there is a default build agent in opencode, so the user will find that opencode build agent is invoked instead of the summary being sent to the build in their social app.

as for @@, why introduce a new standard?

Because the social media space conventions adopted @user long ago. Agents are the interloper. No?
Also it is very early in the AI-Agent use case to insist that conventions are set in stone?

almost every coding agent supports @ syntax for this type of stuff making it @@ would break workflows no?

Possibly, but the change is trivial to make, and users will not need to tie themselves in knots trying to reconcile two different, but overlapping, domains insisting on adopting the same convention for incompatible use cases.

as for @@, why introduce a new standard?

Actually, maybe this is where your earlier idea you canvassed is relevant, by making this configurable: import_prefix: @@ would be useful?
This way if some other project adopt a different convention the users can just redefine the prefix?

hmm perhaps

Working on integrating my first agent/subagent/command/rules stack, so apologies for the evolving and incomplete understanding/requirements....

I think that both the @ and @@ are the most ergonomic.

@: Adapts the "socials"convention. For addressing agents/subagents. Examples:
- @ide set up a rust project for mobile and web app.: Reads and executes the $OPENCODE_CONFIG/agents/ide.md
- @ide/ticket analyze 'README.md': Reads and executes the $OPENCODE_CONFIG/agents/ide/ticket.md where README.md is in the project root.
@@: Convention to import file (current proposed @ behavior). Example:
- CRITICAL: When you encounter a file reference (e.g., @@rules/general.md), use your Read tool to load it on a need-to-know basis.

Thoughts?

We will see, Idk though I think we want things to stay consistent so for file references they will almost certainly remain as just @. Consistent with existing behavior and other popular tools

for file references they will almost certainly remain as just @. Consistent with existing behavior and other popular tools

How do we disambiguate: @ide set up a rust project for mobile and web app. So that it does not just insert the contents of agents/ide.md before set up a rust project for mobile and web app.?

because that would require you to write @agents/ide.md

but i see what u mean there could be some cases and then the question becomes what takes preference

Thanks again for engaging in this.

but i see what u mean there could be some cases and then the question becomes what takes preference

I think the difficulty arises when you want the dev to retain control of what the behavior is, and at the same time make all behaviors consistent and intuitive.

Overloading @ with different behaviors depending on the content of the suffix feels wrong - but that is subjective taste.

More objectively how do you allow developers control over importing without creating idisyncratic behavior.

E.G. import_at: false (current behavior) means @ide do this in acted on but @agents/ide.md is not acted on.

Never mind that the action associated with @ is wildly different: Agent execution vs file read.

If you do insist on overloading @ with different behaviors (agent execution and file reading), would you consider adding the config variable execute_at: true, false, ask ?

@ide

E.G. import_at: false (current behavior) means @ide do this in acted on but @agents/ide.md is not acted on.

But in a command currently, both are acted on

config variable execute_at: true, false, ask ?

I think making things configurable makes sense, but the var name may need some work :)

@ide

E.G. import_at: false (current behavior) means @ide do this in acted on but @agents/ide.md is not acted on.

But in a command currently, both are acted on

Hmm, hadn't stubbed my toes on that idiosyncrasy yet. But will try to bear that in mind.

At least having these config options would make the inconsistent behavior explicit:
In Agents:

import_at: false
execute_at: true

In Commands:

import_at: true
execute_at: true

... but the var name may need some work :)

Yup, apparently one of the two difficult problems in computer science.

To clarify a distinction between @ and /add (proposed) that arose in #1990:

In this context; I believe the following should be respected with unambiguous syntax for each:

there are two sources of data: Config hierarchy, Project hierarchy.
there are two destinations of data: Prompt text, Context text.

This means that @file and /add file should never result in the same file being "imported" - respecting 1.
Also @<anything> should never be placed in the session/LLM context "buffer".
Likewise /add <anything> should never be placed in the session/LLM prompt "buffer".

The debate about @ and @@ concern the Prompt "buffer" content:

@: Submitting a prompt to the LLM, vs
@@: Expanding the content of the prompt before submission via the LLM's API

In the spirit of calling out excellent engineering and design....

I've found that the Pi Coding Agent is more robust and, for me has none of the issues that I've encountered in OC, or has an elegant way to resolve them.... I'm dropping out of OC issues:

To stay organized issues are automatically closed after 90 days of no activity. If the issue is still relevant please open a new one.

Navigation Menu

Repository navigation

How to reference other mds in the md of Subagents by using @? #2965

5 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

How to reference other mds in the md of Subagents by using @? #2965

Description

Activity

github-actions commented on Oct 4, 2025

Cyberbolt commented on Oct 4, 2025

rekram1-node commented on Oct 4, 2025

Cyberbolt commented on Oct 4, 2025

rekram1-node commented on Oct 4, 2025

Cyberbolt commented on Oct 4, 2025

taqtiqa-mark commented on Oct 8, 2025

rekram1-node commented on Oct 8, 2025

taqtiqa-mark commented on Oct 8, 2025

rekram1-node commented on Oct 8, 2025

taqtiqa-mark commented on Oct 8, 2025

webboty commented on Oct 8, 2025

rekram1-node commented on Oct 8, 2025

taqtiqa-mark commented on Oct 9, 2025

5 remaining items

rekram1-node commented on Oct 9, 2025

taqtiqa-mark commented on Oct 10, 2025

taqtiqa-mark commented on Oct 10, 2025

rekram1-node commented on Oct 10, 2025

taqtiqa-mark commented on Oct 11, 2025

rekram1-node commented on Oct 11, 2025

taqtiqa-mark commented on Oct 11, 2025

rekram1-node commented on Oct 11, 2025

taqtiqa-mark commented on Oct 11, 2025

rekram1-node commented on Oct 11, 2025

taqtiqa-mark commented on Oct 11, 2025

taqtiqa-mark commented on Oct 14, 2025

taqtiqa-mark commented on Feb 6, 2026

github-actions commented on Apr 7, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions