Intro
Just to be clear,
I'm not a programmer, so I used Gemini to help me create the ISSUE:
Description
Custom agents defined in Markdown files are not being recognized or loaded by the system, despite following the official documentation and having a valid configuration. While built-in agents (e.g., @general) work perfectly, any custom agent invoked via @mention or the Task tool results in a generic Error or an Unknown agent type message.
Environment
- OS: Windows 11
- App Version: OpenCode Desktop v1.16.2
- Configuration: Agents stored in C:\Users<User>.config\opencode\agents\
Expected Behavior
The agent should be loaded, and the LLM should respond based on the custom system prompt defined in the .md file.
Actual Behavior
- The system returns a generic Error (via Task tool).
- Or it returns: Unknown agent type: designer is not a valid agent type.
Troubleshooting already performed
- Verified built-in agents: @general works perfectly, confirming that the LLM connection and the Task tool infrastructure are operational.
- Frontmatter Audit: Tested different combinations of mode (primary vs subagent), added required description fields, and tried multiple model IDs.
- Path Testing: Tried both absolute paths in opencode.jsonc and relative paths.
- File System: Recreated the agents directory and files to rule out file locks or encoding issues (UTF-8).
- App Restart: Fully closed and restarted the Desktop application.
Conclusion
Since built-in agents function normally but custom .md agents fail, there seems to be a regression or a bug in the agent loading mechanism specific to the Windows Desktop implementation.
Plugins
No response
OpenCode version
OpenCode Desktop v1.16.2
Steps to reproduce
1. Create a custom agent file (e.g., designer.md) in the global agents directory with valid YAML frontmatter:
(Start of YAML block)
description: UI/UX Designer
mode: subagent
model:
System prompt content...
(End of YAML block)
2. (Optional) Explicitly add the agent to opencode.jsonc:
(Start of JSON block)
"agents": {
"DESIGNER": "C:\Users\\.config\opencode\agents\designer.md"
}
(End of JSON block)
3. Try to invoke the agent in the chat using @designer.
Operating System
Windows 11
Intro
Just to be clear,
I'm not a programmer, so I used Gemini to help me create the ISSUE:
Description
Custom agents defined in Markdown files are not being recognized or loaded by the system, despite following the official documentation and having a valid configuration. While built-in agents (e.g.,
@general) work perfectly, any custom agent invoked via@mentionor the Task tool results in a genericErroror anUnknown agent typemessage.Environment
Expected Behavior
The agent should be loaded, and the LLM should respond based on the custom system prompt defined in the .md file.
Actual Behavior
Troubleshooting already performed
Conclusion
Since built-in agents function normally but custom .md agents fail, there seems to be a regression or a bug in the agent loading mechanism specific to the Windows Desktop implementation.
Plugins
No response
OpenCode version
OpenCode Desktop v1.16.2
Steps to reproduce
1. Create a custom agent file (e.g., designer.md) in the global agents directory with valid YAML frontmatter:
(Start of YAML block)
description: UI/UX Designer
mode: subagent
model:
System prompt content...
(End of YAML block)
2. (Optional) Explicitly add the agent to opencode.jsonc:
(Start of JSON block)
"agents": {
"DESIGNER": "C:\Users\\.config\opencode\agents\designer.md"
}
(End of JSON block)
3. Try to invoke the agent in the chat using @designer.
Operating System
Windows 11