Frontmatter support

[jsit]

Supporting frontmatter in an AGENTS.md file will allow for more fine-tuned application and UI implementation enhancements.

---
description: RPC Service boilerplate
globs: ["**/*.go", "**/*.proto"]
alwaysApply: false
---

An AGENTS.md file (or other files inside a directory, see #9) will be added to the chat context only when the conditions in its metadata are met.

description

Can be used for display in a UI when users are viewing rules or disabling/enabling them manually.

alwaysApply

• true: This file gets automatically added to context whenever files matching globs are in context
• false: This file appears in a menu/list for manual selection
• Default: true

globs

File patterns that trigger this rules file when matching files are added to context, and alwaysApply is true.

• Default: **/*

Prior art

• Cursor's rules frontmatter: https://docs.cursor.com/en/context/rules#rule-anatomy
• VSCode's instructions frontmatter: https://code.visualstudio.com/docs/copilot/copilot-customization?wt.md_id=AZ-MVP-5004796#_instructions-file-structure
• JetBrains' Rule Types: https://www.jetbrains.com/help/ai-assistant/configure-project-rules.html

[yordis]

The Cursor specification around the topic is quite frustrating to use, primarily because the discrimination union of the Rule Type are based on the combination of the values instead of being just a field, eg:

kind: always | auto | requested | manual

That would drive the correctness of the payload, I ended up having to create a complex prompting to correct the LLMs in such trivial matter because the combination of things made up the intent.

Lastly, althou I agree that we should have some level of agreement around the topic, starting with an spec that isn't intrusive to existing tool will allow those tools to opt-in for the usage of the spec

[neilsh]

Worth noting that Jetbrains' .aiassistant/rules/ .md files also support frontmatter, although with different fieldnames from Cursor:

• https://www.jetbrains.com/help/ai-assistant/configure-project-rules.html

• example: https://resources.jetbrains.com/help/img/idea/project_code_review_guidelines.md

---
type: always on
pattern: src/main/**/*.java
---

[yordis]

The spec could be conservative around such feature until there is a proven worth to add to the spec path forward. I rather observe that enforce the spec around the topic. Everything could add their own frontmatter as any other markdown file for the time being

[beingminimal]

This feature must be supported, we are already using in vs code and it's helping a lot. Thanks

[SinOverCos]

I'm working on consolidating Copilot and Cursor configs into AGENTS.md to simplify things for a large team and finding that not having this feels like a regression from .cursor/rules/ + making adoption harder.

[karlhorky]

Thanks for this proposal and the .agents/*.md proposal in #9 🙌 I came to the repo today to open similar issues.

An AGENTS.md file (or other files inside a directory, see #9) will be added to the chat context only when the conditions in its metadata are met.

One minor distinction that comes up for me: it seems like front matter will be most useful in the multiple .agents/*.md files. Front matter will be less useful in AGENTS.md files (even if there are multiple AGENTS.md files in nested folders), since there's a conflict between these usage details:

• AGENTS.md files will in most cases contain instructions for multiple file types
• front matter is for specifying globs that all rules in the file apply to

So it feels like probably the .agents/*.md proposal in #9 should be a prerequisite for front matter support.