DotAgents repos

A DotAgents repo is a single directory of resources — commands, skills, rules, hooks, MCP servers, permissions, profiles, subagents, workflows, plugins — that agents-cli syncs into each coding agent's native config. Write it once; every agent (Claude, Codex, Gemini, Cursor, OpenCode, …) gets it in its own format.

The shape

Every DotAgents repo is the same fixed set of top-level directories, one per resource kind, plus an agents.yaml manifest. You only create the kinds you use.

<repo>/
├── commands/      # slash commands (/recap, /ship)        → .md
├── skills/        # reusable knowledge packs              → <name>/SKILL.md
├── rules/         # standing instructions (AGENTS.md)     → rules.yaml + subrules/*.md
├── hooks/         # lifecycle scripts                     → <name>.sh
├── mcp/           # MCP server definitions                → <name>.yaml
├── permissions/   # allow/deny rules                      → groups/*.yaml + presets/*.yaml
├── profiles/      # named run configurations              → <name>.yml
├── subagents/     # delegate definitions                  → <name>/AGENT.md
├── workflows/     # named multi-agent pipelines           → <name>/WORKFLOW.md
├── plugins/       # bundles of the above                  → <name>/.claude-plugin/plugin.json
└── agents.yaml    # manifest (version pins, hooks, run strategy)

Each kind has its own page under Configure with the exact frontmatter and on-disk format. Rules, subagents, workflows, plugins, hooks, permissions, profiles, secrets.

Four tiers, one merged surface

The same shape lives in up to four places. They merge into one surface per agent, nearest wins on a name clash:

project   ./.agents/             # repo-local, checked in       ← wins
user      ~/.agents/             # personal
extra     ~/.agents-<alias>/     # shared / team, added by name
system    ~/.agents-system/      # npm-shipped defaults

# precedence: project > user > extra > system

~/.agents-system is a symlink to ~/.agents/.system. See Config layers for the full precedence model and how the merge is inspected.

Create and manage one

agents setup                       # first-time bootstrap (user + system repos)
agents repo init                   # scaffold a new user-owned repo from the template
agents repo add gh:acme/agents     # add an extra repo (clones to ~/.agents-acme/)
agents repo list                   # what's registered and in what order
agents repo enable acme            # / disable / remove
agents repo push                   # back up your ~/.agents/ to its remote
agents repo pull                   # sync it down on another machine

Inspect any tier — or any path — to see exactly what resources it resolves:

agents inspect user                # your ~/.agents/
agents inspect system              # the shipped defaults
agents inspect ./                  # the project .agents/ for this repo
agents inspect acme                # an extra repo by alias

A worked reference

phnx-labs/.agents-extras is a complete, validated DotAgents extras repo you can read as a reference. It ships a live example for every resource kind plus copy-me templates for the ones that load automatically (rules, permissions, MCP, hooks, profiles). Two examples are worth singling out — both teach a format by generating it:

• Workflow Builder — a workflow that scaffolds new workflows. It bundles two subagents and a custom plugin, so it doubles as the "everything bundled" example of a workflow directory.
• Agent Builder — a subagent that scaffolds new subagents from a role description.

Add it to your own chain with agents repo add gh:phnx-labs/.agents-extras, then read its examples/README.md for the schema-by-schema authoring guide.

Related

• Config layers — full precedence model and inspecting the merge
• Rules — the standing-instructions kind, composed from sub-rules
• Plugins — bundle several kinds under one name