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.

• AI-assisted coding moved from autocomplete to agentic code generation.

• That shift made planning a first-class step. Serious teams now start with a spec or a plan before the agent touches the codebase.

• Build split into two paths: full-stack app builders for prompt-to-product flows, and local developer agents for working inside real repos.

• The biggest new category is local developer agents, especially CLI-native ones.

• Async cloud agents are still early, but they point to a delegated model where coding work runs in the background or overnight.

• AI-assisted review is becoming the only practical way to keep up with the volume of AI-generated code.

I wrote about this landscape last year in AI Coding Assistants Landscape (03/2025). The picture is simpler now. The big change is not only that the tools got better. The workflow changed. Not long ago, the center of the story was autocomplete and inline suggestions. In 2026, the center is agentic code generation guided by a plan, followed by stronger review before code ships.

This is an opinionated map of how the market is organizing itself. The easiest way to understand the ecosystem now is through a simple sequence: plan the work, build it with agents, then review what they produced.

1. Plan

The first major shift is that planning stopped being optional. Teams learned the same lesson from multiple directions: if the plan is weak, the build drifts, the review catches more noise than signal, and the whole agent loop becomes harder to trust.

This planning layer now shows up in two forms. There are dedicated spec-driven tools that formalize planning as a standalone practice, and there are build tools that pulled planning into their core workflow.

1A. Dedicated planning and spec-driven systems

Spec-driven development is the clearest expression of this change. These tools turn vague prompts into requirements, acceptance criteria, design notes, and implementation tasks before code generation begins. If vibe coding is “start building and see what happens,” spec-driven development is the counterweight: decide what you are building first, then let the agent execute.

• Kiro, a productized example of spec-driven development that turns prompts into structured requirements, design artifacts, and task plans.

• GitHub Spec Kit, GitHub’s open source toolkit for spec-first workflows and implementation planning.

• OpenSpec, a lighter open source framework for writing reusable specs for coding agents.

Beyond coding-specific spec tools, broader frameworks such as BMAD-METHOD show that structured AI-assisted planning is also expanding into higher-level delivery and agile workflows. The pattern is the same: teams that invest more in upstream intent get more predictable downstream results.

2B. Planning modes inside build agents

Planning is not confined to dedicated planning tools anymore. The stronger signal is that serious build tools now expose ask, plan, explore, or read-only modes before they touch the codebase. That is the clearest sign that planning became part of the agent loop itself, not something attached later.

• Claude Code, exposes Plan Mode for safe code analysis before editing.

• Cursor, uses Ask mode for exploration, questions, and planning before execution.

• Windsurf, treats planning as a built-in part of the Cascade workflow.

• Cline, makes the split explicit with a Plan and Act workflow.

• Codex, separates Ask mode from Code mode.

• Junie, uses Ask mode to collaborate on an action plan before making changes.

One related shift worth noting is that planning is no longer only text. Screenshots, Figma files, and mockups are increasingly becoming structured inputs into the coding workflow. I would not treat that as a separate category yet, but it matters as a bridge from planning into building. v0 screenshots and files is one obvious example, and the broader full-stack app builders category is also moving in this direction by making design artifacts directly usable for PMs, designers, and non-technical builders.

2. Build

This is where the market split most visibly. It is no longer useful to talk about “AI coding tools” as one bucket. Build is now best understood through three practical categories: full-stack app builders, local developer agents, and async cloud coding agents.

The most important change for developers is that local developer agents became the default serious workflow. But before getting there, it is worth separating them from the other branch: full-stack app builders.

2A. Full-stack app builders

This is the category where vibe coding became productized. These tools combine generation, iteration, preview, runtime, and deployment in one surface. They are not just code generators. They are prompt-to-product environments, closer to “build me the product” than “work with me inside my repo.”

This category matters because it serves a broader audience than professional developers: founders, PMs, designers, mixed-role teams, and non-technical builders. It is the closest thing we have to software creation for everyone, and it is expanding the definition of who can build software in a meaningful way.

• Lovable, full-stack app builder aimed at turning prompts into working products quickly.

• Bolt, browser-based full-stack builder with generation, preview, and deployment in one loop.

• v0, Vercel’s AI full-stack app builder with strong UI, design, and production handoff workflows.

• Replit Agent, browser-native environment that can generate, run, debug, and deploy applications.

• Bubble AI, AI-assisted visual app builder closer to no-code product creation than to local repo development.

2B. Local developer agents

This is the biggest change in the market. The story is no longer “which autocomplete tool is best?” It is “which agent loop do you want to build your workflow around?”

Claude Code helped make this category mainstream, especially on the terminal-native side. But the larger shift is broader than any single tool. The strongest open source and commercial energy now clusters around local agents that can plan, edit, run commands, inspect outputs, and iterate, all inside a real development environment, with the developer supervising the loop. This is where professional software engineering lives in 2026.

CLI-native developer agents

Terminal-based development is now a category in its own right. This is the branch where agentic coding feels most explicit and most professional. It keeps the repo, the terminal, the test loop, and the engineering workflow at the center, rather than wrapping them behind a simplified interface. Not long ago, terminal-native agents were a niche. Today, some of the fastest-growing open source projects in the AI-assisted coding space are terminal-first.

• Claude Code, the terminal-native coding agent that made the category mainstream.

• Codex, OpenAI’s local coding agent that also extends into cloud delegation.

• Gemini CLI, Google’s open source terminal agent with strong community adoption.

• OpenCode, a fast-growing open source coding agent with built-in plan and build agents.

• Goose, open source local agent for install, execute, edit, and test loops.

• Aider, Git-first terminal coding assistant that remains highly popular with working developers.

• Amp, Sourcegraph’s terminal agent with deep code intelligence and codebase-wide context.

• Plandex, a terminal agent designed for larger tasks, planning, and sandboxed diffs.

IDE-native developer agents

The IDE-native tools matter just as much, but their mental model changed too. Even in IDEs, the direction moved away from inline completion and toward planning, tool use, command execution, multi-file edits, and local review. The IDE is still the surface, but the agent loop is now the core interaction, not the autocomplete dropdown.

• Cursor, the bridge product from AI-native IDE to full local agent workflow.

• Windsurf, an IDE-native agent centered on planning, editing, execution, and verification.

• Roo Code, a popular open source editor agent with architect, ask, code, and debug modes.

• Cline, an open source IDE agent with a clear plan-then-act workflow.

• Augment, a context-heavy developer agent that also stretches into review.

• Junie, JetBrains-native coding agent for planning and implementation inside the existing IDE workflow.

2C. Async cloud coding agents

This is the delegated branch of the build step. If local agents are “pair with me,” cloud agents are “go do this and come back.” These tools run in remote sandboxes, often triggered from issues or pull request workflows, and return with patches, branches, or pull requests.

This category is smaller than local agents today, but the workflow matters. It is the beginning of a mode where you hand work to an agent from GitHub, or at the end of the day, and let it run while you are doing something else or simply sleeping. That is why I expect this category to grow even if it still feels early.

• Devin, the flagship async remote coding agent for delegated engineering work.

• Codex cloud, OpenAI’s sandboxed remote execution model for delegated coding tasks.

• GitHub Copilot coding agent, GitHub-native delegation from issues and pull request workflows.

• OpenHands, the open source alternative for issue-to-patch and cloud-agent workflows.

• SWE-agent, an influential open source issue-to-patch system that bridges research and practice.

If you want to go deeper on the delegated, async side of this market, this background agents landscape is worth reviewing. It offers a curated map of tools and infrastructure layers behind these workflows.

3. Review

Once agents started writing much more code, review became the new bottleneck. The point of this step is simple: keep the speed of AI code generation without letting quality collapse.

Code generation accelerated faster than our ability to inspect the output manually. That gap is what pulled review into its own category. The strongest part of this layer today is code review. Testing and verification are still lighter, but they are growing quickly as browser-based agents and cloud runtimes become more capable.

3A. Review agents

The most interesting shift in review is timing. AI review is no longer only something that happens after a pull request exists. The stronger tools now review code locally, before commit or before the PR is opened, and then review again once the PR is live.

That creates a two-stage loop: local review first, shared PR review second. It is one of the clearest signs that review is becoming part of the development loop itself and not only a separate final gate.

• Qodo, is built for enterprise-scale review, using dedicated agents, codebase context, PR history, and team rules to review changes before they reach the PR and again at review time.

• CodeRabbit, an AI reviewer that now spans pull requests, IDE reviews, and CLI reviews before commit.

• GitHub Copilot code review, GitHub-native review in pull requests, now complemented by local review in supported tools.

• Augment Code Review, a PR reviewer that routes findings back into the IDE or CLI for fixing.

• Cursor Bugbot, a mostly PR-native automated reviewer focused on catching real bugs with low noise.

• Greptile, a context-aware reviewer focused on repo-wide reasoning over pull requests.

• Graphite Agent, an AI reviewer integrated into Graphite’s stacked pull request workflow.

3B. Testing and verification agents

This is a lighter category than review today, but it is easy to see why it could become much bigger. As browser-based agents, cloud Chromium environments, and agentic end-to-end testing get stronger, more of the validation work that currently lives in manual QA can move into automated review loops.

For now, testing and verification still belong inside the same review step. If review agents inspect diffs, this emerging branch inspects behavior. That distinction will matter more as the code being generated grows in scope and complexity.

• TestSprite, an intent-to-tests workflow that generates, runs, and explains tests.

• Momentic, a browser testing agent focused on end-to-end validation.

• KaneAI, an AI testing agent for browser and workflow automation.

• mabl Agentic Testing, agentic test creation and maintenance for UI flows.

There are also benchmarks starting to emerge around this review layer. Code Review Bench from Martian is worth watching because it treats code review as a useful foundation for measuring code generation quality and validation, combining an offline benchmark with real developer behavior from open source pull requests.

Appendix: enterprise incumbents and platform suites

These tools still matter, especially in enterprise buying conversations, but they are not the sharpest lens for explaining how the market changed:

• Amazon Q Developer, an AWS-integrated developer assistant and terminal agent.

• Gemini Code Assist, Google’s enterprise coding assistant across IDEs and cloud workflows.

• GitLab Duo, GitLab’s integrated AI layer across the software delivery lifecycle.

• Tabnine, a long-running enterprise AI coding assistant focused on controlled deployments.

• watsonx Code Assistant, IBM’s enterprise tool for code generation and modernization.

• TONGYI Lingma, Alibaba’s coding assistant for enterprise and cloud workflows.

• Refact.ai, a self-hostable coding assistant with strong enterprise positioning.

Implications

If this framing is right, a few implications follow for how we work and what we invest in.

→ Planning will increasingly become the starting point, not an afterthought. The best coding tools already start with a plan before generation, and teams that skip this step will find themselves debugging drift rather than building features.

→ Full-stack app builders will keep pulling in design, product, and prototyping workflows. This is expanding who can create software, and that expansion is not slowing down. For product managers, designers, and founders, these tools are becoming the default way to go from idea to working prototype.

→ Local developer agents will keep taking share from autocomplete-first tools because they fit better with how professional developers already work, inside a real repo, with real tests, in a real terminal or IDE. Developers who learn to work effectively with agent loops will have a meaningful advantage over those still treating AI as a smarter autocomplete.

→Async cloud coding agents will grow as delegation becomes more natural. Send work from GitHub or at the end of the day, and let it run in the background. This mode is still early, but it is the beginning of a shift where engineering work does not have to be synchronous.

→ Review is becoming the next bottleneck and the real quality gate in software delivery. As code generation gets better, review will have to become far more sophisticated too. That is where the next major gains in software quality will come from.

→ Testing is still earlier than review, but it is the clearest next expansion area for agentic tooling. As browser-based testing agents improve and cloud runtimes become cheaper, this is where confidence will grow fastest.

My takeaway: AI-assisted coding is no longer one tool category. It is becoming a connected workflow from planning, to building, to gaining confidence in the result. Teams that understand these layers will be better positioned to adopt the right tools at each step. I share similar analysis on X: https://x.com/bibryam and in this newsletter.

The Generative Programmer

A developer-focused digest revealing how generative AI is transforming coding, architecture, and product development.

By Bilgin Ibryam

Here is a high-level summary of how Kubernetes patterns apply to LLM workloads, which Roland and I will cover in more detail in our upcoming KubeCon + CloudNativeCon Europe 2026 talk in Amsterdam.

Same Kubernetes, Different Workload

A typical cloud-native application on Kubernetes follows a well-known stack.

• An Ingress routes HTTP traffic to stateless App Pods managed by a Deployment.

• An init container runs database migrations before the app starts.

• PostgreSQL runs as a StatefulSet with persistent storage.

• A CronJob generates reports on a schedule.

• A layer of DaemonSets, such as Prometheus Node Exporter and Fluentd, provides

That is six Kubernetes patterns at work: Controller, Stateless Service, Init Container, Stateful Service, Batch Job, Daemon Service.

An LLM workload uses the same patterns, but is a fundamentally different kind of workload.

• A model is not an application binary. It is tens to hundreds of gigabytes of learned parameters, read-only data that must be loaded into GPU memory before a server can handle a single request. Meta’s Llama 70B weighs around 140 GB in full precision (FP16), or 35–40 GB with 4-bit quantization. Loading takes minutes, not seconds.

• It requires specific hardware: a node with the right GPU, enough VRAM (Video RAM, the memory on the GPU where weights and intermediate computations live), and sometimes a specific GPU interconnect topology.

• Initialization looks different too. In a traditional app, an init container fetches a config file or runs a migration, a few megabytes, done in seconds. In an LLM stack, the equivalent step stages tens to hundreds of gigabytes of model weights. Once the weights are in place, the model server (vLLM, TGI) goes through a multi-phase startup: loading weights into GPU VRAM, compiling CUDA graphs, and pre-allocating the KV cache (the memory region where the model stores computed attention states so it doesn’t recompute them for every new token). This takes minutes. Your startup probe needs failureThreshold: 60 with periodSeconds: 10, a 10-minute budget.

• The request profile differs too. In a traditional web service, requests have roughly uniform cost. Round-robin load balancing works. LLM inference breaks this assumption: a 10-token request completes in 200 ms while a 4,000-token request occupies a GPU for 30 seconds. Both arrive as identical POST /v1/chat/completions requests. Round-robin creates hot spots.

• Scaling signals break down. Out-of-the-box HPA on CPU is not a good fit for GPU inference workloads. You need scaling on LLM-specific metrics: token queue depth (vllm:num_requests_waiting), time-to-first-token, KV cache utilization.

• Scale-to-zero is impractical when model loading takes five minutes.

• The infrastructure layer changes. Where you had Node Exporter and Fluentd, you now run NFD (Node Feature Discovery) to label hardware, GFD (GPU Feature Discovery) to add GPU model and VRAM labels, the NVIDIA device plugin to expose nvidia.com/gpu as a schedulable resource, and the DCGM exporter (Data Center GPU Manager) to feed GPU metrics to Prometheus. That is your new stack of DaemonSets forming the GPU infrastructure layer.

Projects like KServe (incubating at CNCF) address these by applying the Controller pattern to model serving. You write an InferenceService CRD, declare the model, the runtime, the scaling policy, and KServe reconciles: Deployment, Service, storage initializer, startup probes, GPU scheduling.

Despite all this, the fundamentals are the same. Controller, Stateless Service, Init Container, Stateful Service, Batch Job, Daemon Service, all present. The parameters changed, but the patterns held.

What stays the same in GenAI on Kubernetes

Many Kubernetes patterns apply to LLM workloads without fundamental modification. The pattern works as-is, you only point it at a different workload.

These are the direct mappings. The Kubernetes primitive stays the same, but the workload behind it changes from web apps and databases to model servers, vector databases, and GPU infrastructure.

What changes in GenAI on Kubernetes

These patterns still apply to GenAI, but something fundamental changes about how they work. The pattern skeleton is the same; the parameters, scale, or semantics push them beyond their original design.

This is where LLM workloads start to stretch familiar Kubernetes patterns. The abstraction still holds, but the operational reality changes. Seconds become minutes. Megabytes become gigabytes. CPU-centric assumptions stop working.

Emerging Patterns for AI Workloads

Some patterns do not have clear ancestors in the Kubernetes pattern catalogue. They emerge from the specific characteristics of LLM workloads.

• Model Data Staging addresses the challenge of delivering hundreds of gigabytes of model weights to Pods without turning every scale-up into a multi-minute outage.

• Token-Aware Routing replaces round-robin with metric-driven endpoint selection based on queue depth and KV cache state. This is being implemented through the Gateway API Inference Extension and projects like llm-d.

• RAG Composition wires together four distinct workload types into a coherent application: the orchestrator, the LLM, the vector database, and the ingestion pipeline. Each maps to its natural Kubernetes primitive.

• Disaggregated Serving separates the compute-intensive prefill phase from the memory-intensive decode phase, runs them on different hardware, and lets them scale independently. Projects like llm-d are enabling this model.

• Agentic Workflows introduce LLM agents that plan, use tools, and iterate. They are also driving new protocols such as MCP (Model Context Protocol) for agent-to-tool integration and A2A (Agent-to-Agent Protocol) for inter-agent communication.

  

  Something related: Our friends at Deep Engineering are hosting a workshop, Building MCP Servers in Production, with Peder Holdgaard Pedersen. If you are exploring MCP beyond demos and into real production systems, this is worth a look, register here.

These patterns are covered in depth in Roland and Daniele’s book Generative AI on Kubernetes. Roland and I will be walking through three of them: Model Data Staging, Token-Aware Routing, and RAG Composition at KubeCon Amsterdam this week.

Subscribe now

If you’d like more posts like this on Kubernetes, cloud-native patterns, and how they intersect with AI workloads, subscribe to my newsletter.

👉 If you’re building with LLMs, agents, or generative AI, bookmark this. It’s a living list.

📚 Books

There are many books on AI, but these go deep and explain how prompting actually works in real systems.

• Prompt Engineering for LLMs – O’Reilly, John Berryman, Albert Ziegler

• Prompt Engineering for Generative AI – O’Reilly, James Phoenix, Mike Taylor

• Generative AI Design Patterns – O’Reilly, Valliappa Lakshmanan, Hannes Hapke

• Prompt Design Patterns – Yi Zhou

• Unlocking Secrets of Prompt Engineering – Packt, Gilbert Mizrahi

• LLM Design Patterns – Packt, Ken Huang

• Patterns of Application Development Using AI – Leanpub, Obie Fernandez

🎓 Courses

Most popular learning paths from beginner to advanced prompt engineering.

• Learn Prompting – LearnPrompting

• Advanced Prompt Engineering for LLMs – Elvis Saravia (DAIR.AI)

• Prompt Engineering for Everybody – Udemy

• Anthropic’s Prompt Engineering Interactive Tutorial -Anthropic

🎥 Videos

Overview, discussions, workshops, and real-world explanations of prompt engineering.

• Prompting 101 | Code w/ Claude – Anthropic

• State-Of-The-Art Prompting for AI Agents – Y Combinator

• Building with Anthropic Claude: Prompt Workshop – AI Engineer

• Prompt Engineering Tutorial – Master ChatGPT – freeCodeCamp

• Google’s 9 Hour AI Prompt Engineering Course in 20 Minutes – Tina Huang

• Prompt Engineering Workshop – Hamel Husain

• Prompt Engineering – For Optimal LLM Performance – Valentina Alto

• CMU Advanced NLP 2022 (9): Prompting - Graham Neubig

📄 Whitepapers

Research that introduced modern prompting techniques like CoT, ToT, self-consistency, tool use, and reflection.

• The Prompt Report: A Systematic Survey of Prompt Engineering Techniques – Schulhoff et al
  https://arxiv.org/abs/2406.06608

• A Prompt Pattern Catalog to Enhance Prompt Engineering with ChatGPT – Jules White et al
  https://arxiv.org/abs/2302.11382

• A Systematic Survey of Prompt Engineering in Large Language Models – Pranab Sahoo et al
  https://arxiv.org/abs/2402.07927

• Buffer of Thoughts: Thought-Augmented Reasoning with LLMs – Ling Yang et al
  https://arxiv.org/abs/2406.04271

• Lost in the Middle: How Language Models Use Long Contexts – Nelson F. Liu et al
  https://arxiv.org/abs/2307.03172

• Toolformer: Language Models Can Teach Themselves to Use Tools – Timo Schick et al
  https://arxiv.org/abs/2302.04761

• Prompting in the Wild – Mahan Tafreshipour et al
  https://arxiv.org/abs/2412.17298

• PromptSource – Stephen H. Bach et al
  https://arxiv.org/abs/2202.01279

• Repository-Level Prompt Generation for LLMs of Code – Disha Shrivastava et al
  https://arxiv.org/abs/2206.12839

• Conversing with Copilot – Paul Denny et al
  https://arxiv.org/abs/2210.15157

• Tree of Thoughts – Shunyu Yao et al
  https://arxiv.org/abs/2305.10601

• Chain-of-Thought Prompting – Jason Wei et al
  https://arxiv.org/abs/2201.11903

• Reflexion – Noah Shinn et al
  https://arxiv.org/abs/2303.11366

• Reprompting – Weijia Xu et al
  https://arxiv.org/abs/2305.09993

• LLMs Are Human-Level Prompt Engineers – Yongchao Zhou et al
  https://arxiv.org/abs/2211.01910

• Self-Consistency Improves Chain-of-Thought Reasoning – Xuezhi Wang et al
  https://arxiv.org/abs/2203.11171

• Language Models Are Zero-Shot Reasoners – Takeshi Kojima et al
  https://arxiv.org/abs/2205.11916

• Prompt Engineering (Whitepaper) – Lee Boonstra
  https://www.kaggle.com/whitepaper-prompt-engineering

• The DALL·E 2 Prompt Book (PDF) – dallery.gallery
  https://dallery.gallery/wp-content/uploads/2022/07/The-DALL%C2%B7E-2-prompt-book.pdf

🌐 Websites & Roadmaps

Living documentation, continuously updated guides, and structured learning paths.

• Prompt Engineering Guide – Sander Schulhoff
  https://learnprompting.org/docs/introduction

• Prompting Guide AI – DAIR.AI

  https://www.promptingguide.ai/

• Prompt Engineering Overview – Anthropic
  https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview

✍️ Articles

Practical write-ups from teams actively shipping LLM-powered systems.

• Prompt Engineering Best Practices - Sarah Chieng
  https://milksandmatcha.notion.site/Prompt-Engineering-Best-Practices-5aab1f04fce246ad9a39d3b69e80ed99

• Lilian Weng Prompt Engineering Guide – Lilian Weng
  https://lilianweng.github.io/posts/2023-03-15-prompt-engineering/

• Anthropic Claude Code Best Practices – Anthropic
  https://www.anthropic.com/engineering/claude-code-best-practices

• OpenAI Best Practices for Prompt Engineering – OpenAI
  https://help.openai.com/en/articles/6654000-best-practices-for-prompt-engineering-with-the-openai-api

• OpenAI Prompt Engineering Guide – OpenAI
  https://platform.openai.com/docs/guides/prompt-engineering

• OpenAI Cookbook Related Resources – OpenAI
  https://cookbook.openai.com/articles/related_resources

• Mistral Prompting Capabilities – Mistral AI
  https://docs.mistral.ai/capabilities/completion/prompting_capabilities

• ParaHelp Prompt Design Blog – ParaHelp
  https://parahelp.com/blog/prompt-design

• OpenAI Techniques to Improve Reliability – OpenAI
  https://cookbook.openai.com/articles/techniques_to_improve_reliability

• OpenAI Guides: Optimizing LLM Accuracy – OpenAI
  https://platform.openai.com/docs/guides/optimizing-llm-accuracy

• Wikipedia: Prompt Engineering – Wikipedia
  https://en.wikipedia.org/wiki/Prompt_engineering

• Automated Prompt Engineering: Hands-On Guide – Towards Data Science
  https://towardsdatascience.com/automated-prompt-engineering-the-definitive-hands-on-guide-1476c8cd3c50/

• Advanced Prompt Engineering (Chain-of-Thought) – Towards Data Science
  https://towardsdatascience.com/advanced-prompt-engineering-chain-of-thought-cot-8d8b090bf699/

• 5 Prompt Engineering Tips for Developers – Slobodan Mehmedovic
  https://slobodan.me/posts/5-prompt-engineering-tips-for-developers/

• Anatomy of a Prompt – Gyorgy Bakocs
  https://www.linkedin.com/pulse/anatomy-prompt-gyorgy-bakocs/

• Gemini 3 Prompt Practices – Phil Schmid
  https://www.philschmid.de/gemini-3-prompt-practices

• Prompt Engineering vs Blind Prompting – Mitchell Hashimoto
  https://mitchellh.com/writing/prompt-engineering-vs-blind-prompting

• Deterministic Quoting – Matty Yeung
  https://mattyyeung.github.io/deterministic-quoting

• Rewrite Your Prompts – Max Leiter
  https://maxleiter.com/blog/rewrite-your-prompts

• Prompt Engineering 101 – Amatria
  https://amatria.in/blog/PromptEngineering

• Prompt Engineering 201 – Amatria
  https://amatria.in/blog/prompt201

• AI Tools Up: Prompt Engineering Resources – aiToolsUp
  https://aitoolsup.com/best-resources-to-become-prompt-engineer/

• Prompt Examples – OpenAI
  https://platform.openai.com/docs/examples

• Prompt Engineering Roadmap – Roadmap.sh
  https://roadmap.sh/prompt-engineering

🧰 GitHub Repositories

Hands-on prompt examples, tooling, collections, and experiments.

• https://github.com/PromptLabs/Prompt-Hacking-Resources

• https://github.com/brexhq/prompt-engineering

• https://github.com/anthropics/prompt-eng-interactive-tutorial

• https://github.com/openai/openai-cookbook

• https://github.com/dair-ai/Prompt-Engineering-Guide

• https://github.com/promptslab/Awesome-Prompt-Engineering

• https://github.com/thunlp/PromptPapers

• https://github.com/thunlp/OpenPrompt

• https://github.com/guidance-ai/guidance

• https://github.com/microsoft/PromptWizard

• https://github.com/swyxio/ai-notes

⚙️ Tools & Services

Playgrounds, prompt testing tools, optimizers, and prompt management platforms.

• OpenAI Chat Playground https://platform.openai.com/chat/edit

• OpenAI Tokenizer https://platform.openai.com/tokenizer

• PromptPerfect https://promptperfect.xyz/

• FlowGPT Guide https://guide.flowgpt.com/

• PromptPort https://promptport.ai/

• Prompt Optimizer https://promptoptimizer.tools/

• TextSynth Completion Playground https://textsynth.com/completion.html

• PromptLayer https://www.promptlayer.com/platform/prompt-management

• Reverse Prompt Engineer https://www.agenticworkers.com/reverse-prompt-engineer

💬 Communities

Where prompt engineers share techniques, failures, and experiments.

• https://www.reddit.com/r/PromptEngineering/

• https://www.reddit.com/r/PromptDesign/

• https://www.reddit.com/r/GenAI4all/

• https://www.reddit.com/r/PromptSharing/

• https://www.reddit.com/r/ChatGPTPromptGenius/

• https://www.reddit.com/r/OpenAI/

Thanks for reading The Generative Programmer 🤖
Subscribe for more curated AI resources, agent patterns, and practical lessons from building with LLMs.

🔥 Top Picks from Issue #17

🔐 How We Hijacked a Claude Skill with an Invisible Sentence - Josh Devon
🧠 Why your AI agents need domain awareness - Russ Miles
🔧 How I Use Every Claude Code Feature - Shrivu Shankar
📊 GenAI in Production: MLOps or GenAIOps? - Dr. Kartakis
👌 The Context Engineering Guide - Weaviate
🔍 Building a Deep Research Agent from scratch - Aurimas Griciūnas
🛡️ Design Patterns for Securing LLM Agents against Prompt Injections - Luca Beurer
📈 I Went All-In on AI. The MIT Study Is Right. - Josh Anderson

🎯 Featured Article

This in-depth tutorial by Aurimas Griciūnas walks you through building a Deep Research Agent from scratch using the open-source DeepSeek R1 model.

It covers every step, from planning and web search to summarization and reflection, without relying on any orchestration frameworks. Highly recommended to check it out!

🤖 Building Agentic Systems

How We Hijacked a Claude Skill with an Invisible Sentence - Josh Devon reveals a critical security vulnerability in Claude Skills that allows attackers to override instructions with invisible text!

Agent IAM in Cloud Native World with SPIFFE and Istio - Mr Posta’s slides on cloud-native identity management with SPIFFE. 🔥

Domain Driven Agent Design - by Russ Miles - Miles explains why AI agents fail when deployed without domain context, creating impressive demos that collapse in production environments.

New prompt injection papers: Agents Rule of Two and The Attacker Moves Second - highlights new research on prompt injection vulnerabilities along with WiFi-enabled conference badge hacking and other tech links.

Design Patterns for Securing LLM Agents against Prompt Injections - Luca Beurer’s paper on security framework for LLM agent protection.

How Many Tools Functions Can An AI Agent Have - to do

💫 The Context Engineering Guide - Learn to optimize LLM performance through context engineering patterns that overcome hallucinations and build reliable AI applications with real-world context.

Why Model Context Protocol and Agentic Workflows Are Shaking Up How We Build Apps - Monica Hockelberg explains how MCP and agentic workflows transform rigid development into more fluid, adaptable systems for the AI era.

Bulletproof agents with the durable task extension for Microsoft Agent Framework - New extension enables resilient agent workflows that can survive interruptions and automatically resume processing.

Agent OS Workflow for Spec-Driven Development - Brian Casel proposes a six-phase AI agent workflow for spec-driven development.

The complete guide to LLM observability for 2026 - Ghost explains how to implement comprehensive LLM monitoring systems with frameworks for tracing, guardrails, cost management, and governance.

Context Engineering in Manus - Erik explores how Manus handles context management for AI agents, addressing challenges of context windows filling up during extended tool-calling sessions.

Building a Toolformer model with OpenAI and Remix - Josh Sanger shows how to build a weather assistant using Toolformer, enabling AI to use external tools via API calls.

Making Agent-to-Agent (A2A) Secure and Reliable with Dapr - I tried A2A with Dapr and saw how easily it adds mTLS, policy enforcement, tracing, and self-healing behavior to any agent workflow. Then showed step-by-step how to turn a deterministic workflow into an agentic one.

🚀 Choose a design pattern for your agentic AI system - Google’s guidance for selecting appropriate agent design patterns to build AI systems that can handle autonomous decision-making and complex workflows.

MCP Apps: Extending servers with interactive user interfaces - Ido Salomon introduces a new extension enabling MCP servers to deliver interactive UIs to hosts, addressing a top community request.

💻 Coding with AI

How I Use Every Claude Code Feature - Shrivu Shankar shares detailed insights on leveraging Claude Code for both hobbyist projects and professional development with high-volume token usage.

Claude Code Can Debug Low-level Cryptography - Filippo Valsorda describes how Claude Code successfully identified a complex bug in his post-quantum signature algorithm implementation when he was stuck.

The evolution of code review practices in the world of AI - Alex Pliutau examines how AI tools are transforming code reviews, improving efficiency while maintaining human oversight.

🔥 GitHub - github/awesome-copilot - github - Curated toolkit to supercharge Copilot.

🔥 GitHub - hesreallyhim/awesome-claude-code - Community-curated collection of commands, files, and workflows to enhance productivity with Anthropic’s CLI-based coding assistant.

How I use AI (Oct 2025) - Stolovitz reflects on his AI usage as a software engineer, highlighting Copilot’s impact on coding productivity since its early days.

Rulebook-AI wants to “elevate vibe coding to vibe engineering” - Tool transforms AI coding assistant configurations into structured guidance, eliminating fragmentation and inconsistency in development workflows.

📰 Long-Form Reads

A Survey of Context Engineering for Large Language Models - Lingrui Mei’s comprehensive overview of techniques to optimize LLM context usage, from retrieval methods to context compression.

The State of AI - McKinsey’s report on current AI adoption trends, business impact, and implementation challenges across industries.

🔬 I Went All-In on AI. The MIT Study Is Right. - Josh Anderson shares firsthand experience using Claude Code exclusively for three months to understand why 95% of corporate AI initiatives fail.

GenAI in Production: MLOps or GenAIOps? - Dr. Kartakis analyzes various operational frameworks for deploying GenAI solutions, clarifying differences between MLOps, LLMOps, and other emerging approaches.

What would you do if you had a chance to sneak peak in the year 2030 and you were a Hubber? - A developer’s 2025 forecast of AI’s rapid takeover of coding jobs, driven by economics and efficiency gains across most software domains.

The Death of Software Engineering as a Profession - Jason Scheirer reflects on incorrect predictions about programming careers and how specialized knowledge remains valuable despite technological advances.

🎨 Nano Banana can be prompt engineered for extremely nuanced AI image generation - Max Woolf explores how Nano Banana offers sophisticated image generation amid competition from FLUX.1-dev, Seedream, and ChatGPT’s viral features.

🎙️ YouTube & Podcasts

The Secrets of Claude Code From the Engineers Who Built It - Explains how Claude Code enables developers to ship features in unfamiliar codebases more efficiently, with each new feature making subsequent development easier.

Practical AI - Podcast making AI accessible through real-world applications.

🗞️ News and Updates

Akshay on X - Who is a Full-stack AI Engineer?

Paweł Huryn on X - 10 Principles of Building AI Agents:

Paweł Huryn on X - Context engineering is the new prompt engineering.

Aurimas on X - AI Engineering Learning Roadmap

TOON (Token-Oriented Object Notation) - Aurimas Griciūnas briefly explains how TOON increases model accuracy while reducing token count, critical for optimizing agentic systems.

🛠️ Tech & Tools

llmtext - Turn any llms.txt into a dedicated MCP server

GitHub - agentregistry-dev/agentregistry - Centralized registry for AI artifact governance.

AI Connectors Directory - Directory of Remote MCP servers for AI custom connectors.

DeepCode: Open Agentic Coding - Open-source tool offering terminal-based and web interfaces for AI-powered code generation from papers and text.

Prompt-Hacking-Resources - PromptLabs’ curated collection of resources for AI red teaming, jailbreaking, and prompt injection, designed for those interested in AI/ML security and safety.

OpenCode | The open source AI coding agent - A privacy-focused AI coding assistant offering free models with no account required and integrations across multiple platforms.

GitHub - toon-format/toon: 🎒 Token-Oriented Object Notation (TOON) - A compact JSON alternative optimized for LLMs that combines YAML’s indentation structure with CSV-like layouts for efficient token usage while maintaining readability.

GitHub - Portkey-AI/gateway - Open-source AI gateway providing fast routing to 1600+ language, vision, audio, and image models with integrated guardrails and enterprise-ready security.

GitHub - metatool-ai/metamcp - MCP proxy that aggregates multiple MCP servers into a unified endpoint with middleware support, enabling developers to build agents on this infrastructure.

You’re Burning 0.02 Per 1K JSON Tokens You Don’t Need To - Ankita Tripathi explains how to optimize JSON structures in API calls to reduce token usage and lower costs when working with AI models.

💰 Frugal AI - Intelligent Application Cost Engineering - AI-powered tool that optimizes application code across major cloud platforms by automatically identifying and fixing inefficiencies in code rather than just resizing infrastructure.

Technology Radar - Thoughtworks’ biannual guide tracking emerging tools, techniques, and frameworks is AI-dominated.

17 Top MCP Registries and Directories - Comprehensive guide to the best MCP registries for server discovery.

cto.new - Free AI code agent offering access to frontier models from Anthropic and OpenAI without requiring credit cards or API keys.

Claude Skills Marketplace - Directory for browsing, searching and installing Claude skills from GitHub, including official Anthropic skills, code skills, and AI automation workflows.

GitHub - anthropics/skills - Anthropics’ repository of reusable Claude skills that enable specialized tasks across creative, technical, and enterprise workflows with clear documentation.

GitHub - langwatch/better-agents - CLI tool and standards that enhance coding assistants to build production-ready agents with industry best practices.

GitHub - ruvnet/claude-flow - Enterprise-grade AI orchestration platform using swarm intelligence with persistent memory and MCP tools for enhanced development workflows.

Kagenti - Kubernetes-based control plane for AI agents that works with any framework, providing modular components to streamline production deployments.

GitHub - kubernetes-sigs/agent-sandbox - Kubernetes CRD for managing isolated, stateful singleton workloads with stable identity, designed for AI agent runtimes and similar use cases.

⚡Code Wiki - Google’s new Gemini-generated documentation.

📚 Learning Picks

🎓 5-Day AI Agents Intensive Course - A 5-day Google course on Kaggle to build, evaluate, and deploy real-world AI agents.

👍 Google, OpenAI, Anthropic Offer Free AI Guides - Here are ten free AI guides worth bookmarking.

🎭 AI Humor

Share The Generative Programmer

👋 See You Next Time

That wraps this issue. If it helped you, pass it along or subscribe. 🙏

In this post, I’ll share a practical guide on how to make your open source project easier for LLMs to understand, and for humans to use through AI tools.

1. Make Your Project Discoverable by AI

When developers face a problem, or research a topic, they don’t go any longer to Stack Overflow or Google first — they ask an LLM through ChatGPT, Claude, or a similar service. Questions such as “How to tune Kafka for low-latency?” or “What’s the best open-source MCP implementation for Kubernetes?” are now answered directly by LLMs.

When a developer is in the zone within their IDE and faces a common issue, like a Python dependency error: “cannot import module x”, they ask their AI assistant inside the IDE how to fix it.

Modern AI systems combine their training data with live web search, scanning documentation, repos, and blogs to generate the best up-to-date responses. But most project sites are designed for people, not machines, they are full of menus, ads, and nested pages. Critical details like installation flags, version notes, or API parameters are often buried deep and hard for AI crawlers to find. As a result, your project may be misunderstood or overlooked even if it’s well-known.

Using llms.txt to Help AI Find the Right Docs

llms.txt is a simple Markdown file placed at the root of your project’s site that gives AI models a clean, structured map of your most relevant documentation. Think of it as a robots.txt for language models, but instead of blocking crawlers, it guides them to the right content. It lists a short summary, key links (docs, APIs, SDKs, examples), and optional secondary sections.

Add /llms.txt to the root of the project website, keep it updated alongside your docs, and every AI-powered search or assistant will instantly understand what your project is and where to look next. The file makes your project easier to find, quote, and recommend in AI-driven tools like ChatGPT, Copilot, and Sourcegraph. There are hundreds of websites already using with it: Supabase, DuckDB, Turso, Hugging Face, Langfuse, and many more in various directories.

llms.txt is an easy addition that can give visibility to your project in a world where LLMs are becoming the primary way of discovering and consuming information. As shown by the tracking site llmstxt.ryanhoward.dev, it’s not yet widely adopted, but the fact that Anthropic themselves use llms.txt and recommend it as part of agentic documentation is a strong signal that it’s the right direction to follow.

There are plenty of tools and plugins that can help you create and validate these files easily, such as llms_txt2ctx, vitepress-plugin-llms, and docusaurus-plugin-llms. To learn, check out llmstxt.org.

2. Onboard AI Agents to Your Project

Open source projects today communicate their community policies and expectations through a variety of simple text files, for example, README.md, INSTALL.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, DEVELOPMENT.md, and ISSUE_TEMPLATE.md. These files explain how to set up the project, contribute, follow coding guidelines, or report issues. This structure has worked well for years when humans were the primary readers.

In the meantime, the number of developers using AI‑enabled IDEs and CLI tools is growing rapidly. Millions of developers rely on Cursor (now surpassing a million users), Claude Code CLI, and OpenAI Codex daily. Yet these users are underserved, their IDEs can’t easily interpret the project’s policies, build steps, contribution rules and community best practices. As a result, contributing through AI‑assisted tools often leads to manual onboarding, lower‑quality pull requests, and contributor-maintainer tension.

Teaching Coding Assistants Your Project’s Way of Working

This is where agent context files come in. The idea started with different IDEs introducing more advanced ways of sharing project context — for example, .cursor/rules files in Cursor, which began as simple rules and later evolved into structured folder hierarchies, or CLAUDE.md, used by Claude CLI to encode build and contribution instructions. These formats help AI-enabled tools understand how to build, test, and navigate a codebase.

As the space grew fragmented with various formats, AGENTS.md led by OpenAI began to emerge as the most widely adopted standard for defining project context. Today, it’s becoming the common denominator across AI-assisted environments, with over 30,000 pull requests on GitHub contributing AGENTS.md files in open-source projects.

AGENTS.md files act as a README for AI agents. They summarize how to build, test, and contribute to your project, covering environment setup, dependency installation, code style, test execution, and commit message rules — but in a way that AI tools can parse and follow. Supported by major IDEs and CLI tools such as Cursor, VS Code, GitHub Copilot, Aider, RooCode, Gemini CLI, Jules, Factory, and Devin, these files help AI agents understand your project’s structure and workflow.

With these files, AI assistants can follow project conventions, and produce contributions that align with human developers’ expectations, reducing friction in collaborative development.

These files are often paired with AI-assisted development guides that show contributors how to configure their IDEs and CLIs for the best experience — such as Angular’s AI development guide and Convex’s guide for Cursor.

In short, AGENTS.md and accompanying IDE setup guides provide the missing layer of context between your code and the growing ecosystem of AI-powered development tools. It’s a lightweight addition that helps AI understand your project’s workflow — and makes your repository ready for the era of AI-assisted coding.

In short, AGENTS.md and accompanying IDE setup guides provide the missing layer of context between your code and the growing ecosystem of AI-powered development tools. It’s not just about onboarding developers anymore — it’s also about onboarding AI agents. This file acts as an onboarding guide for agents, helping them understand your project’s structure, style, and expectations, so they can contribute effectively and make every developer more productive from day one.

3. Define Your AI Contribution Policy

AI coding tools are now part of everyday development, but most open‑source projects still lack clear policies on how and when they can be used. Without guidance, contributors interpret “acceptable AI use” differently, leading to inconsistent pull requests, hidden AI‑generated code, and extra work for maintainers who must assess both quality and authenticity.

Setting Ground Rules for AI‑Assisted Contributions

Projects like Ghostty, Gramps, Servo, and Scientific Python illustrate different approaches, from allowing AI with disclosure, to banning it outright. These examples show that there’s no universal answer, but various efforts to help avoid tension and maintain trust. A great reference comes from the Open Infrastructure Foundation’s policy on AI‑generated content:

“As a contributor, you are responsible for the code you submit, whether you use AI tools or write it yourself. Some AI tools offer settings, features, or modes that can help, but these are no substitute for your own review of code quality, correctness, style, security, and licensing.”

It’s worth emphasizing that every pull request is still reviewed and maintained by humans, not machines. Contributors must ensure that AI‑assisted code meets the same quality, readability, and consistency expectations as any manually written code.

There’s also a broader movement around structured, transparent AI collaboration, such as the Vibe Coding Manifesto. It advocates for integrating AI into open source responsibly, not rejecting it, but managing it through clear PR rules, contributor transparency, and supporting documents like PROMPTING.md. The manifesto also outlines practical steps such as creating small, focused PRs, running self‑reviews and tests before submission, adding clear AI attributions, and limiting concurrent PRs to avoid “PR spam.” These concrete recommendations help maintain quality while keeping the review workload manageable.

Explicit AI contribution guidelines help maintain a healthy balance between speed and quality. Whether your project allows, restricts, or just tracks AI use, defining the rules early prevents confusion and keeps your contributor community aligned.

4. Scale Code Reviews with AI

Once your project becomes more discoverable and contributor‑friendly with clear guidelines, agents onboarded, you’ll start seeing more AI-assisted activity and more pull requests. Reviewing those PRs becomes one of the primary jobs of maintainers. Some PRs might come from bots or low‑quality AI output and can be easily rejected, but many will vary significantly in quality and completeness. The only scalable way to keep up with this volume of AI‑assisted contributions and maintain quality is to use AI for reviewing, too!

Bringing AI into the Review Process

AI can perform first‑pass reviews, freeing human maintainers to focus on architecture, design, and logic rather than repetitive or stylistic feedback. Such tools act as automated reviewers that integrate directly with GitHub. They can:

• Issue Triage & Labeling – Categorize issues automatically

• Documentation Sync – Ensure code and docs remain aligned

• External Contributor Reviews – Apply stricter checks for new contributors

• Custom Review Checklists – Enforce team standards and consistency

• Path‑Specific Reviews – Trigger deeper analysis on critical file changes

• Scheduled Maintenance – Automate repository health checks

• Security‑Focused Reviews – Detect vulnerabilities with OWASP‑aligned checks

Among the most popular AI tools for code reviews are:

• CodeRabbit – the most widely adopted open‑source‑friendly AI code review tool.

  

  CodeRabbit integrates directly with GitHub and offers free plans for open‑source projects. It supports both IDE‑based inline reviews and PR‑based multi‑file reviews, giving teams flexibility for internal and external contributions. Its context‑aware reviews understand file dependencies and coding patterns, and it can review uncommitted changes directly in the IDE before a PR is even created, reducing friction and catching issues early.

• Claude Code Action – integrates Anthropic’s Claude for PR review and comment generation, providing natural‑language insights and feedback.

• OpenAI Codex Cloud Review – runs as a GitHub Action to automate AI‑based feedback on pull requests and highlight potential issues.

As AI assistants generate more code, the number of incoming PRs will rise. Having AI review these PRs first ensures consistent quality without overloading maintainers. The workflow becomes: AI writes → AI reviews → humans approve. That loop keeps velocity high while maintaining the standards as expected.

5. Make Your APIs Agent-Ready

If your project already exposes an API, CLI, or has a client SDK, it’s time to think about how AI agents can interact with it directly. Developers are no longer the only consumers of APIs, AI assistants are becoming first‑class users, too. Yet most APIs today are not agent‑ready: assistants can read about them but not interact in a structured, safe way.

Opening Your APIs to AI Agents with MCP

The Model Context Protocol (MCP) is an emerging open standard that lets AI agents connect to tools, APIs, and data sources. Exposing your API or CLI via MCP makes your project agent‑ready, enabling AI systems to query, test, and trigger actions contextually instead of copy‑pasting examples. It improves discoverability, automation, and supports AI‑native workflows where agents use your project the same way as developers do. It also connects your project to the growing MCP ecosystem of compatible tools, browsers, and registries.

Projects like Apache Kafka, Turso, DuckDB, and Redis are early examples of being agent‑ready. Some already expose MCP endpoints that let assistants query data or perform operations directly. Cloud services such as Confluent Cloud, Supabase have gone further, hosting full MCP servers that make their APIs seamlessly accessible to AI tools.

To get started, tools like FastMCP can automatically generate MCP servers from any OpenAPI specification, instantly turning your existing API into one that AI models can use through MCP. Over time, you can evolve toward a purpose‑built MCP server. Platforms such as Speakeasy also provide MCP server generators with free plans for open‑source projects, making it easy to experiment.

In short, if your project has an API, offering MCP‑based access is becoming table stakes. Adding MCP support transforms your project from something AI agents can only read about into something they can use directly, unlocking the next phase of open‑source and AI integration.

6. Turn Docs into Conversational Interfaces

Developers don’t have the time to dig through endless documentation pages or wait for answers in Discord. They expect instant help, the same experience they are used to from AI tools. Yet, most open‑source documentation is static and unresponsive to real‑time questions, and even outdated as the code changes faster.

How Conversational Docs Improve Developer Onboarding

Adding an AI‑powered chat interface to your docs lets users ask questions directly, based on your project’s documentation, issues, and source code. Tools like Kapa.ai, Inkeep, CrawlChat can index your site, GitHub repo, or forums and deliver answers instantly inside your website, Slack, or Discord. Such services improve onboarding, reduce repeated support requests, and help users learn faster through natural conversation.

If these tools are not affordable for your project, you can also build a simple in‑house alternative like CrewAI’s “Chat with the Docs”, or index your documentation with Context7 and expose it as an MCP server, allowing users to query your docs directly from their IDE.

This is an evolving space, but it’s likely that in the future, all open‑source projects will have built‑in AI chat interfaces, offered for free, either sponsored by their open‑source foundations or integrated directly into platforms like GitHub. For now, you have to find ways to cover this cost.

7. Automate Community Tasks with AI

As open-source communities grow and AI-assisted development accelerates, maintainers face a constant flow of new issues, PRs, and support questions. Repetitive tasks, triaging, labeling, answering common questions, or closing stale tickets, can consume hours that could be spent improving the project itself.

Let AI Handle the Repetitive Work

AI maintainers like Dosu automate many of these repetitive tasks. They can triage issues, answer contributor questions, close inactive discussions, remind authors about missing documentation, and enforce contribution guidelines — all while keeping conversations active and polite. Dosu already works with major projects like LangChain, Prisma, Strapi, Apache Airflow, and several CNCF initiatives, and is free for open-source use (with CNCF and ASF partnerships in place).

In short, AI maintainers act as 24x7 project maintainers, handling the administrative overhead so human maintainers can focus on technical leadership, community growth, and long-term vision.

AI-Ready Project Checklist for Maintainers

Every open-source project has its own culture, workflows, and pace of change. Yet as AI rapidly reshapes how developers build and collaborate, standing still is the worst option. The right move is to adapt early and use AI as an advantage, not a disruption. This checklist helps maintainers identify where to start.

For Users

1. Make your project discoverable: Create llms.txt listing key docs, APIs, and examples so LLMs can index your project. This is a top-of-funnel lever, but with still-unproven impact; treat it as a follow-on step after the other core items.

2. Turn docs into conversations: Deploy a tool like Kapa.ai trained on your documentation and community resources to answer user questions instantly. This is no longer a luxury: users now expect conversational help, and it significantly improves new user experience.

3. Open your project APIs to agent use: If you have a CLI, SDK, or API, create an MCP server so AI agents can call and use it directly. Comprehensive MCP support makes your project easier to integrate with AI tools and stand out among alternatives.

For Contributors

4. Onboard AI-assisted tools to your project: Add AGENTS.md with build, test, and style instructions so AI tools can quickly figure out how to work with your code. Thousands of projects already use it, making it one of the easiest and highest-impact improvements.

5. Define a clear AI contribution policy: Update CONTRIBUTING.md and PR templates with a reminder that contributors are responsible for submission quality and correctness, regardless of which tools they use. This reinforces human accountability while promoting transparency as AI-assisted contributions grow.

For Maintainers

6. Scale code reviews with AI: Connect CodeRabbit or a similar asynchronous AI bot to automatically review pull requests and provide feedback for free on open-source projects. A small setup effort here pays back quickly by reducing reviewer fatigue and catching early issues.

7. Automate repetitive community tasks: Install Dosu or a similar GitHub bot to triage issues, answer questions, and keep discussions organized. Automation beyond code reviews helps sustain healthy collaboration and saves maintainers valuable time.

Together, these practices ensure your project is set up to benefit from AI at every level: users can discover it, get answers instantly, and use it with their AI tools; contributors have clear onboarding and AI usage guidelines; and maintainers gain automation for reviews and community operations. The space is evolving fast, keep an eye on relevant tools and practices, subscribe, and share how you’re using AI in open source.

🔥 Top Picks from This Issue

🧠 Writing Effective Tools for AI Agents – Anthropic 🔥
🧩 Effective Context Engineering for AI Agents – Anthropic again
🏗️ Building Production-Ready Agentic Systems – Shopify’s lessons
🧬 Deep Agents: From Shallow to Deep... – Elvis Saravia
💻 How to Vibe Code as a Senior Engineer – Alex Maccaw
🚀 The AI-Native Software Engineer – Addy Osmani
🧠 How I’m Using Coding Agents in September 2025 – Jesse Vincent
🧭 Context Engineering Needs Domain Understanding – Rod Johnson
⚡ From GPT-2 to gpt-oss: Architectural Advances – Sebastian Raschka 🔥
💡 You Should Be Rewriting Your Prompts – Max Leiter
🧱 Google’s MCP Toolbox for Databases Is Now Open Source
🔥🔥🔥 Prompting 101 - Hannah & Christian from Anthropic

…and if you dare, 100+ updates to explore 👇

Share

🎯 Featured Article

Writing effective tools for AI agents - Anthropic outlines techniques for creating effective tools for LLM agents using the Model Context Protocol, sharing key principles for writing high-quality tools that bridge deterministic and non-deterministic systems.

📰 Building Agentic Systems

🔥🔥🔥 Effective context engineering for AI agents - Anthropic explains how context engineering is replacing prompt engineering, focusing on optimizing the entire token context to achieve consistent LLM performance rather than just finding the right prompt phrases.

Agentic AI Architecture Framework for Enterprises - InfoQ - A framework for building autonomous AI systems with architectural components and implementation patterns.

🔥 AI Agent Orchestration Patterns - Guide to designing multi-agent systems that handle complex tasks collaboratively by Microsoft.

🔥 Building production-ready agentic systems - Shopify’s journey building a production-ready AI assistant with practical lessons learned.

Equipping agents for the real world with Agent Skills - Anthropic: AgentSkills packages domain expertise for more capable AI assistants.

Magentic-One: A Generalist Multi-Agent System for Solving Complex Tasks - Microsoft’s multi-agent system that solves complex tasks through collaborative AI agents.

Supporting our AI overlords: Redesigning data systems to be Agent-first - Berkeley researchers propose redesigning databases for LLM agents’ unique query patterns.

Managing context on the Claude Developer Platform - Anthropic introduces new context management capabilities that help developers build AI agents capable of handling complex, long-running tasks without hitting context limits or losing critical information.

Agent Design Pattern Catalogue: A Collection of Architectural Patterns - Yue Liu - A collection of design patterns for building foundation model agents.

The 5 levels of AI agent autonomy: learning from self-driving cars - Maps coding agents to self-driving car autonomy levels, from manual to fully autonomous.

🔥 Deep Agents - AI systems evolving from shallow to deep agents with strategic planning capabilities.

📰 Coding with AI

🔥🔥🔥 How to Vibe Code as a Senior Engineer - Alex Maccaw explains how “vibe coding” leverages AI models to dramatically accelerate software development, turning traditionally expensive and time-consuming coding processes into rapid, efficient workflows for senior engineers.

Read That F*cking Code! - Developers need to actually read the code that AI generates for them.

🔥 The AI-Native Software Engineer - : Engineers who embrace AI as partners can multiply their productivity.

Onboarding for coding agents - Simplified context delivery for AI coding assistants.

Claude’s new Code Interpreter - reviews Claude’s Code Interpreter and showcases various AI development tools.

AI Coding Assistants for Large Codebases: A Complete Guide - Molisha Shah explains how effective AI coding assistants for large codebases need to understand entire repositories and architectural patterns, not just provide simple autocomplete functionality.

Designing agentic loops - explains how to maximize the potential of coding agents like Claude Code and Codex CLI by designing effective agentic loops that enable these AI tools to iterate toward solutions.

Embracing the parallel coding agent lifestyle - Simon Willison: Developer’s shift toward using multiple AI coding assistants at once.

🔥 How I’m using coding agents in September, 2025 - Developer’s workflow using Claude Code with git worktrees for parallel project management.

Vibe coding is not the same as AI-Assisted engineering. - clarifies the critical distinction between casual “vibe coding” and professional “AI-assisted engineering,” emphasizing that conflating these approaches risks devaluing engineering discipline and misleading newcomers about production software requirements.

Beyond the IDE - explores programming’s evolution from hardware to AI-assisted environments.

Reverse Engineering your Software Architecture with Claude Code to Help Claude Code - Nick Tune: Claude Code works best when it understands your system’s full functionality.

Beyond vibe coding: How AI can transform pull requests - Thoughtworks: Enterprise coding needs more than AI prompts due to regulatory and legacy constraints.

Exploring Cursor, Windsurf and Copilot with GPT-5 - Comparative analysis of GPT-5 coding tools across different development scenarios.

The Rule Maker Pattern: Creating Deterministic Execution with AI Probabilistic Generation - Guy Podjarny explains how developers can establish clear rules and guidelines to transform AI’s unpredictable outputs into reliable, deterministic execution for more consistent results.

How tech companies measure the impact of AI on software development - Orosz: Companies tracking whether AI coding tools justify their increasing costs.

How GPT5 + Codex took over Agentic Coding — ft. Greg Brockman, OpenAI - OpenAI’s GPT-5-Codex disrupts Anthropic’s coding dominance.

📰 Long-Form Reads

🔥🔥🔥 Context Engineering Needs Domain Understanding - Rod Johnson: Context engineering replaces prompt engineering with more precision.

🔥 You should be rewriting your prompts - Max Leiter: Different LLMs require different prompting approaches for best results.

Comparison - LLMs for Creating Software Architecture Diagrams - Testing if AI can create architecture diagrams but not replace architects.

Against “Brain Damage” - debunks fears that AI harms cognition, suggesting productive AI use instead.

GPT-5: Key characteristics, pricing and model card - : Brief notes on OpenAI’s new models and ChatGPT features.

The art and science of context engineering - CodeRabbit examines how effective AI code review tools require sophisticated context engineering to understand specific codebases deeply rather than simply pattern-matching against general rules.

🔥🔥🔥 From GPT-2 to gpt-oss: Analyzing the Architectural Advances - Technical breakdown of OpenAI’s new open-weight models and their architectural improvements.

Superintelligence - Meta’s roadmap for developing safe, advanced AI systems beyond human intelligence.

10 Proven Ways to Get Your Brand Mentioned in AI Answers - Strategies for brand visibility in AI responses through quality content placement.

How far can we push AI autonomy in code generation? - Böckeler: AI can build simple apps but still requires human supervision.

Mastering MCP Server with Spring Boot & AI - Standardized protocol for AI model-application communication.

Prompt injections as far as the eye can see - Researcher documents daily AI prompt injection vulnerabilities across multiple tools.

APIs don’t make good MCP tools - Reilly Wood explains why automatically converting existing APIs into Model Context Protocol tools often works poorly due to context window limitations and the fact that web APIs weren’t designed with these constraints in mind.

Agentic AI has changed my career. I don’t write code… - Elliot Graebert: Manager who stopped coding after early career promotion.

Less is More: Optimizing Function Calling for LLM Execution on Edge Devices - Streamlining LLM function calls for better edge device performance.

Building AI Products In The Probabilistic Era - AI systems work in ways we can’t fully predict or understand.

Your next job will require AI skills - : AI fluency becoming essential across all job functions.

Master the Blueprint: LLM Prompts for Perfect PRDs - Alward shares template for creating LLM-generated PRDs optimized for coding agents.

How AI is Transforming the PRD Process - Sean Shoffstall reflects on how AI tools are revolutionizing product requirements documents, addressing the longstanding problems of traditional PRDs that tend to be either too vague or overly detailed.

Writing product requirements with AI - Kapadia examines why PMs struggle with requirements documentation and AI limitations.

Using LLMs in Software Requirements Specifications: An Empirical Evaluation - Study comparing LLMs to humans in creating software requirement documents.

Vibe Specs: Vibe Coding That Actually Works - Luke Bechtel advocates for making AI write requirements before code, arguing this 5-minute investment saves hours of confusion and improves productivity.

LLM Evaluation: Practical Tips at Booking.com - George Chouliaras shares Booking.com’s methods for evaluating generative AI applications.

To vibe or not to vibe - Birgitta Böckeler examines the nuanced debate around AI-generated code review, challenging binary perspectives and suggesting that the appropriate level of review depends on various contextual factors.

LLMs as Parts of Systems - Marc’s Blog - Systems built with LLMs matter more than LLMs’ theoretical capabilities alone.

Attention Is the New Big-O - Alex Chesser explains how LLMs process text differently than humans, emphasizing that structural choices in prompts can impact results more significantly than word choice.

Let the Model Write the Prompt - Drew Breunig demonstrates how DSPy can be used to define and optimize LLM tasks, using a geospatial conflation problem as an example to show how the framework simplifies, improves, and future-proofs AI implementations.

First Malicious MCP in the Wild: The Postmark Backdoor That’s Stealing Your Emails - Koi reveals details about the first discovered malicious Model Composition Protocol (MCP) backdoor in the Postmark npm package that steals users’ email data.

Context engineering is sleeping on the humble hyperlink - the overlooked solution for efficient LLM context management.

Agentic Lessons learn after 300 agents - Sai Yashwanth - I have built around 300 agents, worked at 5 startups. Here’s what I learnt about AI Agent

Leadership co-processing with LLMs - James Stanier examines how large language models are transforming management practices through techniques for prioritization, communication, and cognitive offloading.

🎙️ YouTube & Podcasts

🔥How To Get The Most Out Of Vibe Coding - Guide to using AI as a coding partner to build faster by Y Combinator.

🔥🔥🔥 Prompting 101 | Code w/ Claude - Hannah Moran and Christian Ryan from Anthropic present fundamental prompting techniques for effectively working with Claude, covering essential strategies developers can use to improve AI interactions.

On Engineering AI Systems that Endure The Bitter Lesson - Building AI systems that last through principled engineering approaches.

🗞️ News and Social

Introducing gpt-oss - OpenAI releases Apache-licensed reasoning models optimized for consumer hardware.

Building agents with the Claude Agent SDK - Anthropic rebrands Claude Code SDK to reflect its broader agent capabilities beyond coding.

Google Labs introduces Opal - a new way to help you build and share AI mini-apps by linking together prompts, models, and tools— all while using simple, natural language

10 Principles of Building AI Agents: - by Pawel Huryn.

OpenAI experiments with new “Study together” tool on ChatGPT - ChatGPT’s new feature creates interactive learning experiences with guided study sessions.

THE WAY OF CODE - a project by n in collaboration with Anthropic:

Tessl launches spec-driven development tools for reliable AI coding agents

8 RAG architectures for AI engineers

Google’s MCP Toolbox for Databases is now open source! 🔥

AI tooling must be disclosed for contributions - AI disclosure requirement for contributions to ghostty-org.

🛠️ Tech & Tools

Agents.md: an open standard for AI coding agents - A file standard for consistent AI assistant instructions across projects.

GitHub - openai/gpt-oss: gpt-oss-120b and gpt-oss-20b - Open-weight models for reasoning and agentic tasks.

OpenCode | The AI coding agent built for the terminal - Open-source AI coding assistant for terminal that respects privacy.

Agent Leaderboard - a Hugging Face Space by galileo-ai - Comparative tool for AI agent performance with filterable metrics.

GitHub - traceloop/openllmetry - traceloop - OpenTelemetry-based observability for LLM applications.

GitHub - terryso/claude-auto-resume - Script that auto-resumes Claude CLI tasks after usage limits expire.

GitHub - f/awesome-chatgpt-prompts - A curated collection of prompts designed for ChatGPT and other LLM tools to help users get better responses from AI language models.

Kilo Code - coding agent for VS Code and JetBrains - AI coding assistant with project management capabilities serving 500k+ users.

GitHub - marcelsud/spec-driven-agentic-development - Specification-driven development framework for AI-assisted software building.

GitHub - charmbracelet/crush: 💘 - Terminal-based AI coding assistant for your workflow.

GitHub - Pimzino/claude-code-spec-workflow - Structured AI-powered development workflows for features and bug fixes.

GitHub - docker/cagent: Agent Builder and Runtime by Docker - AI agent orchestration tool for building collaborative virtual expert teams.

GitHub - kirodotdev/Kiro: Kiro is an agentic IDE that works alongside you - AI-powered IDE that understands your codebase and automates development tasks.

Product requirement document generation using LLM task oriented dialogue · GitHub - LLM-powered PRD generation through guided dialogue.

GitHub - davidkimai/Context-Engineering - First-principles handbook for AI context design and optimization.

GitHub - ashishpatel26/500-AI-Agents-Projects - Curated collection of AI agent applications with implementation resources.

GitHub - GoogleCloudPlatform/kubectl-ai: AI powered Kubernetes Assistant - AI-powered tool that simplifies Kubernetes management.

GitHub - hesreallyhim/awesome-claude-code - A curated resource list for maximizing Claude Code’s capabilities.

AI Coding Tools: Install Trends (based on Visual Studio Code) - Visual tracking of AI coding extension popularity in VS Code.

GitHub - invariantlabs-ai/mcp-scan: Constrain, log and scan your MCP connections - Security scanner for MCP servers detecting vulnerabilities across various configurations.

📚 Learning Picks

Think Python - Free, beginner-friendly Python programming book with interactive Jupyter notebooks.

GitHub - Asabeneh/30-Days-Of-Python: 30 days of Python programming challenge - Self-paced Python learning challenge with daily exercises.

Generative AI for Beginners - Microsoft’s 18-lesson course on building Generative AI applications.

GitHub - microsoft/ai-agents-for-beginners: 12 Lessons to Get Started Building AI Agents - Beginner-friendly AI agent development course .

🎭 AI Humor

Share

👋 See You Next Time

Thanks for reading Generative Programmer! 🙏 If you like the content please support my newsletter by subscribing and sharing with your network: X · LinkedIn · BlueSky · Email. Have a great rest of the week!

Subscribe now