The input was already clean. It had sources, version numbers, caveats, and a clear structure. I had removed most of the easy AI tells beforehand. That made the test useful: the skills could not simply delete stock phrases and declare victory.

I did not get four versions of the same cleanup. I got four editors working at different altitudes.

The four are not equally popular. A 12 September snapshot put Humanizer at about 47,000 GitHub stars and Clarity at about 200, while Stop Slop led the skills registry with roughly 14,000 installs against Humanizer’s 6,500. Neither count says anything about what a skill does to a sentence, which is what the runs were for.

1. Humanizer: the lightest hand

Humanizer changed 14 passages by my diff and reduced the draft by one word. Its own summary described five prose edits plus heading changes. One passage can contain more than one edit, so those counts measure different things.

It documents 25 patterns, yet produced the most conservative result. It caught title-case headings, one shallow -ing rider, a repeated list, and a word echo.

Before: “A2UI 0.9.1 is current, and 1.0 remains a candidate.”

After: “A2UI 0.9.1 is current, and 1.0 is still a candidate.”

That restraint is the value: on a solid draft, it fixes recognizable tells without rebuilding the argument.

Humanizer found a short list of local problems and stopped.

Its report explains why the list was short. It found no em dashes, no decorative bold, no curly quotes, and no stock AI vocabulary to remove, so most of its 25 patterns had nothing to match. The next skill’s word checks came back just as empty.

2. No AI Slop: structural paragraph edits

No AI Slop touched 16 passages and removed 15 words. None of its listed banned words or phrases appeared in this run, so it named actors, shortened tangled sentences, removed duplicated material, and killed the recap.

Before: “cross-client portability remains to be proved”

After: “no one has proved cross-client portability yet”

This result was sharper, but one edit showed the risk. “A common adoption path starts with” became “Most teams start with.” The rewrite is more direct, yet it makes a broader factual claim than the source supports.

It gave the draft structural momentum without flattening the voice, at the cost of one sentence’s precision.

No AI Slop’s word checks stayed quiet, so it worked on structure instead.

Its own summary counted seventeen structural edits against my diff’s sixteen, the same gap between self-report and diff that Humanizer produced. The work itself was plain mechanics: inanimate subjects and passive constructions replaced, one -ing explainer split, repeated detail condensed. Stop Slop went after the same passive constructions and did not stop there.

3. Stop Slop: the strongest intervention

Stop Slop changed 37 passages, more than twice any other run, and made the draft five words longer.

The extra length comes from the rule: naming the actor behind a passive verb usually costs words.

Before: “it is not a W3C Standard”

After: “the W3C has not made it a Standard”

It also replaced “an agent’s” with “your agent’s” throughout. This was the most prescriptive result: named actors, direct reader address, fewer hedges, and fewer abstract subjects.

Explicit rules make it consistent, and the same force can flatten technical prose you wrote flat on purpose.

Stop Slop changed the most passages because it enforced the most rules.

The rule sheet behind that consistency is close to absolute: no adverbs, no passive voice, no Wh-word openings, two list items instead of three, no em dashes. It also reaches past grammar into abstraction, turning “The industry is converging on a different contract at each boundary” into “Vendors and working groups are converging on a different contract at each boundary.”

The run then scored itself 34/50 to 41/50 on its own five dimensions, which is a workflow score rather than independent evidence. All three skills so far began by checking the draft against a list. The fourth began somewhere else.

4. Clarity: the only one that zoomed out

Clarity changed 15 passages and removed 10 words. It was the only run whose summary explicitly diagnosed the whole piece before editing it.

From there it found a problem none of the other three summaries reported: all seven sections ended with the same verdict cadence, “X is mature, but Y remains Z.” Clarity varied those endings, reordered the lead, cut staged transitions, and removed the repeated conclusion.

It still edited sentences; that work came second.

Before: “MCP has broad support across clients, servers, and SDKs, making it the clearest de facto standard in this map.”

After: “MCP has broad support across clients, servers, and SDKs. It is the clearest de facto standard in this map.”

It reads the article before it reads the sentence.

Clarity found repetition across sections, not just inside sentences.

The four runs were not disjoint. Three of them split the same shallow -ing tail and condensed the same repeated OpenTelemetry passage, and two cut the same recap ending. They converged on the local repairs and diverged on everything above them.

The takeaway

The four runs landed at different altitudes. Clarity read the piece. No AI Slop concentrated on the paragraph. Humanizer and Stop Slop spent more attention on sentences and words, from opposite ends of the same level: 14 changed passages against 37. These are observed emphases from one run, not hard capability boundaries.

The rule sheets explain those emphases better than a single score. They disagree on basic choices such as passive voice, adverbs, list length, and whether scoring belongs in the workflow.

The skills disagree on editing policy, not just editing strength.

That turns the comparison into a routing decision. Start with the job, not the most aggressive rule set.

Pick the skill for the job instead of stacking all four.

Choose by the failure you want to prevent. Humanizer for conservative cleanup, No AI Slop for paragraph structure and voice, Stop Slop for explicit rule enforcement, Clarity for whole-piece diagnosis.

Stacking all four blindly is not more thorough. Their priorities can collide, and one editor can undo another’s choices. My practical rule: one skill, two at most, then I read the diff myself.

Method note: I ran the four skills separately against the same draft.md (my next post) Passage counts come from the published thread and describe one qualitative run, not quality scores or a reproducible benchmark. Star and install counts are from a 12 September 2026 snapshot and describe repositories, not writing.

That is why these eight books deserve another look. Their ideas predate today’s coding agents, even where the editions are recent. What follows is my take on applying them to AI-assisted development, with further reading for specific gaps.

Decide what is worth building

An agent can turn a feature request into a convincing prototype before anyone has established that the idea is valuable. A working demo can make the solution feel more certain while the demand for it remains an assumption. That makes it easier to fall into the build trap: shipping more features while the customer or business outcome stays the same.

The book connects product strategy to the decisions teams make every day. Its distinction between outputs and outcomes gives engineers a reason to challenge a request beyond its technical feasibility. What problem are we solving, what should change for the user, and how will we know? Engineers contribute to that evidence through experiments, instrumentation, and feedback from running systems.

For more on discovery, read Continuous Discovery Habits, or Testing Business Ideas for testing business assumptions before committing to a solution.

Agree on what correct means

Once we know what is worth building, we need to agree on its behavior. Natural language leaves room for several plausible interpretations, and an agent can choose one, implement it, and generate tests that repeat the same assumption. Passing those tests tells us little about whether the assumption was right.

This book, published in 2011, offers a practical way to resolve that ambiguity. Product managers, domain experts, and engineers work through concrete examples before that interpretation becomes working code. A request to let customers cancel orders, for example, needs answers about orders that have shipped, partial shipments, and payments already collected. Those cases expose disagreements that a general requirement can hide.

The important examples can then become executable acceptance checks and living documentation. They give an agent a reference for expected behavior when a prompt changes or an implementation is rewritten. Their value comes from agreement with domain experts, independently of the assumptions in the generated code.

In his ten-year retrospective, Gojko Adzic explains why the conversations around examples often proved more valuable than the resulting tests. Use Given-When-Then where it helps; the format alone will not resolve a disagreement.

Read Writing Effective Use Cases for a more structured treatment of user goals, success paths, and exceptions.

Make business meaning explicit

Examples reveal another problem: the same word can mean different things to different teams. A model may know the language of banking or logistics without knowing what “account” or “completed” means inside your organization. If that meaning is wrong, generation can carry the mistake into schemas, APIs, events, and tests.

Domain-driven design gives us a way to discover and preserve those meanings. A ubiquitous language is developed with domain experts, so the terms in the software reflect how the business works. Bounded contexts define where a particular model applies, and context maps make the relationships between models explicit. This matters when an agent reuses code across services: billing and fulfillment may have similar schemas but different rules for what makes an order complete.

The book connects these choices to implementation through business logic and integration patterns. Types, state transitions, and tests can then constrain generated changes, while domain terminology in the code gives the agent context about which rules belong where.

The distinction between core, supporting, and generic subdomains helps decide where careful modeling is worth the effort, while simple business logic can stay simple.

Read Domain Storytelling for discovering knowledge with domain experts, or Domain Modeling Made Functional for expressing rules in types so invalid states are harder to represent.

Choose architectural trade-offs that fit the system

An agent can scaffold a service, its API, and its deployment files without resolving whether the service needs to be separate. Code generation reduces some of the effort of creating a boundary, but the latency, coordination, and failure modes it introduces remain. A design that is easy to generate may still be expensive to operate and change.

This book develops trade-off analysis through the problems of breaking systems apart and putting them back together. Service granularity, coupling, data ownership, orchestration, and distributed transactions are connected decisions. Moving a boundary may make deployment easier while making consistency and failure recovery harder.

That reasoning also matters across repeated agent changes. A locally simpler implementation may remove an intentional boundary or introduce a dependency the team had rejected. Explicit constraints and the reasoning behind them give both agents and reviewers context that the code alone may not reveal.

The examples lean heavily toward distributed architectures, so use them to evaluate whether the benefits justify the added complexity in your system.

Read Just Enough Software Architecture for matching the amount of architecture work to the project’s risks.

Understand your data guarantees

A generated database client may look correct while leaving unanswered which state is authoritative, how stale a read may be, or what should happen when an update arrives twice. These questions affect every cache, event consumer, search index, and model input that depends on the data.

The book connects data models and storage choices to the guarantees an application needs. Its coverage of replication, transactions, consistency, and partial failure helps explain what an API promises and where that promise ends. Schema evolution and batch and stream processing extend the discussion to systems that must change while continuing to serve readers and writers.

This becomes visible when an agent changes a schema and updates all the code it can see. Older consumers, stored events, and derived indexes may still depend on the previous structure. Data contracts make that compatibility requirement explicit, alongside the rules for duplicates, ordering, and freshness that a successful API call cannot establish.

Read Database Internals for storage engines and database machinery, or Streaming Systems when event time, watermarks, and stateful processing dominate the design.

Identify threats and trust boundaries

The security questions extend beyond the code an agent produces. A coding agent may read a README or tool response while also having shell access and credentials. Through prompt injection, untrusted content can influence actions taken with those privileges. The same concern applies when the application itself gives agents access to tools and data.

Shostack’s four-question framework provides a repeatable process: understand the system, identify what can go wrong, decide how to respond, and review the result. Mapping data flows and trust boundaries makes the system concrete, while a method such as STRIDE helps identify threats systematically.

The 2014 book needs to be supplemented with knowledge of these newer attacks, but its method connects them to familiar design questions: which inputs are untrusted, what authority does the agent have, and where are access controls enforced? A prompt can steer the model’s behavior, while enforced permissions limit the available actions even when it follows a malicious instruction.

Read Designing Secure Software for secure implementation practices that complement threat modeling.

Design for production failures

A secure system can still fail under ordinary load or a slow dependency. An agent may wrap a failing API call in a retry loop without accounting for retries already built into the client library. The code can look more resilient while multiplying requests against a struggling dependency.

Release It! connects application design to these production consequences. Its failure patterns explain how blocked threads, mismatched capacity, and cascading failures turn local trouble into system-wide problems. Its stability patterns, including timeouts, circuit breakers, bulkheads, and back pressure, provide ways to contain that trouble.

These patterns require decisions about how much work the system can accept and what happens when it reaches its limits. Runtime visibility and controls let us observe and adjust that behavior, while deployment practices and failure rehearsal test whether recovery actually works.

Pair it with Observability Engineering, Second Edition for understanding system behavior through production telemetry.

Improve the whole delivery flow

Several coding agents can work in parallel while the team still has one review queue. Faster generation can therefore increase work in progress and integration conflicts without getting changes to users sooner.

Accelerate connects delivery performance to technical practices, architecture, management, and culture. Small batches, continuous integration, deployment automation, loosely coupled systems, and effective feedback help teams move changes through the whole process. Throughput and stability need to be considered together, so an improvement in one does not hide a problem in the other.

Evaluate AI adoption by whether changes reach users sooner, how often they fail, and how quickly the service recovers. Commits, generated lines, and suggestion acceptance rates may explain tool usage, but they do not establish an improvement in delivery or product outcomes.

The book predates today’s coding agents, but DORA’s guidance on small batches makes the connection explicit: large generated changes remain difficult to review, test, and integrate.

Read Continuous Delivery for the delivery machinery, or Team Topologies, Second Edition for team boundaries, cognitive load, and interactions that help or hinder the flow of work.

Where to start

Start with the problem your team is struggling with. The map below pairs each main book with two alternatives for going deeper, so you can choose the path that is most relevant to your work.

AI can generate more of the implementation, but it also lets weak assumptions spread through a system much faster. These books remain relevant because they teach us how to reason about everything the generated code depends on, from what to build to how the result behaves in production.

Which software engineering book would you add to this list, and why has AI made it more relevant?

👋 Found this useful? Like and restack it for other software engineers.

This is why a fast database query or LLM call does not prove that the application is fast. We need to measure the full path as a distribution and identify what controls the percentile we care about. Once we know what dominates the critical path, we can bring requests and data closer, reduce work, execute independent work concurrently, or anticipate predictable work. These are general distributed-system patterns that apply equally to AI applications. The map below adapts latency optimization ideas from Pekka Enberg’s Latency into four practical pattern categories.

An agentic request may cross RAG retrieval, databases, a model gateway, one or more LLMs, MCP or other tool servers, and an orchestration loop. A large part of the latency often comes from the LLM calls, but the model is still only one segment of the path. I covered model-serving optimizations such as quantization, decoding, and server scheduling in this talk and this post. In this post, I explicitly focus on non-model latencies across the application path.

Each category bellow explains the patterns through traditional application examples, then how they apply in an AI application. Taken together, there 19 latency patterns across four categories.

Locality Patterns

The first thing to check is whether the request and the data it needs are far apart. That distance may be geographical, between services, between processes on one host, or even between a CPU core and memory. There are four common patterns for shortening this part of the path.

1. Colocation Pattern

Colocation shortens or removes a boundary between the source and the target. The scale can vary significantly. A CDN can serve the dashboard shell closer to the user. Application logic can run in the same region as its database instead of crossing a wide-area network. On one host, CPU affinity and NUMA-aware placement can keep hot work and memory near the cores that use them. The mechanism is the same even when the distances are very different.

When to use. Use colocation when the distance between components that frequently interact is a measurable part of the critical path.

The main trade-off. Tighter placement can reduce scheduling flexibility and make failover or scaling across locations more difficult.

2. Replication Pattern

Replication places a readable copy in more than one location. A nearby replica can shorten the read path, but only when the application is allowed to read from it. For example, a dashboard can read tenant data from the nearest regional replica instead of crossing regions for every query.

When to use. Use replication for read-heavy paths that can tolerate a clearly defined level of staleness.

The main trade-off. Synchronous replication may keep the write waiting for required acknowledgements, while asynchronous replication can respond earlier but allow lag. The application must decide which reads can tolerate older data, how they are routed, and what should happen during a failure.

3. Partitioning Pattern

Partitioning divides data or work into units that can be placed and processed independently. It does not make anything closer by itself, but a good partition key can keep a tenant’s query and data together. For example, a dashboard can partition metrics by tenant so that most queries touch one shard rather than several.

When to use. Use partitioning when requests and data share a stable key that can keep related work within one partition or location.

The main trade-off. A poor key can create a hot partition, while a request that spans several partitions brings routing and coordination back onto the critical path.

4. Caching Pattern

Caching creates a shortcut for repeated reads or computation. The hit ratio tells us how often the shortcut works, while the miss penalty tells us how painful the original path remains. For example, a dashboard can cache common aggregates close to the application instead of recalculating them for every page load.

When to use. Use caching when reads or computations repeat and their results can be safely reused.

The main trade-off. A high hit ratio can still produce a bad tail when misses are expensive. Freshness, invalidation, and ownership determine whether the cached result can be trusted.

Choosing What to Bring Closer

In a traditional application, start with the kind of distance that creates the delay. Use colocation when two components communicate frequently, replication when reads are far from the source, partitioning when related data can be kept together, and caching when the same data or computation is requested repeatedly. The patterns can be combined, but each addresses a different reason for travelling across the system.

In an AI application, apply the same test to the orchestrator, the model provider, retrieval store, state store, and tools. Colocate dependencies that communicate frequently, replicate read-heavy knowledge where residency rules allow it, partition state by tenant or session, and cache repeated retrieval, schema discovery, session summarization, policy lookup, or model prefill work.

Work Reduction Patterns

If the latency trace points at computation as the bottleneck, the next move is to remove work. Work that no longer exists cannot delay the request, consume capacity, or create another failure point.

5. Algorithmic Work Reduction Pattern

An index over tenant and time can replace a full scan. A hash lookup can replace a linear search. Filtering before an expensive join or sort can reduce the dataset before the costly operation begins. These changes reduce the amount of work rather than making the same work slightly faster.

When to use. Use this pattern when query or computation cost dominates and a better algorithm, index, or data structure can reduce the work.

The main trade-off. A faster access path may require additional indexes, memory, preprocessing, or implementation complexity.

6. Selective Data Processing Pattern

A dashboard does not need the full object graph when the first chart uses five fields. Building large intermediate objects, copying them between layers, serializing them, and then discarding most of the result consumes time without changing what the user sees. A lean response should carry only what the next step needs.

When to use. Use selective data processing when the next step needs only a subset of the available data.

The main trade-off. Removing too much data can trigger another request or prevent a later step from completing.

7. Setup Reuse Pattern

Reusing an established connection, a parsed schema, or validated orchestration state avoids repeating the same setup on every request.

When to use. Use setup reuse when the same initialization cost is paid repeatedly and the resulting state can be retained safely.

The main trade-off. Reused state needs explicit lifecycle, freshness, isolation, and failure handling.

8. Request Coalescing Pattern

Combining several known reads into one request can remove repeated serialization, scheduling, and round trips. This is where request batching can help latency. For example, a dashboard backend can fetch the summary, alerts, and recent events in one call instead of making three sequential requests.

When to use. Use request coalescing when several predictable calls cross the same boundary and can be safely combined.

The main trade-off. A combined request can make one slow operation hold back all the others. It should be measured against the user-visible latency target, not assumed to be faster.

9. Runtime Tuning Pattern

Allocation, garbage collection, demand paging, scheduling, and context switches can all delay useful work. Profile the critical path first, then reduce only the runtime costs that measurably affect it. For example, a service may reduce short-lived allocations or tune its heap after profiles tie p99 spikes to garbage-collection pauses. These costs are measurable suspects, not default explanations for every slow service.

When to use. Use runtime tuning when profiles show that runtime overhead affects the percentile you are trying to improve.

The main trade-off. Runtime tuning can increase implementation complexity and may depend on a specific runtime, operating system, or hardware configuration.

Choosing What Work to Remove

In a traditional application, first identify what kind of work dominates the trace. Algorithmic work reduction changes how the result is found. Selective data processing reduces how much data moves through the path. Setup reuse avoids repeating initialization, while request coalescing removes repeated boundary crossings.

In an AI application, reduce latency by doing less work. Use regular code or indexed search for simple lookups instead of calling a model. Send only relevant information to the model, reuse existing tool connections, and combine calls that always happen together. Use a smaller model for simple tasks when it provides good enough results, stop generation when the answer is complete, and limit how much tool output enters the prompt. But do not remove so much context that the application must fetch more information and call the model again. That extra round trip may make the request slower overall.

Once the remaining work is necessary, the next question is whether it really has to run in sequence.

Concurrent Execution Patterns

Some work is necessary but does not need to happen in sequence. Suppose authentication must finish first, but four dashboard panels are then independent. Running them serially makes the user wait for roughly the sum of their durations. Starting them together can bring the wait closer to the slowest required panel, plus scheduling and coordination overhead.

10. Synchronization Avoidance Pattern

A contended lock can make otherwise short operations line up behind one owner. Immutable state may remove the shared dependency, while a single-owner design may replace lock contention with an explicit queue. The important question is whether another operation must finish or release something before this one can continue.

When to use. Use synchronization avoidance when coordination over shared state is a measurable source of waiting and the state can be made immutable, partitioned, or owned by one component.

The main trade-off. Removing a lock may move the waiting elsewhere or require a different state-management model.

11. Independent Concurrency Pattern

Concurrency lets several tasks make progress, while parallelism executes work at the same time. For the dashboard, separate panel reads can run concurrently. In an agentic application, a research agent can query independent document stores and market-data sources in parallel, then join the results before synthesis. If one tool needs an identifier returned by another, that dependency remains serial.

When to use. Use independent concurrency when required tasks have no data dependency and the system has enough capacity to run them together.

The main trade-off. Concurrency does not help when one task genuinely needs the result of another, and it can make latency worse when the fan-out exhausts a shared dependency.

12. Progressive Response Pattern

An event loop can use resources more efficiently while external I/O is pending, but it does not make the database, model, or remote service intrinsically faster. The visible latency improves when an AI application streams useful model output or an independently useful tool result instead of holding everything until the full task completes.

When to use. Use a progressive response when a partial result is independently useful and time to first useful result matters to the user.

The main trade-off. This pattern shortens time to first useful result, not full completion, and the client must handle partial or provisional state.

13. Concurrency Budget Pattern

A queue stores waiting; it does not remove it. If arrivals exceed capacity, the queue grows and tail latency follows. Set a concurrency budget, propagate deadlines and cancellation, apply backpressure, and stop work when the user no longer needs it. For example, a dashboard can allow only four panel queries to run at once rather than sending an unbounded fan-out to the database.

When to use. Use a concurrency budget when one request can fan out across services, databases, models, or tools and overload a shared dependency.

The main trade-off. A budget that is too low leaves capacity unused, while one that is too high moves the queue into a downstream dependency.

14. Hedged Requests Pattern

Request hedging reduces exposure to a straggler by sending equivalent copies and accepting the first valid response. For example, after a short delay, a service can send the same read to a second replica and use whichever valid response arrives first.

When to use. Use hedged requests when rare stragglers dominate tail latency, spare capacity exists, and the operation is idempotent or side-effect-free.

The main trade-off. Hedging spends extra capacity and can worsen overload if it is used without a strict budget.

Choosing What Can Run Together

In a traditional application, synchronization avoidance removes unnecessary waiting, while independent concurrency overlaps work that has no dependency. A progressive response changes when useful output becomes visible, not how fast the full operation completes. A concurrency budget protects shared capacity, while hedged requests spend additional capacity to reduce exposure to rare stragglers.

In an AI application, run independent model, tool, and retrieval calls at the same time. If one call needs the result of another, run them in order. Progressive responses, such as streaming, show useful results sooner but do not change which calls can run together. Limit how many model, agent, tool, and retrieval calls run at once to avoid overload. Use hedged requests only for operations that are safe to repeat. The goal is to reduce waiting, not to start as many calls as possible.

Anticipation Patterns

If a remaining delay cannot be removed or safely overlapped after the request arrives, we can anticipate likely work and move it earlier.

15. Predictive Prefetching Pattern

Once authentication identifies the user, the application may fetch the default dashboard before the browser asks for its first panel. This is a prediction about a future read.

When to use. Use predictive prefetching when the next read is predictable enough to justify occasionally wasted work.

The main trade-off. Prefetching helps only when the data arrives in time and is still useful when the application needs it. A wrong prediction consumes resources without shortening the request.

16. Optimistic Update Pattern

A filter can appear selected while persistence continues, as long as the interface shows that the change is pending and can roll it back after a failure. This improves perceived latency after the user acts. It does not make durable completion happen earlier.

When to use. Use optimistic updates when success is common, failure is visible, and the operation can be safely reversed.

The main trade-off. A failed operation requires rollback, and provisional state must never be presented as completed work.

17. Speculative Execution Pattern

Speculative execution runs a likely branch before the actual choice arrives. For example, a dashboard can start calculating the most common time range while the user is still opening the time-range filter.

When to use. Use speculative execution when a small number of likely branches can run safely, independently, and be cancelled.

The main trade-off. The work must be isolated and cancellable because a wrong prediction consumes resources without helping the request.

18. Precomputation Pattern

Maintaining a tenant aggregate as events arrive can replace repeated foreground computation with a read. Precomputation moves known work from the foreground request to the point where the source data changes.

When to use. Use precomputation when an expensive result can be refreshed as its source changes rather than calculated for every request.

The main trade-off. Precomputed results consume storage and refresh capacity, and they may be stale when the source changes faster than they can be updated.

19. Prewarming Pattern

A small worker pool, connection pool, or execution environment can be initialized before traffic arrives. Prewarming moves predictable setup cost off the foreground critical path.

When to use. Use prewarming when cold-start or setup cost is predictable and keeping limited capacity ready is affordable.

The main trade-off. Warm resources consume capacity even when no request uses them.

Choosing What to Do Earlier

In a traditional application, predictive prefetching prepares a likely read, optimistic updates show likely success before durable completion, and speculative execution starts a likely branch. Precomputation prepares reusable results when source data changes, while prewarming prepares resources before requests arrive. The difference is what is moved earlier: data, feedback, a branch, a result, or capacity.

In an AI application, start predictable work early. Once the application understands what the user wants, it can fetch likely context and start safe, read-only searches. It can also prepare reusable data such as embeddings, indexes, summaries, and policy information, or keep agent workers and model or tool connections ready to avoid setup delays. If the interface expects a tool action to succeed, show it as pending until it actually completes.

Measure whether this early work was used, finished in time, and reduced latency. Also track wasted work and actions that had to be reversed. Cancel work when it is no longer needed. If early work consumes enough resources to slow normal requests, it is not an optimization.

Find the Bottleneck, Apply the Pattern

Do not start by choosing a pattern. Start by tracing the full request and locating where delay enters the critical path: context retrieval, model access, tools, agent coordination, or verification and delivery.

Read the matrix in two moves. First, choose the column where the delay appears. Then move down that column and select the intervention that matches its cause:

• Locality Patterns: The request, data, or dependency is too far away.

• Work Reduction Patterns: The application performs unnecessary computation, data processing, or calls.

• Concurrent Execution Patterns: Independent work is waiting in sequence.

• Anticipation Patterns: Predictable work remains on the foreground path.

The cells are starting points, not a checklist. Pick the smallest pattern that changes the dominant part of the path. Before applying it, check whether it will amplify the tail or trade away quality, freshness, privacy, cost, or correctness. Then measure the same latency clock at the target percentile together with task success. If the bottleneck moves, return to the matrix.

Further reading

The following resources cover the main ideas behind this catalogues.

Measuring the AI application path

• OpenTelemetry, Generative AI semantic conventions: shared spans, metrics, and events for models, agents, and MCP.

• NVIDIA, LLM inference metrics: definitions of time to first token, end-to-end request latency, inter-token latency, and throughput.

• Gil Tene, How NOT to Measure Latency: coordinated omission and other measurement errors that can hide real latency.

Fan-out and tail latency

• Jeffrey Dean and Luiz André Barroso, The Tail at Scale: why rare stragglers become common as requests fan out.

• Marc Brooker, Serial, Parallel, and Quorum Latencies: a simulator for understanding how latency composes across dependent and parallel work.

System-level diagnosis

• Pekka Enberg, Latency: Reduce Delay in Software Systems (highly recommended read and the inspiration for this post)

• Brendan Gregg, Systems Performance: Enterprise and the Cloud, Second Edition: a methodology for finding latency outliers across the full stack.

• Alexey Ivanov, Optimizing web servers for high throughput and low latency: a production case study from hardware and NUMA to the kernel and application.

An agent system has several places to add context and control. Tool definitions advertise available capabilities upfront in the model request. A system prompt establishes the baseline. Project files and path rules add local instructions. A user prompt brings the immediate task. Skills provide procedures when they become relevant. Tool results later return data, errors, or action outcomes. Steering can change an active run, and delegation can move work into a separate context.

These mechanisms have different scope, timing, and trade-offs. They are not interchangeable ways to stuff more instructions into an agent. The design problem is to put the right information or control at the narrowest useful point, for only as long as it is needed. I will use Claude Code as the running example. Other agent systems expose comparable mechanisms, though their names and behavior vary.

This diagram separate two clocks. The left side shows when the runtime resolves a source: configuration, files, user input, a Skill, or a result. The right side shows how calls evolve. Eager tool definitions, the system prompt, and root instructions form a stable prefix that is presented on every call and often cached. Conversation, matched instructions, invoked Skills, and results append to growing history, which may later be compacted. Let’s dive into each one.

1. User prompt: tell the agent what matters now

The most immediate place to add task-specific context is the user prompt. It is the instruction sent with the current turn and represents what the user wants the agent to care about now.

> Review @docs/chapter.md.
> Focus on the argument and examples. Do not rewrite it yet.

In Claude Code, the message enters the conversation portion of the active context. An @file reference includes the file contents with that turn, while an attachment serves a similar purpose on surfaces that support it. The prompt identifies the desired outcome, the artifact that matters, and any temporary constraints around the task.

The message can remain until the context is cleared or older history is compacted, so it may influence follow-up turns. Its intended scope is still the current task. The user prompt is therefore the right place for one-off objectives, corrections, output formats, referenced material, and temporary instructions.

When to use. Immediate tasks, temporary constraints, conversational corrections, and attached or referenced material.

The main trade-off. User prompts are flexible and precise, but repeated guidance depends on the user remembering to supply it consistently.

If guidance keeps recurring, place it according to scope: in the system baseline if it is universal, in scoped instructions if it is project-local, or in a Skill if it describes a procedure.

2. System prompt: establish the standing baseline

The system prompt sits at the other end of the persistence spectrum. It is supplied by the host before the user conversation and defines the agent’s baseline identity, operating rules, tool-use guidance, and constraints that should influence the whole run.

Claude Code already provides a default system prompt. You can extend it for one invocation without replacing its built-in coding and tool guidance:

claude --append-system-prompt \
  "Separate verified facts from inference. Cite the evidence used."

The --append-system-prompt flag adds that instruction to the system layer for the session. A custom agent application usually configures the same kind of baseline when creating the agent. Some APIs call this a system instruction, but the architectural role is similar.

The temptation is to treat the system prompt as the universal home for anything important. That becomes expensive because every model call carries the instructions whether the task needs them or not. Each addition also competes for limited context and model attention.

For that reason, this layer should contain things that genuinely apply across the run: identity, broad safety constraints, universal response requirements, and important behavioral defaults. A 60-line production release checklist does not belong here. That checklist may be critical during a release, but every unrelated task would otherwise carry it as well.

When to use. Identity, universal priorities, broad safety posture, and rules that should influence nearly every model call.

The main trade-off. System instructions are consistently available, but they consume context on every task. As the baseline grows, conflicts become more likely and adherence problems become harder to diagnose.

Most durable guidance is not actually universal. Repository architecture, build commands, package conventions, and local coding rules matter only when working in a particular project or area. That is where scoped instructions become useful.

3. Scoped instructions: load project guidance where it applies

Rather than putting all persistent guidance into the system prompt, agent systems can scope instructions to a repository, directory, or file pattern. The guidance stays close to the code it describes and enters context only when that part of the workspace becomes relevant.

CLAUDE.md is Claude Code’s native project instruction file. AGENTS.md is a portable project instruction format used by compatible coding agents. Claude Code does not read it directly, but a project can import a shared file rather than maintaining duplicate instructions:

@AGENTS.md
## Claude Code additions
Use pnpm, not npm. Run `pnpm test` before finishing.

For more precise targeting, .claude/rules/api.md can add a path selector:

---
paths:
  - "src/api/**/*.ts"
---
Validate every public API input.

See the AGENTS.md specification for the portable file format.

Claude Code loads CLAUDE.md files from the working directory and its ancestors when the session starts. Nested files below that directory can load when Claude reads files in their subtree. Rules without a paths selector load at launch, while path-scoped rules become relevant when Claude reads a matching file.

Here, the workspace location or matching path determines which guidance applies. We can keep API conventions with API code, migration guidance with migrations, and generated-code rules with the files they govern instead of making every task carry all of them.

There is also a difference between loading a rule and enforcing one. CLAUDE.md, AGENTS.md, and similar natural-language files provide advisory context to the model. Their loading may be deterministic, but the model can still fail to follow what they say. Permissions and blocking hooks, which we will get to later, provide a stronger runtime boundary.

When to use. Project architecture, build commands, team conventions, and guidance that applies only to particular packages, directories, or file types.

The main trade-off. Scoping removes irrelevant context, but it also makes the full active instruction set less obvious. Nested files can overlap or conflict, and the model can still fail to follow the guidance.

Scoped instructions are useful for describing what is true or expected. They are less suitable for a procedure that should run only when a particular kind of work is requested. A release review is a good example: the repository may contain release-related conventions, but there is no reason to load the full release procedure while fixing an unrelated test.

That is the gap Skills address.

4. Skills: load a reusable procedure when needed

A Skill packages reusable instructions for performing a recurring task. Instead of copying a procedure into the system prompt, project rules, or every user request, we can keep it separately and make it available when the task requires it. In Claude Code, a project Skill lives in .claude/skills/<name>/SKILL.md.

---
name: release-check
description: Verify release readiness before approving a production release.
---
1. Run the required test suites.
2. Check migrations, monitoring, and rollback readiness.
3. Return a go or no-go recommendation with evidence.

The Agent Skills specification uses progressive disclosure. Initially, the agent sees only enough metadata, such as the Skill name and description, to understand when the procedure might be useful. When the Skill is selected, the full SKILL.md body enters the active context. Supporting references, templates, assets, and scripts can remain outside the working context until the procedure actually needs them.

An agent can therefore access many procedures without loading all their instructions into every request. In Claude Code, Claude may select the Skill from its description, the user can invoke /release-check directly, or a custom subagent can preload it.

The distinction from scoped instructions is the trigger. A path rule becomes relevant in a matching part of the repository. A Skill becomes relevant because a procedure has been selected for the task. One describes how work should be done in a scope; the other packages a reusable method.

A Skill is still instructions, not a new capability. In Claude Code, allowed-tools can pre-approve listed tools while the Skill is active, but it does not restrict the other tools the agent can see. Host permissions still apply, and writing “check the current deployment” into SKILL.md does not magically give the agent access to the deployment system.

When to use. Repeatable, conditional procedures such as releases, incident investigation, migrations, research, or specialized review methods.

The main trade-off. Progressive loading keeps the initial context smaller, but it introduces a routing decision. A vague description may prevent the correct Skill from being selected or activate it for the wrong task. Once selected, its instructions also occupy working context.

This brings us to the next boundary. A procedure can tell an agent that it should verify the production release status, but retrieving that live status requires something more than instructions. It requires a capability.

5. Tools: expose a capability and bring back results

Tools connect the model to computation, files, APIs, and external systems. A tool definition tells the model what an action is called, what it does, and which arguments it accepts. A simplified Anthropic client-tool definition might look like this:

{
  "name": "release_status",
  "description": "Read the current deployment state for a service.",
  "input_schema": {
    "type": "object",
    "properties": { "service": { "type": "string" } },
    "required": ["service"]
  }
}

Tools contribute to the agent’s context at two different points. Before the model runs, each tool’s name, description, and input schema tell it which capabilities exist and how to call them. After a tool is invoked, its result brings new information into the conversation. The definition affects what the model knows it can do, while the result changes what it knows about the world.

This is earlier than the previous diagram implied. For Claude, Anthropic documents the stable request prefix in the order tools, system, then messages. Other APIs may expose these as sibling request fields, but a tool definition is still part of the input prepared before inference, not something appended after the conversation.

This matters as the tool catalog grows. A handful of definitions is cheap, but hundreds of schemas can consume a significant part of the starting context before the task begins. The tool list should therefore contain capabilities the agent can realistically need, with concise descriptions and schemas.

MCP fits into this layer as the connection mechanism that can expose tools, resources, and prompts. It should not be confused with the procedure for using those capabilities well. A Skill might explain when and how to check release readiness, while an MCP server exposes the deployment system that allows the agent to retrieve the actual release state.

When to use. Live data, deterministic computation, external services, and actions with explicit inputs and outputs.

The main trade-off. Tools consume upfront context and introduce permissions, latency, schema drift, partial failures, and potentially side effects.

At this point, the agent has instructions telling it what to do and tools allowing it to act. But giving a model access to an action is different from deciding whether that action should actually be allowed. A release Skill may conclude that a deployment should proceed, for example, but that does not mean an autonomous git push or production deployment should happen without another control point.

That is where steering enters the loop.

6. Steering: intervene while the loop is running

The mechanisms so far shape what the model knows, the guidance it receives, and the capabilities it can invoke. Steering acts on live execution. A human can interrupt, a permission rule can require approval, or a hook can inspect a proposed action before it executes.

{
  "permissions": {
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./secrets/**)"]
  }
}

In Claude Code, permission rules provide allow, ask, and deny gates around tool calls. PreToolUse hooks can inspect the tool and its arguments, rewrite them, inject context, require approval, or block the call. The hook runs outside the conversation unless it returns guidance to it.

This highlights an important difference between two kinds of “rules” that are easy to mix together in agent systems. A natural-language rule in CLAUDE.md tells the model what it should do. A permission rule or blocking hook determines what the runtime will allow it to do. One relies on model behavior, while the other places control around that behavior.

Not every hook is steering either. A passive hook that records tool calls for audit purposes is instrumentation because it observes the run without changing it. It becomes steering when it can alter the next step, inject corrective information, require approval, or stop an action.

When to use. Human approval, action validation, output checks, recovery guidance, and policies that need to react to the current execution state.

The main trade-off. Runtime intervention introduces more branches, retries, latency, and state that must be tested. Some hook failures leave the action to normal permissions rather than block it, so security-critical restrictions still need permissions, sandboxing, and least privilege.

Steering is useful when the current loop is still the right place to perform the work but some of its decisions require control. Sometimes, however, the problem is the loop itself. A security review may require reading dozens of files, running searches, and producing a focused result, while none of that intermediate work needs to occupy the parent’s context.

For that kind of work, rather than continuing to enlarge the current context, we can open another one.

7. Delegation: open a separate context for the work

Delegation gives a bounded task to another agent loop. The worker receives its own instructions and selected context, performs the work separately, and returns a result to the parent. In Claude Code, a custom worker can be defined in .claude/agents/security-reviewer.md:

---
name: security-reviewer
description: Review security-sensitive changes and report evidence.
tools: Read, Grep, Glob
---
Inspect only the area named in the delegated task.
Return concise findings with file references.

The parent can then delegate directly from the conversation:

> Run the security-reviewer and test-runner in parallel.
> Give each the changed files, then combine their findings.

A non-fork Claude Code subagent starts with a fresh context window. It does not automatically see the parent conversation, previously invoked Skills, or files that the parent has already read. The parent supplies a task message, while the worker adds its own system prompt, applicable project instructions, configured tools, and any preloaded Skills.

A security reviewer can search dozens of files, inspect dependencies, and collect evidence without filling the main conversation. The parent receives a bounded result rather than the complete working history. A context-inheriting fork is the exception.

Several workers can run concurrently for independent work such as security review, test execution, or documentation analysis. Parallelism helps, but context isolation is often more important: specialist work does not consume the context needed for the main task.

Context isolation should not be confused with filesystem isolation, though. Two workers with separate context windows may still edit the same checkout and overwrite each other’s changes. Separate worktrees, sandboxes, or explicit file ownership are still needed when parallel changes must not collide.

When to use. Specialist, high-volume, expensive, or independent work that benefits from a clean context and can return a bounded result.

The main trade-off. Delegation adds cost, latency, routing risk, and potentially lossy handoffs. Parallel modification also introduces coordination problems unless the underlying files are isolated.

Delegation is therefore not simply a way to “make the agent smarter.” It is another context-management mechanism. Instead of putting even more information into the current loop, we decide that a piece of work deserves a context of its own and bring back only the result that matters.

The takeaway

When an agent struggles, first ask when the missing context or control should enter, how far it should reach, and whether the work needs its own context.

Use the narrowest mechanism that introduces what is missing where it becomes relevant. The goal is not more context, but correctly placed context.

The emerging skill-security stack

If you only want the shortlist rather than the full walkthrough, here are the ten projects:

1. NVIDIA SkillSpector: Scans skills before installation with deterministic checks, dependency analysis, and optional semantic review.

2. Cisco AI Defense Skill Scanner: Performs multi-engine static analysis with rules, YARA, AST, taint tracking, and policy gates.

3. SkillWard: Escalates suspicious skills from static scanning to semantic review and sandboxed execution.

4. Agent Audit: Scans full agent repositories for risky data flows, secrets, MCP configuration, and excessive privileges.

5. AgentShield: Audits active agent configuration, hooks, permissions, secrets, and runtime policy.

6. Microsoft Agent Package Manager: Controls installation of agent assets through manifests, policy, lockfiles, integrity checks, and SBOMs.

7. NVIDIA Verified Agent Skills: Offers evaluated and signed skills with provenance, verification evidence, and tamper detection.

8. NVIDIA OpenShell: Runs agents in policy-controlled sandboxes that restrict files, processes, network access, and inference.

9. Kubernetes Agent Sandbox: Provides Kubernetes APIs and controllers for isolated, stateful agent workspaces.

10. Microsoft Agent Governance Toolkit: Adds deterministic policy, approvals, and audit logging around consequential agent actions.

The map shows each project’s primary control point. Each project section below explains what it does, how it works, who it is for, and where its boundary ends.

1. NVIDIA SkillSpector: a pre-install scanner for skills

SkillSpector answers the first question most users have when they find a new skill: is this safe enough to install?

What it does. It scans a local file or directory, Git repository, URL, or ZIP and returns a risk score from 0 to 100, severity, recommendation, and findings. Its MCP wrapper also returns a safe_to_install signal. Reports can be written for humans or automation, including JSON, Markdown, and SARIF.

How it works. A source loader inventories the artifact, then deterministic checks inspect 68 patterns across 17 categories. Dependency findings use live OSV data when reachable and fall back to bundled data when it is not. An optional LLM pass adds semantic review before the findings are merged into an install recommendation. skillspector scan ./my-skill --no-llm needs no model key, although dependency coordinates may still be sent to OSV.

Best for. Individual developers, catalog maintainers, and CI pipelines that want a quick admission check with a clear decision at the end.

Boundary. SkillSpector does not execute the skill. Static and semantic inspection can identify suspicious intent and known patterns, but it cannot prove what a skill will do in a live environment.

2. Cisco AI Defense Skill Scanner: deeper multi-engine static analysis

Cisco AI Defense Skill Scanner is also a pre-install scanner, but it emphasizes a collection of specialized analysis engines and configurable security policy.

What it does. It scans a skill directory for malicious instructions, suspicious code, vulnerable execution paths, and behavioral risks, then produces console, JSON, Markdown, HTML, table, or SARIF output. A strict, balanced, or permissive scan policy tunes detection, while a separate severity threshold turns the result into a CI decision.

How it works. The default core combines YAML signatures and YARA rules, Python bytecode integrity checks, and shell-pipeline taint analysis. Optional local analyzers add Python AST and dataflow, trigger checks, and OSV lookups. Optional model and service analyzers add LLM review, meta-analysis, VirusTotal, or Cisco AI Defense. A strict high-severity CI gate is skill-scanner scan ./skill --policy strict --fail-on-severity high.

Best for. AppSec and platform teams that want explainable, CI-oriented checks and more language-aware analysis than a simple pattern scan.

Boundary. The core path is static: it inspects what could happen but does not run the skill. Some optional enrichments use external services and therefore do not belong in a strictly offline setup.

3. SkillWard: escalate suspicious skills into a sandbox

SkillWard treats skill analysis as an escalation pipeline. Cheap checks run first; uncertain cases can progress all the way to controlled execution.

What it does. It produces a behavioral verdict and evidence for a skill, including actions that are only visible when the skill is actually invoked.

How it works. Stage A uses YARA, regular expressions, and static inspection. Stage B asks a model to classify intent and escalates uncertain cases. Stage C launches the skill with an in-container agent inside Docker. A guard inspects tool calls and file content for evidence such as network access, sensitive writes, credential access, and exfiltration, while decoys make malicious behavior easier to expose. The semantic stage can use a locally hosted model.

Best for. Security researchers, reviewers, and higher-assurance catalogs investigating a suspicious or ambiguous skill after static scanning.

Boundary. Dynamic evidence is stronger, but it is also slower and depends on the test scenario reaching the malicious branch. “Nothing happened in this run” is not proof of safety.

4. Agent Audit: scan the whole agent repository

Agent Audit broadens the target beyond a packaged skill. It looks for security problems across the surrounding agent application.]

What it does. It finds dangerous operations, untrusted-data flows into sensitive tools, exposed secrets, risky MCP configuration, skill and package risks, and excessive privileges. Its deepest AST and taint analysis is for Python, while the current scanner also covers TypeScript and JavaScript, Go, Solidity, SKILL.md, and configuration files. Results can fail a build and can be exported as SARIF.

How it works. Repository discovery feeds several analyzers: a Python AST scanner, intra-procedural source-to-sink taint tracker, tool-boundary analyzer, three-stage secret scanner, MCP configuration scanner, privilege scanner, and a shared rule engine. The current project documents 72 rules. A typical static gate is agent-audit scan . --fail-on high; an optional dynamic mode can connect to MCP servers for read-only inspection.

Best for. Developers and AppSec teams reviewing an agent as an application, especially Python-based projects with tools and MCP servers.

Boundary. The default scan is static and does not run the agent application. Optional MCP inspection expands discovery, but the project is not a runtime monitor or execution sandbox.

5. AgentShield: audit what is active on a developer machine

AgentShield shifts the target again, from a single downloaded artifact to the agent configuration already present in a project or user environment.

What it does. Its default mode discovers agent-related files and checks secrets, permissions, hooks, MCP configuration, and agent settings against 102 static rules in five categories. It can also execute hooks in a controlled temporary directory, run active injection tests, watch configuration changes, and install a PreToolUse policy hook.

How it works. The default invocation selects one root: a local .claude directory, otherwise the home .claude directory, otherwise the current directory. Discovery classifies findings by runtimeConfidence, separating active runtime and project-local material from examples, documentation, plugins, and hooks. npx ecc-agentshield scan runs the static checks; optional modes add model review, hook execution, continuous watch, or runtime allow and block decisions.

Best for. Developers, endpoint-security teams, and CI jobs that need to understand the effective agent attack surface of an environment.

Boundary. The default scan is a posture snapshot. Its optional watch and PreToolUse modes expand the boundary, but the hook sandbox is a host child process with a temporary working directory, not a hard operating-system or network boundary.

6. Microsoft Agent Package Manager: govern what gets installed

Microsoft Agent Package Manager, or APM, treats prompts, skills, MCP servers, and other agent assets as a dependency graph rather than files copied by hand.

What it does. It resolves declared agent dependencies, applies installation policy, deploys approved assets to a target harness, records exact versions and integrity data, and can export a CycloneDX or SPDX SBOM from the lockfile.

How it works. apm.yml declares the package graph and apm-policy.yml defines admission rules. During apm install, the resolver fetches dependencies into a cache, scans for hidden Unicode, requires explicit trust for transitive MCP server declarations, checks policy and integrity, deploys approved assets, and writes apm.lock.yaml. Later, apm audit verifies the declared, locked, and deployed state and replays a scratch install to detect drift. apm lock export produces the SBOM separately.

Best for. Platform teams that want repeatable, reviewable distribution of agent assets across developers and CI environments.

Boundary. APM governs what gets installed. It does not execute downloaded package code by default, but explicit lifecycle scripts and experimental canvas extensions are execution exceptions. The agent harness still governs what runs, so installation control must be paired with runtime policy or isolation.

7. NVIDIA Verified Agent Skills: signed provenance plus evaluation evidence

NVIDIA’s verified agent-skills catalog is less a scanner than a trust and distribution pattern for published skills.

What it does. It gives consumers a curated catalog in which each accepted skill carries a skill specification, skill card, evaluation evidence, security review, and a detached signature that can be verified before installation.

How it works. An upstream release pipeline evaluates the skill, runs SkillSpector review, resolves findings, and signs the approved artifact. The catalog’s hourly mirror checks required artifacts, signature state, and source or signature drift; it does not rerun the evaluation, and BENCHMARK.md is commonly published rather than required by the catalog gate. Consumers separately verify the directory against NVIDIA’s root certificate, then install it.

Best for. Skill publishers, catalog operators, and organizations that need provenance and tamper detection, not just a point-in-time vulnerability scan.

Boundary. A valid signature proves origin and integrity, not harmlessness. The catalog’s review raises confidence, but runtime controls are still needed after a verified skill starts acting.

8. NVIDIA OpenShell: contain the running agent

NVIDIA OpenShell moves the control point from artifact inspection to execution. It assumes agent code and skills may be untrusted and gives them a constrained place to run.

What it does. It isolates an agent in a sandbox and enforces policy over filesystem access, processes, network connections, and model inference. Denied operations are stopped at the boundary rather than merely reported afterward.

How it works. The OpenShell Gateway stores desired state and asks a compute driver to provision the sandbox. Inside that sandbox, a Supervisor launches the restricted process. Filesystem and process controls are enforced locally, ordinary egress passes through a local policy proxy and OPA, and model traffic passes through an inference router. Docker and Podman are local options, the VM path is experimental, and Kubernetes is the cluster driver. On Kubernetes, that driver creates a Sandbox resource for the separate Agent Sandbox controller to reconcile into a Pod. The commands openshell sandbox create -- claude and openshell policy set demo --policy policy.yaml --wait are valid, but only network and inference policy are hot reloadable.

Best for. Platform and infrastructure teams running coding agents or other tool-using agents that need OS-level containment.

Boundary. OpenShell limits the blast radius of execution; it does not certify that the skill source is safe or decide whether the business intent of an allowed action is appropriate.

9. Kubernetes Agent Sandbox: provision isolated agent workspaces on Kubernetes

Kubernetes Agent Sandbox is the project that is easy to confuse with OpenShell. It is developed under Kubernetes SIG Apps rather than being a separate CNCF-hosted project. Kubernetes itself is a CNCF graduated project.

What it does. It provides a standardized Kubernetes API for isolated, stateful, singleton workloads, the shape needed by long-running coding agents and other autonomous runtimes. A sandbox can keep a stable identity and persistent storage, then be suspended, resumed, or replaced without treating it like a replicated web service.

How it works. The core Sandbox CRD and controller reconcile a Pod and its lifecycle, with a conditional headless Service and optional PVCs. Extension CRDs add reusable SandboxTemplate definitions, SandboxWarmPool capacity, and SandboxClaim allocation. A claim can request a warm pool, the pool references a template, and the controllers allocate or adopt a Sandbox. A template can add a managed NetworkPolicy and select a stronger RuntimeClass, including gVisor or Kata Containers. The Kubernetes introduction explains the broader model.

Google Cloud has also introduced Agent Substrate, an adjacent open-source project that pairs sandbox and snapshot capabilities with a specialized control plane for denser agent execution on Kubernetes. It maps many stateful actors onto fewer ready worker Pods, then suspends, resumes, and routes them on demand. The repository is still early and not production ready, and its threat model says security hardening is minimal, so treat it as a scalability substrate rather than an additional security control.

Best for. Platform teams building a multi-tenant Kubernetes substrate for agent runtimes, especially when they need stable workspaces, warm starts, persistent state, and a common API that several agent platforms can consume.

Boundary. Agent Sandbox provisions and manages the workload boundary; it is not an agent-aware security policy engine. The actual strength of isolation depends on the selected runtime, network policy, credentials, and cluster configuration. OpenShell can sit above it to add filesystem, process, egress, inference, and credential policy.

10. Microsoft Agent Governance Toolkit: policy-gate every action

Microsoft Agent Governance Toolkit, or AGT, focuses on the semantic action an agent is about to take: send an email, query data, call a tool, or delegate to another agent.

What it does. It wraps selected callables and configured framework intervention points, evaluates deterministic policy, can require human approval, and records an audit decision. A denied wrapped call never reaches the underlying tool.

How it works. A developer wraps a function with govern(my_tool, policy="policy.yaml"), which returns a GovernedCallable. Each wrapped invocation builds governance context, runs the YAML PolicyEngine with deny-overrides behavior, optionally requests approval, and writes to a Merkle-chained audit log. The broader toolkit separately offers Agent Control Specification support, OPA and Cedar backends, identity and trust, framework adapters, sandboxing, MCP security, compliance, and SRE modules.

Best for. Application, security, and compliance teams that need explainable authorization for every consequential agent action.

Boundary. The basic middleware and the agent share a process boundary, and the default audit log is in memory unless an external sink is configured. Microsoft’s own guidance recommends container isolation for stronger protection; the policy gate should not be mistaken for the operating-system boundary provided by OpenShell.

Where the projects overlap and where they do not

The first five projects all find risk, but their inspection targets are different. SkillSpector and Cisco Skill Scanner focus most directly on a skill artifact. SkillWard adds controlled execution. Agent Audit follows dangerous flows through the wider agent codebase. AgentShield inventories the configuration that is active in an environment.

APM and NVIDIA Verified Agent Skills operate on the software-supply-chain problem. APM makes installation deterministic and policy-controlled; NVIDIA’s catalog adds publication requirements, evaluation evidence, and signed provenance. Neither replaces source analysis or runtime containment.

The final three control points intervene while an agent is operating, but at different boundaries. AGT authorizes the agent’s intended action. OpenShell constrains what the process can actually do at the operating-system and network boundary. Kubernetes Agent Sandbox provisions and manages the underlying stateful workload when that process runs on Kubernetes.

That produces a useful three-line mental model:

• Intent: Is this requested action allowed for this agent? AGT answers that question.

• Capability: Can this process reach the resource at all? OpenShell enforces that boundary.

• Substrate: Where does the isolated stateful workload run? Agent Sandbox provides that lifecycle.

Comparison at a glance

The table condenses the primary target, mechanism, effect, and GitHub stars for all ten projects.

For an organization adopting third-party skills, I would start with four layers:

1. Scan before trust. Run SkillSpector or Cisco Skill Scanner on every incoming skill; escalate ambiguous, high-risk artifacts to SkillWard.

2. Control distribution. Use APM-style manifests, policies, lockfiles, and SBOMs; verify signatures when a curated catalog provides them.

3. Authorize actions. Put deterministic policy and audit around consequential tool calls with AGT or an equivalent middleware gate.

4. Contain execution. Run the agent inside an OpenShell-style sandbox, and use Agent Sandbox as the Kubernetes substrate when the workload needs cluster-native lifecycle and isolation.

No single project spans the entire lifecycle yet. That is not a weakness in the ecosystem; it is the shape of defense in depth. The important step is to stop treating a skill as “just a Markdown file.” It is a supply-chain artifact that can steer a privileged, autonomous runtime.

The repository contained the implementation: source code, tests, configuration, and dependency manifests. Developers read across the surrounding artifacts, reconciled the desired outcome with architectural judgment, and translated both into code.

As AI-assisted coding becomes normal, the repository is becoming the meeting point between that project knowledge and the agent changing the software. A monorepo brings codebases and their dependency graph together. An agent-ready repository also brings in the knowledge required to change them correctly.

Software has always been understood through different lenses: principles and NFRs, architecture and design, concrete specifications, implementation plans, domain rules, and lessons learned during operation. A growing family of Markdown files now captures these dimensions in forms that coding agents can discover and use. This article looks at the formats and tools that are emerging. Together, they let an agent act as an intent compiler, translating human intent and judgment into source code.

Agent onboarding starts with a README for agents

A human onboards to a project once. An agent effectively onboards every time it starts a task. It needs to orient itself in the repository, discover the relevant commands and conventions, and understand the rules that apply before it changes anything.

AGENTS.md is the closest thing to a neutral standard for this purpose. The project describes it as a README for agents. A root file can explain the repository structure, build commands, tests, coding conventions, and pull request expectations. Nested files can add instructions for a package or subsystem. The format deliberately has no required fields.

The ecosystem also has vendor-native alternatives that serve the same purpose:

• AGENTS.md provides cross-tool project guidance for Codex, Cursor, Cline, Copilot, OpenCode, and other compatible agents.

• CLAUDE.md and .claude/rules/ provide standing and path-scoped guidance for Claude Code.

• GEMINI.md provides hierarchical context for Gemini CLI.

• .github/copilot-instructions.md and path-specific instruction files guide GitHub Copilot.

• .clinerules/ carries persistent and conditional rules for Cline.

Use pnpm, not npm. Do not edit generated clients. Run the billing integration tests after changing an invoice flow. Read the relevant ADR before moving a service boundary. These are standing instructions that should remain true across many tasks.

Once the agent understands the repository, the next question is how to perform a particular kind of work.

Skills package repeatable procedures

A skill is a playbook tailored to a particular kind of work.

Consider a database migration. AGENTS.md might state that every schema change needs a rollback path. A migration skill can describe the complete procedure: inspect the current schema, create the migration, update generated types, run compatibility checks, verify the rollback, and prepare the review summary.

The open Agent Skills specification gives that playbook a portable package. Each skill has a required SKILL.md containing metadata and instructions. It may also include scripts, references, templates, and other assets. Agents initially see the metadata, load the full instructions when the skill is relevant, then access supporting material as needed.

Agent Skills originated at Anthropic and were released as an open standard. They are separate from MCP, which Anthropic contributed to the Agentic AI Foundation. The skill format is now documented by Codex, Gemini CLI, GitHub Copilot, and other compatible clients.

The boundary is concrete:

• AGENTS.md and native rule files describe standing context and constraints.

• SKILL.md describes a repeatable procedure invoked for a specific task.

A procedure explains how to work. It still needs a reviewed description of what should be built.

Planning files make software design reviewable

Software design, planning, and task breakdown are also moving into versioned Markdown. When they exist only in chat, they disappear into session history. When they become repository artifacts, architects and developers can review them before an agent turns them into implementation.

GitHub Spec Kit is the clearest mainstream example. Its documentation reports more than 121,000 GitHub stars and 35 coding-agent integrations. Its default workflow uses a chain of files:

1. spec.md records the requirements and desired outcome.

2. plan.md explains the technical design and implementation approach.

3. tasks.md breaks the plan into executable units.

4. The agent implements and validates the change.

A project constitution can carry principles that should apply across many changes.

Spec Kit is not the only approach. OpenSpec, Kiro Specs, and project-specific PLANS.md use different files and workflows. They are nevertheless converging on a recognizable sequence: requirements, design, plan, tasks, implementation, and validation become separate artifacts that humans can review and agents can follow.

These files describe a generic software development lifecycle. Applications also need instructions for their particular domain.

Domain files give agents specialized context

A frontend, an identity platform, and a data pipeline do not need the same context. Domain files give agents specialized instructions for the parts of a system that generic onboarding, skills, and plans cannot fully describe.

• ARCHITECTURE.md can describe system boundaries, components, dependencies, NFRs, and long-lived architectural decisions. It is an established human documentation convention that becomes operational for agents when project instructions tell them when to read it.

• Google Labs’ DESIGN.md describes visual identity, design tokens, components, and design rationale. The project currently labels the format alpha.

• WorkOS’ AUTH.md is an experimental, service-hosted recipe that teaches agents how to register and authenticate on behalf of users.

• Kilo’s REVIEW.md lets a repository define review priorities, severity, skipped files, verification expectations, and how a review agent should divide work.

These formats have different maturity levels and scopes. ARCHITECTURE.md is a long-standing documentation convention. DESIGN.md, AUTH.md, and REVIEW.md are emerging, domain-specific experiments. Their common direction is clear: more specialized engineering knowledge is becoming directly legible to agents.

Some of that knowledge is designed in advance. Other knowledge emerges only while the software is being built and operated.

Memory makes learned context durable

An unexpected build prerequisite, a debugging pattern, or the reason a deployment failed might previously have ended up in a ticket comment, commit message, Slack thread, incident report, or SRE playbook. Those records range from ephemeral to durable, but a coding agent may not find the relevant lesson when it begins the next task.

Agent memory keeps learned context associated with a repository and available across sessions. Claude Code makes the authorship distinction unusually clear:

• Humans write CLAUDE.md to provide shared instructions, conventions, and project context.

• Claude writes auto memory into a MEMORY.md index and optional topic files such as debugging.md and api-conventions.md.

The auto memory is repository-specific but machine-local. Claude normally stores it outside the Git repository, and it is not automatically shared with the team. Anthropic documents the two mechanisms separately.

Memory therefore does not replace tickets, commit history, or operational documentation. It reduces repeated rediscovery. When a learned fact becomes important to the whole team, it needs a promotion path:

1. The agent records a tentative observation in local memory.

2. A human reviews it when the observation recurs or affects shared work.

3. Durable knowledge moves beside the source code into a project rule, skill, ADR, or domain document.

Tentative knowledge stays local. Reviewed knowledge becomes shared. Kilo is experimenting with a similar loop for review: it can analyze how a team responds to review comments and propose changes to the repository’s review guidance.

Putting the Markdown files together

Shared project files carry reviewed knowledge beside the source code. Agent-written memory remains machine-local until a durable lesson is promoted into the repository.

The practical distinction is the role each file plays, who writes it, and how broadly it is supported.

The formats range from cross-tool standards and established vendor conventions to emerging domain-specific experiments.

A project does not need every file. Use the smallest set that agents can reliably discover, keep reviewed knowledge beside the source code, and treat vendor-specific files as thin compatibility bridges when another file is canonical. AUTH.md remains service-hosted, while Claude’s auto memory stays machine-local until a human promotes a durable lesson into the repository.

The takeaway

The repository is becoming the meeting point between source code and metacode: the Markdown that carries requirements, NFRs, architecture, design, rules, procedures, plans, and durable learning.

When agents can read both, they act as intent compilers. Source code becomes a byproduct: the executable result of human intent and judgment made legible to the agent.

The engineering task is to keep that metacode scoped, reviewed, and current. It does not replace testing or review. It gives the next code change a better source.

Other emerging standards

• Open Knowledge Format (OKF)

His framework maps how that wider adoption tends to unfold. A new tool or practice lets a person or team run more AI work, often in parallel. That works until another constraint becomes binding. The bottleneck moves from access, to the engineer’s attention, to review, to trust, and finally to deciding what should be automated at scale.

These are not company-wide levels. Different people, teams, and workflows can move through them at different speeds. Boris’s evidence and examples are Claude-specific. I use the progression as a vendor-neutral heuristic that can also help teams reason about other coding agents. The agent counts in the image are scale cues, not targets.

With that in mind, let’s look briefly at what each phase means and what moves the work forward.

Gated: open an approved path

The first phase is about whether people can use AI on real company work at all.

Some organizations do not approve the latest models for company code. Others route access through an internal service that adds authentication, policy checks, and latency. A developer may be allowed to experiment locally but have no approved way to deploy what the agent produces. The work waits for security, data, procurement, and IT approval.

At this point, the AI adoption stack contains only a few things:

• Claude.ai chat as the approved entry point.

• SSO, SCIM, and role-based access so use is tied to company identities.

• Organization budget caps, data-governance rules, and existing IAM and deployment controls around the work.

When the organization has an approved workflow that can use Claude and ship its output without requesting a policy exception each time, the gated phase has been passed. The next bottleneck is the engineer’s attention.

Assisted: one engineer and one agent

With access open, adoption moves into the developer’s daily workflow. One engineer works with one agent but still reviews nearly every response and code edit. AI makes the task faster, yet the work remains synchronous: while Claude works, the engineer watches.

The practical stack now expands from access to one bounded, self-checking task loop:

• Claude Code in Desktop, CLI, or IDE, with Plan mode to review the approach before edits begin.

• Tests, build, lint, type checks, and end-to-end tests in a real development environment so the agent can check its own work.

• Auto mode to remove routine permission interruptions inside an approved policy.

For the organization, Claude Code Analytics, OpenTelemetry export, spend caps, and centrally managed settings keep this new path visible and bounded.

When the agent can close one bounded task and the engineer can begin another, attention stops being the immediate constraint. The work becomes parallel.

Parallel: one engineer and several agents

One engineer can now coordinate several agents. Each works in an isolated checkout, runs its checks, and returns a final diff. Output grows quickly. The review capacity of one person does not, so the bottleneck moves to review.

The new tools are built for concurrency:

• Agent view keeps multiple sessions visible, while worktrees keep their edits from colliding.

• Claude Code Review and Claude Security investigate code and security findings before human approval.

• Claude Code on Mobile, cloud execution in Desktop, and Remote control let the engineer monitor work away from the terminal.

These sessions inherit the previous phase’s verification loop. The new guardrails are for concurrency: pre-approve common safe Bash and MCP commands in settings.json, isolate each task, and retain human merge and security approval. The Chrome extension or an iOS or Android simulator MCP can extend verification to end-to-end behavior.

The point is not to remove review. It is to stop reviewers spending attention on failures the agent could have found itself. This phase works when parallel sessions return evidence, not another pile of unchecked output.

Supervised autonomy: manage loops, not sessions

Once repeated parallel tasks become reliable, teams can turn them into loops. A person no longer needs to start and steer every session. Claude can gather context, delegate work, and begin scheduled or event-driven tasks.

Trust is now the bottleneck. A deep agent tree cannot be watched step by step, and scaling it before the loop has earned trust only multiplies failures, decisions, and token use.

This phase adds:

• Subagents to delegate work into separate workers.

• Routines, /loop, /batch, /goal, and Dynamic workflows for scheduled, repetitive, or multi-agent work.

• Claude Tag to watch a channel, use the shared context, and start work proactively.

• CLAUDE.md and Skills to encode standards, plus agent sandboxing to limit filesystem and network access.

At this scale, operating cost becomes part of trust: a loop that is correct but wasteful will not scale. Boris calls out advisors, language servers, model selection, and moving large CLAUDE.md instructions into lazily loaded Skills to reduce token use.

The phase has been passed when a background loop can gather its context, check its result, and stop or return to a person predictably. The question then changes from “Can this run?” to “Which work should we automate at scale?”

AI-native: steer by intent

In the final phase, trusted loops become domain-specific automations: code migrations, fuzzing, feature building, or feedback remediation. Many agents may run, some started by other agents. People set the intent and monitor exceptions instead of assigning and inspecting every task.

The bottleneck is identifying valuable work to automate and choosing the right guardrails for each kind of work.

The product list is short:

• Claude Agent SDK to build and schedule agents programmatically.

• Cost controls and model selection for each automation.

One global autonomy policy will not fit every workflow. Each needs its own scope, checks, and cost ceiling. Human judgment becomes the bottleneck: deciding which work should run, what evidence is sufficient, and where a person must remain in the loop.

The takeaway

These phases describe a progression, but they are not a single company-wide maturity score or a mandatory linear path. They map what enables more AI work to happen in parallel and where each workflow waits next.

As technical constraints fall away, the bottleneck often moves into human attention, review, trust, or judgment. Find where the workflow waits. Add the smallest tool and guardrail that can remove that constraint. Then watch where the queue moves.

More tokens do not move a team through these phases. Better operating loops do.

Based on Boris Cherny’s X post and Steps of AI Adoption.

As skills move from personal snippets into shared repositories, maintenance becomes the harder problem. A skill quietly decays as models change, APIs move, and infrastructure drifts. Left untouched, it can stop helping and start steering the agent in the wrong direction.

Shared collections already accumulate duplicates, stale instructions, uncertain provenance, and overlapping capabilities. Teams need to know what is installed, where it came from, who maintains it, and what is affected if it is compromised. We learned to fight code rot with linters, tests, scanners, package managers, and monitoring. Skills need the same treatment, from the cheapest offline check to the richest production signal.

1. Skill Linting: Catch Problems Before a Skill Runs

A skill can be broken before anyone runs it: an underspecified description may fail to trigger it, oversized instructions can crowd the context window, required fields may be missing for the target format, and unsafe instructions may omit guardrails. Without an offline check, you discover these problems the expensive way, when the agent misfires in front of a user.

Static analysis inspects a skill without executing it, and it scales from shallow to deep as it does for code. The shallow end is deterministic linting: does the skill have the required fields, valid references, and a description specific enough to be selected? A layer up sits best-practice review, matching it against published authoring guidance for concision, progressive disclosure, and clear trigger cues. The deep end is substance review, with a model reading the skill the way a senior engineer reads a pull request and asking whether it does a sensible thing at all. The rules already exist in guidance and in the skill authoring patterns; the discipline is turning them into repeatable checks.

Related tools.

• Field and schema linters that validate skill structure

• Best-practice reviewers that score against authoring guidance

• Generic LLM reviewers for substance, in the spirit of an automated code review

When to use. Run deterministic schema, reference, and style checks on every change. Schedule model-based substance review according to cost and risk.

The main trade-off. Static analysis can inspect structure, semantics, dependencies, and likely risks, but it cannot observe runtime behavior. A skill can pass those checks and still fail in a real agent, model, tool, and repository environment.

2. Skill Evals: Test How a Skill Behaves

Linting tells you a skill is well formed. It cannot show how the skill behaves on a task. Running representative tasks provides behavioral evidence, though it cannot prove that a skill works universally. Without that evidence, every change is guesswork, the same trap as code with no tests.

A useful, intentionally imperfect analogy is the test pyramid. Skill evals isolate one skill. Project evals combine a repository‘s context and can replay a past pull request. Broader system evals exercise a production-like setup end to end. Any of those scenario tiers can be run across target models when the question is model choice. A smaller model can make an isolated run cheaper, but passing it means only that no regression was observed in those scenarios. Scenario quality, repeated runs, and target-model coverage matter more than a comforting coverage number.

Related tools.

• OpenAI’s Codex eval pattern captures a run’s trace and artifacts, scores deterministic checks, and adds schema-constrained model grading for qualitative criteria

• Eval harnesses that run an agent through a defined task environment

• Scenario extractors that turn a past pull request into a repeatable test

When to use. As soon as a skill is doing something you would be afraid to change. That is the moment you need a test.

The main trade-off. Evals provide behavioral evidence, but environments and judges cost time to build and maintain, and an unvalidated judge can create false confidence.

3. Skill Scanning: Scan Skills Before You Trust Them

Skills are not inert documents. Depending on the client, an agent may follow their instructions, execute bundled scripts, or invoke tools under the harness‘s permissions. That makes third-party skills a supply-chain surface. The risks fall into three broad groups: malicious skills designed to cause harm, negligent skills that omit safety boundaries, and vulnerable skills that expose secrets or unsafe flows. Skills are already part of the attack surface, not merely the next one.

Open-source scanners already cover several layers. NVIDIA SkillSpector and Cisco Skill Scanner combine static detection with optional semantic analysis; SkillWard adds sandbox execution for suspicious skills; Snyk Agent Scan can discover installed agent components as well as inspect an individual skill. These projects use different combinations of signatures, data-flow analysis, dependency checks, model-assisted review, inventory, and sandbox execution. That variety matters because no one technique covers the whole attack surface. Underneath them all is supply-chain security: knowing what you run and where it came from, so a compromised skill is traceable rather than invisible.

Related tools.

• Static and semantic scanners integrated into publishing or installation

• Sandboxed execution and red-teaming harnesses that probe runtime behavior

• Provenance and supply-chain tracking for installed skills

When to use. Before any third-party skill enters your workspace, and continuously on whatever is already installed.

The main trade-off. Scanning can flag known risk classes, but false positives, false negatives, and runtime-only behavior remain. It reduces risk without proving a skill safe.

4. Skill Dependencies: Make Hidden Relationships Explicit

Skills can depend on tools, scripts, packages and, in clients that support programmatic skill invocation, other skills. An incident-response workflow might use one capability to gather logs, another to run root-cause analysis, and a third to file the ticket. The open Agent Skills format defines the skill folder, but it does not standardize dependency declarations or skill-to-skill calls, so many of these relationships remain implicit.

Package managers now exist, so this practice is no longer hypothetical. Microsoft’s Agent Package Manager is one concrete implementation: it uses apm.yml for declarations and apm.lock.yaml for resolved commits and content hashes, with transitive dependency resolution and policy gates. The ecosystem still lacks one universally adopted manager, but the shape is becoming clear: discovery, versioned releases, a project manifest, a lockfile, provenance, and install-time quality and security controls. That is what turns the shared-repository swamp into something a large organization can govern.

Related tools.

• Skill registries for discovery and publishing

• Project manifests that declare packages and lockfiles that pin resolved versions and hashes

• Plugin bundlers that package related skills together

When to use. The moment more than one person shares skills, or one skill starts depending on another.

The main trade-off. A package manager buys governance and traceability at the cost of process friction, and asking a culture that currently copies a markdown file to adopt manifests and version gates is a real adoption hurdle.

5. Skill Observability: Learn From Skills in Production

Offline checks cannot reproduce every production workload. You can lint, test, scan, and version a skill carefully and still miss how it behaves against real users, repositories, and drift. Runtime traces, user feedback, and experiments add another kind of evidence.

As a runtime complement to pre-install scanning, Microsoft’s Agent Governance Toolkit wraps agent tool calls with policy checks and records allow-or-deny decisions in an audit trail. That trail shows what the agent attempted and what policy decided; it does not prove the real-world outcome.

The discipline is to monitor agents at runtime and feed what you learn back into the other four. Observability closes the loop in two directions. It turns representative failures into candidate eval scenarios, so production teaches the test suite. And it clusters recurring behavior that may reveal a missing, misfiring, or redundant skill. Those are hypotheses for review, not automatic deletion decisions: a skill that never fires may have a weak description or cover a rare but important case. This is the move that can turn maintenance from a chore into an optimization loop.

Related tools.

• Agent-run logging and policy-decision audit trails across real sessions

• Scenario extraction that promotes a production failure into an eval

• Trace clustering that proposes skills to add, fix, or review for removal

When to use. Once skills are live in front of real work, and especially before you trust a shared repository at scale.

The main trade-off. Production telemetry is rich but requires runtime instrumentation and access to potentially sensitive agent logs, creating real retention, access, and privacy responsibilities.

The takeaway

These five disciplines borrow established software-engineering practices and point them at a new artifact. If skills are treated as code-like context, they deserve comparable lifecycle controls.

The broader discipline is a context development lifecycle: generate context, evaluate and test it, optimize it, distribute it, consume it safely, observe what happens, and repeat. The five disciplines support that loop; they are not identical to its stages. Guy Podjarny‘s Skills Are the New Code talk was the spark for this post. The treatment here is my synthesis of that lifecycle argument with current specifications, eval practice, security tools, package management, and runtime operations.

That is the point where memory becomes a mixed control plane. The issue is not that CLAUDE.md is bad; it is that one file is asked to carry facts, procedures, boundaries, style, external capabilities, and workflow triggers, even though Claude Code has separate mechanisms for each of these jobs.

Project memory, path-scoped rules, skills, manual commands, subagents, hooks, permissions, MCP servers, output styles, and system-prompt overlays steer Claude in different ways. They have different context costs, different loading models, and different authority over the final behaviour. Treating them as stronger or weaker versions of the same prompt is how instructions get duplicated, diluted, and then repeated in chat again.

The practical question is simple:

Where should this instruction live so that it is visible when needed, cheap when not needed, and enforced when it must be?

Why this matters now

Claude Code has grown into a small operating environment around the model: memory files hold project facts, rules scope constraints, skills package work, subagents isolate investigation, hooks and permissions enforce behaviour, output styles set response posture, and MCP servers connect live capabilities. Once a repository uses more than one or two of these, the useful design question becomes placement rather than wording.

The concrete artifact in this post is Claude Code itself. I am not trying to restate the docs, but to extract the operating map teams need when their setup grows beyond one shared memory file.

That placement question has two dimensions. The first is scope: how widely should this apply across every session, one directory, one file glob, one workflow, one subagent, one external tool, or one lifecycle event? The second is enforcement: is this guidance the model should follow, or a boundary the runtime must guarantee?

If you get these two dimensions right, Claude feels much more reliable because each instruction has a natural place and a matching level of authority. If you get them wrong, you end up repeating the same intent in multiple places, while still paying for it on turns where it does not matter.

The map is the whole article in one picture. Most mechanisms guide Claude through context, routing, tool access, response posture, or isolation, while hooks and permissions enforce outside the model in the hard sense. The rest still matter, but they do not become hard policy just because the sentence sounds strict.

A rule such as “never edit production migrations” does not belong only in CLAUDE.md. The memory file can explain the policy, but the boundary itself belongs in a permission rule or a hook, because the model may forget prose while the harness should not forget policy.

The 10 steering mechanisms

These are not just features. They are placement mechanisms, and each one answers a different question about where an instruction should live.

1. Project Memory Index: CLAUDE.md

Use CLAUDE.md for stable project facts that Claude should know in most sessions: build commands, test commands, repo layout, architectural landmarks, and team conventions.

Think of it as an index rather than a manual. A new teammate should be able to read it and understand where they are, but it should not contain every process your team ever invented. Procedures belong in skills, local constraints belong in rules, and hard boundaries belong in hooks or permissions.

Use it when: the information is broad, stable, and useful across many tasks.

Example:

# Project basics
- Package manager: pnpm
- Unit tests: pnpm test
- API routes live in packages/api/src/routes
- Service ownership is documented in docs/service-ownership.md

2. Path-Scoped Constraint: rules

Rules are for constraints that are narrower than project memory. They live under .claude/rules/; without paths, a rule becomes broad context, while with paths, it loads only when Claude works with matching files.

This is the main mechanism for monorepos and mixed stacks, where API code, frontend code, infrastructure code, generated code, and migrations rarely share the same rules. A rule can improve behaviour significantly, but it is still text. If editing old migrations must be impossible, add a hook that blocks the edit rather than trusting a convention written as prose.

Use it when: a convention applies to a directory, file type, or concern.

---
paths:
  - "src/api/**/*.ts"
---
All API handlers must validate input with Zod before processing.
Return errors using the shared ApiError format.

3. Just-in-Time Procedure: skills

A skill is the right home for a reusable workflow, such as release notes, code review, incident analysis, dependency upgrades, migration planning, or API change review.

Only the skill description is visible up front, so Claude can decide when to use it, and the body loads only when the skill is invoked. That makes skills the best way to carry long procedures without paying for them on every turn. The description is the routing signal, so write it like a trigger, not like a vague title.

Use it when: you keep pasting the same checklist into chat.

Example:

---
name: release-notes
description: Create release notes from the current git diff and recent commits.
---
Create release notes for $ARGUMENTS.
1. Read the current diff and recent commits.
2. Group changes into Features, Fixes, Breaking Changes, and Internal.
3. Mention migration risk only when visible in the diff.
4. Keep the final output under 400 words.

4. Human-Triggered Workflow: manual skills and slash commands

Some workflows should not run just because Claude thinks the work looks ready. Commit, deploy, publish, release, notify, migrate, and update production are human-triggered workflows because the moment they run matters as much as the steps inside them.

Custom commands now fit into the skill model, but the operational distinction is still useful: some skills Claude may choose, and some skills the user must invoke explicitly. Convenience is good for review, but it is not a deployment policy.

Use it when: the workflow has side effects and should start only by explicit user action.

Example:

---
name: deploy-staging
description: Deploy the current branch to staging.
disable-model-invocation: true
allowed-tools: Bash(pnpm test *) Bash(pnpm build *) Bash(./scripts/deploy-staging *)
---
Deploy $ARGUMENTS to staging.
1. Run tests.
2. Build the application.
3. Deploy to staging.
4. Verify the health endpoint.
5. Summarise the result.

Invoke it explicitly:

/deploy-staging payments-service

5. Isolated Investigator: subagents

A subagent runs work in its own context and returns a result to the main session. It can have its own prompt, tools, model, permissions, hooks, skills, and MCP access, which makes it useful when the investigation should not flood the main conversation.

Use this mechanism for noisy work such as broad code search, log analysis, security review, dependency audit, or parallel investigation. The main conversation does not need every intermediate grep result, and in many cases it is better to receive a focused conclusion than a transcript of the whole search.

Claude does not pick a subagent only because the file name sounds relevant. Automatic delegation depends on the task, current context, and especially the description; natural language is a hint, while an @ mention guarantees the subagent for one task and --agent makes it session-wide.

Use it when: the work is useful, but the transcript would pollute the main thread.

Example:

---
name: security-reviewer
description: Use proactively after auth, crypto, permission, or data-access changes.
tools: Read, Grep, Glob
model: sonnet
---
Review the changed files for security risks.
Return only concrete findings with file references, risk level, and fix suggestions.

6. Session Posture: output styles

Output styles change how Claude responds by modifying the system prompt to set role, tone, and output shape. They are useful for persistent posture, but they do not add project knowledge and they do not enforce correctness.

Use an output style when you want Claude to keep acting like an architecture reviewer, terse implementer, teacher, RFC reviewer, or pair programmer across the session. For strict JSON, exact document structure, or a policy that must always hold, use a schema, test, hook, or CI step instead. For coding styles, keep keep-coding-instructions: true unless you intentionally want to remove Claude Code’s default software-engineering behaviour.

Use it when: you keep asking for the same response style every turn.

Example:

---
name: Architecture Review
description: Respond as an architecture reviewer who explains trade-offs first.
keep-coding-instructions: true
---
Start with the trade-off being made.
Then cover coupling, operational impact, security risk, migration cost, and simpler alternatives.
Keep the answer direct. Avoid generic praise.

Set it in settings:

{"outputStyle":"Architecture Review"}

7. One-Run Overlay: --append-system-prompt

Appending to the system prompt is for temporary framing that applies to the current invocation without changing project memory, repository rules, or saved output styles.

Use it in scripts, CI jobs, one-off reviews, and temporary domain framing where the instruction is important for this run but should not become part of the repo. Keep it sharp, because a command flag can quietly become a second CLAUDE.md if every team preference starts getting pasted into it.

Use it when: the instruction matters for this run, not for the repo.

Example:

claude --append-system-prompt-file ./prompts/rfc-reviewer.txt

Where rfc-reviewer.txt says:

For this session, review changes as an RFC reviewer.
Always include risks, alternatives, and migration impact.

8. Live Capability Boundary: MCP servers

An MCP server is not another memory file and it should not be treated as one. It is a capability boundary that gives Claude a controlled way to reach live systems such as GitHub, Jira, databases, documentation, observability tools, browser automation, or internal APIs, where static context is either stale, too large, or unable to perform actions.

Tool search can defer MCP tools until needed, which reduces context cost, but broad MCP access is still broad capability. Use alwaysLoad only for the small set of tools Claude truly needs every turn, and connect the rest in a way that matches the task rather than exposing your whole stack by default.

Use it when: Claude needs live external data or external actions.

Example:

Use the GitHub MCP server to read PR #421, check unresolved comments, and review only the changed files.

9. Event Gate: hooks

Hooks run outside the prompt and fire on lifecycle events such as before a tool call, after a file edit, at session start, before compaction, or when a turn ends.

This is where “always do X when Y happens” belongs. PreToolUse is the place to block or validate before an action, while PostToolUse is better for formatting, logging, and reaction because the tool has already run by then.

Use it when: behaviour must run mechanically at a known event.

Example:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-bash.sh"
          }
        ]
      }
    ]
  }
}

The script can inspect the tool input and exit with the blocking code when it sees a dangerous command.

10. Hard Boundary: permissions

Permissions decide which tools, files, commands, domains, and skills Claude may use, and they are enforced outside the model context.

This is the right home for “never”, because prose helps the model understand a boundary while permissions make the boundary operational. A denied action cannot be negotiated back into existence by a convincing explanation in the chat.

Use it when: the action must be allowed, denied, or require approval regardless of what Claude wants to do.

Example:

{
  "permissions": {
    "allow": [
      "Bash(git diff *)",
      "Bash(pnpm test *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push --force *)"
    ]
  }
}

The decision tree

The mechanism catalog tells you what exists, while the tree gives you a practical starting point when you are about to place a new instruction.

The first question is the only one that changes the category: must this be guaranteed? If the answer is yes, stop writing a better paragraph and use permissions to allow, ask, or deny, or use hooks to run, block, or validate at a lifecycle event.

If the answer is no, decide whether you are steering work, context, voice, or capability. Work becomes a skill, manual command, or subagent; context becomes CLAUDE.md or a rule; voice becomes an output style or appended system prompt; live data and external actions become MCP.

That sounds like many choices, but in practice the map becomes fast: facts go to CLAUDE.md, scoped constraints go to rules, procedures go to skills, human-triggered procedures go to slash commands, noisy investigations go to subagents, session voice goes to output styles, one-off framing goes to appended system prompts, live capability goes to MCP, always-do behaviour goes to hooks, and never-do boundaries go to permissions.

What changes in long sessions

Long sessions make placement visible because compaction does not treat every mechanism the same way. Root CLAUDE.md and unscoped rules come back after compaction, but they still compete for attention. Nested CLAUDE.md files and path-scoped rules return only when Claude works near matching files again, while skill bodies enter when used and may need to be re-invoked after compaction.

Subagents keep noisy intermediate work out of the main thread and return summaries instead of full transcripts. Output styles and appended system prompts live at the system-prompt level for the session. MCP depends on how tools are loaded: tool search keeps tools deferred, while alwaysLoad puts them into startup context.

Hooks and permissions do not need to survive compaction because they never depended on the main context in the first place. They are code and configuration around the model, which is why the cheapest guardrail is often the one outside the context window.

Final takeaway

The recent Anthropic post on steering Claude Code is useful as a feature tour, but the team lesson is more operational. Claude Code is now a small operating environment around the model, and that means the steering layer deserves the same design attention as any other part of the system.

Scope controls cost, while enforcement controls reliability. Once you know how widely an instruction should apply and whether it must be guaranteed, the right mechanism becomes much easier to pick.

Subscribe to The Generative Programmer for practical maps, pattern catalogs, and production notes on AI coding agents.

A skill is the unit of reuse for a coding agent. It is a folder with a SKILL.md that teaches the agent a capability once so you stop re-explaining it in every session, and the agent loads it only when the task calls for it. If you want the background, Anthropic’s Equipping agents for the real world with Agent Skills and the Claude Code skills docs are the two primary sources worth reading first.

This is a companion to The Agentic Coding Reading List. That list curated the people worth following. This one curates the capabilities worth installing.

The thesis: the best skill is usually the one you write for your own codebase. But you should not start from a blank folder. Install the proven ones first, learn the shape, then write your own. Every link below was checked live. Here is the shelf.

The short version

If you only want the install path, use this order:

1. Start with the official repositories to learn what a good SKILL.md looks like.

2. Bookmark the marketplaces and awesome lists for discovery.

3. Install one workflow framework before collecting individual tricks.

4. Add vendor skills for the stack you actually use.

5. Write your own skill when you repeat the same instruction three times.

Skills are going portable. They began in the Claude ecosystem, but the SKILL.md format is spreading. OpenAI now documents skills in ChatGPT and Agent Skills for Codex, and several collections here already run across Claude Code, Codex, Cursor, and Gemini. Pick skills for what they do, not for one vendor.

Where to get them

Before any single skill, know where they live. Start at the source and work outward.

• anthropics/skills is the official Claude repository and the right first stop. It holds the document skills that ship with Claude, the mcp-builder, and skill-creator, which appears again at the end of this post. Reading a few of these is the fastest way to learn what a good SKILL.md looks like.

• openai/skills is the same idea from the other side: the official skills catalog for Codex, including ready-made integrations like a Linear skill. Its existence is the clearest signal that skills are becoming a cross-agent format, not just a Claude convention.

• Claude Skills Marketplace is the searchable directory of community skills, where you go when you have a specific job in mind and want to see what already exists before writing anything yourself.

• Smithery is a registry for skills and MCP servers with one-command installs, for when you want to wire something up quickly rather than clone and copy files by hand.

• Agensi rounds out the set as a marketplace that includes paid skills. Worth knowing the commercial layer exists, even if most of what you install will be free.

The collections I keep bookmarked

Three curated lists do the filtering for you. When a new skill trends, it usually shows up in one of these before it reaches the official repos.

• ComposioHQ/awesome-claude-skills is the broad awesome list for Claude skills, resources, and tools. The first place I check when I want a map of the whole landscape.

• VoltAgent/awesome-agent-skills collects over a thousand skills from official dev teams and the community, tagged by which agents they run on. Stronger on cross-CLI coverage if you are not Claude-only.

• Agent-Skills-for-Context-Engineering, by Murat Can Koylan, is the focused one: skills for context engineering, multi-agent architectures, and production agent systems. Reach for it when you are building agents, not just using them.

Start with a framework, not a single skill

The highest-leverage move is not one skill but a coherent collection that brings a whole way of working. Here is what I run, plus two widely watched collections worth studying.

• superpowers, by Jesse Vincent, is an agentic skills framework and development methodology rather than a loose bag of tricks. It gives the agent disciplined habits: brainstorming before building, test-driven development, systematic debugging, writing and executing plans, and asking for review at the right moments. This is the one I run daily because it changes how the agent works, not just what it knows.

• andrej-karpathy-skills distills Andrej Karpathy’s observations about where language models go wrong when they write code into a single drop-in guardrail. Also installed here, and a small one with an outsized effect: it heads off common failure modes before they reach your diff.

• gstack, by Garry Tan, is his exact Claude Code setup packaged for anyone to adopt: a couple of dozen opinionated tools standing in for a CEO, designer, engineering manager, release manager, and QA. Reach for it when you want a complete, pre-wired way of working rather than parts to assemble.

• mattpocock/skills, by Matt Pocock, is “skills for real engineers, straight from my .claude directory.” A working practitioner’s actual setup is often more useful than anything built to be shared.

Best practices for your stack

One of the most useful categories is official skills from the tools you already build on. It points at a real shift in how vendors ship knowledge. Instead of a documentation site you are meant to read, more teams now ship a skill the agent runs: best practices made prescriptive and executable rather than left as a guide you hope someone follows.

These are the ones I install to match my own stack.

• database-skills, from PlanetScale, teaches the agent to work with databases properly, schemas, queries, and migrations, instead of inventing SQL that looks right and breaks quietly. Pair it with neondatabase/agent-skills for Neon’s serverless Postgres, including a claimable Postgres skill that hands the agent a real database, and redis/agent-skills for caching done right.

• next-skills, from Vercel’s engineering team, carries the frontend half, with a next-best-practices skill that keeps the agent inside the framework’s intended patterns. supabase/agent-skills does the same for the Supabase platform.

• The vendor roster now reads like a stack diagram: Stripe for payments, Cloudflare for the edge, HashiCorp for Terraform, Hugging Face for models, and Trail of Bits for security, alongside Netlify, Sanity, WordPress, and Expo. Check whether the tools you depend on ship one. Increasingly, they do.

Pick a skill for your job

Past the frameworks, the rest is role-specific. Depending on what you do, grab the skill that matches your job. There are far more than these, but four map cleanly to four kinds of work. Follow this far enough and you will want one that does not exist yet, which is the next section.

• Software engineers want agent-skills, from Addy Osmani: a collection of production-grade engineering skills, less a single trick than a framework for the way careful, maintainable code gets written.

• Designers want open-design, by Nexu, a local-first, open alternative to Claude’s design tooling that turns the agent into something that can generate interfaces, prototypes, and slides across several agent CLIs.

• Anyone who writes wants humanizer, which strips the tells out of AI-generated prose, the giveaway phrasing and rhythm that make a draft read like a machine wrote it.

• Researchers and the perpetually curious want last30days-skill, by Matt Van Horn, which researches any topic across Reddit, X, YouTube, Hacker News, Polymarket, and the open web, then synthesizes a grounded summary. Not writing code, but gathering current signal before you do.

When none of these fit, build your own

Follow the list this far and you will hit the skill that should exist but does not. Once you have seen the shape of a good SKILL.md, your own repeated instructions are the next thing to capture, and two skills exist to help you do exactly that.

• skill-creator is Anthropic’s skill that builds skills. It scaffolds a new one and, in the spirit of the methodology, has you run it on a few test cases and read the transcripts before you trust it.

• Skill_Seekers, by Yusuf Karaaslan, comes at it from the other direction: it converts documentation sites, GitHub repositories, and PDFs into skills automatically, with conflict detection. This is the fast path when the knowledge you want already exists as docs and you just need it packaged.

Where skills and MCP blur

Not everything useful is packaged as a skill yet, and the line between a skill and an MCP server is getting thinner. Two tools make the point better than another definition.

• context7, from Upstash, pulls up-to-date, version-correct documentation and code examples for a library straight into the model’s context, so the agent stops writing against an API it half-remembers from training. It is also the cleanest example of the shift: it ships as an MCP server, a CLI, and a skill. Same capability, packaged three ways, installed however your setup prefers. I keep it on.

• Playwright is the same split caught live. Microsoft’s playwright-mcp is a widely used way to give an agent real browser control for automation and testing, and it is an MCP server. playwright-skill, by Jordan Lackey, rebuilds that capability as a model-invoked skill that writes and runs its own browser automation. Try both: the MCP if you want the mature option today, the skill if you want the load-only-when-needed behavior that context7 already points toward.

The takeaway

The marketplaces will tempt you with thousands of skills. That number is a trap. A handful you actually understand and trust will do more for your work than a directory you never open, the same way a short reading list of durable sources beats an endless feed.

Bookmark the collections, run a framework that changes how your agent works, add the vendor skills that match your stack, grab the one that fits your job, and then write the one that does not exist yet. That last one is the point of all the others.

Subscribe to Generative Programmer for practical maps, pattern catalogs, and production lessons for AI coding agents and agentic developer tools.

This is a living document. Last checked: 2026-06-14. If a skill here has moved or you think something essential is missing, tell me and I will update it.

Other development practices widened the same idea. Behaviour-Driven Development (BDD) moved the loop toward shared behavior and examples. Acceptance testing moved it toward user-visible definitions of done. CI moved it into the delivery pipeline. The shape stayed the same: define the next bit of intent, run the system, check the result, and tighten the design.

AI is widening the loop again. The thing inside one iteration used to be a line, a function, or a failing test. Now it can be a task, a pull request, a migration, or a recurring workflow. That is what I mean by loop-driven development: the engineer designs the trigger, goal, context, harness, verifier, and state around an agent loop.

This is not a claim that agents can safely own arbitrary software delivery. It is the opposite. The more autonomy you give the loop, the stronger the checks have to become. TDD did not remove engineering judgment. It pushed judgment into tests and refactoring. Loop-driven development does the same at a larger scale.

The progression is additive

The useful parts of each era do not disappear. Each era keeps the previous layer and adds a new control surface.

The progression looks like this:

code completion -> prompt loop -> repo context -> harness -> supervised loop

The unit of work keeps getting wider, and the engineer’s leverage point keeps moving up.

1. Autocomplete

2021-2022

Autocomplete put the model inside the editor. GitHub Copilot made this mainstream by drawing context from the code being edited and suggesting whole lines or functions. Cursor Tab belongs in the same era. It is the completion side of Cursor, where the model predicts the next edit and the developer accepts or rejects it while writing code.

The loop still lives mostly in the developer’s hands. You type, inspect the suggestion, accept or reject it, and continue. The benefit is speed: less boilerplate, fewer mechanical edits, and faster movement through familiar code. The limit is scope. The model helps with the next edit, but it does not own the task.

What got added:

• Model

• Local file context

• Inline completion

This was the Autocomplete era.

2. Prompt Engineering

2022-2023

The next step was to move from completion to task steering. ReAct was not a coding assistant, but it gave agents an important primitive: reason, act, observe, repeat. The model could think about a step, call a tool, read the result, and continue.

AutoGPT made the idea feel autonomous. Instead of asking for one answer, you gave the system a goal and let it prompt itself. That shift created the first native discipline of this era: prompt engineering. The developer was no longer only writing code. The developer was writing instructions that caused code to be written.

I still believe this skill never fully goes away. You have to know how to talk to these models well, in one form or another, which is what I have been collecting in my Prompt Patterns book.

The benefit was delegation at the task level. You could ask for a script, a test suite, an investigation, or a migration plan. The limit was convergence. A prompt loop without disciplined context and a reliable stop condition can drift, repeat itself, or optimize for the wrong thing.

What got added:

• ✓ Model

• Tools

• Goal

• Prompt loop

This was the Prompt Engineering era.

3. Context Engineering

2024-2025

Once agents could act, the bottleneck became what they could see. A coding agent needs repo context, not only a prompt. It needs files, tests, logs, conventions, architecture notes, issue history, and the current state of the work.

This is where Cursor Agent, Devin, and Ralph-style loops fit. Cursor Agent moves beyond tab completion into autonomous coding tasks, terminal commands, and file edits. Devin is positioned as an autonomous software engineer that can write, run, and test code. Ralph made a narrower but important point: durable state should live in files and git, not only in the chat transcript.

The benefit is scope. Agents can work across files, run commands, inspect failures, and make repo-aware changes. The limit is that context is not correctness. A well-contextualized agent can still finish the wrong task unless the environment can tell it what done means.

I wrote about the broader tool landscape in AI Coding Assistants Landscape. The pattern that matters here is the move from assistant-in-editor to agent-in-codebase.

What got added:

• ✓ Model

• ✓ Tools

• ✓ Goal

• Repo context

• Terminal / files

• Tests

This was the Context Engineering era.

4. Harness Engineering

2025-2026

A harness is the environment a single agent runs inside. It includes the prompt, repo context, tools, sandbox, permissions, tests, linters, type checks, CI, evals, and review gates. The point of a harness is not to make the model magically correct. The point is to make the work observable, constrained, and checkable.

OpenAI Codex is a clear example. Codex runs in isolated cloud containers, works against the provided repository, edits files, runs commands, and can propose changes for review. OpenAI’s own harness engineering write-up describes the role shift directly: engineers design environments, specify intent, and build feedback loops that let agents do reliable work. Claude Code fits the same era from the terminal side: it understands a codebase, edits files, runs commands, and handles git workflows.

This is why I think the harness framing is more useful than another prompt taxonomy. In 12 Agentic Harness Patterns from Claude Code, I broke the harness into reusable patterns: persistent instructions, scoped context, memory tiers, tool permissions, lifecycle hooks, and workflow separation. In The Missing Quality Layer for AI Coding Agents, I argued that the next bottleneck is proving the diff is safe to review, not generating the diff.

The benefit is repeatability. The agent no longer just generates code. It runs inside a system that can reject bad work. Deterministic checks should come first: tests, builds, type checks, lint, contract tests, benchmarks, screenshots, traces, and CI. Model-based judging can help with subjective checks, but maker and checker should be separated. These checks matter most when they push back on the agent in the moment rather than after the fact, giving the loop backpressure so it self-corrects before a human has to step in.

What got added:

• ✓ Model

• ✓ Tools

• ✓ Goal

• ✓ Repo context

• Sandbox

• Verifier

• CI / eval harness

This was the Harness Engineering era.

5. Loop Engineering

Now

Once the harness is reliable, the next layer is the loop that runs it. A loop is not just an automation. An automation executes fixed steps. A loop has a decision inside it. It checks whether the goal is met and decides whether to continue.

A practical agent loop has five parts:

• Trigger: human kickoff, schedule, or event

• Goal: the desired end state

• Harness: the environment the agent runs in

• Verifier: the check that decides whether to continue

• State: memory outside the current model call

This is where current tools are converging. Codex has /goal for long-running work with a verifiable stopping condition and Automations for recurring tasks. Claude Code has /goal, /loop, and scheduled tasks for recurring work. MCP gives agents a standard way to connect to external tools and data sources. Addy Osmani’s Loop Engineering framing captures the same ingredient set: automations, worktrees, skills, connectors, sub-agents, and memory.

The benefit is leverage. A loop can watch CI, triage issues, update dependencies, fix flaky tests, chase review feedback, prepare PRs, and keep working until a condition holds. The risk grows with the leverage. A bad prompt wastes a turn. A bad loop can waste hours, mutate the repo, and generate a pile of plausible work that still needs human judgment.

Skills and playbooks become especially important here. A loop that has to rediscover project conventions every run is fragile. A loop that can call well-scoped skills has a better chance of doing the same work consistently. That is why I see skills as part of the loop substrate, not only better prompt files. I wrote more about that in 9 Principles That Separate Useful Skills from Markdown Essays.

What got added:

• ✓ Model

• ✓ Tools

• ✓ Goal

• ✓ Repo context

• ✓ Verifier

• Automations

• Worktrees

• Skills / playbooks

• Connectors (MCP)

• Durable memory

• Orchestration

This is the Loop Engineering era.

The Engineering Leverage Stack

What the stack below shows is not five tools but a single control point moving up. Each era lets you author less of the code directly and more of the system that produces it, trading fine-grained control for reach. The higher you stand, the more a single decision is worth, and the more it leans on the checks in the layers beneath it.

A harness is the environment for one agent run. A loop is the control system around that harness. A factory is a system of loops: one loop finds work, another implements it, another verifies it, another opens or updates the PR, and another escalates what needs human judgment.

That is the leverage shift:

The important word is wrap. Prompting did not replace coding. Context did not replace prompting. Harnesses did not replace context. Loops do not replace harnesses. Each layer wraps the one below and changes where engineering judgment is applied.

What loop-driven development means

Loop-driven development is TDD at a larger unit of intent. In TDD, the loop wraps a unit of behavior: write the failing test, make it pass, refactor. In loop-driven development, the loop can wrap a task, a PR, a migration, or a recurring workflow.

The verifier is the difference between a loop and a vibe. Without a verifier, you have repeated prompting. With a verifier, the loop can converge. The verifier can be deterministic, like tests and builds, or probabilistic, like a separate reviewer model, but it has to exist outside the agent’s desire to be done.

This is also where the human role becomes more important, not less. The engineer chooses the goal, designs the context, sets the permissions, defines the checks, reviews the result, and decides what risks are acceptable. The loop can run faster than you can type, but it cannot decide what should matter.

The takeaway

Software was always written in a loop. TDD made the loop explicit around behavior. BDD and acceptance testing widened it toward product intent. AI is widening it again around agents, harnesses, and recurring workflows.

That is the shift from test-driven to loop-driven development.

Not because tests stop mattering. Because tests, evals, reviewers, sandboxes, worktrees, skills, memory, and CI are becoming parts of a larger loop.

Build the loop. Stay the engineer.

Subscribe to The Generative Programmer for practical maps, pattern catalogs, and production notes on AI coding agents.

The failure mode is simple: the agent produces code faster than the engineering system can push back on bad output. Without that pushback, the human becomes the compiler, the test runner, the linter, the UI checker, and the reviewer. Every trivial mistake waits for a person to notice it, explain it, and send the agent back for another attempt.

That is not review. That is babysitting.

In Don’t waste your back pressure, Moss Banay describes this as wasted human backpressure: spending attention on mistakes the agent should have been able to detect itself, such as missing imports, broken builds, and visual errors.

I call this the Backpressure Loop Pattern.

The problem

A coding agent is a fast producer. The human reviewer is a slow consumer.

That mismatch creates pressure. If the only meaningful feedback comes from the human, every failure becomes review work. The agent writes code, the human spots a broken test, the human explains the failure, and the agent retries.

That loop does not scale.

Marc Brooker makes the deeper point in What’s Easy Now? What’s Hard Now?: agents are feedback loops around a useful but flawed model. The key shift is moving feedback from the human loop into the agent loop: build, test, inspect, repair, and iterate.

So the question is not only:

How good is the model?

The better question is:

What feedback can the agent use without asking me?

The pattern

Intent: Move cheap correctness checks out of human review and into the agent loop.

Context: A coding agent can edit files, run commands, read failures, and retry.

Problem: Agents produce code faster than humans can validate it.

Solution: Expose fast, machine-readable feedback sensors to the agent: types, tests, linters, builds, browser checks, logs, traces, and structural rules.

Result: The agent fixes mechanical failures before review. The human focuses on intent, design, and trade-offs.

What counts as backpressure

Backpressure is any signal that can push back on bad agent output before a human spends attention on it.

Thoughtworks calls these feedback sensors for coding agents: deterministic quality gates wired into agent workflows so failures trigger self-correction.

That distinction matters:

• A CI failure after the agent is done is a gate.

• A failure the agent sees while working is backpressure.

A green build is not enough

A green build is useful, but narrow.

It tells you the code compiled, the formatter ran, and the existing tests passed. It does not prove the product rule survived. It does not prove the generated test asserts meaningful behavior. It does not prove the refactor respected the architecture.

So the goal is not just “run CI earlier.”

The goal is to make feedback fast, specific, and actionable enough for the agent to repair the work.

Bad feedback:

The code is wrong.

Better feedback:

auth/session.test.ts failed.
Expected expired sessions to redirect to /login.
Received 200 from /dashboard.
Fix the session expiration path.
Do not change the test.

The second version gives the agent something to do.

Effective feedback beats more feedback

More output is not the same as better backpressure.

A recent arXiv preprint, Scaling Laws for Agent Harnesses via Effective Feedback Compute, makes this point in research terms. The authors argue that agent harnesses scale less with raw tokens, tool calls, wall time, or cost, and more with how efficiently they convert raw budget into useful feedback.

They call this Effective Feedback Compute: feedback that is informative, valid, non-redundant, and retained for later decisions.

That maps directly to coding agents.

A test failure is useful only if the agent can understand it, trust it, avoid repeating it, and use it to change the next attempt.

Useful backpressure has four properties:

That is why a thousand lines of logs can be worse than a short, structured failure.

The goal is not more agent activity. The goal is more effective feedback.

How to implement it

Start with the boring checks.

Put the exact commands in AGENTS.md, CLAUDE.md, or the equivalent project instruction file:

After changing TypeScript:
- run npm run typecheck
- run npm run lint
- run npm test -- --changed
- fix failures before opening a PR

Then make the output efficient.

Do not dump hundreds of lines of passing test output into the agent context. Passing checks should be tiny. Failing checks should show the useful detail.

HumanLayer describes this as context-efficient backpressure: replace passing test, build, and lint output with a small success signal, but expose full output when a command fails.

Example:

✓ typecheck
✓ lint
✗ auth tests
FAIL auth/session.test.ts
Expected redirect to /login for expired session.
Received 200 from /dashboard.

That is enough signal for the agent to continue.

The rule:

Success should be compressed. Failure should be actionable.

The trade-off

Backpressure is not free.

Fast sensors improve flow, but slow sensors choke it.

Do not put every possible check inside the inner loop. Layer them.

In session:
typecheck, lint, focused tests, build, screenshots
Before PR:
full tests, integration tests, structural rules, security checks
Scheduled or explicit:
mutation testing, fuzzing, semantic evals, architecture drift review

Birgitta Böckeler’s Maintainability sensors for coding agents is useful here because it separates sensors that run during the coding session from sensors that belong in the pipeline, on a schedule, or in production.

That is the right mental model: not every check belongs in the same loop.

The inner loop should be fast enough that the agent can run it repeatedly. Slower checks belong outside the session unless the task is risky enough to justify the cost.

The rule

When you correct the same agent mistake twice, turn it into backpressure.

A test.
A type.
A linter rule.
A build check.
A browser assertion.
A better error message.
A small script the agent can run before it asks for review.

The future skill is not asking agents to try harder.

It is designing feedback loops that make bad output harder to accept.

That shift matters because coding agents make the first draft cheaper, but they do not make quality automatic. A green build is still a narrow signal. It tells you the code compiled, the formatter ran, and the existing tests passed. It does not tell you whether the agent preserved the product rule, whether a generated test asserts real behavior, whether a refactor crossed an architectural boundary, or whether an installed MCP server had access to credentials it should never see.

The trend I’m seeing is the emergence of a quality layer around agentic coding. It sits between the agent and the pull request. Its job is to give the agent useful feedback while it works, constrain risky changes before they grow, and leave enough evidence behind for humans to understand what happened later.

This is where Birgitta Böckeler’s work on maintainability sensors for coding agents is useful. She describes how agents can quietly compound inadvertent technical debt when they lack the right feedback signals. OpenAI’s Codex engineering team describes a similar discipline as harness engineering: custom checks, architectural constraints, and repository-level quality signals become part of the environment agents work inside.

I think of this as the agent quality layer. It has two jobs: catch mistakes before they become review work, and prove where the work came from after it lands.

This post covers five practical controls for that layer. Each one names a failure mode, the control that reduces it, and tools or techniques teams can use today.

1. Feedback Sensors

A coding agent that produces a diff without compiler feedback turns the human reviewer into the first quality gate. Reviewers end up seeing type errors, broken builds, failing tests, formatting noise, and simple lint violations that should never leave the session.

Feedback sensors wire deterministic checks directly into the agent’s loop. Compilers, linters, type checkers, structural tests, and focused test suites run during the session. When a check fails, the agent sees the output and tries again before the human reviews the diff.

The useful detail is not only running the check, but giving the agent failure messages it can act on. Böckeler describes embedding self-correction guidance inside lint errors, for example through a custom ESLint formatter. The agent sees what failed, why it failed, and how the team expects the fix to look. OpenAI’s Codex team describes the same move: custom lint messages carry remediation guidance into the agent context at the point of failure.

Related tools and techniques.

• Start with the compiler, type checker, project-specific lint rules, focused test commands, and build validation for the changed module.

• Add custom lint formatters for recurring agent mistakes.

• Use mutation testing tools such as cargo-mutants when passing tests is not enough evidence that tests assert meaningful behavior.

• Use fuzzers such as WuppieFuzz for API and input-space testing where examples miss edge cases.

• In Claude Code or Cursor, run fast checks through hooks, tasks, or a reviewer agent so they happen consistently.

When to use. Any team using coding agents on production code. Start with fast checks in the session: lint, types, focused tests, and build validation for the changed module.

The main trade-off. Slow sensors choke the loop. Keep fast checks in-session, and push slower checks such as mutation testing, fuzzing, and modularity reviews into CI, scheduled runs, or explicit review passes.

2. Semantic Evals

Deterministic sensors catch mechanical failures, but they do not catch code that compiles, passes tests, and still does the wrong thing. This is common with agent-generated tests, policy logic, tool-use workflows, data transformations, and customer-facing answers where correctness depends on meaning rather than syntax.

Semantic evals add probabilistic checks that score output against expected behavior. A semantic eval might verify that a generated test fails for the right reason, that an agent used the correct tool sequence, that a response stayed grounded in retrieved evidence, or that a policy decision matches known examples.

The eval suite should live near the test suite, but it evaluates agent behavior and generated output rather than only deterministic function results.

Related tools and techniques.

• Keep a small golden set of examples for behavior the agent must preserve.

• Use DeepEval or a similar framework for tool-use, hallucination, answer-quality, and custom use-case checks.

• Use LLM-as-judge only with reviewed examples, clear thresholds, and failure review.

• Consider approaches such as semantic entropy when you need to flag fluent answers that may still be uncertain.

• For code structure, use LLM-assisted analyzers such as Vlad Khononov’s modularity plugin to inspect coupling, abstraction boundaries, and semantic duplication.

• Combine semantic review with deterministic rules. Do not make model judgment the only gate.

When to use. Agent-generated logic that affects business decisions, customer workflows, policy interpretation, migrations, or domains where correctness is hard to verify by reading.

The main trade-off. Semantic eval is itself probabilistic. False positives train teams to ignore alerts, while false negatives create a false sense of safety. Treat the eval suite as production code: review examples, tune thresholds, and track failures over time.

3. Refactor Boundaries

Coding agents can rewrite code faster than humans can review it. That speed is useful in clean modules and risky in old, high-churn parts of the codebase. A 2,000-line god class with twelve years of business logic is exactly the kind of structure an agent may confidently refactor, and exactly the kind of structure where a refactor can delete behavior nobody documented.

Refactor boundaries classify the codebase by complexity, churn, ownership, and architectural risk before the agent starts rewriting. The output is a practical map: green zones for routine edits, yellow zones for scoped changes with focused tests, and red zones where large rewrites need human design first.

The point is not to block agents from refactoring. The point is to make safe refactoring cheaper than unconstrained rewriting.

Related tools and techniques.

• Use CodeScene or a similar tool to combine static complexity metrics with version-control history and surface hotspots.

• Mark high-risk files with CODEOWNERS, required reviewers, or path-based approval rules.

• Use dependency-cruiser, ArchUnit, or Spring Modulith to enforce module boundaries and dependency direction.

• Track a lightweight quality score per domain or module, especially in areas where agents make repeated changes.

• Let agents make small cleanup PRs in green zones, but require a human design step before broad rewrites in red zones.

OpenAI’s Codex team applies this shape at scale by splitting business domains into fixed layers, tracking per-domain quality, and enforcing architectural boundaries with custom linters. That is the practical lesson: constraints make speed safer.

When to use. Any codebase where not every file is equally safe for an agent to touch. This usually starts once the codebase has legacy modules, high-churn hotspots, or undocumented domain rules.

The main trade-off. Hotspot maps need calibration. The line between safe and unsafe is judgment, not a constant, so teams should revisit thresholds as the codebase and agent capabilities change.

4. Provenance Trails

Traditional attribution assumes a human wrote the code. In an AI-assisted codebase, that assumption breaks down because a line may come from a human, an agent, or a mixed session where the human accepted, edited, and committed generated output. git blame shows who committed the line, but not which model, prompt, skill, or tool contributed to it.

Provenance trails capture attribution for AI-generated changes with enough detail to reconstruct what happened later. At minimum, this means recording whether a change was human-authored, AI-authored, mixed, or unknown. A more useful trace also records the agent, model, prompt or task description, tool calls, installed skills, and the point where a human took over.

The practical benefit is not only auditability. Humans and agents can query the original intent behind a block of code before changing it again.

Related tools and techniques.

• Start with low-friction provenance in PR metadata: agent used, model, prompt summary, tool summary, and generated files.

• Use Git AI when you need commit-level or line-level tracking of AI-generated code.

• Track attribution with Git Notes or another side channel when you do not want provenance metadata in source files.

• Watch Agent Trace, Cursor’s proposed format for AI code attribution across version-control systems.

• Move from PR-level metadata to line-level attribution when audits, compliance, or long-lived generated code justify the cost.

When to use. Teams that need to audit AI contributions, debug generated code, or reconstruct why a piece of code exists months after it was merged.

The main trade-off. Attribution metadata grows with the codebase. Storage, query cost, and developer workflow friction are real, so the harness should record provenance automatically instead of relying on manual discipline.

5. Agent Surface Inventory

The agent’s surface area is no longer just the model. It includes skills installed in the plugin directory, MCP servers it can call, marketplaces it pulls from, and credentials it can reach. Each one is a dependency, and some of them have more access than a library imported into application code.

Agent surface inventory treats that surface like a software supply chain. The team keeps an inventory of installed skills, plugins, MCP servers, versions, owners, permissions, credential scopes, and source locations. New entries go through review before they become part of the approved harness, and existing entries are scanned for risky flows.

This is the same basic discipline teams already apply to package dependencies: know what is installed, know who owns it, pin versions where possible, and review anything that gets access to internal systems.

Related tools and techniques.

• Maintain an allowlist of approved skills, plugins, and MCP servers.

• Version-pin what is installed.

• Use least-privilege credentials for MCP servers.

• Scan local agent directories in CI or on developer machines.

• Use Snyk Agent Scan to inspect MCP servers, skills, and plugins for risks such as prompt injection, tool poisoning, toxic flows, hardcoded secrets, and unsafe credential handling.

• Use MITRE ATLAS as a shared vocabulary for threat modeling AI systems and agentic attack paths.

• Treat marketplace installs the same way you treat npm, Maven, or container dependencies: reviewed, versioned, and owned.

When to use. Any team that allows skills, plugins, or MCP servers from sources the team did not author, or any team where agents can reach internal systems through credentials.

The main trade-off. Scanners produce noise. Validate signal quality and false-positive rates in the team’s own environment before scan results become a hard gate, otherwise developers learn to ignore the output.

The takeaway

AI coding agents make first drafts cheaper, but trust still comes from engineering controls: fast feedback, semantic evals, refactor boundaries, provenance, and agent-surface inventory.

The Thoughtworks Technology Radar is a useful signal that these practices are becoming normal engineering hygiene, not a separate AI ritual. The tools will change, but the quality layer will remain.

This builds on the foundation I covered in How Teams Scale Claude Code Across Monorepos and Large Codebases: context, maps, skills, hooks, and shared harnesses. Once agents can find the right code, the next question is whether teams can trust what they change.

This post follows my 12 Agentic Harness Patterns. It looks at how engineering organizations adapt Claude Code for large codebases, based on Anthropic’s post on how Claude Code works in large codebases.

The 13 patterns fall into three groups:

1. How Claude finds the right code context.

2. How the harness keeps a session effective.

3. How a working setup reaches every developer and stays maintained.

   

Navigating the Codebase

In a large codebase, Claude is only as useful as its ability to find the right context. Loading too much context slows it down and distracts it, while loading too little leaves it guessing. These four patterns make the repo legible before Claude starts reading files.

1. Context Cascade Pattern

A single root-level CLAUDE.md becomes either bloated or too vague. In a large repo, one file cannot carry every team’s conventions, commands, and gotchas without turning into noise.

The Context Cascade pattern puts CLAUDE.md files at multiple levels of the tree. The root file contains global rules, pointers, and critical gotchas. Subdirectory files hold local commands, conventions, and domain terms. Claude loads the files along the path from the working directory to the root, so guidance gets more specific near the code being edited.

Start the session where the work happens. Running claude from services/payments/ picks up the payments-specific tests, lint rules, and build commands. Starting from the repo root may only load the root guidance. This works well in service-oriented monorepos, while compiled-language monorepos with deep cross-directory dependencies may also need project-level build configuration.

When to use. Any monorepo with multiple team conventions, or any codebase where subtrees follow different rules.

The main trade-off. The cascade only works if teams keep each level focused. Session-level notes in the root file, or universal rules buried in a leaf directory, undo the benefit.

2. Repo Map Pattern

When directory names are opaque, Claude cannot infer where to start. Legacy partitions, internal codenames, domain slices, and years of reorgs all create the same problem: the right code exists, but the tree gives weak clues.

The Repo Map pattern adds a lightweight Markdown file at the repo root. It lists each top-level folder with a one-line description. Claude scans the map before opening folders, which reduces blind search.

Keep the map boring and factual: folder name, owner if useful, purpose, and main entry points. Avoid architecture prose that will go stale.

When to use. Repos with unconventional layouts, legacy partitions, internal codenames, or many top-level folders. It also helps new engineers orient themselves.

The main trade-off. This adds one more file to maintain. Stale entries actively mislead Claude and send it down the wrong path with confidence.

3. Noise Filter Pattern

Generated files, build artifacts, and vendor code distract Claude in every session. A blanket exclusion rule helps most developers, but it can hurt the team that owns the generator and needs to inspect those files.

The Noise Filter pattern commits default exclusions in .claude/settings.json. Every developer inherits the same search and read defaults on clone. Developers who need exceptions override them locally without changing the team baseline.

When to use. Any repo where generated code, vendor folders, or build outputs would otherwise pollute Claude’s searches.

The main trade-off. Over-aggressive exclusions hide files that downstream code depends on. Local overrides are the safety valve, but only for developers who know they exist.

4. Symbol Lookup Pattern

A text search for handleRequest in a million-line codebase can return thousands of matches. Claude then burns context opening files just to find the relevant symbol. It can also pick the wrong one, such as two User classes in different modules or two functions with the same name in different languages.

The Symbol Lookup pattern exposes Language Server Protocol capabilities to Claude. Text matching becomes symbol resolution, and filtering happens before Claude reads files. This is especially valuable in strongly typed, multi-language codebases where mature language servers already exist.

When to use. Multi-language codebases, repos with common function names, and ecosystems with mature LSP support such as C, C++, Java, C#, and TypeScript.

The main trade-off. The setup cost is real. Each language needs the right code-intelligence plugin and language server binary, and ecosystems with weak LSP support will return less value.

Scaling the Harness

The harness, not the model alone, determines how well Claude Code performs in a large repo. Here, harness means CLAUDE.md, hooks, skills, plugins, MCP servers, and subagents. These five patterns keep sessions useful as the codebase grows.

5. Just-in-Time Skill Pattern

A large codebase carries many task types: security review, docs, deploys, migrations, release checks, and more. Only one or two matter in a given session, so loading every workflow into CLAUDE.md makes every session pay for knowledge it does not need.

The Just-in-Time Skill pattern packages each specialized workflow as a skill that loads only when the task calls for it. The base context stays small, and task-specific knowledge appears when needed.

Keep each skill narrow: when it should trigger, what steps it follows, which commands it runs, and what common failures mean.

When to use. Any codebase with more than a handful of distinct task types, especially when workflows would dwarf the actual coding context.

The main trade-off. Activation logic needs care. Skills that trigger too eagerly bloat context; skills that trigger too narrowly stay dormant when they would have helped.

6. Scoped Skill Pattern

In a monorepo, a payments deployment skill should not load while someone edits the inventory service. Generic skill activation ignores where the work is happening, which turns useful expertise into noise.

The Scoped Skill pattern binds skills to specific subtrees. Teams can place skill files under a subtree’s .claude/skills/ directory or use paths globs in the skill frontmatter. A payments deployment skill becomes visible in payments sessions and invisible elsewhere.

When to use. Multi-team monorepos where subtree-specific procedures differ enough that cross-loading them is harmful.

The main trade-off. Skill ownership can outlive team ownership. When a path changes hands, its skill bindings need review.

7. Scout Subagent Pattern

Mapping a subsystem and editing code are different jobs. Doing both in one session burns the same context window on exploration, notes, and implementation. By the time editing starts, the context may already be polluted with irrelevant detail.

The Scout Subagent pattern uses a read-only subagent for exploration. The scout maps the subsystem in its own context, writes findings to a file, and returns the path. The main agent then reads the findings and edits with a cleaner context.

A useful scout output is concrete: relevant files, ownership boundaries, important call paths, tests to run, and risks to avoid.

When to use. Refactors, cross-cutting bug fixes, security audits, or integrations with code Claude has not seen before.

The main trade-off. This adds another round-trip, and the scout’s findings are only a snapshot. If later edits invalidate an assumption, the main agent must notice and re-check.

8. Search-as-a-Tool Pattern

Claude’s default tools work inside the repo, but much of the knowledge a developer needs does not. Design docs, postmortems, runbooks, tickets, dashboards, and incident notes often contain the answer Claude needs.

The Search-as-a-Tool pattern wraps the organization’s existing search infrastructure as a tool Claude can call. That search backend might be Elasticsearch, Glean, an internal knowledge graph, or another system. MCP is only the mechanism; the pattern is making institutional knowledge accessible from the coding session.

When to use. Organizations where Claude routinely needs information outside the repo and where internal search already exists.

The main trade-off. The search tool becomes critical infrastructure, so outages affect every session that depends on it. Access control also matters because Claude inherits the permissions behind the tool.

9. Deterministic Checks Pattern

Instructions such as “always run the linter before committing” are easy to forget. They compete with every other instruction in context and produce inconsistent behavior across sessions.

The Deterministic Checks pattern moves quality enforcement from instructions into hooks. Linting, formatting, type-checking, and targeted tests run on defined events whether Claude remembers them or not.

When to use. Any rule that can be expressed as “this check must always run on this event”: lint on save, format before commit, type-check after file write, or run a focused test after a generated change.

The main trade-off. Slow hooks drag every session, and hooks that fail noisily interrupt Claude’s flow. Checks should be fast, focused, and easy to interpret.

Rolling Out the Harness

The technical patterns only matter if they reach developers and stay maintained. These four patterns cover packaging, rollout, governance, and continuous improvement. In most organizations, a single DRI owns the harness. In larger ones, this becomes an “agent manager” role: a hybrid PM and engineer responsible for settings, permissions, plugin catalogs, and CLAUDE.md conventions.

10. Harness Bundle Pattern

Good Claude Code setups often stay tribal. One engineer wires up a useful mix of skills, hooks, and MCP servers on their machine. Another team rebuilds the same thing months later, usually worse. New engineers start from zero.

The Harness Bundle pattern packages skills, hooks, and MCP configuration into a single installable plugin. New engineers install it on day one and inherit the team’s working setup. Updates flow through a managed channel instead of copy-pasted local config.

When to use. Whenever a useful configuration exists on one machine and the team would benefit from sharing it. Most teams reach that point within weeks of adoption.

The main trade-off. Bundles ossify. A plugin that everyone installs becomes hard to change without coordinating across consumers, just like any shared library.

11. Day-One Harness Pattern

A developer’s first Claude Code session strongly shapes adoption. If they must assemble the harness before getting value, many bounce. Bottom-up enthusiasm can also fragment into incompatible local setups.

The Day-One Harness pattern builds the harness before broad access opens. A small team prepares the core plugins, MCP servers, skills, hooks, and docs so a developer’s first session works with the codebase, not against it.

When to use. Any organization rolling out Claude Code beyond a pilot, especially when the codebase has non-obvious conventions.

The main trade-off. Pre-rollout work costs time and people. Skipping it is cheaper at first, but usually creates a long tail of fragmented setups to clean up later.

12. Curated Starter Set Pattern

Open access to every skill and plugin creates security, governance, and consistency problems. A misconfigured MCP server can read too much. An unreviewed skill can push developers toward unsafe workflows. Blocking everything kills adoption.

The Curated Starter Set pattern starts narrow: approved skills and plugins, required review processes, and limited initial access. The set expands as confidence grows and edge cases become clear.

When to use. Regulated industries such as finance, healthcare, and defense. It is also useful in any large organization where security review comes before broad adoption.

The main trade-off. An overly conservative starter set frustrates early advocates. The expansion cadence matters as much as the starting set; slow curation makes the rollout feel blocked.

13. Self-Improving Hook Pattern

Claude’s mistakes are visible during a session and then easy to forget. The next session repeats them. CLAUDE.md improves only if someone updates it while the lesson is still fresh.

The Self-Improving Hook pattern runs a stop hook at session end. The hook reviews the transcript and proposes CLAUDE.md updates, including additions and retirements. It also surfaces drift as models and tools improve. A workaround that helped an older model may constrain the current one; a shim for a missing tool may become dead weight once native support lands.

When to use. Teams that actively maintain CLAUDE.md and benefit from small, frequent improvements. It pairs especially well with the Context Cascade pattern.

The main trade-off. Without curation, suggestions pile up and noise overtakes signal. The hook proposes changes, but humans still decide what to merge.

The takeaway

Claude Code can work well in large codebases, but not because it magically understands the whole repo. It works when the codebase gives it the same advantages a good engineer has: a clear starting point, local conventions near the code, a map when the structure is not obvious, and tools that expose knowledge outside the repo.

The practical setup is not one giant CLAUDE.md. It is a fitted harness around the existing codebase: a small root file, local CLAUDE.md files, repository maps, path-scoped skills, fast hooks, LSP-backed symbol lookup, and search tools for internal knowledge. Together, these narrow the work before Claude spends context.

The best large-codebase setups look ordinary from the outside. They reduce search waste, load context just in time, enforce checks consistently, and make one good configuration available to every developer. The goal is not more agent infrastructure. It is a codebase that Claude Code can enter at the right place, read with the right hints, and change without dragging the whole repository into the session.

Skills come in many shapes: task workflows, reference guides, persona prompts, tool wrappers. The tactical advice for each is in my previous post on skill authoring patterns. Underneath those tactics sits the same kind of higher-level layer: a small set of principles that cut across every skill type. They are not rules about what to put inside a SKILL.md. They are the questions you ask before reaching for any specific pattern: should this skill exist at all, can it be found when it matters, and will it still be useful six months from now?

Nine principles in three acts: getting selected, running reliably, and surviving contact with reality.

Act 1: Getting Selected

These principles apply at the moment a request arrives, before the skill body has run. They cover whether the skill is recognised at all, what it costs to bring into context, and what shape its content needs to take to actually drive work. A skill that fails here never gets the chance to be useful.

1. Metadata is the gate

At session start, Claude does not read every SKILL.md. It sees the skill listing: metadata such as the name and description; in Claude Code, any when_to_use text can also be included in that listing. A vague description (”helps with documents”) never fires when it should, fires when it shouldn’t, or competes with three other skills for the same trigger.

The principle: the description is not a summary; it is the main signal at selection time. A skill that fails the metadata-only round never runs.

Two of the skill authoring patterns serve this principle from opposite sides. Activation Metadata is how you pull the right skill in: positive triggers, domain keywords, and the “pushy” framing Anthropic’s skill-creator recommends. Exclusion Clause is how you push the wrong ones out: “Do NOT use for blog articles, newsletters, or long-form content.” Same goal, opposite directions.

The same skill, weak and strong:

Weak: “Helps with dashboards and visualization.”

Strong: “Use whenever the user mentions dashboards, internal metrics, or data visualisation, even if they do not explicitly ask for a dashboard. Do NOT use for blog charts, marketing graphics, or one-off notebook plots.”

This principle guides the trade-off between discoverability and budget. The Agent Skills docs cap description at 1024 characters; Claude Code truncates description plus when_to_use at 1536 characters in the skill listing. Every sentence competes with positive triggers, exclusions, and domain keywords for the same finite slot, so being precise about the skill’s intent matters more than covering every edge case. Write the description as if those characters cost real money. In practice, they do.

2. Disclose progressively

Context is a shared budget. Every token your skill spends is a token unavailable to every other skill, the conversation history, and the user’s actual request. A skill that re-explains what JSON is, what a database is, or how an API works wastes that budget on things Claude already knows. Multiply verbose metadata across many installed skills, or bloated SKILL.md bodies across a multi-skill task, and useful context disappears before the hard work begins.

The principle: load only what the current task needs, and load it only when it needs it. Metadata loads at session start; SKILL.md loads only when the skill is triggered; reference files load only when the current task points to them. Scripts in scripts/ can be invoked via Bash, so their source never has to enter context. Only their output does.

Two of the 14 skill patterns serve this principle. Context Budget is the discipline of being frugal with the words you do load. Progressive Disclosure is the structural technique of tiering what gets loaded when. The halves are inseparable: frugality without tiering still loads everything in full; tiering without frugality just spreads the bloat across more files.

A bloated and a frugal opening for the same skill:

Bloated: “A database is a structured collection of data... Migrations are scripts that update the schema... PostgreSQL is a relational database...”

Frugal: “Schema changes go in supabase/migrations/, named YYYYMMDDHHMMSS_description.sql. See references/migration-format.md for the four required artifacts.”

This principle guides the trade-off between frugality and model strength. What reads as crisply concise to Sonnet may be too terse for Haiku, which needs more guidance to reach the same outcome. If you target multiple models, write to the level the weakest one needs and let stronger models skim. Frugality that breaks weaker models is false economy: you saved the tokens, then paid them back in retries and corrections.

3. Process over prose

A skill that opens with two thousand words on the philosophy of testing gets read, generates a plausible summary, and still lets the agent skip the actual testing. Reference essays are not actionable. Many “AI rules” repos that ship as long markdown files do little in practice because they describe good behaviour instead of making the agent perform it.

The principle, from Addy Osmani: a skill is a workflow with checkpoints, not reference documentation. If a junior engineer reading it would not know what to do next, it is an essay, not a skill. Steps with exit criteria beat essays without them.

Several patterns from the previous post relate to this principle from different angles. Template Scaffold gives the skill a fixed shape to fill in. Execution Checklist gives it ordered steps with checkboxes. The whole Workflow control family, including self-correcting loops and plan-validate-execute, only makes sense once the skill is a workflow in the first place.

The same TDD content in two shapes:

Prose (rejected): “Test-driven development is the practice of writing tests before implementation. It produces better-designed code by forcing the author to consider the interface before the internals...”

Process (kept): “1. Write the failing test. 2. Run it. 3. Verify it fails for the expected reason. 4. Implement the minimum to pass. 5. Run it. 6. Refactor. 7. Commit.”

This principle guides the trade-off between actionability and coverage. Workflows are actionable but narrow: each step is a specific thing to do. References are broad but inert: the model has to decide what to apply and when. Most skills should be workflows, but reference skills (style guides, domain glossaries, persona prompts) are the legitimate exception. Forcing a workflow shape onto them produces brittle, awkward content. The right question is not “is this a workflow?” but “does the reader of this skill know what to do next?” If the answer is no, the principle is being violated regardless of shape.

Act 2: Running Reliably

Once the skill is selected and loaded, the question shifts to whether it actually drives the behaviour the author intended. These principles cover two halves of that problem: how rules should be phrased, so the model both generalises from what is written and complies under pressure to skip, and how much freedom the skill grants, so the model’s autonomy matches the task’s tolerance for variance.

4. Explain the why

A skill written as strings of ALWAYS, NEVER, and MUST in capital letters gives Claude rigid rules with no context. The model follows the letter and misses edge cases the author did not anticipate, or over-applies a rule where a judgement call was needed. Anthropic’s skill-creator flags all-caps imperatives as a yellow flag for exactly this reason.

The principle: state the rule, then state the reason. Reasoning becomes the rubric for cases the skill did not spell out.

Two patterns from the previous post connect to this principle, for different reasons. Explain-the-Why is the direct technique: pair every rule with its reason in the SKILL.md text. Control Tuning is about where to apply that pairing: rule-with-reason where the model needs to exercise judgement, narrow imperative where one wrong move is catastrophic and judgement is the wrong tool.

A Spring style-guide rule in two forms:

Rule alone: “Use constructor injection. Never field injection.”

Rule with reason: “Use constructor injection. Field injection breaks testability; we cannot mock the field without spinning up a Spring context.”

The first covers the canonical case and stumbles on variants. The second lets the model score options the skill never names: a builder that passes deps in build() passes (parameters, mockable without Spring); setter injection on a @Component fails (same testability problem); a service locator inside the method fails (hidden dependency). The rule covers one case. The reason covers all four.

This principle guides the trade-off between generalisation and length. Adding reasoning to every rule helps the model handle cases the skill never named, but explanations cost tokens. For genuinely fragile steps, such as DB migrations, cryptographic operations, or anything where one wrong move is catastrophic, a narrow imperative may still be the better tool. Reserve prose-with-reasoning for the steps where you actually want the model to think. For the rest, terseness is a feature, not a flaw.

This principle addresses a knowledge gap: the model that does not know enough to handle the variant. A separate gap shows up when the model knows the rule and the reason, then argues itself out of compliance anyway. That one needs a different tool.

5. Anticipate the excuse

Imagine a database-migration skill with a non-negotiable: “Always run the migration on a staging clone first.” The why is documented: staging catches what the SQL diff does not show, including default ordering, type coercion, and unintended index rebuilds. The model has the rule and the reason. Given a small migration and a user who wants to move fast, here is what it produces anyway:

“This migration adds a single nullable column. Staging clones take 4 minutes to spin up. The change is additive, the user is in a hurry, and the SQL is short and reviewable. Running on production directly is acceptable here.”

That paragraph is plausible. It cites real reasoning. It even acknowledges the rule before talking past it. That is rationalisation: a confident excuse for this particular case. Adding more rules does not fix it. Adding more reasons does not fix it. The model already accepts the why and dismisses it for this case.

The principle, from Addy Osmani: anticipate the excuse. Write the rebuttal next to the rule, in the skill itself. The model is excellent at rationalising; it is poor at arguing past pre-written counters that sit in its own context.

No pattern in the previous post directly serves this principle. Its closest cousin is Known Gotchas, but Gotchas catches external surprises (the world surprising the agent), while rebuttals catch internal ones (the agent surprising itself). The two complement each other but address different forces.

The rebuttal table for the migration rule, written into the SKILL.md:

ExcuseRebuttal“This migration is additive / nullable / small.”Small migrations are where staging catches low-level mistakes. Default ordering, type coercion, unintended index rebuilds. Four minutes is cheap insurance.”User is in a hurry.”User is in a hurry to ship working code, not to run a migration twice. Run staging.”I reviewed the SQL manually; it looks safe.”Manual review is not a substitute for running it. You are not the database engine.

When the model reaches for the rationalisation, it has to produce text that argues past three rebuttals it just read. That is a much higher bar than arguing past a one-line rule.

Where do the rebuttals come from? Three places:

1. Universal rationalisation archetypes. A small set recurs everywhere: “this case is too small”, “I’ll do it later”, “I checked manually”, “risk is minimal here”, “user is in a hurry”. One or two often apply to any non-trivial rule.

2. Observed runs. The first time the agent skips a step, it produces a paragraph explaining why. Copy it. The next version has a rebuttal for it.

3. Post-incident learnings. The last time someone skipped step X and got burned, that incident becomes a rebuttal.

This principle guides the trade-off between defensive coverage and credibility. The temptation, once you accept the principle, is to write a rebuttal table for every rule in the skill. Speculative rebuttals based on imagined failure modes read as paranoid filler and inflate the SKILL.md without earning their tokens. Rebuttals only land when they answer real excuses you have actually watched the model produce, or your team produce under pressure. Write them sparingly, for the two or three steps that are most tempting to skip, and grow the list from observed runs rather than from imagination.

6. Code over inference

Asking the model to generate a validation script, a PDF extractor, or a JSON normaliser from scratch on every invocation is slower, less reliable, and burns tokens on code the user never sees. Each run rediscovers the same logic with small variations.

The principle: where a step can be a deterministic program, it should be. Move work out of the inference loop into code that runs and returns only its output.

Two patterns from the previous post connect to this principle, for different reasons. Utility Bundle is how you ship pre-built scripts alongside the SKILL.md: purpose-built helpers the model invokes via Bash. Autonomy Calibration is how you constrain what the model can do at all, narrowing the tool surface so the script becomes the path of least resistance.

A schema-validation step in two forms:

Re-derive each time: model writes a 60-line validation snippet inline, runs it, parses the output, decides whether the schema passes. Source enters context. Logic varies between runs.

Pre-built script: python scripts/validate.py schema.json. The script’s output (”OK” or a structured error list) enters context. Source does not. Logic is identical every run, testable independently, and the model invokes it via Bash without having to think about how it works.

This principle guides the trade-off between determinism and portability. A script gives you reliable behaviour and lower context cost, but introduces a runtime dependency the inference path does not have. Python may be missing, a library version may differ, and paths may be Windows where the author wrote them for Unix. Validate preconditions in the SKILL.md, prefer forward slashes in paths, and have the script exit with a clear error rather than a stack trace when something is missing. For skills shipping to mixed environments, some logic is genuinely better off staying in inference, despite the cost.

7. Stay in scope

You ask the agent to fix one off-by-one in a function, and it returns a forty-line diff across three files: the fix, a var to const modernisation, a helper rename, and a TODO cleared up on the way past. The fix is mergeable. The PR is not. Unwinding the unrelated changes costs more than the original task.

The principle, from Addy Osmani: touch only what the skill is asked to touch. Don’t refactor adjacent systems. Don’t rewrite files you brushed against. Don’t expand the diff. Addy ranks this as the single biggest determinant of whether an agent’s PR is mergeable or has to be unwound.

No pattern in the previous post directly serves this principle. Exclusion Clause is adjacent but operates at the metadata layer, deciding whether the skill fires at all; this principle operates inside the skill, governing what the agent does once it has fired. Scope discipline is closer to a cultural rule than a markdown technique. It has to be enforced at every step the skill takes, not declared once.

The same parseRange() off-by-one fix in two diffs:

Out of scope (47 lines, 3 files): off-by-one, var to const modernisation, helperFunc to parseHelper rename, and // TODO cleanup.

In scope (3 lines, 1 file): off-by-one.

This principle guides the trade-off between helpfulness and reviewability. A wider diff feels more helpful because the agent saw a related issue and addressed it on the way past. A wider diff is also harder to trust because review cost grows with diff size, and reviewers stop trusting any of the changes once one of them looks unrelated. Build in a fallback for genuine ambiguity: “if the fix demonstrably requires another file, name that file before editing it and explain why”. The principle should block silent expansion, not legitimate cross-file work.

Act 3: Surviving Contact with Reality

The first two acts assume the skill exists at a single moment in time. The world is not constant. The codebase changes, the libraries update, the team turns over, and the model the skill was authored against gets replaced by a stronger one that interprets its instructions slightly differently. These principles cover what happens to a skill over time, and how authoring practice itself has to anticipate that drift from the start.

8. Skills decay

Libraries update. APIs change. Conventions evolve. A skill written six months ago against last quarter’s framework now points at a renamed function, a deprecated flag, or an API surface that has moved. Unlike a stale comment an engineer skims past, the agent invokes the stale skill confidently and produces wrong output that looks right.

The principle: skills are living artefacts, not frozen docs. A skill you have not re-run in months is a liability you have not measured.

No single pattern in the previous post serves this principle directly. Decay is a property of the system over time rather than something you fix inside a SKILL.md. The trade-off note attached to Known Gotchas, “gotchas are a moving target”, is a special case. A skill that pinned a deprecated framework flag will write code the framework refuses to compile, with the agent citing the stale skill as justification. Pattern catalogues rarely catch that failure mode because the failure happens months after the skill was correct.

This principle guides the trade-off between stability and staleness. A skill you never touch is stable, but stability is not the same as correctness. The world it describes drifts away from the skill faster than the skill drifts from itself. Treat skills the way you treat any piece of code that can drift from the system it touches: assign an owner, exercise them periodically against current tasks, and retire them honestly when they stop earning their keep. The principle does not prescribe a calendar. What matters is that someone is watching, not how often.

9. Run before you ship

A skill written from imagination at authoring time describes the world the author hoped for, not the world the agent encounters. It ships with the wrong rebuttals, the wrong gotchas, and helper scripts the author guessed at. The first real invocation reveals all three at once.

The principle, from Anthropic’s skill-creator: the skill is debugged from observed runs, not from your imagination at authoring time. Run it on two or three realistic test cases. Read the transcripts. If multiple runs wrote the same helper independently, promote that helper into scripts/. If the model produced the same rationalisation twice, write the rebuttal. If the same gotcha tripped two different runs, document it.

No pattern in the previous post serves this principle in isolation. Running a skill is not a thing you put inside the SKILL.md; it is a thing you do to the SKILL.md. But this principle is upstream of several others: the rebuttals in Anticipate the excuse, the gotcha entries any mature skill accumulates, and the helper scripts that get promoted into scripts/. None of these should be guessed at the desk. They are observed during test runs and added back into the skill afterwards.

This principle guides the trade-off between speed and correctness. Imagination-authoring is fast. You can ship the first version of a skill in an afternoon, and on simple skills the difference rarely matters. Real-run authoring is slower on the first version, and only pays back from the second version onward, when the rebuttals and gotchas you observed in the test runs save the user from hitting them in production. For genuinely tiny skills, such as a one-line alias or a five-line reference, the loop is overkill. For anything with a workflow, a non-negotiable rule, or a script, the loop is what separates a skill that compounds from one that ships broken and stays broken because no one watched it run.

The takeaway

The nine principles compose, but they also prioritise. Metadata is the gate, Process over prose, and Run before you ship are the foundations: a skill that does not fire never runs the workflow; a skill that is an essay never enforces the workflow; a skill that ships from imagination has the wrong workflow. The other six are corrective. They fix specific failure modes inside a skill that is otherwise structurally sound, but none of them can save a skill that gets the foundations wrong.

Skills are starting to become a well-understood building block for agents. My earlier posts looked at the mechanics: 12 Agentic Harness Patterns from Claude Code covered the runtime around the agent, and 14 Skill Authoring Patterns covered what to put inside a skill. This post is about the next layer: the principles that make a skill worth building, worth loading, and worth maintaining.

Software engineering has SOLID, KISS, YAGNI, and separation of concerns. Skill authoring needs the same kind of shared language. These nine principles are my proposal, drawn from working skills, popular skills, and the failure modes that show up once agents start using them for real.

> Subagents isolate context. Advisors unblock execution.

Both patterns add a second model inside a Claude agent, each with different strengths. A subagent takes a piece of the work off the main agent’s hands and runs it in its own context window. An advisor never touches the work. It reads the shared transcript and returns guidance on what to do next. One scales throughput and context. The other scales judgment.

Left: a main agent delegates a scoped task to a subagent, which runs independently and returns a result. Right: an executor stays in control and consults a stronger advisor when it hits a decision it can’t reasonably solve.

The subagent pattern

In one line. A main agent delegates a scoped task to a separate subagent, which runs independently in its own context window and returns a result.

Subagents are defined in Markdown files with YAML frontmatter, stored in .claude/agents/ (project) or ~/.claude/agents/ (user). Each one runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent’s description, it delegates, the subagent works independently, and the summary returns to the parent conversation.

The docs are direct on when to reach for one: “a side task would flood your main conversation with search results, logs, or file contents you won’t reference again.” Running tests, fetching documentation, processing log files. The verbose output stays in the subagent’s context; only the relevant summary comes back.

You can restrict tools with an allowlist or denylist, pick the model (sonnet, opus, haiku, or inherit), set permission modes, scope MCP servers, attach skills, enable persistent memory, run in an isolated git worktree. Claude Code ships with three built-in subagents: Explore (Haiku, read-only, for codebase search), Plan (read-only, for plan mode), and general-purpose (all tools).

One structural constraint: subagents cannot spawn other subagents as nested delegation is not supported. If you need it, the docs point at skills or chaining subagents from the main conversation.

There are two flavors of subagents: fresh-start vs forked.

• The default subagent starts with empty context.

• A forked subagent, behind the experimental CLAUDE_CODE_FORK_SUBAGENT=1 flag, inherits the parent’s full transcript, system prompt, tools, and model instead. Tool calls still stay out of the parent’s view and only the final result returns, so the context-window benefit holds. Because the system prompt and tool definitions match the parent, the first request reuses the parent’s prompt cache, which makes a fork cheaper than a fresh subagent for context-heavy side work. Reach for forked subagents when re-explaining the situation to a fresh subagent would cost more than it saves, or when you want to try several approaches in parallel from the same starting point.

The main trade-off. A default subagent starts fresh, trading conversation continuity for isolation and tool restrictions. A fork keeps the continuity but gives up the ability to swap models, restrict tools, or override the system prompt. In both cases, returns add back to the main context window, so running many subagents that each return detailed results can re-flood the context you were trying to keep clean.

The advisor pattern

In one line. A faster and cheaper executor (Sonnet or Haiku) consults a stronger advisor (Opus) model mid-generation, inside a single /v1/messages request.

The advisor tool ships as advisor_20260301 on the Claude Platform. You declare it alongside your other tools in the Messages API, and the executor decides when to invoke it. The advisor never calls tools or produces user-facing output. It reads the shared transcript, returns a plan, a correction, or a stop signal, and the executor resumes.

The handoff is a server-side sub-inference inside one /v1/messages request. No extra round-trips. Advisor responses are short, typically 400 to 700 text tokens, and max_uses caps them per request. Executor and advisor tokens bill at their own rates, so the overall run costs well below running the advisor model end-to-end.

In Anthropic’s evaluations, Sonnet with an Opus advisor gained 2.7 percentage points on SWE-bench Multilingual and reduced cost per task by 11.9%. The framing is deliberate: the advisor strategy “inverts a common sub-agent pattern, where a larger orchestrator model decomposes work and delegates to smaller worker models.” Here, the smaller model drives and escalates. Frontier reasoning applies only when the executor needs it.

The pattern has academic precedent. UC Berkeley researchers formalised it in late 2025 as “advisor models”: small policies trained to generate per-instance natural-language steering for larger black-box models. The paper found that advice generalises across model families (advisors trained on GPT transferred to Claude without retraining), which is why this is an architecture pattern, not a Claude feature. Anthropic’s contribution is making it a one-line tool declaration experience.

The main trade-off. Every escalation is a synchronous pause in the executor’s stream while the advisor runs. The advice is one-shot. No iteration, no debate. If the advisor is wrong on a specific point, the executor’s only recourse is another advisor call to reconcile, which burns more of the max_uses budget.

A decision framework

Questions separate them:

1. Does the work split into specialized, distinct tasks with well-defined inputs and outputs? Subagents. Distribution pays when each unit of work has a clear start, a clear end, and doesn’t need a back-and-forth conversation with the main agent in the middle.

2. Does the work mostly need better judgment, not more hands? Advisor. One model can usually handle a task if someone smarter checks in at the hard moments.

3. Is a side task about to flood the main context with output you won’t reuse? Subagent, read-only, summarize back. This is the pattern’s textbook case.

When none of these fire cleanly, the work is probably small enough to stay in the main conversation.

When to use both

The two patterns compose. A Sonnet executor can consult an Opus advisor on hard decisions and spawn Haiku subagents for bounded or parallelizable subtasks in the same run. Distribution handles breadth, escalation handles depth, and the cost shape composes too: Haiku does the cheap bulk, Opus applies frontier reasoning only where it changes the outcome, and Sonnet carries the rest.

A subagent is its own Claude run, so it can carry its own advisor too. Anthropic has only benchmarked the top-level composition publicly; treat nested advisor-inside-subagent as an op

A Sonnet executor consults an Opus advisor on hard decisions and spawns Haiku subagents for bounded subtasks

One more shape: agent teams

There is also a third shape worth naming: agent teams. Use them when subagents need to talk to each other directly, not just report back to a parent. They are more experimental, more complex, and harder to reason about than either pattern here. Reach for them only when the coordination overhead is justified. For a deeper comparison between subagents and agent teams, Han HELOIR YAN’s write-up is the clearest one I’ve found.

The takeaway

Subagents break a complex task into smaller blocks, each with its own context, tools, and specialization. The advisor makes each block more autonomous: when the cheaper model hits a hard call, the stronger one is a tool call away. Together, they give you specialization plus depth, a real step toward long-horizon agent runs that a single model in a single context cannot sustain.

Sources: The advisor strategy, Anthropic, April 9, 2026. Create custom subagents, Claude Code documentation.

This post goes one layer further out. Once an agent has a harness and a way to load Skills, the next question is more practical: how does it reach the production systems it needs to do real work?

Anthropic’s post, Building agents that reach production systems with MCP, is about exactly that. It compares direct API calls, CLIs, and MCP, then explains why production agents increasingly land on MCP: agents are moving to the cloud, the systems they need are remote, and auth, discovery, and rich interaction need a common layer. Anthropic says they are seeing this across more than 200 MCP servers, millions of daily Claude users, and fast-growing MCP SDK usage.

Share

The original post is written as practical guidance for MCP servers and clients. I am taking a slightly different angle: the pattern view. What are the reusable shapes behind the advice? What problems do they solve? When should you use them? And what are the trade-offs? I see 12 core patterns spread across five groups.

Tool surface

The shape of your tool set is the first architectural choice, and it is rarely “one tool per endpoint.” Three default moves cover the span from small services to hundreds-of-endpoints monsters.

1. Remote-First Server Pattern

The first foundational architectural choice for an MCP server is where it runs.

Local MCP servers over stdio work only when the agent can spawn a child process on the same machine: desktop Claude, local IDE agents, and some CLIs. That excludes agents running in browsers, mobile apps, or cloud execution environments, which is where most production agent traffic is heading.

Build the server as a remote HTTP endpoint from day one, not as a local-only module the team might “put on the network later”. Every other production concern in this post (auth, elicitation, discovery) assumes the server is reachable over the network. A local-only server has to rebuild each of those the moment it needs to scale beyond the local machine.

Remote-first also makes distribution portable. One server, one auth flow, many clients. No per-client bundle to ship, no machine-level install to maintain.

When to use. Any time the agent on the other side might not run on the same machine as the server. In practice, this is the default for most production integrations.

The main trade-off. Network transport raises the bar on reliability, latency budgeting, and auth. You have to engineer a public surface where a local process would have been enough, and you carry the operational weight of every internet-facing service.

2. Intent-Grouped Tools Pattern

This is probably the most common MCP server design mistake: exposing one tool per API endpoint. It feels like the fastest and most faithful implementation, but it creates the wrong interface for agents.

The agent does not think in API endpoints. It thinks in tasks. A 1:1 API wrapper leaves the agent assembling long chains of primitives. More tool definitions in context, more round-trips per task, more ways to get the chain wrong.

Group tools around user intent, not around the endpoints they happen to hit.

A single create_issue_from_thread tool is better than

get_thread + parse_messages + create_issue + link_attachment.

The agent goes from a four-call chain to a one-call intent, and each intent is something a human reviewer can reason about directly.

The implication is that your MCP server is not a proxy. It is a new surface. Expect to write wrapper tools that compose multiple endpoints, normalise half-formed IDs, retry on rate-limited calls, and return the output the agent will actually use, not the output the endpoint happened to produce. Anthropic has a companion post on writing effective tools that covers the craft details.

When to use. Default for any service with roughly fifty or fewer tools. When you find yourself inventing a fifth parameter to keep tool count down, you have probably outgrown this pattern.

The main trade-off. Every new intent is new code on your side, not a schema export. The server stops being a thin translation layer and becomes a product surface you have to design, test, and version.

3. Thin Surface Pattern

Some services have hundreds, sometimes thousands, of operations: Cloudflare, AWS, Kubernetes. Even grouped by intent, the full toolset blows past what fits in context, and any given agent task touches only a sliver of it.

Drop the intent-grouped model and expose a deliberately thin surface that accepts code. Two tools suffice: a search tool that lets the agent find the right API operation, and an execute tool that runs a short script written by the agent against the underlying API in a server-side sandbox. Only the result returns to the model.

Cloudflare’s MCP server is the reference implementation: two tools cover roughly 2,500 endpoints in about 1,000 tokens of definitions. The agent gets the full expressive power of the API without paying to have every operation described upfront. The sandbox contains the blast radius. Scripts cannot reach past what the server hands them. This pattern compounds with Programmatic Tool Calling on the client side: the client processes results in its sandbox, the server executes calls in its sandbox, and raw data never needs to reach the model.

When to use. When an intent-grouped surface would need more than roughly thirty to fifty tools to be useful, or when the underlying service is API-shaped (Cloudflare, AWS) rather than intent-shaped (Linear, Slack).

The main trade-off. You inherit sandbox operations. Script isolation, resource limits, timeout policies, and API-key handling inside the sandbox are all your problem. The agent has more power, which means you have more to defend.

Interaction Semantics

A tool that only returns text pushes the UI problem to the model. That is fine for small answers, but a poor fit for dashboards, tables, forms, previews, confirmations, and anything else the user needs to inspect or act on.

MCP adds interaction primitives that let the server take back some of that responsibility. Instead of asking the model to describe everything in prose, the server can return UI, ask for structured input, or hand the user to an external flow when needed.

4. Inline UI Pattern

A tool that returns a wall of JSON leaves the user reading compressed prose about their own data. For anything dashboard-shaped, such as charts, tables, forms, and interactive confirmations, the agent is the wrong rendering layer.

Ship UI with the tool response. MCP Apps let the server return an interactive interface that the client renders inline in chat: charts, forms, dashboards, and mini-views built from your product’s real components.

The bar is not “build a full web app.” The bar is simpler: if the tool’s result is something a user wants to look at rather than hear described, return a view, not a paragraph. Your product’s design system is more readable than any Markdown the model can synthesise.

When to use. Any tool whose output is fundamentally visual or tabular: search results, dashboards, file previews, status views.

The main trade-off. You now ship UI alongside your API, which means component versioning, accessibility, and design review. The MCP server is no longer backend-only.

5. Elicited Input Pattern

Agents hit real-world ambiguity constantly: missing parameters, destructive actions that need confirmation, multiple matches that need disambiguation. The usual fallback is to guess, or to ask the user to restart the conversation with more detail. Both cost trust.

Pause the tool call and ask the user directly. MCP elicitation, specifically Form Mode, lets the server return a form schema mid-call. The client renders it natively. The user fills it. Control returns to the server, and the tool completes.

This keeps the user in the flow instead of sending them back to model output with “please specify the region.” The agent’s job stays the same; the server gets to be honest about what it does not yet know.

When to use. When the missing information is structured, such as a region, an ID, or a confirmation, and the user is the only source of truth.

The main trade-off. Every elicitation is a UX moment your server now owns. Poor form design turns a helpful pause into an annoying interrogation, and the pattern is untested in headless or batch agents where no human is available to fill it.

6. External Handoff Pattern

Some steps should never transit the MCP client at all. Downstream OAuth against a third party, taking a payment, collecting a credential that the agent’s context window must not see. If the client sees it, your threat model just widened.

This is not for authorizing the MCP client to access the MCP server. That belongs to MCP authorization. URL Mode is for sensitive downstream flows the server needs to complete on the user’s behalf.

Hand the user to a browser URL with URL-Mode elicitation. The server returns a link; the client opens it in the user’s browser; the user completes the sensitive flow out-of-band; control returns to the server once it is done. The MCP client never sees the secret. This is the right shape for downstream OAuth, payments, or any credential that should never transit the MCP client.

The distinguishing question between this and Form-Mode elicitation is where the secret lives after the interaction. Data the server can legitimately hold goes to Form Mode. Data a third party should hold goes to URL Mode.

When to use. Third-party OAuth flows, payments, and anything governed by compliance rules that say the credential never hits your infrastructure.

The main trade-off. The user leaves the agent interface. Every handoff is a chance for them to drop off, and you have to design resume-after-redirect cleanly.

Auth and Credential Flow

Production agents run in the cloud, against systems protected by OAuth. Two patterns replace custom per-server authentication with standard plumbing.

7. Discoverable Auth Pattern

Every MCP server that invents its own auth adds friction at install time: configuration screens, token pastes, stale credentials. First-time failure rates climb, and re-auth prompts wear users down.

Publish and support standard OAuth metadata so the client can discover how authentication should work. For client registration, MCP supports Client ID Metadata Documents: the client uses an HTTPS URL as its client_id, and that URL points to a JSON document describing the client, its redirect URIs, and related metadata.

The practical effect: a user adds the server, the client discovers the auth flow, OAuth starts with the right client metadata, and the user does not have to paste tokens or manually configure client IDs.

When to use. Every production MCP server with user-scoped data. It is not optional if the goal is cross-client adoption.

The main trade-off. You are committing to standard OAuth behavior rather than a shortcut that works only for your own client. That means metadata endpoints, scope discipline, redirect URI validation, token validation, and the operational discipline to keep the flow working across clients.

8. Vault-Held Credentials Pattern

Even with discoverable auth, OAuth tokens still need a home. If every MCP server handles tokens directly, every integration ends up rebuilding the same secret store, refresh loop, rotation policy, and revocation path.

Offload token lifecycle to a platform vault. In Claude Managed Agents, OAuth credentials can be registered once, referenced by vault ID at session creation, and injected into the right MCP connections by the platform.

The practical effect: the MCP server does not need to receive tokens in tool calls or implement its own token storage. Refresh, revocation, and credential handling move one layer up.

When to use. Whenever you are shipping on a managed-agent platform that offers a vault. At a minimum, design your server so that credentials could be injected from one. Do not bake token handling into tool calls.

The main trade-off. You are trusting a platform vault with production credentials. Its uptime, security posture, and export policy become part of your production story. Self-hosted servers outside a managed platform have to rebuild the pattern themselves.

Context Economy

The agent’s context window is finite. Two client-side patterns keep it lean even when the tool population and tool results are large.

9. On-Demand Tool Loading Pattern

A client connected to several MCP servers can easily have hundreds of tool definitions in play. Loading all of them upfront blows the context budget before the first tool even fires.

Load tool definitions lazily through a tool-search meta-tool. The agent searches for tools by description; only matching definitions are loaded into context; everything else stays out. Tool search can cut tool-definition tokens significantly while maintaining high selection accuracy (docs).

This is the client-side complement to Intent-Grouped Tools and Thin Surface on the server side. Good server design keeps the total tool count manageable. Good client design keeps only the needed subset in context.

When to use. Any agent with more than a handful of tool sources, or any cross-cutting task that might touch tools from several MCP servers.

The main trade-off. The search step adds a round-trip and depends on description quality. Tools with vague descriptions will not surface when they should, and the cost of a miss is the agent picking a neighbouring tool that looks close.

10. Programmatic Tool Calling Pattern

Tool results, such as long lists, nested JSON, logs, traces, or large document payloads, often land in the model’s context window raw. The agent pays tokens to read them, even when the task is only to filter, count, aggregate, or join the data.

Process tool results in a code-execution sandbox before they reach the model. Programmatic tool calling lets the agent loop, filter, and aggregate across calls in code, with only the final useful output entering context. The same idea is described in more detail in the engineering post on code execution with MCP.

This cuts token usage on complex multi-step workflows and compounds with On-Demand Tool Loading. Fewer tool definitions go in, less raw data comes back, and the model reasons over the result rather than the full payload.

When to use. Multi-step workflows that chain several tool calls and transform results before the model needs to see them.

The main trade-off. You need a sandbox environment, sandbox debugging, and a mental model that includes code the agent writes against your results. Simple single-call tools do not benefit.

Packaging and Distribution

A server on its own is rarely the whole integration. Two patterns ship servers with the skills, hooks, and subagents that make them useful.

11. Plugin Bundle Pattern

A real integration rarely ships as a single MCP server. It is usually an MCP server plus a Skill that teaches the agent how to use it, a subagent for specialised work, and hooks for lifecycle events. Distributing them separately creates configuration drift and version skew.

In Claude Code, ship them as one plugin. Plugins bundle Skills, MCP servers, hooks, LSP servers, and specialised subagents into one distribution unit. One install, one version, one name.

The data plugin for Cowork is a good reference example: 10 Skills and 8 MCP servers covering Snowflake, Databricks, BigQuery, Hex, and more, installable as a unit.

When to use. Whenever your integration needs more than a bare MCP server to be genuinely useful, which in practice is most real-world integrations.

The main trade-off. Bundling couples release cadences. An update to any component ships the whole plugin, and teams with independent release cycles per component will feel the drag.

12. Server-Distributed Skills Pattern

An MCP server gives the agent access to tools, but access is not the same as expertise. The server provider usually knows the best workflows, safe sequences, common mistakes, and domain-specific conventions. Without a way to share that knowledge, each client has to rediscover it, and each agent has to improvise.

Ship Skills from the MCP server itself. The client gets both the raw tool access and the procedural knowledge for using those tools well. In practice, the server does not only expose capabilities; it also ships the playbook for using them. Canva, Notion, and Sentry already do this in Claude today.

The MCP community is working on a portable extension so that Skill delivery can work across compliant clients, versioned with the API the Skill depends on. Today the pattern is client-specific; the experimental extension makes it protocol-level.

When to use. When your MCP server wraps a surface rich enough that “how to use it well” is a real Skill, not a one-paragraph hint.

The main trade-off. Experimental today. Early adopters of portable server-distributed Skills commit to spec changes; sitting out means losing the adoption advantage that comes with shipping expertise alongside capabilities.

The takeaway

These patterns are not only about MCP as a protocol. They show the shape production agent integrations are starting to take:

• MCP servers are becoming agent-facing product surfaces. The useful ones expose intent-based tools, not endpoint mirrors. They hide API choreography, return agent-ready outputs, and sometimes return UI instead of prose.

• Interaction is moving beyond text. The server can ask for structured input, request confirmation, show inline UI, or hand the user to an external flow when secrets, payments, or third-party auth are involved.

• Auth is becoming standard plumbing. Discoverable OAuth flows and vault-held credentials move production agents away from custom token handling inside every tool call.

• Context is now an architectural constraint. Tool definitions need on-demand loading, and large tool results need filtering, joining, and aggregation before they hit the model. Otherwise, the context window becomes the bottleneck.

• Distribution is becoming richer than “ship an MCP server.” Real integrations include servers, Skills, hooks, subagents, and product-specific playbooks. The raw capability matters, but the instructions for using it well matter just as much.

Some of these extensions are still early, and the patterns will keep evolving. But they are already visible in real MCP usage, and several are gaining traction across production servers and clients. That is why they are worth naming.

If you want to read the earlier parts of this series, start with these two posts:

• 12 Agentic Harness Patterns from Claude Code

• Skill Authoring Patterns from Anthropic’s Best Practices

Skills come in two rough types. Task skills (often as disable-model-invocation: true) are step-by-step workflows (deploy, commit, security-review) that a user often invokes directly via /skill-name. Reference skills (user-invocable: false) are passive knowledge (style guides, domain vocabulary) that Claude applies inline whenever a relevant request matches. Most of the patterns below apply to both, but where emphasis shifts I will call it out.

The 14 patterns fall into five categories: discovery and selection, context economy, instruction calibration, workflow control, and executable code.

Discovery and selection

Two patterns decide whether a skill fires at all. At session start Claude sees only metadata: the name and description of every installed skill. A skill that cannot survive this metadata-only round never runs.

1. Activation Metadata pattern

With dozens of installed skills, Claude picks the wrong one, or none at all, when descriptions are vague like “helps with documents”. The description field is not just a summary; it is the only signal Claude has at selection time.

This pattern packs the description with both what the skill does and the specific triggers or contexts that should fire it, written in third person. Anthropic’s skill-creator goes further and recommends writing descriptions that are a little “pushy”, since Claude has a measured tendency to under-trigger skills: “Make sure to use this skill whenever the user mentions dashboards, data visualization, or internal metrics, even if they do not explicitly ask for a dashboard.”

Use this pattern on every skill. Nothing else matters if the skill fails at selection. The trade-off is budget: in the open Agent Skills spec, the description field caps at 1024 characters; in Claude Code, the combined description and optional when_to_use text is truncated at 1536 characters in the skill listing. So every sentence competes with positive triggers, exclusion clauses, and domain keywords for space.

2. Exclusion Clause pattern

A description that only says when to fire misses half the job. The skill triggers on tangentially related requests, hijacks work that belongs to another skill, or steps in when bare Claude would have done fine.

This pattern ends the description with explicit exclusions: “Do NOT use for blog articles, newsletters, emails, tweets, or long-form content.” Ruben Hassid calls this the single most important line in the description, above the positive trigger. Positive triggers pull a skill in; exclusions push it out. Both are needed and they compete for the same budget.

Use this for any skill that shares vocabulary with other skills or with bare Claude (most of them). The trade-off is maintenance: as your skill library grows, exclusion clauses must be kept in sync so two skills do not both claim or both reject the same territory.

Context economy

Two patterns exist because the context window is a shared budget. Every token in your skill crowds out tokens from other skills, the conversation history, and the user’s actual request.

3. Context Budget pattern

A skill that re-explains what a PDF is, what a library is, or how JSON works spends tokens teaching Claude things Claude already knows. Multiply that waste across a library of 20 skills and the context window is half-full before the user has said anything.

This pattern demands each paragraph justify its token cost. Default assumption: Claude is smart. If removing a sentence would not confuse a competent reader, remove it. Consistent terminology matters too: pick one term (always “field”, never “field / box / element”) to reduce cognitive load. And avoid time-sensitive phrasing (”before August 2025...”) that dates the skill; put legacy information in an “old patterns” appendix instead.

Use this pattern on every skill; it is a baseline discipline. The trade-off shows up with less-capable models: what reads as crisply concise to Sonnet may be too terse for Haiku. If you target multiple models, aim for the level of detail that works for the weakest one you plan to support.

4. Progressive Disclosure pattern

Stuffing every detail into SKILL.md burns context on material most invocations never need. An 800-line SKILL.md with forms, API references, and examples costs the same whether the user asked about forms or about something else entirely.

This pattern treats SKILL.md as a table of contents. The body stays under 500 lines and links to domain files (FORMS.md, REFERENCE.md, reference/finance.md). Claude reads the metadata on every session; loads SKILL.md only when the skill is triggered; and pulls in detail files only when the current task references them. Scripts in scripts/ can execute without loading, so their internal code usually stays out of the context window. Keep the reference graph shallow: every file one hop from SKILL.md. Nested chains like SKILL.md -> advanced.md -> details.md increase the odds Claude only partially reads the target and misses the rest. Long reference files, especially those over a few hundred lines, get a table of contents at the top so Claude can see the full scope even from a truncated read.

Use this for any skill pushing past ~300 lines in SKILL.md. The trade-off is fragmentation: splitting content across files makes it harder for authors to hold the whole skill in their head, and Claude has to make correct routing decisions about which file to load next. Mis-routing costs turns.

Instruction calibration

Five patterns dial instruction specificity up or down. Control Tuning is the meta-rule for how tightly to constrain Claude. Explain-the-Why shapes how that specificity is phrased. Template Scaffold, In-Skill Examples, and Known Gotchas are concrete techniques at the low-freedom end of the dial.

5. Control Tuning pattern

A skill that rigidly scripts every action strangles Claude on tasks where context should shape the approach. A skill that gives only loose guidance fails on fragile procedures where one wrong step breaks everything.

This pattern matches instruction freedom to task fragility. High freedom (text instructions, “use your judgement”) fits open-field tasks like code review where many valid approaches exist. Medium freedom (pseudocode, parameterised scripts) fits preferred-but-flexible flows like a deploy runbook. Low freedom (exact scripts, no flags, “do not modify this command”) fits fragile operations like database migrations where one wrong step is catastrophic.

Tone is part of the dial too: opening with a persona (”You are a senior code reviewer focused on correctness over style”) sets the judgement rubric for the whole skill and is common in reference skills that shape voice.

Use this pattern by asking, for each step in the skill, how much variance is acceptable. The trade-off is judgement: authors consistently err toward over-constraining, because rigid instructions feel safer. They are not; they just fail differently.

6. Explain-the-Why pattern

Skills written as strings of ALWAYS, NEVER, MUST in capital letters give Claude rigid rules with no context. The model follows the letter but misses edge cases the author did not anticipate, or over-applies a rule in situations where a judgement call was needed. Anthropic’s skill-creator explicitly flags all-caps MUST/ALWAYS/NEVER as a yellow flag to reframe.

This pattern states the rule, then explains why so Claude can generalise to cases the skill did not spell out. “Use constructor injection. Field injection breaks testability because we cannot mock the field without Spring context” beats “MUST use constructor injection. NEVER use field injection.” The reasoning becomes the rubric for unanticipated cases.

Use this pattern wherever you catch yourself reaching for capitalised imperatives. The trade-off is length: explanations cost tokens, and for genuinely fragile steps (see Control Tuning), a bare imperative is still correct. Reserve prose-with-reasoning for the cases where Claude will need to exercise judgement.

7. Template Scaffold pattern

When output structure matters, reports, commit messages, API payloads, release notes, Claude produces inconsistent shapes across invocations. The shape is implicit in examples elsewhere, but the skill does not make it explicit, and each run rediscovers a slightly different structure.

This pattern ships a template in the skill body with placeholders Claude fills in. Templates come in two strictness levels. Strict: “ALWAYS use this exact template structure” for data contracts or machine-parsed output. Flexible: “A sensible default; adapt sections as needed” for documents where the author trusts Claude to judge.

Use this whenever output structure has downstream readers or parsers. The trade-off is creative flatness: strict templates suppress the structural variation that can make output more useful in edge cases, so prefer flexible templates unless a machine is reading the output.

8. In-Skill Examples pattern

Description alone rarely conveys tone, formatting conventions, or the right level of detail. Claude hits the right shape but the wrong style: commit messages that use the correct conventional-commit prefix but miss the tone the team writes in.

This pattern embeds concrete input/output pairs in the skill body, the same few-shot trick used in prompting. Two or three examples, each labelled Input: and Output:, show the desired pattern directly. Claude matches on the examples instead of inferring from prose. Templates (previous pattern) show the skeleton; examples show populated instances. The two compose well, with the template defining shape and examples calibrating style.

Use this for skills where output quality depends on style as much as structure: commit messages, release notes, changelog entries, review summaries. The trade-off is drift toward the examples. If the three examples share a subtle bias, Claude reproduces that bias across all invocations, so the examples need to span the variation the skill should support.

9. Known Gotchas pattern

Skills that document only the happy path teach Claude what to do, not what to watch for. The first time the skill hits a real-world edge case, a form field that does not exist, a command that works on macOS but fails on Linux, a library that silently returns empty results, Claude has no prior and invents a fix.

This pattern adds a dedicated section to SKILL.md listing concrete failure modes previously seen: “Scanned PDFs return [] silently. Check page type first.” “Rotated pages need page.rotation=0 before column extraction.” One practitioner guide calls the gotchas section the most valuable content of a mature skill.

Use this pattern on mature skills, populated from observing real runs. The trade-off is that gotchas are a moving target: libraries update, APIs change, and a stale gotcha can send Claude chasing a problem that no longer exists.

Workflow control

Three patterns structure multi-step procedures. Execution Checklist is the linear case. Self-Correcting Loop introduces iteration. Plan-Validate-Execute adds a verifiable artifact before any side effects.

10. Execution Checklist pattern

In long multi-step procedures Claude skips validation steps, loses track of which step it is on, or declares done prematurely. “I think we are finished” at step four of a six-step process is a common failure mode.

This pattern provides a copyable checklist Claude pastes into its response and ticks off as it works. The checklist lives in the conversation, so skipping a step is now visible to both Claude and the user. The act of rendering unchecked items each turn raises the bar for declaring completion.

Use this for any workflow with more than three steps, especially where a skipped validation step is costly. The trade-off is verbosity: the checklist is rendered in full on every turn, so in long sessions it multiplies tokens, and for very short flows it is overkill.

11. Self-Correcting Loop pattern

When Claude generates code, edits XML, or drafts against a style guide, a single forward pass often ships mistakes the skill could have caught. The skill describes the correct output but has no mechanism to verify what Claude actually produced.

This pattern wires in an explicit loop: produce output, run a validator, if it fails, fix and revalidate. The validator can be a script (python validate.py fields.json) or a document (re-read STYLE_GUIDE.md and check each rule). The loop terminates only when validation passes.

Use this for quality-critical tasks where mistakes are expensive and programmatic verification is feasible. The trade-off is non-termination: a weak validator (or a Claude that keeps making the same mistake) can loop indefinitely, so the pattern needs a retry cap and a fallback to the user.

12. Plan-Validate-Execute pattern

For batch or destructive operations, updating 50 form fields, migrating rows, rewriting a document, a direct “just do it” pass lets errors cascade silently. By the time you notice Claude referenced non-existent fields, the changes are already applied.

This pattern inserts a verifiable intermediate artifact, typically a JSON plan, between understanding the task and acting on it. A script validates the plan before any side effects. That is the distinction from Self-Correcting Loop, which iterates after the work has already landed. Claude iterates on the plan freely; the real target is only touched once the plan passes validation.

Use this for batch, destructive, or high-stakes operations. The trade-off is ceremony: for a two-field edit the plan-validate-execute loop is more process than the task deserves, so reserve it for operations where “undo” is costly or impossible.

Executable code

Two patterns apply to skills that ship runnable helpers alongside SKILL.md. Together they shift work out of Claude’s inference loop and into deterministic scripts that run, succeed or fail, and return only their output.

13. Utility Bundle pattern

Asking Claude to generate a validation script, a PDF extractor, or a data-normaliser from scratch every invocation is slower, less reliable, and burns tokens on code the user never sees. Each run rediscovers the same logic with small variations.

This pattern ships purpose-built scripts in scripts/ alongside SKILL.md. Claude invokes them via bash, so only their output consumes context. Scripts should handle common failure modes cleanly instead of dumping ambiguity back on Claude. Sometimes that means creating a missing file with a sensible default. Sometimes it means failing fast with a clear error. Constants need justifying comments (”30s timeout covers slow connections”), not magic numbers. When in doubt about which helpers to bundle, run the skill on three test cases and read the transcripts: if subagents all wrote the same helper independently, promote it to scripts/.

Use this for any operation that is deterministic, frequently repeated, and worth testing independently. The trade-off is environment dependence: scripts need a runtime, and platform-specific helpers fail differently on user machines than on the author’s, so validate package availability in SKILL.md and prefer forward slashes in every path.

14. Autonomy Calibration pattern

A skill that runs with the full default tool set can do anything: write files, shell out, call MCP servers, even when its task only needs read access. A security-audit skill with Write and Bash permissions is still a standing risk, regardless of what SKILL.md says.

This pattern declares an allowed-tools list in the skill’s YAML frontmatter to pre-approve only the capabilities it actually needs. A security audit gets Read, Grep, Glob; a documentation generator gets Read, Write; a deploy skill gets Bash with a narrow command matcher. That reduces approval friction, but it does not by itself restrict which tools are available. In Claude Code, actual restrictions come from permission rules, not from allowed-tools alone.

Use this for any skill where a narrow pre-approved tool set is genuinely sufficient, especially security, audit, review, and analysis skills. The trade-off is confusion: an over-broad allowed-tools list quietly grants more hands-off autonomy than intended, and it is easy to mistake pre-approval for sandboxing. If you need real restrictions, pair this with permission rules.

The takeaway

These 14 patterns are essential. The description field decides whether the skill even runs; progressive disclosure decides how much context it costs; explain-the-why and known gotchas decide whether Claude handles the edge cases; plan-validate-execute and autonomy calibration decide how much can go wrong when something breaks. Each pattern addresses a failure mode that shows up across authors and domains.

As with the harness patterns in the previous post, these are not product-specific tricks. They are becoming the cornerstones of how agents get extended, and they will remain relevant as the models and tools change underneath them.

The source material for this post is Anthropic’s own Skill authoring best practices, their skill-creator SKILL.md (Anthropic eating their own dog food), the 33-page Complete Guide, plus community writing from Akshay Pachaar, Ruben Hassid, Tort Mario, Alex Xu, and Siva.

The patterns fall into four categories: memory and context, workflow and orchestration, tools and permissions, and automation.

Memory and Context

These five patterns form a progression: from giving the agent a static file of rules, to scoping those rules by directory, to organizing memory into tiers, to cleaning that memory in the background, to compressing the conversation itself when the context window fills up.

1. Persistent Instruction File Pattern

Without a persistent instruction file, every agent session starts blank. The user repeats the same conventions, commands, and boundaries each time. The agent makes the same mistakes in session five that it made in session one.

This pattern introduces a durable project-level configuration file loaded automatically at the start of every session. It defines build commands, test commands, architecture rules, naming conventions, and coding standards. It ships with the repo, not with the user’s clipboard.

Use this when your agent works on a codebase across multiple sessions. The main trade-off is the maintenance burden: the file must stay current as the project evolves, and a stale instruction file can be worse than none if it teaches the agent outdated rules.

2. Scoped Context Assembly Pattern

A single instruction file works for small projects. As a codebase grows, one file either becomes a giant blob that gets ignored, or stays too generic to be useful for any specific directory.

This pattern loads instructions dynamically from multiple files at different scopes: organization, user, project root, parent directories, and child directories. The agent sees different rules depending on where in the codebase it is working. Import syntax allows splitting large instruction sets across files without duplication.

Use this in monorepos, multi-language projects, or any codebase where different directories follow different conventions. The main trade-off is discoverability: when instructions live in many files, it becomes harder to understand what the agent actually sees. Conflicting rules across scopes can produce surprising behavior.

3. Tiered Memory Pattern

An agent that remembers everything the same way ends up remembering nothing well. Loading all memory into the context window every session wastes tokens, hits size limits, and buries useful information under noise.

This pattern organizes agent memory into distinct layers with different loading strategies. A compact index (capped at 200 lines in Claude Code) stays in context at all times. Topic-specific files load on demand when the current task matches them. Full session transcripts stay on disk and are only searched when needed. One of the most detailed breakdowns of the leaked code confirmed this three-layer design.

Use this when your agent runs across multiple sessions and needs to retain preferences, decisions, or workflow state. The main trade-off is the added complexity in deciding what goes where, when to promote or demote information between layers, and how to keep the index in sync with the underlying files.

4. Dream Consolidation Pattern

Even with tiered memory, agent memory degrades over time. Duplicate entries accumulate, outdated facts contradict new ones, and the index grows until it is no longer compact.

This pattern runs a background process that periodically reviews, deduplicates, prunes, and reorganizes agent memory during idle time. Think of it as garbage collection for agent state. The leaked code revealed an “autoDream” mode that merges duplicates, prunes contradictions, and keeps the index tight. A separate analysis found 8 phases of memory management and 5 types of context compaction.

Use this when your agent accumulates memory across many sessions and you cannot rely on users to curate it manually. The main trade-off is that the consolidation process itself uses tokens and can make mistakes. An overly aggressive prune might delete something the user still needs.

5. Progressive Context Compaction Pattern

Long agent sessions eventually hit the context window limit. The agent either loses its earliest context entirely or stops working. Neither is acceptable for tasks that require sustained reasoning across many turns.

This pattern applies multiple stages of compression tuned for different ages of the conversation. Recent turns stay at full detail. Older turns get lightly summarized. Very old turns get aggressively collapsed. The leaked code used four layers: HISTORY_SNIP, Microcompact, CONTEXT_COLLAPSE, and Autocompact, each progressively more aggressive.

Use this when sessions regularly exceed 20-30 turns. The main trade-off is lossy compression: every summarization step discards detail, and if the agent later needs something from a collapsed segment, it may hallucinate rather than admit it forgot.

Workflow and Orchestration

The common theme here is separation: separating reading from writing, research context from editing context, and sequential work from parallel work. These patterns matter because the default behavior of most agents is to mix everything together, and that mixing degrades quality as the task grows.

6. Explore-Plan-Act Loop Pattern

When an agent jumps straight to editing files, it makes changes based on incomplete understanding. The result is edits to the wrong files, missed dependencies, and approaches that ignore existing patterns.

This pattern separates the workflow into three phases with increasing write permissions. In the explore phase, the agent can only read, search, and map the codebase. In the plan phase, it discusses the approach with the user. Only in the act phase does it get full tool access. The leaked code showed distinct plan and act phases with system prompts that steer the agent away from editing before it understands the codebase.

Use this for any task that touches an unfamiliar codebase or involves non-trivial changes across multiple files. The main trade-off is speed: enforcing exploration and planning adds turns before the agent produces output, which feels slow for simple tasks.

7. Context-Isolated Subagents Pattern

In a long agentic session, the context window accumulates everything: research findings, planning discussions, code edits, test output, error logs. By the time the agent is deep into editing, its context is polluted with irrelevant material from earlier phases.

This pattern runs separate agents with their own context windows, system prompts, and restricted tool access. Research agents cannot edit code. Planning agents cannot execute commands. Each subagent sees only what it needs for its specific task.

Use this when sessions are long, multi-phase, or involve tasks with very different context needs. The main trade-off is coordination overhead: the main agent must decide what to pass to each subagent, and important nuance from an earlier phase can get lost in the handoff.

8. Fork-Join Parallelism Pattern

Large tasks that could be split into independent units still run sequentially if the agent can only work on one thing at a time. A migration across 20 files takes 20 sequential steps even though most of those files have no dependencies on each other.

This pattern spawns multiple subagents in parallel, each working in an isolated git worktree on an independent copy of the repo. The parent’s cached context is reused by each fork, making parallel branching essentially free in token cost. Results merge when all branches complete.

Use this when a task decomposes into independent units that do not depend on each other’s output. The main trade-off is merge complexity: when parallel branches touch overlapping files, the merge can produce conflicts harder to resolve than sequential work would have been.

Tools and Permissions

If the memory patterns are about what the agent knows, and the workflow patterns are about how it works, these patterns are about what it is allowed to do. The leaked code showed a level of tool design and permission granularity that goes well beyond what most agent frameworks implement today.

9. Progressive Tool Expansion Pattern

Giving an agent access to every available tool at once creates a selection problem. With 60 tools visible, the model spends more time deciding which to use and is more likely to pick the wrong one.

This pattern starts with a small default set (fewer than 20 tools in Claude Code) and activates additional tools on demand. Justin Schroeder noted the deliberately small default set. The agent starts with Read, Edit, Write, Bash, Grep, Glob, and a handful of others. MCP tools, remote tools, and custom skills activate only when needed.

Use this when your agent has access to many tools but most tasks only need a few. The main trade-off is that the expansion logic adds complexity: the harness must decide when to activate tools, and activating too late means the agent wastes turns without the right capability.

10. Command Risk Classification Pattern

Letting an agent run arbitrary shell commands without inspection is dangerous. But asking the user to approve every command creates fatigue, and users end up clicking “yes” to everything.

This pattern applies deterministic pre-parsing and per-tool permission gating before execution. Each tool has individual allow, ask, and deny rules with pattern matching. Shell commands pass through a classification layer that parses the verb, flags, and target to assess risk. The auto-mode classifier found in the code auto-approves low-risk actions while keeping a safety classifier for anything dangerous.

Use this when your agent can execute shell commands or interact with external systems. The main trade-off is rigidity: a deterministic classifier cannot anticipate every safe or dangerous command, so the rules need ongoing tuning.

11. Single-Purpose Tool Design Pattern

When an agent routes every file operation through a general shell (cat, sed, grep, find), the commands are harder to review, harder to permission, and harder for the model to use correctly. A sed command that edits a file looks identical in structure to one that corrupts it.

This pattern replaces the general shell with purpose-built tools for each common operation: FileReadTool, FileEditTool, GrepTool, GlobTool. Each tool has typed inputs, a constrained scope, and its own permission rules. Raschka calls this out explicitly: the harness provides “predefined tools with validated inputs and clear boundaries” rather than allowing improvised commands.

Use this when your agent performs common file and search operations frequently. The main trade-off is flexibility: purpose-built tools cannot cover every edge case, so you still need a general shell as a fallback.

Automation

The final pattern stands alone because it cuts across all other categories. It addresses a problem that applies equally to memory, workflow, and tools: the model cannot be trusted to remember procedural steps that must happen every time.

12. Deterministic Lifecycle Hooks Pattern

Some actions must happen every time without exception: run the formatter after every edit, validate commands before execution, reload configuration when the working directory changes. Relying on the model to remember these through prompt instructions is unreliable. The model will forget, skip, or reinterpret the instruction depending on context pressure.

This pattern runs shell commands or other actions automatically at specific points in the agent lifecycle, outside the prompt entirely. The leaked code includes 25+ hook points such as PreToolUse, PostToolUse, SessionStart, and CwdChanged. Anything that must happen every time belongs in a hook, not in an instruction.

Use this when you have invariant behaviors that should never be skipped. The main trade-off is debugging difficulty: when something goes wrong in a hook, it can be harder to diagnose than a prompt-level instruction because hooks run outside the conversation.

The Takeaway

I believe these patterns are not temporary tricks or product-specific features. They are cornerstones of agentic harness design. Memory tiering, context compaction, permission gating, lifecycle hooks: these are the kinds of architectural decisions that will remain relevant as the models and tools evolve underneath them.

The Claude Code leak gave us a rare opportunity to see how these patterns are implemented at the cutting edge, in a production agent used by hundreds of thousands of developers. That visibility will not last, but the patterns will.

The leak handed everyone a blueprint for how a production coding agent is assembled. That blueprint is more interesting than the drama around it, and this post is about the practical lessons I took from it, things Claude Code users and agent builders can apply.

What happened

If you want a video walkthrough, Matthew Berman’s coverage is the fastest entry point. Anthropic confirmed this was a release packaging mistake caused by human error, not a hack. No customer data, API credentials, or model weights were exposed.

One surprising detail, noted by Justin Schroeder, is that much of the system prompting lives in the client-side source rather than behind a server-side API. For a company like Anthropic, shipping prompts, which are important IP, inside a distributed npm package was unexpected. The codebase is TypeScript and React with Bun bindings, and the code is full of comments written for LLMs, not humans, so that agents working on the codebase can understand each section. A technical breakdown at ccunpacked.dev mapped the full structure.

What happened next

The code escaped almost immediately. Mirrors spread across GitHub, takedowns followed, and community rewrites appeared within hours.

The most visible follow-on project was Claw Code, presented as a clean-room Python rewrite of the harness. The repository now includes a Rust port and frames itself as “better harness tools” rather than an archive of leaked code. That “clean-room” phrasing matters, but it is not a magic legal shield. Whether a rewrite is actually lawful depends on how it was produced, not on what the README says.

There is also a security warning. BleepingComputer reported fake GitHub repositories using the leak as bait for infostealer malware. Attackers also registered malicious npm packages targeting anyone who tried to compile the leaked source. The sensible stance: study the incident, learn from it, do not run random “leaked Claude Code” repos.

The more interesting signal is how quickly open-source projects started absorbing the patterns. You can see it directly in OpenCode’s issue tracker, where users asked whether the harness design should be incorporated. The community treated the leak as a public architecture review, not gossip.

What Claude Code users can learn from this

Below are ten lessons. They are useful whether you use Claude Code or you are building your own agentic application.

1. Treat CLAUDE.md like a config file

The leak confirmed that CLAUDE.md is not an optional README. It is a control file loaded at the start of every session. A community analysis showed how the harness treats it as persistent project memory that shapes every interaction. Build commands, test commands, architecture boundaries, naming rules. It all belongs there.

Run /init once to generate a starting version, then edit it by hand. A good CLAUDE.md reads more like a .eslintrc than a README:

# CLAUDE.md

## Build & test
- Run tests: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Architecture rules
- All API handlers go in `src/api/`
- Never import from `src/internal/` outside that directory
- Use Zod for all request validation, no manual parsing

## Conventions
- Use `snake_case` for database columns, `camelCase` for TypeScript
- Every new endpoint needs a test in `tests/api/`

If you are building your own agent, the same principle applies. Give it a structured instruction file that loads every session, not a prompt you paste each time.

2. Keep memory selective, not exhaustive

One of the most detailed breakdowns of the memory system showed a three-layer design: MEMORY.md as a compact index always loaded into context, topic-specific memory files loaded on demand, and session transcripts only searched when needed. Auto memory is capped at the first 200 lines. The code also revealed an “autoDream” mode, a background process that consolidates memories during idle periods, merging duplicates, pruning contradictions, and keeping the index tight. A separate mem0 analysis found 8 phases of memory management and 5 types of context compaction.

The takeaway: memory should be curated. Store stable preferences, recurring workflow hints, and things that are not obvious from the code. Do not store stack traces, logs, or facts Claude can derive by reading the repo. If a memory note would not help in a future session, it should not exist.

3. Split instructions by scope

The leaked code showed context assembled from multiple files dynamically, not crammed into one prompt. Claude Code supports multiple instruction scopes: org-level, user-level, project root, local overrides, parent and child directories.

Keep one short root CLAUDE.md with broad project rules. Put language-specific or module-specific instructions closer to the code they govern.

4. Explore first, then plan, then code

The leak revealed how seriously Anthropic treats the separation between planning and execution. The harness has distinct plan and act phases, and the system prompts steer the agent away from editing before it understands the codebase.

In practice: first ask Claude to map the codebase. Then ask for a plan. Only then let it edit or run commands. This one habit eliminates most “random edits to the wrong files” problems. The impulse to jump straight to coding is strong, but exploration first is always faster.

5. Use subagents to isolate context

The leaked source showed a modular multi-agent architecture with separate system prompts and cache boundaries for each subagent type. The Explore agent is read-only. It can search and analyze but cannot mutate anything. Each subagent runs in its own context window with restricted tool access.

Context contamination is one of the main failure modes in long agentic sessions. Research, planning, and editing have different context needs. Mixing them degrades all three. Use separate agents or modes for each phase. If you are building your own agents, treat context isolation as a design decision, not a side effect.

6. Use worktrees for parallel work

More analysis of the subagent system showed that subagents leverage cached context for fork-join operations, making parallel execution essentially free in terms of repeated context loading. Claude Code spawns background agents in isolated git worktrees, one per unit of work.

When you have multiple independent tasks, use separate worktrees. Do not let several agents edit the same branch. If a task is large, split it into chunks with clear outputs. And stop starting fresh sessions for everything. Continue sessions when working on related code.

7. Configure permissions at the tool level

One of the most concrete findings was the tool count: Claude Code runs fewer than 20 default tools. AgentTool, BashTool, FileReadTool, FileEditTool, FileWriteTool, WebFetchTool, WebSearchTool, and a handful of others. A deeper inventory showed the system can expand to 60+, but the default set is deliberately small. Fewer tools, better results.

8. Reduce approval fatigue

The leaked source confirmed that Claude Code users approve 93% of permission prompts. The auto-mode classifier found in the code is Anthropic’s answer: a layered system that auto-approves low-risk actions while keeping a safety classifier for anything dangerous.

When you approve almost everything, the permission system becomes a speed bump, not a safety mechanism. You stop reading what you approve. Move repetitive safe actions into allow rules. Use Plan mode or Accept Edits mode where appropriate. Use Auto mode when the task is bounded and the direction is clear. The goal is not fewer safety checks. It is better-placed checks you actually pay attention to.

9. Use hooks for repeatable automation

The community found 25+ event-driven hook points in the leaked code, including PreToolUse, PostToolUse, SessionStart, CwdChanged, and more. Hooks are one of the most powerful features in Claude Code and probably the most underused.

A hook that runs tests after every file edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "FileEditTool",
        "command": "npm test --silent 2>&1 | tail -5"
      }
    ]
  }
}

The general principle: if you repeat the same instruction in every prompt, it should be a hook.

10. The harness matters more than the prompt

This is the lesson: Sebastian Raschka put it well: Claude Code’s secret sauce is probably not the model. If you are building your own agent, spend less time polishing one giant system prompt. Spend more time on tool boundaries, context loading, review loops, and memory discipline. The best coding agent is not the one with the cleverest instructions. It is the one with the best workflow design.

Bonus: the small details

The leak also surfaced things that are not actionable but say a lot about how the product is built. Wes Bos found 187 hardcoded spinner verbs, the loading messages you see while Claude thinks.

Someone found Boris’s WTF counter, an internal metric tracking unexpected states. Good agent products are not only inference. They are interface, orchestration, trust, and taste.

The bottom line

The takeaway is straightforward: use the product more deliberately: write a better CLAUDE.md, keep memory tight, split exploration from editing, move repeated behavior into hooks, configure permissions properly, and use worktrees when parallelism matters. Most of these features were already documented. It took seeing the internals to realize how seriously the team behind Claude Code takes them.

For anyone building agentic applications, the lesson is the same. The moat is not the model, it is the harness.