Production Claude Code in May 2026: the Skills, Hooks, and Orchestration Layout That Actually Ships

The production directory layout, end to end

The .claude/ directory is where the orchestration lives. Everything outside it is your application. Inside it, five things matter: skills/, commands/, settings.json, settings.local.json, and CLAUDE.md. Here is the exact tree from a client engagement at dvnc.dev:

CLAUDE.md is the project constitution. It tells Claude Code what this codebase is, what it must never do, and which skills are in scope. Keep it under 400 words. The model reads it on every session start; padding it with policies nobody checks is how you get a 900-token context tax on every invocation.

settings.json is committed. settings.local.json is not. The split matters because settings.local.json carries developer-specific allowlists and local tool paths that have no business in version control. The pattern is:

The deny list is not aspirational. git push stays out of the allow list because Claude Code pushing directly to main on a client repo is an incident, not a feature. .env* stays denied because I have watched a model helpfully write a .env.production with placeholder values over a real one.

settings.local.json typically looks like:

Permissions in settings.local.json merge with settings.json. The local file wins on conflict.

Skills versus slash commands: where each one wins

Skills and slash commands solve different problems and conflating them is the most common layout mistake.

A skill is a steering primitive. It tells the model what kind of thinker to be for this session. typescript.md does not list commands; it establishes priors: prefer unknown over any, never widen a union in a type guard, keep function signatures under four parameters. When a skill fires, it shapes every tool call the model makes for its duration. Skills are declarative.

The effort field is new in 2.1.130. It accepts low, normal, and high. low means the model skips extended reasoning passes and returns faster at lower token cost. high means it reasons through edge cases before writing code. For a review.md skill I set effort: high. For test.md running unit test generation I set effort: normal. The practical difference on a complex type refactor is roughly 40 seconds and $0.08 per invocation. On a test stub generation pass, low is fine and saves both.

A slash command is a deterministic workflow. /pr-ready runs in sequence: typecheck, lint, test, generate a summary of changed files, and print the result. It does not make decisions; it executes steps. The model is the executor, not the planner.

The boundary is clear: if you are giving the model a set of rules to apply when it thinks, use a skill. If you are giving it a sequence of commands to run mechanically, use a slash command.

One non-obvious interaction: skills can disable model invocation entirely for specific file patterns. A skill with effort: low and triggers: ["*.svg"] will handle SVG file reads without spinning up a reasoning pass. For projects with large asset trees this is a meaningful token reduction.

The hooks pattern that catches 80% of QA failures

Three hook events matter in practice: PreToolUse, PostToolUse, and SessionStart. The other events exist but they fire in situations where you either cannot recover (session crash) or do not need to act (tool cancel).

PreToolUse is your write guard. It fires before any tool executes. The job is to block destructive writes before they happen, not clean them up after.

PostToolUse runs after a tool completes. The job here is to catch the failure the model would otherwise silently move past. TypeScript errors are the main case: Claude Code will write a file, see the write succeed, and continue. It does not automatically re-run the type checker. You have to.

ctx.warn does not block execution. It injects the error output into the model's context so the next prompt has the type errors visible. In practice the model fixes them on the next pass 80% of the time without a human prompt.

SessionStart is the hook that keeps breaking, and it broke harder after Claude Code on the Web launched. The Web client does not inherit your shell environment. It does not have your $PATH, your .nvmrc, or your $DATABASE_URL. If your SessionStart hook calls which psql and psql is not in the Web client's PATH, the hook throws, and Claude Code starts the session with no environment context at all.

The fix is to make SessionStart defensive about environment:

Every external call is wrapped in try/catch. Every missing value has a graceful fallback. The hook reports what it finds rather than asserting what it expects to find. This version runs identically in the local CLI and in Claude Code on the Web.

What 2.1.130 through 2.1.138 actually changed in May 2026

Four changes landed that matter for production use. They are not equally important.

Effort levels (2.1.130) are the most immediately useful. Before this, skills had no cost control. Every skill invocation spun up the same reasoning budget regardless of task complexity. Setting effort: low on skills that handle mechanical tasks (test stub generation, import sorting, changelog formatting) dropped token spend by about 30% on the client stacks I measured. The non-obvious part: effort levels interact with max_thinking_tokens in settings.json. If you have both set, effort level caps the ceiling; max_thinking_tokens sets the hard limit. Set both or set neither; mixing them produces confusing behavior where a high effort skill silently underperforms because max_thinking_tokens is still at the default 1000.

The --plugin-url flag (2.1.132) lets you point Claude Code at a URL rather than a local MCP server binary. In practice this means you can run a shared MCP server on a Hetzner CX22 box and have every developer on a project connect to it without local installs. It also enabled gateway model discovery in the same release: if the server at your plugin URL exposes a /models endpoint, Claude Code will populate the model picker from it automatically. For teams routing through a LiteLLM gateway, this is significant; you no longer maintain a static model list in settings.json.

MCP OAuth refresh (2.1.137) fixed the bug that had been dropping authenticated MCP connections after 60 minutes. The fix is straightforward but the behavior before the fix was subtle: the connection would appear active, tool calls would succeed for cached resources, and only requests that required a fresh API call would silently 401. The session log showed nothing useful. The fix landed in 2.1.137 and is verified against the standard OAuth 2.0 token refresh flow. If you were working around this with a cron job that restarted your MCP server every 45 minutes, you can stop.

The changelog entry that looks minor but is not: 2.1.134 changed how Claude Code resolves model names when a gateway is present. Previously, if you set model: claude-opus-4-5 in settings.json and your gateway had that model available under a different name, Claude Code would fail silently and fall back to a default. Now it queries the gateway's /models endpoint and resolves aliases. The practical implication is that settings.json model names can now match your gateway's display names rather than Anthropic's canonical names, which matters when you are routing through a proxy that renames models for cost reporting.

Where this layout breaks

The directory and hooks pattern I described works well for solo engagements and small teams. It starts showing seams at around five developers and breaks outright at fifty.

The immediate failure mode for larger teams is settings.json merge conflicts. When everyone is adding allowlist entries, the permissions array becomes a conflict surface on every branch. The fix is to move permissions into per-developer settings.local.json files and commit only the minimal shared allow list in settings.json. This works until your team needs to audit what permissions are actually in use, at which point local files are invisible to any central audit.

The skills directory scales better than permissions, but skill authorship becomes contentious. Who owns typescript.md? When a senior engineer changes the union type rule, every open PR that has staged changes against that skill gets inconsistent behavior depending on when Claude Code loads the skill file. The answer is to version skill files (e.g., typescript-v2.md) and update settings.json as a deliberate migration, not an in-place edit. This is tedious and nobody does it until they get burned once.

The cost shape at scale is the deeper issue. At one developer, effort: high on review skills is fine at maybe $4 a day. At fifty developers, that number is $200 a day and the usage patterns are invisible without centralized logging. The daily cap pattern I use on client projects is a PreToolUse hook that reads from a shared Redis counter and blocks if the day's spend exceeds a threshold. The threshold is set per environment: $15 on local dev, $50 on staging. It is blunt, but a $612 bill at 2am from a runaway agent session is what it prevents.

The other place this layout breaks is Claude Code on the Web when your workflow depends on local filesystem state. Commands that call git diff, read from .env, or check lockfile changes all assume a local checkout. In a Web session you either need to provide that context explicitly in CLAUDE.md or accept that those commands will partially fail. SessionStart helps here, but it cannot fully substitute for a real checkout.

For a 50-engineer org, I would replace the flat skills/ directory with a registry served by the plugin URL endpoint, version skills explicitly with semver, add centralized spend logging to every PostToolUse hook, and require PR reviews on settings.json changes the same way you would require them on CI config. None of that is necessary for a solo engagement or a three-person client project, and adding it early is overengineering.

Next quarter I am going to look hard at moving the hooks to a shared MCP server rather than local TypeScript files. The --plugin-url flag makes that feasible now in a way it was not in April. The payoff is that hooks become deployable artifacts with their own test suite and version history, rather than files that live in the client repo and accumulate bespoke exceptions. The tradeoff is that every session requires a network round-trip for hook execution. At 5ms per call in the same region, that is acceptable.

The Claude workflow build-out on the Anime.js project covers how the two-phase approach and minimal-base principle apply when Claude Code is the primary builder rather than a reviewer. The hooks pattern described here is the verification layer that sits on top of that workflow: the build-out tells Claude Code what to make, the hooks tell it when it has made something wrong.