Configuring Claude Code
and Codex

The configuration is not a set of files dropped into ~/.claude. It is a build pipeline. The source files live in ~/.config/ai-agents/src/ and no client reads them. A render script produces an immutable release from them, and it is that release's artifacts that get installed into the home directory.

This indirection gives both agents a configuration that is consistent by construction. Hand-editing ~/.claude/CLAUDE.md would work, but would leave ~/.codex/AGENTS.md behind, and would produce 2 agents with different judgment on the same code.

Enlarge ↗

The most common mistake is putting a rule that must be guaranteed into an instructions file. The model will read it, follow it often, and forget it sometimes. If forgetting it is costly, it belongs in a hook, not a sentence.

The 2nd mistake is letting the instructions file accumulate. It stays in the context of every session, on every project. Every line is paid for in context over the entire lifetime of the machine's use. A long procedure reserved for one specific task belongs in a skill: only its description weighs until the body is loaded.

Enlarge ↗

scripts/render.mjs reads src/, produces a directory under releases/, and names it after the SHA-256 of its normalized manifest. 2 renders of the same content produce the same identifier; a single byte of difference produces a different directory. The current pointer is a symbolic link to the active release.

The sourceCommit field is only the base Git reference. The manifest separately binds the actual content through sourceProvenance.contentDigest, and every rendered byte through manifest.artifacts. The distinction matters because a render produced from a modified working tree stays traceable, whereas a plain commit hash would lie.

{
  "schemaVersion": 1,
  "releaseId": "f4528d92…e657847",
  "sourceCommit": "27cb7932…866d0e6",
  "sourceProvenance": {
    "commitRole": "base-reference-not-content-proof",
    "contentBinding": "manifest.sources",
    "contentDigest": "f5e7ea7a…8c5a0067",
    "releaseBinding": "manifest.artifacts"
  },
  "requirements": { "node": ">=22" },
  "artifacts": {
    "claude/CLAUDE.md": { "hash": "8f9790e7…", "mode": 420, "type": "file" },
    "codex/AGENTS.md":  { "hash": "…", "mode": 420, "type": "file" }
  }
}

The installer uses an exclusive lock, compares the exact preimages of the live files, writes atomically target by target, and logs durably. A stale preimage invalidates the approval: if a file has changed between validation and writing, the transaction stops. Rollback only restores a target that still matches its recorded postimage.

# which release is active
readlink ~/.config/ai-agents/current

# drift between the live Claude copy and the projection
node ~/.config/ai-agents/scripts/check.mjs --home

# state of both skill roots
node ~/.config/ai-agents/scripts/inventory.mjs

The 2 hosts do not read skills from the same place. Claude Code reads ~/.claude/skills, Codex reads ~/.agents/skills then ~/.codex/skills. The release provides one projection per host, but they are not installed the same way.

Enlarge ↗

Both Claude Code bugs are referenced in the sources: issue 38051 for the symlinked root being ignored, issue 50052 for the link being deleted on auto-update. The real copy costs a disk duplication and a drift risk; that is the price of a root that survives an update.

Claude Code renders global instructions flat. The rendered file contains no mutable @ import, because a broken import would make the whole block silently disappear. The pipeline therefore renders a single file, and the long editorial reference stays a separate file, loaded only when a long writing task justifies it.

Alongside the main file, ~/.claude/rules/ carries 5 topical rules, also loaded in context.

A skill is a directory containing a SKILL.md with a YAML frontmatter. The description field is the main information the model sees before deciding whether to load the skill, along with its name. A vague description produces a skill that never triggers, or one that triggers all the time.

---
name: my-skill
description: What the skill does. Use when <trigger situations>. Do not use for <what looks similar but does not belong here>.
---

The decisive point is writing both boundaries, when to use it and what looks like it but is not. Without the negative boundary, 2 neighboring skills fight over the same prompts and the model picks one at random.

The workstation carries 95 global skills, 35 agents, and about 48 commands. At this scale, 2 mechanisms prevent saturation: the skillOverrides field in settings.json, which carries 80 entries turning skills off or restricting them to user-invocable-only, and the BM25 router described in part III.

A hook receives JSON on its standard input and decides. On PreToolUse, an exit code of 2 blocks the call and sends the message back to the model so it can correct course, without failing the session. What that code does depends on the event: on UserPromptSubmit it rejects the prompt, and on PostToolUse the tool has already run. This mode is preferable because a hook that breaks a session ends up disabled, and is then worth nothing at all.

"PreToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      {
        "type": "command",
        "command": "~/.config/ai-agents/releases/d16f4a6c…866bfc84/hooks/claude-adapter.sh",
        "timeout": 5
      }
    ]
  }
],
"UserPromptSubmit": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "env SKILL_ROUTER_HOST=claude SKILL_ROUTER_DATA_DIR=\"~/.local/state/ai-agents/skill-router/claude\" node \"~/.config/ai-agents/releases/d16f4a6c…866bfc84/hooks/skill-router/bm25-suggest.js\"",
        "timeout": 5
      }
    ]
  }
]

The 3 mechanisms do not overlap. deny outright refuses a command or path pattern. ask pauses to request confirmation. The sandbox is OS-level isolation, applied to each shell command taken separately.

Enlarge ↗

The excludedCommands list takes commands out of isolation, so it deserves a careful read. That is necessary for gh, docker, or package managers, but every entry is a deliberate breach. It has to stay justifiable line by line.

"permissions": {
  "defaultMode": "auto",
  "deny": [
    "Bash(git push --force *)",
    "Bash(git reset --hard *)",
    "Bash(gh repo delete *)",
    "Read(**/.env)",
    "Read(**/*.pem)",
    "Read(**/.ssh/**)"
  ],
  "ask": [
    "Bash(git push *)",
    "Bash(gh pr merge *)",
    "Bash(npm publish *)",
    "Bash(vercel *--prod*)"
  ]
},
"sandbox": {
  "enabled": true,
  "autoAllowBashIfSandboxed": true,
  "allowUnsandboxedCommands": false,
  "network":     { "allowedDomains": ["<44 domains>"] },
  "filesystem":  { "allowWrite": ["<22 directories>"], "allowRead": ["<2 entries>"] },
  "credentials": { "files": ["<5 paths>"], "envVars": ["<13 variables>"] },
  "excludedCommands": ["gh *", "glab *", "docker *", "<92 more>"]
}

An agent with 95 skills would keep as many descriptions in context, before any body is loaded. It has to decide, before every turn, which ones deserve to be flagged.

BM25 was chosen. The accepted trade-off is that the router compares words, not meanings. In exchange, it is debuggable, since a score is a readable sum of per-term contributions.

BM25, or Okapi BM25, is the default ranking in Lucene, Elasticsearch, and SQLite FTS5. For every query term q present in document D, it computes a contribution, and the total score is the sum over all the query terms.

score(q, D) = IDF(q) × ( f(q,D) × (k1 + 1) )
                       ÷ ( f(q,D) + k1 × (1 - b + b × |D|/avgdl) )

IDF(q) = log( 1 + (N - n + 0.5) / (n + 0.5) )

f(q,D)  frequency of term q in document D
|D|     document length
avgdl   average document length in the corpus
N       total number of documents
n       number of documents containing q

Constants used: k1 = 1.2, b = 0.3

Enlarge ↗

`k1 = 1.2`, saturation. This is what prevents linearity. A document containing the word sitemap 10 times is not 10 times more relevant than a document containing it once. The function rises fast, then plateaus.

`b = 0.3`, length normalization. Without it, a long document wins mechanically, because it contains more terms, so more chances of matching. The |D|/avgdl factor penalizes documents longer than average. b = 0 disables normalization, b = 1 applies it fully.

The 0.3 value is low, deliberately. The corpus is made of sentences of 5 to 15 words, where length carries almost no information. A b close to 1 would unfairly penalize a detailed phrasing against an isolated keyword.

const K1 = 1.2;
const B = 0.3;

function computeIdf(docs) {
  const N = docs.length;
  const df = new Map();
  for (const doc of docs) {
    for (const t of new Set(doc.tokens)) df.set(t, (df.get(t) || 0) + 1);
  }
  const idf = {};
  for (const [t, n] of df) idf[t] = Math.log(1 + (N - n + 0.5) / (n + 0.5));
  return idf;
}

function scoreDoc(queryTokens, doc, idf, avgdl) {
  const tf = termFreq(doc.tokens);
  const dl = doc.tokens.length || 1;
  let score = 0;
  for (const q of queryTokens) {
    const f = tf.get(q);
    if (!f) continue;
    const num = f * (K1 + 1);
    const den = f + K1 * (1 - B + B * (dl / avgdl));
    score += (idf[q] || 0) * (num / den);
  }
  return score;
}

A raw score does not say whether to suggest. That is where the router's quality is decided, not in the formula.

Enlarge ↗

1. Maximum per target, never the sum

   A skill's score is that of its single best scenario. Summing would mechanically favor a skill with 40 scenarios over one with 10, regardless of relevance.

2. Threshold tau calibrated per target

   Every skill gets its own threshold, computed when the index is built. A target with fewer than 8 positive scenarios or fewer than 2 negatives is excluded from calibration, because below that the threshold would be tuned on noise. Positives are scored against the other positives of their own target, excluding themselves, otherwise the score is perfect by construction.

3. The threshold is calibrated on the skill's declared negatives

   Threshold calibration looks only at the skill's own scenarios: its positives, scored against its other positives, and its declared negatives. The comparison between neighboring skills comes later, in the cross-skill evaluation.

4. Sweeping every candidate threshold

   The threshold chosen is the one that maximizes F-beta over the whole set of observed scores, by testing every midpoint between 2 consecutive scores. The skill reaches status ok when the F1 measured at that threshold reaches 0.60, and stays in conflict otherwise.

5. The cross-skill evaluation decides eligibility

   A skill calibrated to ok is not suggestible yet. The builder replays every skill together, keeps those whose cross-skill F1 reaches 0.55, then drops the weakest one while the global F1 stays below 0.70. Only the skills that survive that pass carry eligible.

The optimization is asymmetric. The F-beta used sets beta = 2, which makes recall weigh 4 times more than precision. A missed suggestion is a skill that goes unused. An extra suggestion is a line the model ignores. The policy therefore accepts false positives to reduce missed suggestions.

# index summary, without writing anything
SKILL_ROUTER_HOST=claude node \
  ~/.config/ai-agents/current/hooks/skill-router/routing/build-index.js --dry-run

# rebuild the index
SKILL_ROUTER_HOST=claude node \
  ~/.config/ai-agents/current/hooks/skill-router/routing/build-index.js

# test a suggestion end to end
echo '{"prompt":"prépare un message pour l équipe"}' \
  | SKILL_ROUTER_HOST=claude node \
      ~/.config/ai-agents/current/hooks/skill-router/bm25-suggest.js

function scoreSkills(queryTokens, scenarios, index) {
  const bySkill = new Map();
  const negativeBySkill = new Map();
  for (const s of scenarios) {
    const raw = scoreDoc(queryTokens, s, index.idf, index.avgdl);
    if (s.polarity === 'neg') {
      if (raw > (negativeBySkill.get(s.skill) || 0)) negativeBySkill.set(s.skill, raw);
      continue;
    }
    if (s.polarity !== 'pos') continue;
    if (raw > (bySkill.get(s.skill) || 0)) bySkill.set(s.skill, raw);
  }
  // One score per skill: its best scenario, never the sum.
  return [...bySkill]
    .map(([skill, score]) => ({ skill, score, negativeScore: negativeBySkill.get(skill) || 0 }))
    .sort((a, b) => b.score - a.score);
}

function filterEligible(scored, thresholds, activeSkills) {
  return scored.flatMap((candidate) => {
    const threshold = thresholds[candidate.skill];
    const active = activeSkills[candidate.skill];
    if (!threshold || threshold.status !== 'ok' || threshold.eligible !== true || !Number.isFinite(threshold.tau)) return [];
    if (Number.isFinite(candidate.negativeScore) && candidate.negativeScore >= candidate.score) return [];
    if (candidate.score < threshold.tau || !active || !active.skillMd) return [];
    return [{ ...candidate, skillMd: active.skillMd }];
  });
}

Handing over this configuration as-is would make no sense, because it contains project paths, MCP servers with their keys, and 35 agents most of which serve only one specific purpose. The starter kit carries the structure and a standalone BM25 router, with 2 example skills so the mechanics are verifiable right from installation.

agent-config-starter/
├── README.md                     the 4 layers, when to use which
├── install.sh                    dry run by default, --apply to write
├── docs/bm25.md                  the full algorithm
├── claude/CLAUDE.md              generic global instructions
├── claude/settings.json          permissions + hooks
├── codex/AGENTS.md               mirror
├── codex/config.toml.example     commented, no secrets
├── hooks/anti-ai-markers.sh      PreToolUse hook, exit 2 = fix yourself
├── hooks/skill-router/           standalone BM25 router, 4 files
└── skills/<name>/                example skills with corpus

Its install script runs in dry-run mode by default and only writes with --apply. It backs up to .bak.<timestamp> before any overwrite, and never merges an existing settings.json. It drops a .new file next to it and leaves the merge to a human. Automatically merging configuration JSON overwrites an existing field or resolves a conflict wrongly, without saying so.

Enlarge ↗

This behavior is consistent with the design, in which activating hooks is a separate transaction, distinct from installing instructions and skills. It requires explicit approval tied to a digest. The practical consequence is that this transaction has to be replayed after every hook change, and nothing reminds anyone of that.

The two cover different objects and are therefore not strictly redundant. The question to settle is whether routing agents and commands still deserves a separate engine, or whether the 2 corpora can merge into the host-aware router.

The release router does not carry this flaw, because its guardrail requires the name preceded by the sigil, /name for Claude and $name for Codex, which tells apart an invocation from a vocabulary word. This is the version to adopt if the legacy router is kept. The reusable starter kit was fixed in this direction, and a test case covers it.

This report shows one configuration, as inspected on September 16, 2026. The pieces below, published on the same site, take each layer separately and lay out the reasoning, the measurements, and the mistakes that led to this shape.

BM25 / Okapi BM25

Lexical ranking function that scores a document's relevance to a query from term frequency, term rarity, and document length. Default ranking in Lucene, Elasticsearch, and SQLite FTS5.

Hook

Script executed by the harness at a session lifecycle event. Receives JSON on its standard input. An exit code of 2 sends a correction message back to the model without failing the session.

Projection

Skill tree rendered by a release for a given host. Claude receives a real copy, Codex a symbolic link.

Skill

Directory containing a SKILL.md file with frontmatter. Loaded on demand. Only its description is seen before the decision to load it.

Conclusion

The value of this configuration is not in the number of skills, nor in how fine-tuned the router is. It is in a clean separation between what is suggested to the model and what is imposed on it, and in a pipeline that keeps the 2 hosts consistent as long as the installed release is checked.

Each of the 3 gaps calls for a disposition. Pinning the hooks to a release earlier than the current pointer has no effect today, but it will go stale with no signal: the activation transaction has to be replayed after every hook change. The legacy router sits on disk without being wired: either it gets a deliberate wiring back, or it is removed. Its anti-duplicate guard has to be fixed before any new wiring, as it already was in the starter kit.

To pass on the method without passing on the inventory, the starter kit's structure is enough: the 4 layers, a verifiable router, and 2 example skills, which the recipient fills in at the pace of their real needs. The starter kit itself is not published to date.

Dated sources

• Claude Code, issue 38051: symlinked skills root ignored · 16 September 2026 · Source documentaire
• Claude Code, issue 50052: skills link deleted on auto-update · 16 September 2026 · Source documentaire
• Official Claude Code hooks documentation · 16 September 2026 · Source documentaire
• Okapi BM25, description of the ranking function · 16 September 2026 · Source documentaire
• Elasticsearch, BM25 similarity and the role of the k1 and b parameters · 16 September 2026 · Source documentaire

“Accessed on” gives the date the source was read. A source may have been published earlier and later updated.

Update history