Repository navigation
[FEATURE]: Support a Shared .agents/ Directory and Manifest-Based Discovery #47742
Description
Feature hasn't been suggested before.
- I have verified this feature I'm about to request hasn't been suggested before.
Describe the enhancement you want to request
As more development agents emerge, repositories are increasingly accumulating tool-specific top-level directories such as:
.claude/
.claude-plugin/
.config/
.cursor/
.devcontainer/
.eslint-plugin-local/
.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.
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/
cursor/
codex/
devcontainer/
eslint/
plugin-local/
gemini/
github/
human/
vscode/
opencode/
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.
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.
Activity
github-actions commentedon Sep 7, 2026
This issue might be a duplicate of existing issues. Please check:
.agents/vendor-neutral layout and a manifest-based discovery format (plugin.json) — directly overlapping with both proposals here.e-gleba commentedon Sep 28, 2026
+1 here who'd like to see this implemented
jjjermiah commentedon Oct 11, 2026
+1, mostly for proposal 1. I already keep specs, plans and skills in
.agents/, so having a separate.opencode/at the root just for agents, commands andopencode.jsoncbugs me more than it probably should.v2 is most of the way there already.
config/discovery.tschecks for.agentsat every level on the way up, it just only reads.agents/skillsout of it. That came from #35864, which even says.agents"may supply more than skills over time". Treating.agents/opencode/as another project config dir looks like a small change indiscovery.ts, plus the two spots in the TUI that hardcode.opencode(themes and TUI plugins)..opencodewould keep working exactly like it does now.jjjermiah commentedon Oct 11, 2026
@e-gleba put up a PR for proposal 1 in #54594 if you want to give it a try or a thumbs up
e-gleba commentedon Oct 12, 2026
Got it, will try today, thanks!
rekram1-node commentedon Oct 13, 2026
Has anyone else adopted this yet?
e-gleba commentedon Oct 16, 2026
No. Only
.agents/skillsis shared. I found no.agents/<tool>/for commands, agents, scripts in official docs..agents/skillsfrom cwd up to root, rest stays under.codex/(Codex skills).claude/skills/,.claude/commands/,.claude/agents/(Claude Code skills Claude Code commands).gemini/skills/and.gemini/commands/(Gemini CLI skills Gemini CLI commands).github/skills/and.github/agents/(Copilot skills).grok/(Grok Build docs).agents/<tool>/tree (Kimi Code skills)agentskills.iocompat for skills, no.agents/<tool>/layout (Hermes docs)SKILL.mdwith name plus description (Agent Skills spec Claude skills overview)But. Parsing
.agents/opencodeas alias to.opencodekeeps root clean: onelswith no extra dot dirs, all agent stuff in one place, old path still works. Same logic holds for other tools if they map.agents/<tool>/to their own dir.opencodejr commentedon Oct 28, 2026
Thanks for the detailed proposal! In short, you're asking OpenCode to also read its config from a shared
.agents/opencode/directory, and, longer term, to let a manifest say where skills, commands and other resources live instead of relying on fixed directory names.Some context on where things stand now:
.agents/in the project and its parent directories, but at the moment it only reads skills from.agents/skills. Other project config is read only from.opencode/.skills.paths, which covers part of the manifest idea.Related work:
.agents/opencode/as a project config directory (proposal 1)..opencode/stays supported and wins when both exist.Maintainers will consider this.