Install the team's skills, rules and commands once, and every coding agent you use has them — in every project.
Paste this into Claude Code, Codex or opencode:
Clone https://github.com/danielvogler/agent-harness-config, read its AGENTS.md,
and set it up on this machine.
The agent takes it from there. To do it by hand, see First 10 minutes.
Shared agent configuration for the team. Install it once and the same skills, commands and rules are available in every harness you use — Claude Code, Cursor, Codex, Antigravity, opencode — and in every project on your machine, with no per-project setup.
The problem it solves is N×M: N repos of team-authored agent content times M harnesses, each installed by hand, by each person. Miss one and that harness behaves differently, so two people on the same task get different agent behaviour — and so does one person switching tools mid-task. Here, a new source repo is a manifest entry instead of another install ritual across five tools.
This is not about enforcement. Nothing is locked down. The point is that the same capabilities are available everywhere by default, rather than depending on who remembered to install what.
Three commands. Do them in order.
git clone git@github.com:danielvogler/agent-harness-config.git
cd agent-harness-config
make install # 1. copies skills, rules, commands and agents into every tool you use
make setup-user # 2. turns them on: permissions, two safety hooks, no AI attribution, conventions for Codex
make doctor # 3. confirms it worked, and tells you if you are out of date latermake install copies files. make setup-user is what turns them on — without it you keep
clicking through permission prompts, nothing blocks a destructive command, and Codex and
opencode never see the team conventions. It backs up everything it touches and prints how to
undo. Run python3 tools/setup-user.py --dry-run first if you want to see it before it writes.
A smaller install is opt-in: make reinstall PROFILE=lean keeps the guards, the team's own
rules and skills, the Python, TypeScript and web rules and four agents, and leaves out
upstream's rules/common, its commands, its workflow-quality skills and the other agents.
Use reinstall, not install, to switch: the installer never removes files. Pass the same
PROFILE=lean to every later make update.
Optionally, make mcp connects four servers: live library docs (context7), read-only
BigQuery, Miro boards, and self-hosted Jira and Confluence. A fifth, GitHub, is opt-in:
make mcp ADD=github. SKIP=bigquery leaves an agreed one out on your machine. See overlay/README.md.
Miro authenticates in the browser and needs nothing from you first. The others need personal values:
- Tokens go in your shell profile (
~/.bashrcor~/.zshrc), never in a file here.make mcpchecks they are set but does not store them; each server reads them from the shell you start Claude Code in. A changed token takes effect on the next Claude Code start. - Everything else (instance URLs, the GCP project) can also go in
.env, which is gitignored:
cp .env.example .env # then fill in the values for the servers you wantCONFLUENCE_URL and CONFLUENCE_TOKEN are required for the Atlassian server, JIRA_URL and
JIRA_TOKEN are optional, and tokens come from each system's own profile settings. The
Atlassian server speaks to self-hosted Jira and Confluence only, not *.atlassian.net
Cloud sites. If a value is missing, make mcp says so and skips that one server rather than
failing everything.
The GitHub server also needs its program: brew install github-mcp-server. It reaches the
repos of whichever token is in the shell, and a fine-grained token covers one owner. For
several owners, keep one token per owner and pick it per folder with
direnv, the token itself in the macOS keychain:
security add-generic-password -a "$USER" -s github-myorg -w # asks for the token
# ~/projects/myorg/.envrc — applies to every repo under it; run `direnv allow` once
export GITHUB_PERSONAL_ACCESS_TOKEN=$(security find-generic-password -s github-myorg -w)
export GH_TOKEN="$GITHUB_PERSONAL_ACCESS_TOKEN" # gh follows the same tokenNothing team- or person-specific is written into a rule or skill, and changing a value needs no reinstall.
GCP uses gcloud's own named configurations, which hold the project and the region. The
gcp.md rule has agents read them with gcloud config get:
gcloud config configurations create proj-a
gcloud config set project my-project-id
gcloud config set compute/region europe-west6
gcloud config configurations activate proj-a # switch at any timeTo switch per folder, put export CLOUDSDK_ACTIVE_CONFIG_NAME=proj-a in an .envrc and use
direnv.
Everything else is an environment variable. Set it in your shell (~/.bashrc or
~/.zshrc); the values that are not secrets can also go in .env here for make mcp:
| Variable | Used by | What it is |
|---|---|---|
GOOGLE_CLOUD_PROJECT |
BigQuery server | Overrides the gcloud project for make mcp; GCP_PROJECT also works |
CONFLUENCE_URL, CONFLUENCE_TOKEN |
Atlassian server | Self-hosted Confluence base URL and personal access token (shell only) |
JIRA_URL, JIRA_TOKEN |
Atlassian server | Optional, the same for Jira |
GITHUB_PERSONAL_ACCESS_TOKEN |
GitHub server | Fine-grained token, scoped to the repos you use (shell only) |
MCP servers keep the non-secret values they were registered with, and make mcp skips any
server that is already registered. After changing a URL or the GCP project, or to pick up
an optional value you set later, re-register:
claude mcp remove atlassian-agent -s user
make mcpmake mcp prints a [note] when a registration is out of date, including one that still
has a token stored in it from before tokens were left to the shell. A stored token keeps
being sent after it expires, and self-hosted Confluence answers an expired token as an
anonymous user, so restricted pages look as if they do not exist.
Then go to any project and work as normal. Nothing is per-project; it applies everywhere.
To check it took: in a Python repo, ask an agent to add a BigQuery query. It should reach
for uv rather than pip, and it should not write a query without maximum_bytes_billed. If it
does neither, run make doctor.
Later: make update pulls the latest shared config. make doctor tells you when you are
behind. If something looks wrong, run make doctor before asking — most answers are "you are
behind, run make update".
Where to complain: open an issue on this repo. A convention that annoys you is a bug in the convention, not in you.
This repo holds the pin and our content. It does not contain a copy of upstream. At
install time, tools/materialize.py clones ECC at the
pinned SHA into a gitignored .ecc/, drops custom/ into it, patches its manifests from our
overlay, and lets ECC's own installer fan everything out.
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#FFFFFF","primaryTextColor":"#202124","primaryBorderColor":"#DADCE0","lineColor":"#5F6368","secondaryColor":"#F8F9FA","tertiaryColor":"#F8F9FA","clusterBkg":"#F8F9FA","clusterBorder":"#DADCE0","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":40,"rankSpacing":64,"useMaxWidth":true}} }%%
flowchart TB
subgraph SRC["Sources"]
UP["affaan-m/ECC<br/>cloned at pinned SHA"]
ASL["ai-skills-library"]
KDS["claude-scientific-writer<br/>grants · lit review · peer review"]
end
subgraph REPO["agent-harness-config (this repo)"]
PIN["upstream.json<br/>the pinned SHA"]
MAN["overlay/<br/>manifest-overlay.json"]
OWN["custom/<br/>skills · commands · rules"]
end
ASL --> OWN
KDS --> OWN
PIN --> INS
MAN --> INS
OWN --> INS
UP --> INS
INS{{"make install → materialize .ecc/ → .ecc/install.sh --profile custom"}}
subgraph HOME["User scope (~) — written once, applies everywhere"]
CL["~/.claude/<br/>skills · agents · commands · rules"]
CU["~/.cursor/<br/>rules · hooks/*.js"]
CX["~/.codex/<br/>config.toml · agents/*.toml"]
AG["~/.gemini/config/skills/"]
OC["~/.config/opencode/"]
end
INS --> CL
INS --> CU
INS --> CX
INS --> AG
INS --> OC
CL -.-> ANY["any project<br/>cd ~/projects/whatever && claude"]
CU -.-> ANY
CX -.-> ANY
AG -.-> ANY
The key thing: this repo is build material, not a workspace. Nobody works inside it. It
writes into ~, and every harness picks things up from there in every other project.
agent-harness-config/
├── upstream.json ← the pinned upstream SHA, and where custom/ came from
├── overlay/
│ └── manifest-overlay.json ← our delta to ECC's manifests, applied at install time
├── custom/
│ ├── skills/ ← 91 skills, vendored + ported
│ ├── commands/ ← research overlays
│ └── rules/ ← our conventions: python, gcp, agents
├── tools/
│ ├── materialize.py ← builds .ecc/ from the pin + custom/ + overlay
│ ├── validate-manifests.py ← pre-commit gate on the pin and the overlay
│ ├── check-profile.py ← the custom and lean profiles still resolve after materialize
│ ├── context-cost.py ← what the config costs in context per session
│ ├── doctor.py ← is what you have installed still current?
│ ├── repo_conformance.py ← the repo-conformance hook: .agent/ ledgers, AGENTS.md
│ └── langfuse-local.py ← installs, starts and checks the local Langfuse
├── .pre-commit-hooks.yaml ← hooks other repos pin by tag (custom/rules/repo.md)
├── langfuse/ ← a local Langfuse for traces of your agent sessions
│ (optional, make langfuse-install; langfuse/README.md)
├── Makefile ← install / update / doctor / context / check / mcp
├── UPSTREAM.md ← the pin, every delta, and known issues
├── CHANGELOG.md ← what changed, in words; tags are made by auto-release
└── .ecc/ ← gitignored; created by make install
Prerequisites: git, node (ECC's installer is Node), python3, make.
git clone git@github.com:danielvogler/agent-harness-config.git
cd agent-harness-config
make installThat is once per person, per machine. Run make plan first if you want to see what it will
write before it writes anything, and make uninstall to remove everything it wrote.
Langfuse shows what a session did, turn by turn, with tokens, cost
and duration. It runs on your own machine and nothing leaves it. It is not part of
make install or make update: it needs a Docker engine with 4 CPUs and 8 GiB of memory
(with Colima: colima start --cpu 4 --memory 8) and about 6 GB of images.
make langfuse-install # the pinned release in ~/opt/langfuse, generated passwords, ports on 127.0.0.1
make langfuse-plugin # the pinned Claude Code plugin that sends your sessions to it
make langfuse-status # seven containers up, ports local only, the pinned version
make langfuse-down # stop it; langfuse-up starts it again, the traces staymake langfuse-install ends with the steps that are yours: an account in the local web
UI, two API keys in the Keychain, four lines in ~/.zprofile. A trace holds everything
a session read, secrets in files included. That, how it behaves in claude-sb, and
make langfuse-reset, which deletes everything: langfuse/README.md.
make doctor reports an install that is behind the pin or no longer local-only.
ECC installs one harness per invocation, and only claude, codex and opencode are user-scoped
("home") targets. Its cursor and antigravity targets write into the current working
directory, not ~. So the install-once-and-forget promise holds for three of the five; for the
other two you install per project:
make install-project PROJECT=~/projects/whateverSkills still reach Cursor and Antigravity — they just land in that project's .cursor/ and
.agents/ rather than in your home directory.
Thereafter:
make updatewhich pulls this repo, re-materializes at whatever SHA the pin now names, and reinstalls.
Since the install writes into ~ there is no directory to inspect, so to find out whether yours
is current:
make doctorIt compares the upstream SHA and the content actually installed against this checkout, reports how
far behind origin/main you are, and delegates per-file drift to upstream's own doctor. Almost
everything it flags is fixed by make update. Run it before reporting that something is broken —
"am I on the current config?" is the first question, and this answers it.
make install never touches ~/.claude/settings.json: your settings file is yours, and
make uninstall could not reverse a change to it. make setup-user writes two lists into
permissions there, both defined in tools/setup-user.py as ALLOW
and DENY. That file is the only copy; this section explains them rather than repeating them.
allow stops the prompt on read-only commands: git status, gcloud ... list,
bq show, uv run pytest and the like. Without it you approve the same harmless command
fifty times a day, which trains people to approve without reading. None of it can create,
modify, delete or spend.
deny refuses a command outright, without a prompt. It is the only part Claude Code
enforces regardless of what the model or you decide in the moment, and it wins over allow
and over anything a project's own settings allow. Because it sits in your user settings, it
applies in every project. It covers:
| Rule | Why |
|---|---|
gcloud * delete*, bq rm, gsutil rm -r, terraform destroy, tofu destroy |
Destroys cloud resources; custom/rules/gcp.md requires an explicit yes first, and a rule can only advise |
rm -rf |
Recursive deletion of local files |
sudo |
Nothing an agent does needs root, and a wrong one damages the machine, not a repo |
Read of *service-account*.json, .env, id_rsa, id_ed25519 |
Keeps keys and credentials out of the agent's context entirely |
A denied command fails with a message; to run it, run it yourself in a terminal. The rules match on the command text, so they catch mistakes, not an agent deliberately working around them.
How it is applied:
- It merges. Missing entries are appended, your own entries are left alone, and nothing
is reordered. Run it again after every
make update; it reportsalready currentwhen there is nothing to do. - It removes only what it retired. A rule an earlier version wrote and that is now wrong
is listed in
RETIREDin the same file, and the next run deletes it. Nothing else is ever removed, including a rule we dropped fromALLOW; that is whatRETIREDis for. - It backs up first, to
~/.claude/settings.json.bak.python3 tools/setup-user.py --dry-runshows what it would change without writing. - To see what is in force, run
/permissionsin Claude Code.
Rule syntax, if you add your own: Bash(git status *) matches git status followed by
anything. The space matters: Bash(ls*) also matches lsof. The older :* suffix
(Bash(git status:*)) still works but is deprecated, and combined with another * it never
matches, which is what broke the gcloud rule (#1).
An AgentShield scan flagged "no deny list configured" as its one finding that applied to our real setup. Details and its other results are worth reading before trusting the tool further.
What is deliberately absent, and should stay absent: no bare Bash(gcloud:*) or
Bash(bq:*) — those would permit delete and rm, quietly overriding what
custom/rules/gcp.md requires. No bq query without --dry_run,
because a real query costs money and that prompt is doing useful work. No git push,
git commit, terraform apply, or rm. If you want to widen one, widen the subcommand,
never the binary — and use /permissions to see what you already allow, or the
fewer-permission-prompts skill to generate additions from your own transcripts.
Fan-out is not uniform, and this is inherent to the harnesses rather than a flaw in the tooling — Codex has no hook system, so nothing can give it one.
| Claude | Cursor | Codex | Antigravity | opencode | |
|---|---|---|---|---|---|
Skills (SKILL.md) |
✅ | ✅ | ✅ | ✅ | ✅ |
| Agents | ✅ | ✅ | ✅ | ✅ | ❌ |
| Commands | ✅ | ✅ | ❌ | ✅ | ✅ |
| Rules | ✅ | ✅ | ❌ | ✅ | ❌ |
| Hooks | ✅ | ✅ | ❌ | ❌ | ✅ |
Rule of thumb: if it must work in every harness, make it a skill.
Everything this repo installs is one of four things. Choosing the wrong one is the most common mistake, so here they are in a sentence each:
- Rule — ambient guidance. Prose loaded into the model's context that shapes how it
behaves without being asked. Best for standing conventions ("use
uv, not pip"); it advises and can be reasoned around, so it can never guarantee anything. - Skill — a procedure the model chooses to open. A folder with a
SKILL.md(plus optional scripts and templates) that stays closed until its one-line description looks relevant to the task. Best for know-how too long to keep in context permanently. - Command — a prompt macro you invoke. A file you trigger by typing
/name, which pastes a scripted set of instructions into the conversation. Best for repeatable jobs you start deliberately, like/agent-frameworks. - Hook — a shell command the harness runs at a fixed event. Not context at all; it
executes whether the model likes it or not, and a
PreToolUsehook exiting2blocks the tool call outright. The only one of the four that can actually enforce anything.
The one-line version: rules advise, skills inform, commands initiate, hooks enforce. If it must hold in every harness, make it a skill — that is the only kind all five read. If it must actually stop something, it has to be a hook or a pre-commit hook.
Not everything installed is in context. This is what makes a 91-skill bundle affordable — and worth understanding before you add anything:
| What | Loaded | Trigger | Cost on a typical session |
|---|---|---|---|
Rule without paths: frontmatter |
Every session | Unconditional | ~6.4k tokens — always paid |
Every skill's name + description |
Every session | Unconditional | ~11.4k tokens — always paid |
Rule with paths: frontmatter |
On demand | Model reads a matching file | 0 until it matches (~67k available) |
| Skill body (+ its scripts) | On demand | Model judges the description relevant, or you name it | 0 until opened |
| Command | On demand | You type /name |
0 until typed |
| Hook | Never in context | Fires on a tool-call event | 0 tokens — it is a subprocess |
Run make context for the live numbers on your own machine. Note the surprise in the
right-hand column: skill descriptions cost nearly twice all always-on rules combined.
Skill count is the expensive dimension, not rule length.
The output of make context on one machine, first part only. Yours will differ.
One free saving while you are here. Upstream's rules/ecc/README.md is ~1.4k tokens of
documentation about the rules directory, loaded unconditionally in every session because it
has no paths: frontmatter — the largest always-on file installed, and it instructs nothing.
Skip it via ~/.claude/settings.json, then re-run make context to see the drop:
{ "claudeMdExcludes": ["**/.claude/rules/ecc/README.md"] }Our own custom/rules/README.md is not installed at all, for the same reason.
You run claude in ~/projects/some-model, and ask it to add a BigQuery loader.
- At startup, Claude loads
~/.claude/rules/ecc/common/*.mdand ourcustom/gcp.md— both unscoped — plus the one-line description of all 91 skills. It has not readpython.md, or any skill body. - It reads
src/loader.py. That path matchespython.md'spaths: ["**/*.py"], sopython.mdenters context now — uv, ruff, no bareexcept. - It decides the
python-testingskill looks relevant and opens that skill's body. The other 90 stay shut. - It proposes
bq querywithoutmaximum_bytes_billed.gcp.mdwas loaded at step 1, so it catches itself — this is why that file is deliberately unscoped: agcloudorbqdecision is never a file read, so a scoped rule would arrive too late. - You type
/agent-frameworksto start a research run. Only now does that command's text enter the conversation. - It tries
git commit --no-verify. No rule stops that reliably — but theblock-no-verifyhook exits2and the tool call never runs. (On a stock install that hook is inert; see the warning below.)
Everything is concatenated, not overridden — later text wins a direct conflict:
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#FFFFFF","primaryTextColor":"#202124","primaryBorderColor":"#DADCE0","lineColor":"#5F6368","secondaryColor":"#F8F9FA","tertiaryColor":"#F8F9FA","clusterBkg":"#F8F9FA","clusterBorder":"#DADCE0","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":40,"rankSpacing":64,"useMaxWidth":true}} }%%
flowchart LR
M["managed policy<br/><i>IT-deployed, cannot be excluded</i>"] --> U
U["<b>user</b><br/>~/.claude/rules/, ~/.claude/CLAUDE.md<br/><i>this repo installs here</i>"] --> P
P["<b>project</b><br/>./CLAUDE.md, ./.claude/rules/"] --> L
L["<b>local</b><br/>./CLAUDE.local.md<br/><i>gitignored, personal</i>"] --> H
H["<b>hooks</b><br/><i>not context — they execute</i>"]
So a project can always override what this repo installs. That is intended: the shared config is a floor, not a ceiling. And the last box sits outside the chain entirely — rules are text a model can talk itself out of; a hook is a subprocess.
Diagrams drift faster than prose. When you change what installs where, or how loading works, update these in the same PR — a confidently wrong diagram is worse than none.
After make install, in ~/.claude/ (other harnesses get the subset in the table below):
| Directory | Holds | Read when |
|---|---|---|
rules/ecc/common/ |
upstream's language-agnostic conventions | every session |
rules/ecc/custom/ |
ours — python.md, gcp.md, agents.md |
gcp.md every session; the others on matching files |
rules/ecc/<lang>/ |
21 upstream language packs, all path-scoped | only in that language |
skills/ |
91 ours + upstream's, one folder each | descriptions always; bodies on use |
commands/ |
/agent-frameworks, upstream's |
when you type the name |
agents/ |
subagent definitions | when a subagent is spawned |
hooks/hooks.json |
the 21-matcher registry | never — currently inert, see below |
ecc/install-state.json |
every file the installer wrote | by make uninstall and make doctor; pruned of records for files no longer on disk by make setup-user |
In this repo, the mirror of that is custom/<kind>/ — add a file there and it fans out to
all five harnesses on the next make update.
The custom profile installs these. Upstream modules come from the pinned ECC checkout; ours
come from custom/.
| Module | Source | What it provides |
|---|---|---|
rules-core |
upstream | Shared conventions plus 21 language rule packs, loaded into context |
agents-core |
upstream | Subagent definitions, each carrying a prompt-injection defense block |
commands-core |
upstream | The /-command library |
platform-configs |
upstream | The per-harness translation layer — why one piece of content reaches five tools |
workflow-quality |
upstream | TDD, eval-harness, verification-loop and context-budget skills |
custom-skills |
ours | 91 skills — 81 from ai-skills-library, 8 academic/grant-writing from claude-scientific-writer, plus custom-deep-research and paper-search |
custom-research |
ours | /agent-frameworks, which drives the custom-deep-research pipeline |
custom-rules |
ours | Team conventions — Python, GCP and agent-building practice. The delta against upstream's generic, TypeScript-biased rules |
hooks-runtime |
upstream | 21 hooks over 7 events — but see the warning below: they are currently inert |
Hooks reach Claude, Cursor and opencode only — Codex and Antigravity have no hook system, so
anything that must hold everywhere still has to be a skill. Individual hooks can be switched
off with ECC_DISABLED_HOOKS=id,id, or the whole set dialled back with
ECC_HOOK_PROFILE=minimal. See UPSTREAM.md for the audit behind enabling them.
⚠️ The installed hooks currently do nothing. ECC writes them to~/.claude/hooks/hooks.json, but Claude Code only activates hooks declared in a settings"hooks"key or inside an enabled plugin directory — it does not read that path. So all 21 are inert on a stock install.make doctorreports it. Rules, skills, commands and agents are unaffected and work normally; the practical consequence is that nothing here currently blocks anything, so a convention that must be enforced belongs in that repo's.pre-commit-config.yaml. Details and the reason it is not yet fixed are inUPSTREAM.md.
Deliberately not installed: the security module (mostly domain-specific) and 15 modules
removed outright.
Never run --profile full.
The durable part is the pattern, not the current list of sources. Adding one should be a five-minute edit anyone can do:
- A skill — drop a directory containing
SKILL.mdintocustom/skills/and open a PR. Nothing else needs wiring;custom-skillsalready points at that directory. - A command — same, into
custom/commands/. - A rule — same, into
custom/rules/. - A whole new source repo — put its content under
custom/<kind>/, add a module entry tooverlay/manifest-overlay.json, add the module to thecustomprofile, and record the source repo and its SHA inupstream.json.
make validate checks all of it. Run make setup once to activate it as a pre-commit hook.
It needs the pre-commit CLI on your PATH first: uv tool install pre-commit.
If you change a script in tools/, run make test (after
pip install -r requirements-dev.txt). make check runs everything CI runs, tests included.
Full contributor guidance is in AGENTS.md.
make update for the shared config. Bumping upstream is separate and deliberate: edit the
SHA in upstream.json, run make validate && make plan, read the diff, commit. Never track
upstream main — it takes daily commits. Review monthly.
Releases are automatic and local. When git pull brings merged pull requests into main, the
auto-release hook (tools/auto_release.py, a post-merge hook installed by make setup) tags
the next version from the conventional commits since the last tag: feat the minor, fix and
perf the patch, a breaking change the major (the minor before 1.0). It pushes the tag and
creates the GitHub release with gh; the notes list those commits. No CI workflow is involved.
python3 tools/auto_release.py --dry-run shows what the next pull would release.
Apache-2.0, as this repo was created. Upstream ECC is MIT and is cloned at install time rather
than redistributed here. Vendored skills in custom/skills/ keep their own upstream licenses
(Apache-2.0, MPL-2.0, MIT). Their license texts and which skill came from where are in
THIRD_PARTY_LICENSES/.
The original build draft specified an MIT badge, on the assumption this repo would contain a fork of MIT-licensed upstream code. It no longer does, so the repo's existing Apache-2.0 license was left alone. Switching to MIT is a one-line change if that is what the team wants.