Local overrides

A folder loads only when it exists. Project sync ignores ~/.agnostic-ai/, and global sync ignores every project. Your personal setup wins over the shared one.

Layout

local/ mirrors the source directory:

my-project/.agnostic-ai/
├── AGNOSTIC_AI.md                 # shared, committed
├── rules/testing.md
├── skills/review/SKILL.md
└── local/                         # yours: ignored, still synced
    ├── AGNOSTIC_AI.md             # extends the shared instructions
    ├── rules/scratch-notes.md     # new name: appends
    └── skills/review/SKILL.md     # same name: edits the shared skill

The project folder reads every spec kind: agents/, skills/, rules/, hooks/, mcps/, commands/, settings/, reviews/, environments/, and ignore/. It stays at .agnostic-ai/local/ even when custom sources paths in agnostic-ai.yaml move the shared specs.

For the global folder’s supported kinds and layout, see global configuration.

Override fields

A local spec with the same kind and name as a shared one merges into it. Write only what changes; when the team edits the shared spec, the next sync keeps your changes on top.

Shared, committed:

---
name: custom
description: Draft the release notes.
model:
  claude: sonnet
  codex: terra
---
Read the merged PRs since the last tag.

Local, ignored:

---
name: custom
model:
  claude: opus
---

After sync, Claude uses opus; the description, body, and Codex model stay as shared.

Frontmatter (the YAML fields between --- lines) merges key by key, the same way agnostic-ai.local.yaml merges over agnostic-ai.yaml:

For example, tools: [Read] replaces the shared list, and tools: null removes it.

For settings, a local per-tool model or effort map treats a shared single value as its default. Shared model: sonnet with local model: {codex: sol} gives Codex sol and every other tool sonnet. A local default overrides that shared value.

Inside an x-<target> map, null removes one key: x-codex.model: null drops model for Codex only.

The local file's location sets its scope. local/rules/style.md applies to the whole project even when the shared rules/backend/style.md applies to backend/ only.

YAML specs (hooks, MCP servers, settings, environments) follow the same rules: a local mcps/docs.yaml can change env.PORT and keep the shared command and args.

Turn a shared spec off

List the targets you do not want in targets-exclude:

---
name: review
targets-exclude: [claude, codex, cursor]
---

Extend the body

• Empty local body. The shared body stays.
• A ::parent line. The shared body goes there. Put your text before it, after it, or around it.
• Any other body. It replaces the shared one.

Shared:

---
name: custom
---
Review the changed code.

Local:

---
name: custom
---
::parent
Then run my local benchmark.

The result is the shared review instruction followed by your benchmark step.

::parent must start at column 0 and stand alone on its line. Keep it outside a ::target fence. In a spec with a new name, ::parent has nothing to extend, so sync drops it.

Skill assets

A local skill folder with only a SKILL.md keeps the shared folder's supporting files, such as scripts and templates. If the local folder holds any other file, its own supporting files replace the shared supporting files.

What does not merge

Only personal overrides merge field by field. A project spec replaces a pack spec with the same kind and name in full.

Two files with the same name in one folder are a mistake: one wins, and agnostic-ai lint reports the other (LINT003).

Extend the instructions

.agnostic-ai/local/AGNOSTIC_AI.md extends .agnostic-ai/AGNOSTIC_AI.md. Sync appends its text to every root instruction file it writes (CLAUDE.md, AGENTS.md, GEMINI.md, and the rest), after the shared body and any inlined rules:

<!-- agnostic-ai:local:start -->

Answer in Spanish. Run `make test` before every commit.

<!-- agnostic-ai:local:end -->

• A legacy outputs.<target>.rules-file that names the entry point gets the block too, after the rule bodies.
• ::target fences and @path imports work as in the shared file.

In the global folder, local/AGNOSTIC_AI.md comes last in the managed instructions block, after the shared instructions and rules.

Import

agnostic-ai import never writes your local specs into .agnostic-ai/, even though sync puts them in the native files import reads (such as a local rule inlined into AGENTS.md). Import skips every name your local folder declares and lists what it skipped. A shared spec your local folder extends keeps its own content.

Hooks are matched by event, matcher, and handler. A local handler is removed from the imported hook, and a script that only local hooks run stays out of .agnostic-ai/scripts/.

Settings, reviews, and environments share one native file per target. If your local folder holds one of these kinds, import leaves every shared spec of that kind unchanged and says so.