The Case for .contributing: One Folder for Every Coding Agent

Open almost any repository that has leaned on AI coding tools over the past year and a half, and count the dot-folders at its root. You will probably find .claude/, .cursor/, .codex/, .gemini/, and .opencode/ sitting side by side. Five folders do one job: each holds the agents, skills, memory, commands, and settings that teach an AI how to work in your codebase. Same contents, one folder per provider.

That duplication is the problem, and it shows up in two layers. Developers and others using AI already solved the first: they agreed on one neutral instruction file that every tool reads. The second layer, the folder, is still broken, and it holds the agents, skills, and memory that do the real work. This article makes the case for .contributing/, one shared folder any agent can read, and covers why the folder is the fix, why its name fits, and how you adopt it today.

The file is solved. The folder is not.

Two years ago the same mess lived one level down, in the files. Every tool wanted its own instructions file: CLAUDE.md, .cursorrules, .windsurfrules, GEMINI.md, copilot-instructions.md. You wrote the same project description five times and kept five copies in sync.

Then the ecosystem converged. AGENTS.md emerged as a neutral "README for agents." OpenAI shipped it first, Google, Cursor, Factory, Sourcegraph, and Amp backed it, and the Linux Foundation's Agentic AI Foundation now stewards it. By mid-2026, more than two dozen tools read it across tens of thousands of repositories. Even Claude Code, which keeps its richer CLAUDE.md, learned to read it. The lesson lands hard: developers converge fast when someone offers one good neutral format, and the providers who offered it competed on the quality of their agents rather than the stickiness of a filename. Moving first earned them the credit, not a loss of ground.

But AGENTS.md covers exactly one thing, a single file of prose. Modern agents load far more than prose:

• Agents: specialized personas for review, testing, and migration

• Skills: reusable, self-contained capabilities

• Commands: project-specific workflows

• Hooks: scripts that run before or after actions

• Memory: durable notes that survive across sessions

• Settings: permissions, tool access, and model defaults

Here is the catch: every provider expects that same list. Claude Code, Cursor, Codex, and OpenCode all reach for agents, skills, and memory, because agentic work needs the same ingredients no matter whose agent runs them. The content is provider-agnostic. Only the folder name is provider-specific. So we copy identical material into five provider-branded folders and sync it by hand. We fixed the file and rebuilt the same fragmentation one level up, with more to duplicate this time. And the pressure only builds. As capable models increasingly run locally, every new harness that wraps one adds another folder, even though it needs the same agents, skills, and memory as the rest.

One folder, and a name that fits

Standardize the folder the way we standardized the file. Put the agents, skills, memory, commands, hooks, and settings in one neutral directory:

.contributing/
├── agents/        # personas: review, test, migrate
├── skills/        # reusable capabilities
├── commands/      # project workflows
├── hooks/         # pre/post action scripts
├── memory/        # durable context
└── settings.json  # permissions, defaults, guardrails

AGENTS.md stays at the root as the front door. .contributing/ holds the machinery behind it. Any conformant tool reads .contributing/ first. Vendors keep their own folders for the genuinely proprietary parts, but the shared 90%, the agents and skills that describe your project rather than your vendor, lives in one place you maintain once. One place is also one place to secure, review, and keep in policy, and one fewer way for any single vendor to capture your project.

Now the name. It answers a question open source has asked for fifteen years: how do I help with this project? CONTRIBUTING.md has always held that answer for humans. It carries the build steps, the conventions, the test commands, and the etiquette.

Coding agents are contributors too. They arrive every session with no memory, needing the exact orientation a human newcomer needs. So the folder that configures them is not vendor exhaust. It is contribution guidance for a new kind of contributor. .contributing/ reads as part of the project, the way .github/ and CONTRIBUTING.md do, right down to the first-class treatment platforms already give those files. It belongs to the codebase, not to a company, and that feeling drives adoption.

That legibility matters more as agents move past code. Many people steering agentic work are not developers; they draft documents, build decks, and run analyses. .contributing/ tells them what it is at a glance, while .claude/ asks them to learn tool internals they would otherwise never touch. Developers shrug at a dotfolder and a symlink. For everyone else, a plain name is the on-ramp.

Adopt it today

Standards win by making the easy path the correct one.

Start now with symlinks. Point the vendor folders at the shared one:

ln -s .contributing .claude
ln -s .contributing .cursor

Developers already do this by hand, and tools like ruler exist to fan one source of truth out to many vendor folders. Nothing breaks and nobody has to agree: your vendor folders keep working, the change reverses in one command, and you get the full payoff alone, today. That people already improvise it proves the standard is missing.

Next, tools add .contributing/ to their discovery chain, the same cheap move that let them read AGENTS.md as a fallback. Vendor folder overrides shared folder, and the nearest directory wins, exactly as AGENTS.md resolution already works. The incentive runs both ways: a CLI or IDE that reads the shared folder works in any repo already configured for a rival, so trying it costs the user nothing, and a model provider makes the same open bet that paid off with the instruction file.

Then stewardship. The Agentic AI Foundation already governs AGENTS.md, MCP, and Goose. A folder that complements AGENTS.md sits squarely in its scope. Nobody has to found a new body. They have to finish a job that body already started.

Three objections come up, and none survives contact:

• "This is just xkcd 927, one more competing standard." That holds only if a folder standard already existed. None does. This fills a vacuum instead of re-solving a solved problem, which is the one case that justifies a new standard.

• "Tools need proprietary behavior." They do, and they keep their vendor folders for it. The point stands: your project's agents and skills are not proprietary, so they should not live in a vendor's folder.

• ".contributing/ will get confused with CONTRIBUTING.md." Keep them complementary. CONTRIBUTING.md stays human-first prose, and .contributing/ holds machine-loadable capabilities. If the overlap ever bites, the same proposal works as .agents/. But "contributing" carries meaning the ecosystem already respects.

What to do next

The ecosystem already standardized the instruction file and proved that developers converge on one neutral format. The folder is that same problem one layer up, and .contributing/ is the neutral folder that keeps the agents, skills, and memory you build portable and yours, ready for whatever agent you run next. Adoption costs a symlink today and a discovery-chain entry tomorrow.

So do three things. Create a .contributing/ folder in your next repository. Symlink your vendor folders to it today. And if you maintain a coding agent, add .contributing/ to your discovery chain and take the proposal to the Agentic AI Foundation.

Write your project's guidance once. Put it where contributors of every kind already look. Call it .contributing/.

One more thread

Throughout this piece I kept AGENTS.md and CONTRIBUTING.md in separate lanes, one for agents and one for humans. But the naming argument keeps pulling at that line. If agents are contributors, and CONTRIBUTING.md is where contributors have always looked, then why does agent guidance need a second file at all? The two already overlap on build steps, conventions, and test commands, and maintaining both is the file-level version of the duplication this article set out to kill.

Maybe the front door was never supposed to be a new file. Maybe it was CONTRIBUTING.md all along.

I'll consider that as a follow up article.

---

Written by Claude, edited by Cavelle Benjamin, across 14 iterations.