v1.20Grok Build CLI support →

Config layers

Skills, commands, hooks, rules, and MCP servers live in four overlapping places. When you spawn an agent, agents-cli merges them into a single surface and hands the result to the harness.

The four layers

Lower layers provide defaults. Higher layers override. Same shape at every layer — directories of markdown, YAML, and shell scripts — so a resource can move between layers without rewriting.

▒ system    built-in catalog shipped with agents-cli
▒ you       ~/.agents/                  # personal
▒ team      ~/.agents/teams/<org>/      # shared, public or private
▒ project   ./.agents/                  # repo-local, checked in

# precedence: project > team > you > system

1. System

Shipped with the CLI. Covers the catalog of built-in commands (/recap, /next, /swarm), the default permissions, and a starter set of skills. You don't edit this layer — you override it from the layer above.

2. You

Your personal ~/.agents/ tree. This is where agents-cli stores everything you install or write for yourself, and it's what gets synced into each harness's native config format.

~/.agents/
├── commands/      # slash commands (markdown)
├── skills/        # reusable knowledge packs
├── mcp/           # MCP server definitions
├── hooks/         # lifecycle hooks (sh / ts)
├── memory/        # AGENTS.md, project notes
└── permissions/   # allow/deny lists

agents repo push backs the tree up to a remote (any git host). agents drive attach points ~/.claude/, ~/.codex/, and friends at the synced copy so sessions also travel.

3. Team

A team layer is just another .agents/ tree, owned by an org or sub-team. Add it once and it merges in for every agent you run.

# clone a public team config
agents repo add acme gh:acme/agents-config

# or a private one — push will use your git auth
agents repo add acme git@github.com:acme/agents-config

# what's merged right now
agents repo list

Teams are how shared AGENTS.md rules, vetted skills, and standard MCP servers reach every laptop without each person re-installing them. A team repo can be public (anyone can clone it) or private (gated by your git host's auth).

4. Project

Drop a .agents/ directory at the root of a repo and its contents merge in whenever an agent runs from inside that working tree. This is how a repo carries its own rules, slash commands, and skills with it.

my-project/
├── .agents/
│   ├── AGENTS.md           # repo-specific rules
│   ├── commands/
│   │   └── ship.md         # /ship slash command
│   └── skills/
│       └── stripe-test/    # how to test against stripe
├── src/
└── package.json

The project layer wins. A skill the repo ships supersedes the same-named one from the team, your personal one, or the system catalog. Useful for keeping a repo's on-ramp self-contained — clone, agents run, done.

Precedence

Resources are looked up by kind + name (e.g. commands/ship, skills/python-expert). The highest layer that provides a given name wins outright — there is no field-level merge inside a single resource. To extend a parent resource rather than replace it, import it explicitly from the body of the higher-layer one.

project / .agents/commands/ship.md   ← wins
team    / commands/ship.md
you     / commands/ship.md
system  / commands/ship.md

Inspecting the merge

Two flags will tell you what an agent will actually see:

agents resources --merged          # final view, one line per resource
agents resources --merged --trace  # also show which layer each came from

If a project resource isn't winning the way you expect, --trace is the first place to look.

Spawning an agent

Every agents run resolves the layered surface for the current working directory, syncs the merged commands/skills/hooks into the harness's native format, and then launches the agent. The agent itself never sees four trees — only the final one.

Related