[FEATURE] Proposal: Support a Shared `.agents/` Directory and Manifest-Based Discovery
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
As more development agents emerge, repositories are increasingly accumulating tool-specific top-level directories such as:
.claude/
.claude-plugin/
.cursor/
.github/
.opencode/
.vscode/
...Each tool introduces its own conventions, fixed directory names, and sometimes additional companion directories outside its own namespace. This approach does not scale well for repositories that need to support multiple agents over time.
Proposed Solution
Proposal 1: Support a Shared .agents/ Directory
Instead of requiring every agent to create its own top-level directory, consider also supporting the following layout:
.agents/
claude/
plugins/
marketplace.json
settings.json
cursor/
codex/
gemini/
github/
human/
skills/
README.md
...Each agent remains free to organize its own internal files however it prefers, but all agent-related resources live under a single shared root. This keeps repositories organized while allowing every agent to evolve independently.
This proposal is not asking to replace the current layout. It simply asks to also support discovering configuration under .agents/<agent>/, preserving full backward compatibility with existing repositories.
Benefits
- Keeps the repository root clean and predictable.
- Prevents namespace pollution.
- Makes repositories easier to navigate.
- Provides a single location for all agent-related resources.
- Simplifies supporting multiple agents simultaneously.
- Allows future agents to coexist without introducing additional top-level directories.
---
Proposal 2: Prefer Manifest-Based Discovery Over Fixed Directory Layouts
Many tools currently require resources to exist in hard-coded filesystem locations. For example, an agent may require directories such as:
skills/
prompts/
commands/to exist beside its configuration directory. These assumptions unnecessarily couple repository layout to a particular implementation. Instead, consider allowing a manifest file to explicitly declare resource locations. For example:
skills:
- /.agents/skills
prompts:
- /.agents/prompts
commands:
- /.agents/commands
references:
- /docs/The manifest becomes the contract rather than the directory structure. This allows repositories to organize their files according to their own architecture while remaining fully compatible with the agent. It also enables future resource types without introducing new fixed filesystem conventions.
Alternative Solutions
_No response_
Priority
Medium - Would be very helpful
Feature Category
Other
Use Case Example
_No response_
Additional Context
Project Documentation
Agent instructions and project documentation serve different audiences and should remain clearly separated. A natural convention is:
.agents/ # Instructions and resources intended for agents (How)
/docs/ # Project documentation intended for any agents as humans, tools, AIs (Why)Project documentation should not be tied to a specific agent. Whether the consumer is a human, an IDE, a CLI tool, or an AI model, the same documentation should remain accessible from a predictable location.
---
Why This Matters
Repository structure should not become coupled to individual tools. Agents are broader than AI models. IDEs, automation tools, CI systems, documentation generators, and even humans can all be considered agents interacting with a repository. A repository should be able to support many different agents simultaneously without each one requiring its own top-level directory structure or filesystem conventions.
Supporting a shared .agents/ directory together with manifest-based discovery would improve interoperability, reduce repository clutter, and make the ecosystem easier to extend while remaining fully backward compatible.
4 Comments
I built a plugin that implements both proposals here without waiting on a core change: agents-dir-bridge
It's a
SessionStarthook. If.agents/exists, it reads.agents/manifest.json(or simple YAML) and symlinks the declared paths into Claude Code's native.claude/skills,.claude/commands,.claude/agents,.mcp.json. No manifest → falls back to mirroring.agents/claude/<resource>directly. No.agents/→ no-op, fully backward compatible.Non-destructive: only touches symlinks it created itself, tracked in a state file. Real files under
.claude/are never overwritten. Prompts have no native discovery dir in Claude Code, so those get injected asadditionalContextat session start instead.Since this repo is the plugin-catalog/docs repo and not the CLI source, a PR wasn't an option — this is a working reference implementation instead, in case it's useful for whatever gets decided here. Limitations (MCP merging,
settings.json, YAML parser scope) are listed in the README.Dear @deepresearcher08, Thanks for taking the time to build and share this. It's a clever workaround, and I appreciate the effort.
That said, my goal with this proposal isn't to find a workaround for Claude Code specifically.
The goal is to encourage a common ecosystem convention that any development agent can support. I plan to open the same proposal across multiple agent projects because I believe this is a broader interoperability issue, not a Claude-specific one.
In fact, I also opened the proposal for VS Code, and it has already been accepted as a feature request pending community support:
https://github.com/microsoft/vscode/issues/327256
So even if a plugin can bridge the gap today, I still believe native support is the right long-term direction. Repository layout shouldn't need to depend on agent-specific filesystem conventions or require compatibility layers.
The same applies to manifest-based discovery. Rather than requiring fixed directory layouts, I think agents should be able to discover their resources from a manifest while remaining fully backward compatible with existing repositories.
Your plugin demonstrates that the concept is technically feasible, which is great. My proposal is simply to make this capability a first-class ecosystem feature instead of something every project needs to solve independently.
I found a real-world example that illustrates why I think native support for a shared
.agentsdirectory (or manifest-based discovery) matters.Because of the current fixed directory conventions, the project ends up maintaining the same skill in two different locations:
https://github.com/maximiliamus/spec-kit-canon/blob/master/.claude/skills/bumping-spec-kit-canon-version/SKILL.md
https://github.com/maximiliamus/spec-kit-canon/blob/master/skills/bumping-spec-kit-canon-version/SKILL.md
The Claude-specific version mainly exists to redirect users to the shared implementation rather than containing the actual knowledge itself.
This is exactly the kind of duplication and repository coupling that a shared
.agentsdirectory and manifest-based discovery could eliminate while remaining fully backward compatible.It's a small example, but I think it demonstrates that this isn't just a theoretical concern—it already affects real projects.
One additional thought related to Proposal 2. Today, the ecosystem distinguishes between concepts such as Instructions and Skills, but after working with several AI platforms, I'm no longer convinced they are fundamentally different. Project instructions are effectively just always-active reusable practices. The only real difference is their loading strategy.
This also makes me question the term "skill" itself.
A document is not a skill. A skill is an ability possessed by an agent. What these files actually contain are descriptions of practices—repeatable reasoning patterns or ways of working. Reading a document does not immediately give an agent a skill; it provides a practice that can be applied and eventually become part of the agent's behavior.
If Proposal 2 (manifest-based resource discovery) were adopted, it might also be worth reconsidering the naming of these resources. Instead of hardcoding a
skills/directory, repositories could choose a conceptually more accurate name such as:The agent would discover the resource locations from the manifest rather than from fixed directory names. This would decouple the conceptual model from implementation details while giving projects the freedom to organize reusable reasoning resources in a way that best matches their own architecture.