Repository navigation
Agent definition using frontmatter in markdown files, don't appear in agents list in oc? #3461
Description
Description
So I have spent some time trying to get agents restricted from running things they really shouldn't :)
Using the example here -> You can set permissions for specific bash commands.
I tried this in the md file with frontmatter, but it didn't appear in the list of agents, using tab to cycle through them, I only have plan,/build.
"permission": {
"bash": {
"git status": "allow",
"*": "ask"
}
}
So I took a step back and created a really basic markdown file with frontmatter, and it doesn't appear in the list of agents either;
> cat ~/.config/opencode/agent/test.md
---
description: Test agent for YAML frontmatter validation
mode: subagent
model: opencode/x-ai/grok-code-fast-1
temperature: 0.1
---
# Test Agent
This is a test agent to verify YAML frontmatter parsing.
## When invoked
Use this agent to test if YAML frontmatter configurations work in opencode.
## Process
1. Verify the agent appears in opencode agent list
2. Test basic functionality
3. Confirm frontmatter fields are recognized
### Testing Steps:
1. Create the file manually with the above content
2. Restart opencode
3. Check if test appears in the agent list
4. If it appears, the basic frontmatter works - then add the missing name: field to your existing agents
5. If it doesn't appear, YAML frontmatter is not supported in this opencode version
I just wondered what I might be missing?
Does oc support permission etc in frontmatter or not, as there don't appear to be any examples in the docs, only for straight json files.
Is frontmatter supported as I have it in the example, or not?
Thanks in advance
OpenCode version
0.15.18
Steps to reproduce
Add the markdown file as an agent in oc, and it should appear in the list of avilable agents, as non frontmatter markdown files do.
Screenshot and/or share link
No response
Operating System
nix
Terminal
fish
Activity
github-actions commentedon Oct 26, 2025
This issue might be a duplicate of existing issues. Please check:
Feel free to ignore if none of these address your specific case with frontmatter permissions configuration.
rekram1-node commentedon Oct 26, 2025
@amnnku if you look at this section: https://opencode.ai/docs/agents/#permissions
There is this example:
Did you see it?
You should be able to do:
amnnku commentedon Oct 26, 2025
Hi @rekram1-node yes I did see it thank you and have tailored it to exactly what I wanted, but it doesn't work for me.
So I went back to basics and the basic markdown file with frontmatter just doesn't appear in the list.
If I remove the frontmatter the agent appears with the name of the markdown file, as expected.
I should add, grepping the log shows nothing.
~/Developer/opencode 19:40:49> grep -a -i test.md /home/dev/.local/share/opencode/log/dev.log | tail -5I should also add I am using opencode-baseline, if that changes anything :)
rekram1-node commentedon Oct 26, 2025
@amnnku remove
mode: subagentand it will appear in your list, you can't run a subagent yourself they can only be delegated or @ referencedBut I see how this is confusing it should still show up in the list
amnnku commentedon Oct 26, 2025
Cool, thank you, that seems to be it, it loads now :), although it throws an error on the ModelNotFoundError, but goes away when the model defn is removed, so gets me going for now.
Some more reading it seems, but thanks for the quick reply, appreciated.
rekram1-node commentedon Oct 26, 2025
@amnnku the model not found error is easy to resolve, are you trying to use the opencode or openrouter grok code
Your model definition looks like the openrouter version (aside from opencode prefix)
opencode version is: opencode/grok-code
to see full list of models you have available run:
opencode models
amnnku commentedon Oct 26, 2025
Cools, that's helpful, thanks.
I was trying for opencode/grok-code 👍
Thanks for following up.
rekram1-node commentedon Oct 26, 2025
ofc!