Directory support

[jsit]

For better organization and modularity, the spec should support additionally crawling files in a directory, such as .agents.

By default, files within that directory will always be added to the context, but can be individually disabled within the IDE or code assistant tool (or with frontmatter, see #10).

For instance, a user might have a structure like this:

|-- .agents
|  |-- naming-conventions.md
|  |-- personality.md
|  |-- project-overview.md
|  `-- testing.md
`-- AGENTS.md

Prior art

• Cursor's .cursor/rules directory: https://docs.cursor.com/en/context/rules
• RooCode's .roo/rules directory: https://docs.roocode.com/features/custom-instructions
• Kilo Code's .kilocode/rules directory: https://kilocode.ai/docs/advanced-usage/custom-rules#rule-location
• Trae's .trae/rules directory: https://docs.trae.ai/ide/rules-for-ai
• Windsurf's .windsurf/rules directory: https://docs.windsurf.com/windsurf/cascade/memories#rules
• Augment's .augment/rules directory: https://docs.augmentcode.com/setup-augment/guidelines#working-with-rules
• VSCode's .github/instructions directory: https://code.visualstudio.com/docs/copilot/copilot-customization?wt.md_id=AZ-MVP-5004796#_use-instructionsmd-files

[danielmeppiel]

VSCode / GitHub Copilot is an example of modularization as well:

You can have any number of .github/instructions/*.instructions.md which already support applyTo in the frontmatter (docs here).

Matching patterns like applyTo simplify the creation, distribution and reuse of context files.

[jsit]

Matching patterns like applyTo simplify the creation, distribution and reuse of context files.

@danielmeppiel Thanks, this is addressed in #10.

[yordis]

I would prefer something like .agents/rules so that .agents directory is set for future expansion without introducing breaking changes. Also, I would expect nested directories inside such rules. I use .agents/rules/internal to have uncommitted rules, as an example. Or have hierarchical structure based on technologies or frameworks, or things of that nature

[SinOverCos]

Wondering if @dkundel-openai or someone from OAI can comment on this -- is this considered for the spec or is this a dead end?

[malhashemi]

@yordis totally agree on .agents/rules I was also coming to propose the following features to .agentsdirectory

• Reusable prompts .agents/prompts/
• Reusable Sub-Agents (with the contents of the MD files being used as system prompt) .agents/subagents/x.md
• Rules .agents/rules/
• Tools .agents/tools/ for any executable tools and scripts

There are tremendous amount of tools getting added everyday, and with each adding the same feature under different folder structure it is getting tedious having all these different folders in every codebase just to cover the dev tools of every developer.

[TomLucidor]

Seconding this + find out only this issue got the Windsurf mention at the moment P.S. please check https://github.com/intellectronica/ruler

[BradKML]

@malhashemi but when will this get a PR, or adopted as the new standard? You do know that description (universal?), globs (Cursor only), alwaysApply (Cursor) or auto_execution_mode (Windsurf) etc. shows that IDEs often differ from one another when it comes to headers?

[malhashemi]

@malhashemi but when will this get a PR, or adopted as the new standard? You do know that description (universal?), globs (Cursor only), alwaysApply (Cursor) or auto_execution_mode (Windsurf) etc. shows that IDEs often differ from one another when it comes to headers?

@BradKML well they differ coz there is no standard. The standard in my opinion should evolve as more of the functionality becomes widely used enough that they need a standard. Descriptions for example is indeed global enough to be part of the header, there could be some sort of a key like ide that allows for specific vendors header imagine something like

- ide
  - [vendor]
    - [vendor_specifc_header]

At least we get to a point where every file can be reusable across IDEs rather than having a mess of various .vendor folders per codebase.

[danielmeppiel]

Hi folks,

I am proposing a paradigm / tooling to handle this called Agent Package Manager. It basically builds on what we are raising here. Have a look at https://github.com/danielmeppiel/apm

Allows to install modular instructions/prompts and "compile" instructions that use applyTo patterns into nested Agents.md. So this is portable across clients.

[malhashemi]

Hi folks,

I am proposing a paradigm / tooling to handle this called Agent Package Manager. It basically builds on what we are raising here. Have a look at https://github.com/danielmeppiel/apm

Allows to install modular instructions/prompts and "compile" instructions that use applyTo patterns into nested Agents.md. So this is portable across clients.

@danielmeppiel Hi, thanks for making this, how would this work with something like OpenCode? Where there are agents, subagents, commands, MCPs, custom tools, AGENTS.md files etc. Or even Claude Code subagents, output-styles etc. If team members who are working on the same project have their own dev workflows that they like to use how would it accommodate that? I have something in mind to build addressing this but was hoping for a standard to emerge rather than the current wild west.

[danielmeppiel]

@malhashemi OpenCode and Claude Code both support the Agents.md standard.

APM just allows teams to dynamically generate the Agents.md nested hierarchy for their project out of context packages. Coding agents that support the Agents.md standard will just honor those once they've been created. Agents.md is the gluing standard here.

If they have their own workflows (i.e. prompts), they can just store them locally. Example project here.

[BradKML]

Also, I realized that symlinks are a halfway solution for directories (but people say it is harmful) https://kau.sh/blog/agents-md/ https://pnote.eu/notes/agents-md/

[mathieufortin01]

Also, I would expect nested directories inside such rules. I use .agents/rules/internal to have uncommitted rules, as an example.

Nested directories should be part of this feature. One other use case is propagating common set of rules to bunch of repos. With cursor we can have a dedicated subfolder, containing a bunch of .mdc files. It makes things well organized and easy to sync. That said, it could also use a dedicated file prefix in a single folder.

[waldyrious]

FYI, the recently announced Claude Skills are based on a hierarchical structure of files under a base directory, which greatly overlaps with the functionality that would be unlocked by this feature.

[BradKML]

The issue would be whether Claude Skills will be rolled into AGENTS.md standard, or they are just gonna make it exclusive

[JolanDeNef]

Interesting development is that Google's Antigravity (build by the developers they brought over from Windsurf) now uses the .agent/ folder.

This also means that e.g. rules and workflows from .windsurf will work if you copy (or symlink) them to the .agent folder. First step in generalisation?

[leochiu-a]

I added support in universal-agents for AGENTS.md to read the .agents/ subfolder.

.agents/
  skills/
    code-review/
      SKILL.md
  rules/
    api-guideline.md
    react-components-guideline.md
AGENTS.md

[TomLucidor]

@danielmeppiel are there ways of creating a less fractured multi-IDE ecosystem for this simple folder-based design? (Ruler vs APM vs Universal Agents vs other services)

[jsit]

@danielmeppiel are there ways of creating a less fractured multi-IDE ecosystem for this simple folder-based design? (Ruler vs APM vs Universal Agents vs other services)

That’s what AGENTS.md, this very repo, was supposed to solve. But this project seems effectively abandoned.

[TomLucidor]

@jsit cus AGENTS.md is a bad spec compared to what everyone else want to do for a whole folder... Which is sad cus OpenAI is gonna do what they want