Why Every AI-Assisted Project Needs a .agents/ Folder

Jack Del Aguila — Tue, 10 Mar 2026 19:03:46 +0000

The Problem
Introducing ACS
Progressive Disclosure
The Manifest
Permissions
Compatibility
Where It Stands

The Problem

If you've used Claude Code, Cursor, GitHub Copilot, or any AI coding
assistant in the last year, you've probably noticed something frustrating:
every tool wants its own config file.

Claude Code reads CLAUDE.md. Cursor reads .cursorrules. Copilot has
its own instructions format. Some teams write AGENTS.md. Others use
SKILL.md.

The result? You end up maintaining 3–4 overlapping files that all say
roughly the same thing — just in different formats, for different tools.

There has to be a better way.

Introducing ACS — Agentic Collaboration Standard

ACS is an open format that defines a single .agents/ folder for
agent-ready projects. Write your context, skills, and permissions once
— use them across any tool.

\your-project/ └── .agents/ ├── acs.yaml ← manifest ├── context/ ← what your project is ├── skills/ ← reusable task instructions ├── commands/ ← shortcuts agents can run ├── agents/ ← named subagent definitions └── permissions/ ← what agents can/can't touch \\

The Core Idea: Progressive Disclosure

Most agent configs dump everything into one giant file. ACS uses a
3-tier loading strategy:

Tier 1 — Always loaded (~50 tokens per skill): just the name and
description. The agent knows what skills exist without reading them.

Tier 2 — On activation: when a task matches a skill, the full
SKILL.md body loads.

Tier 3 — On demand: supporting files like references/, scripts/,
or assets/ load only when the skill instructions reference them.

This keeps your context window lean and fast, while still giving agents
everything they need when they need it.

A Real Example: the `acs.yaml` Manifest

\yaml acs_version: "1.0" project: name: "my-app" description: "Full-stack SaaS built with Next.js and Prisma" layers: context: true skills: true commands: true agents: true permissions: true compatible_with: [claude-code, cursor, any] \\

One file tells any compliant agent tool everything it needs to know
about your project's structure.

Permissions That Actually Work

Tired of agents touching files they shouldn't? ACS includes a
permissions/policy.yaml:

\yaml deny: read: [".env", ".env.*", "secrets/**"] write: ["prisma/migrations/**"] allow: read: ["**"] write: ["src/**", "app/**"] \\

Simple, readable, and tool-agnostic.

100% Compatible With What You Already Use

ACS doesn't ask you to throw away your existing setup:

AGENTS.md → keep it alongside .agents/
SKILL.md (agentskills.io) → copy directly to .agents/skills/, zero changes
CLAUDE.md → map content to context/ and skills/
MCP → different layer entirely, they complement each other

Where It Stands Today

ACS v1.0 is a draft open standard. The spec, JSON schemas, reference
implementations in Python and TypeScript, and example projects are all
live on GitHub.

Intentionally out of v1.0: workflows, hooks, profiles, CLI tool — scoped
to v2.0 to keep the first version simple and adoptable.

If you work on an AI coding tool and want to add compatibility, open an
issue. If you adopt ACS in your project, add yourself to ADOPTERS.md.

The ecosystem is fragmented enough. Let's fix it together.

Explora la especificación oficial de ACS

jackby03 / agentic-collaboration-standard

A unified open format for agent-ready projects across tools, teams, and platforms.

ACS — Agentic Collaboration Standard

ACS defines how projects describe themselves to AI agents through a single .agents/ folder that any ACS-compatible agent can read, regardless of which tool, IDE, or platform you use.

The problem

Every agentic tool invents its own configuration format. Teams end up juggling different files and paths across tools such as Cursor, Zed, Claude Code, Gemini, Codex, Kiro, Trae, Windsurf, JetBrains Junie, Coodo, GitHub Copilot, Roo Code, Antigravity, Firebase Studio, and others.

In practice, that fragmentation shows up in vendor-specific files and folders:

Tool	Config file / path
Claude Code	`CLAUDE.md` + `.claude/`
Cursor	`.cursorrules` or `.cursor/rules/`
GitHub Copilot	`.github/copilot-instructions.md`
Codex (OpenAI)	`AGENTS.md` + `~/.codex/config.toml`
Windsurf	`.windsurfrules`
Gemini CLI	`GEMINI.md`
Zed	`.zed/` (editor settings with AI context)
Kiro	`.kiro/steering/`
JetBrains Junie	`.junie/guidelines.md`
Trae	`.trae/rules/`
Aider	`.aider.conf.yml` or `CONVENTIONS.md`
AGENTS.md-based tools	`AGENTS.md`

Note: this table is a compatibility landscape snapshot for context, not a normative ACS…

View on GitHub

DEV Community: Jack Del Aguila

Why Every AI-Assisted Project Needs a .agents/ Folder

Table of Contents

The Problem

Introducing ACS — Agentic Collaboration Standard

The Core Idea: Progressive Disclosure

A Real Example: the `acs.yaml` Manifest

Permissions That Actually Work

100% Compatible With What You Already Use

Where It Stands Today

jackby03 / agentic-collaboration-standard

A unified open format for agent-ready projects across tools, teams, and platforms.

ACS — Agentic Collaboration Standard

The problem

DEV Community: Jack Del Aguila

Why Every AI-Assisted Project Needs a .agents/ Folder

Table of Contents

The Problem

Introducing ACS — Agentic Collaboration Standard

The Core Idea: Progressive Disclosure

A Real Example: the acs.yaml Manifest

Permissions That Actually Work

100% Compatible With What You Already Use

Where It Stands Today

jackby03 / agentic-collaboration-standard

A unified open format for agent-ready projects across tools, teams, and platforms.

ACS — Agentic Collaboration Standard

The problem

A Real Example: the `acs.yaml` Manifest