The Six Building Blocks of AI Coding Agents

Whether you're using Cursor, Claude Code, Windsurf, Cline, Codex CLI, or any other tool, there are six core concepts you need to understand. These aren't tool-specific features. They're becoming the shared language of how humans work with AI coding agents. Every tool implements them slightly differently, but the underlying ideas are the same.

The six building blocks are:

1. Rules - How you tell the agent who it is and how to behave
2. MCPs - How you give the agent superpowers beyond reading and writing files
3. Skills - How you create reusable workflows the agent can execute
4. Hooks - How you automate actions around the agent's behavior
5. Sub-Agents - How the agent delegates work to specialized child agents
6. Plugins - How you package and distribute bundles of the above

Think of your AI coding agent as a new hire at your company. Rules are the company culture and values they absorb on day one. MCPs are the tools and software you give them access to. Skills are the SOPs and playbooks they follow for repeatable tasks. Hooks are the compliance checks and quality gates that run automatically. Sub-agents are the departments they can delegate work to. And plugins are the franchise kits, pre-packaged bundles of all of the above that let you onboard a new team member (or project) in one step.

Understanding these six concepts (and how they affect the context window) is the difference between someone who just uses a coding agent and someone who actually controls one.

Why This Matters Now

If you started vibe coding six months ago, you could get away with just knowing how to prompt. Open a chat, type a request, get code. That's not enough anymore.

The tools have matured. They now support rules, custom MCPs, skills, hooks, sub-agents, plugins, and dozens of configuration options. The gap between someone who just prompts and someone who configures their agent properly is widening fast.

📐 Part 1: Rules

What Are Rules?

Rules are persistent instructions that shape how the AI agent behaves in your project. Think of them as your company culture and values, the handbook every new hire reads on day one. They shape how everyone behaves without needing to be repeated each time. Rules are included at the start of AI interactions and tell the agent things like: what tech stack you're using, what coding conventions to follow, what patterns to prefer, and what mistakes to avoid.

Without rules, the agent starts every conversation as a blank slate. It doesn't know your project uses TypeScript with strict null checks. It doesn't know you prefer functional components over class components. It doesn't know your team uses snake_case for database columns. You'd have to repeat all of this context in every single conversation.

Rules fix that. They're the foundation of everything else.

The Three Tiers of Rules

Across all AI coding tools, rules break down into three tiers. The naming varies slightly by tool, but the concepts are universal:

1. User-Level Rules (Apply to everything you do)

These are your personal preferences, the ones that follow you across every project. They live in your home directory or user settings, outside any specific repo. They typically cover:

• Communication style ("Be concise. Don't repeat yourself.")
• General coding principles ("Prefer composition over inheritance")
• Language preferences ("Always use TypeScript, never plain JavaScript")
• Personal conventions ("Use meaningful variable names. No abbreviations.")

Every major tool supports user-level rules. Claude Code, Codex CLI, and Gemini CLI use Markdown files in your home directory. Cursor and Windsurf use settings panels or global config files. Cline uses Markdown files in a dedicated rules folder. The format differs, but the concept is identical: preferences that follow you everywhere.

User-level rules are loaded into every conversation regardless of what project you're in. They're the lightest touch, your baseline preferences.

2. Project-Level Rules (Apply to a specific codebase)

These are the rules that live inside your repository and get version-controlled alongside your code. This is where the real power is.

Project-level rules tell the agent about your specific codebase:

• Architecture decisions ("We use the repository pattern with service layers")
• Framework conventions ("All API routes go in app/api/ and use the Next.js App Router")
• Naming conventions ("Components use PascalCase, utilities use camelCase, database columns use snake_case")
• Error patterns to avoid ("Never use any type. Never import from @internal packages")

Every tool has its own file or folder convention for project-level rules, typically a Markdown or config file at the repo root with a tool-specific name. Project-level rules are the single highest-leverage thing you can configure. They compound over time. Every rule you add is a mistake the agent will never make again in this project.

3. Scoped / Conditional Rules (Apply only in specific contexts)

This is where things get interesting. Some tools let you define rules that only activate under certain conditions, like when the agent is editing a specific type of file, or when you manually invoke them.

The implementations vary across tools, but the common patterns include:

• File glob patterns — rules that activate only when certain file types are being edited (e.g., testing rules for *.test.ts files)
• AI-driven activation — the agent reads the rule's description and decides whether to include it based on relevance
• Manual activation — rules that only load when you explicitly reference them by name
• Subdirectory scoping — placing a rule file in a subdirectory activates it only when working on files in that path

Why scoped rules matter for context: They're a direct answer to the context window problem. Instead of loading 2,000 lines of rules into every conversation (eating up valuable context), you load only what's relevant. Testing rules activate when you're testing. Database rules activate when you're writing migrations. Frontend rules activate when you're editing components. The agent gets exactly the context it needs, nothing more.

The Cross-Tool Reality: AGENTS.md

There's now a convention emerging around AGENTS.md as a tool-agnostic instruction file. The idea is simple, put an AGENTS.md file in your project root (or subdirectories), and any AI coding tool should be able to read it.

Codex CLI, Gemini CLI, Cursor, Windsurf, Cline, and several other tools already support it natively. Claude Code does not natively support AGENTS.md yet (it's one of the most-requested features, with thousands of upvotes on GitHub), but you can work around this by referencing it from your CLAUDE.md or symlinking.

You lose tool-specific features like conditional rule activation or nested scoping. But you gain portability.

My recommendation: Use AGENTS.md as your shared baseline, then add tool-specific rules on top. This way, anyone on your team gets the core instructions regardless of their tool, and those using specific tools get the additional benefits of native rule formats.

Best Practices for Writing Rules

Rules are only as good as how you write them. The three things that matter most:

✅ Be specific and actionable - "Use Zod for all API input validation" beats "Validate inputs properly." Vague rules like "write clean code" mean nothing to an agent.

✅ Document anti-patterns - Tell the agent what NOT to do. "Never use any type" prevents a common LLM default.

✅ Evolve over time - When you see the agent make the same mistake three times, create a rule. This "Rule of Thrice" from the Cursor guide is how rules compound.

🔌 Part 2: MCPs (Model Context Protocol)

What Are MCPs?

MCPs (Model Context Protocol) are a standardized way for AI coding agents to connect with external tools and data sources. Invented by Anthropic, they extend what your agent can do beyond reading and writing files.

MCPs are the tools and software subscriptions you give your new hire access to: the CRM, the analytics dashboard, the design tool, the database admin panel. Without them, your hire is sitting at a desk with nothing but a text editor. With them, they can actually do their job.

Without MCPs, your agent is stuck in a box. It can see your code, edit files, and run terminal commands. That's it. MCPs break the box open. They let your agent browse the web, query databases, interact with APIs, control browsers, search documentation, create images, manage deployments, and hundreds of other things.

How MCPs Work (The Simple Version)

An MCP server is a small program that exposes a set of tools the agent can call. The agent sees a list of available tools (with descriptions of what each one does), and decides when to use them based on your prompts and the task at hand.

The flow:

1. You configure MCP servers in your tool's settings
2. When a conversation starts, the agent receives a list of available MCP tools
3. Based on your request, the agent decides which tools to call
4. The MCP server executes the action and returns results to the agent
5. The agent uses those results to continue working

The list of available MCP tools is injected into every conversation. Each MCP tool comes with a name and description that the agent needs to see. This directly eats into your context window. More on this in Part 7.

What MCPs Exist

The ecosystem is broad. Here are the most common use cases:

• Browser automation — navigate websites, click buttons, fill forms (Playwright MCP, Chrome DevTools MCP)
• Database access — query and modify databases directly (Supabase MCP, PostgreSQL MCP)
• API interactions — interact with third-party services (Stripe MCP, GitHub MCP)
• Documentation — fetch up-to-date library docs (Context7, FireCrawl)
• Web search — search the internet for current information (Linkup, Perplexity MCP)
• Project management — read and update issues (Linear MCP, Jira MCP)
• Monitoring — check error logs and performance metrics (Sentry MCP, Datadog)
• Deployment — trigger and monitor deployments (Vercel MCP, Railway MCP)
• File storage — manage files beyond the local filesystem (S3 MCP, Google Drive MCP)
• Design systems — access component libraries and design tokens (shadcn MCP, Magic MCP)

The MCP Trap: Less is More

Most people go wrong by installing 15-20 MCPs because they look cool. Browser automation, Slack integration, image generation, Figma access, database tools, three different documentation fetchers...

Don't do this.

Every MCP you install adds tool descriptions to your context window. Each tool might add 100-300 tokens of description. If you have 20 MCPs with 3 tools each, that's 60 tool descriptions eating up 6,000-18,000 tokens before you even type your first message. That's a significant chunk of your context window consumed by tools the agent probably won't use in most conversations.

My recommendation: Start with 3-5 MCPs that cover your core needs:

1. One documentation MCP - Context7 or FireCrawl
2. One browser MCP - Chrome DevTools MCP or Playwright MCP
3. Your database MCP - If you use Supabase, Postgres, etc.
4. One search MCP - Linkup or Perplexity (optional, some tools have built-in web search)
5. Your project management MCP - Linear, GitHub, etc. (optional)

You can always add more later. But start lean.

Pro tip: Some tools let you toggle MCP servers on and off. If you have MCPs you only need occasionally (like an image generation MCP), keep them installed but disabled by default. Enable them only for sessions where you need them. This keeps your context window clean. And vet your MCPs like you'd vet a dependency — check when it was last updated, who maintains it, and what data access it requires.

⚡ Part 3: Skills

What Are Skills?

Skills are reusable workflows that you can trigger on demand. If rules tell the agent how to behave and MCPs give it tools to use, skills tell it what to do in a specific, repeatable way.

Think of skills as your SOPs and playbooks, the documented step-by-step processes for onboarding a customer, handling a refund, or deploying to production. Anyone can follow them and get a consistent result. Instead of explaining the same complex workflow every time ("review my code looking for security issues, check for SQL injection, XSS vulnerabilities, and authentication bypasses, then format the results as a checklist"), you package it into a skill and trigger it with a single command.

How Skills Work

The implementation varies across tools, but the concept is the same everywhere:

1. You define a workflow (a set of instructions, sometimes with parameters)
2. You give it a name or trigger
3. When you invoke it, the instructions are injected into the conversation
4. The agent follows those instructions to complete the task

How skills differ from rules: Rules are passive, they sit in the background and shape behavior. Skills are active, they're triggered explicitly and drive specific actions.

Most tools implement skills as Markdown files containing the instructions, triggered via a slash command (like /security-review). You type the command, the instructions get injected, and the agent follows them. Some tools let you pass additional context after the command name (like /create-component UserProfileCard), which gets appended to the skill's instructions.

One tool takes this further: Claude Code distinguishes between Agent Skills (which the AI can invoke on its own when it determines they're relevant) and Slash Commands (which require the user to trigger them explicitly). This is a meaningful distinction — it means your skills can be proactive, not just reactive.

When to Create a Skill

Not everything needs to be a skill. Here's the filter:

✅ Create a skill when:

• You find yourself typing the same prompt more than 3 times
• The workflow involves multiple steps that need to happen in sequence
• Different team members need to perform the same task consistently
• The task has specific requirements that are easy to forget

❌ Don't create a skill when:

• It's a one-off task you'll never repeat
• The task is simple enough that a single prompt handles it
• The workflow changes significantly each time

Practical Skill Ideas

Skills that have been genuinely useful in production: /spec (start a specification workflow), /component (scaffold a new component with tests and types), /review (comprehensive code review on the current diff), /security-audit (check for vulnerabilities), /deploy-checklist (run through pre-deployment checks), /debug (structured debugging session with log collection).

Skills and the Context Window

Skills only consume context when activated. Unlike rules (which are loaded into every conversation) and MCPs (whose tool descriptions are loaded into every conversation), skills are injected on demand.

This is a significant advantage. You can have 50 skills defined and they cost you nothing until you use one. When you do use one, it adds its instructions to the current conversation's context, but only for that conversation.

This makes skills the most "context-friendly" of all the building blocks. Define as many as you want without worrying about bloating your default context.

🪝 Part 4: Hooks

What Are Hooks?

Hooks are automated actions that execute in response to specific events in the agent's workflow. If rules shape behavior, MCPs add capabilities, and skills trigger workflows, hooks automate the surrounding process.

Hooks are your compliance checks and quality gates, the automated audit that fires before every release, the legal review before every contract goes out. They don't do the work, they gate it. Hooks run around the agent's actions, not instead of them. The agent does its thing, and hooks fire before, during, or after to enforce standards, run checks, or transform outputs.

The Two Levels of Hooks

1. Tool-Level Hooks (Within your AI coding tool)

These hooks fire in response to events inside the coding tool itself. They let you intercept and respond to things like:

• Before or after the agent edits a file — run linting, formatting, or block changes to protected files
• Before or after the agent runs a command — validate commands, log actions, or gate dangerous operations
• When the agent starts or stops — run setup or cleanup tasks
• When sub-agents are spawned — monitor delegation behavior

The sophistication varies by tool. Some offer a handful of lifecycle events; others provide a comprehensive event system with dozens of hooks and multiple hook types (shell commands, LLM prompts, sub-agent spawning). But the concept is the same: you define what happens when specific events occur, and the tool enforces it automatically.

A rule says "please don't modify migration files." A hook prevents the modification from happening. Rules are suggestions; hooks are enforcement.

2. Git-Level Hooks (Your safety net)

Git hooks aren't specific to AI coding tools, but they become essential when working with agents. They act as your last line of defense before code gets committed or pushed.

The most important git hooks for vibe coding:

• pre-commit - Runs before a commit is created. Use it for linting, formatting, and type checking
• pre-push - Runs before code is pushed. Use it for running tests
• commit-msg - Validates commit messages. Use it for enforcing commit conventions

Why git hooks matter more with AI agents: When you're writing code yourself, you naturally catch issues as you go. With an agent writing code at speed, things slip through — type errors, formatting inconsistencies, broken tests. Git hooks catch these automatically, regardless of whether a human or an agent created the code. Tools like Husky and lint-staged make setup easy.

When Hooks are Overkill

Like everything else, hooks can be over-engineered. Not every project needs elaborate hook systems.

✅ Use hooks when:

• You have quality gates that must always pass (linting, formatting, type checking)
• You want to prevent the agent from touching certain files or directories
• You need automatic post-processing on agent output (formatting, cleanup)
• You're working in a team and need to enforce consistency

❌ Don't use hooks when:

• You're prototyping and speed matters more than standards
• The hook would slow down every single agent action significantly
• You can achieve the same result with a rule ("Don't modify files in X directory")

Pro tip: Start with git hooks (they're universally useful), then add tool-level hooks only when you notice specific patterns that rules alone can't enforce. A rule says "please don't do X." A hook prevents X from happening.

🤖 Part 5: Sub-Agents

What Are Sub-Agents?

Sub-agents are child agents that the main agent spawns to handle specific tasks. If rules shape behavior, MCPs add capabilities, skills trigger workflows, and hooks automate checks, sub-agents let the agent delegate and parallelize work.

Sub-agents are the departments you delegate to. You're the CEO handing a brief to the design team, the legal team, and engineering simultaneously. Each department works independently with its own resources and reports back a summary. Without sub-agents, your agent is a solo founder doing everything sequentially. With them, it becomes a CEO who can delegate.

This is a big deal for two reasons:

1. Speed - Multiple sub-agents can work on different parts of a task simultaneously
2. Context isolation - Each sub-agent gets its own context window, so the main agent doesn't get bogged down with every detail of every subtask

How Sub-Agents Work

The pattern is consistent across tools, even though the implementation details vary:

1. The main agent receives your request
2. It decides the task is large enough (or has independent sub-tasks) to benefit from delegation
3. It spawns one or more sub-agents, each with a focused instruction
4. Each sub-agent works independently with its own context window and tools
5. Sub-agents report results back to the main agent
6. The main agent synthesizes the results and continues

Sub-agents typically cannot spawn their own sub-agents. This prevents infinite nesting and runaway resource consumption. It's a one-level delegation model in most tools.

Where Things Stand

Every major tool now offers some form of delegation, though the architectures differ. Some use a parent-child model (agent spawns sub-agents that report back). Others are peer-to-peer (independent agents working in parallel on separate branches). Many support custom agent definitions — Markdown files where you specify an agent's instructions, tools, and personality, so you can create a "research agent," "test writer," or "security reviewer" tailored to your workflow.

The frontier is pushing further with experimental multi-agent coordination and agent-to-agent protocols. But the common thread is clear: every tool is moving toward delegation.

When Sub-Agents Shine (and When They Don't)

✅ Sub-agents are great for:

• Large tasks with clearly independent subtasks ("update the API, write the tests, and update the docs")
• Research-heavy work where you don't want intermediate findings polluting the main context
• Parallelizing independent changes across different parts of the codebase
• Exploratory tasks where the agent needs to investigate before deciding what to do

❌ Sub-agents are overkill for:

• Simple, focused tasks that touch one or two files
• Tasks where every step depends on the previous one (sequential work)
• Quick fixes and small edits
• Situations where you want full visibility into every decision (sub-agents work somewhat autonomously)

Pro tip: The biggest practical benefit of sub-agents isn't speed, it's context isolation. When a sub-agent researches your codebase, reads 20 files, and reports back a summary, only that summary enters the parent's context. Without sub-agents, those 20 files would have filled the parent's context window directly. For complex tasks, this changes everything.

📦 Part 6: Plugins

What Are Plugins?

Plugins are the packaging and distribution layer of the AI coding agent ecosystem. They're the franchise kits, pre-packaged bundles of culture docs, SOPs, tool subscriptions, compliance checklists, and team structures that let you spin up a new location (or project) with one purchase instead of building everything from scratch.

A single plugin might include custom skills, hook configurations, MCP server setups, sub-agent definitions, and even Language Server Protocol (LSP) integrations, all namespaced, versioned, and installable with one command. Without plugins, you'd manually copy configuration files between projects, share rule snippets in Slack, and hope everyone on the team sets up their MCPs the same way. Plugins solve that distribution problem.

How Plugins Work

The concept is straightforward:

1. Someone bundles a set of related extensions (skills, hooks, MCPs, etc.) into a plugin with a manifest
2. The plugin gets published to a marketplace or shared as a Git repository
3. You install it with a single command
4. All the bundled components activate in your environment, namespaced under the plugin's name
5. Updates flow through the same marketplace or repository

Plugins don't add new capabilities themselves. They package and distribute the other five building blocks. A plugin is a delivery mechanism, not a primitive.

The Current Landscape

The plugin ecosystem is still early but moving fast. Claude Code has the most structured system: a formal manifest format, namespaced components, and both an official marketplace and third-party ones. Gemini CLI launched its own extensions system with a gallery and launch partners (Figma, Stripe, Shopify, Snyk, and others). Other tools are earlier in this journey, but the direction is clear: plugins are becoming the standard way to share and distribute agent configurations.

When to Use Plugins vs. Manual Configuration

✅ Use plugins when:

• You want a pre-built, maintained setup for a common integration (GitHub, Sentry, etc.)
• You're sharing configurations across a team and want consistency
• The plugin bundles multiple related components that would be tedious to set up individually
• You want LSP-powered code intelligence (this is hard to configure manually)

❌ Don't use plugins when:

• You only need a single MCP or skill (just configure it directly)
• The plugin includes way more than you need (bloats your setup)
• You need fine-grained control over every configuration detail
• The plugin is unmaintained or from an untrusted source

Pro tip: Treat plugins like dependencies in your code. Audit what you install, especially plugins that bundle MCPs with access to external services. A plugin that bundles 5 MCPs with 4 tools each silently adds 20 tool descriptions to every conversation — the same "install everything" trap, just at a larger scale.

🧩 Part 7: The Context Window (Where It All Comes Together)

Why the Context Window Matters More Than Anything

Everything in this guide, rules, MCPs, skills, hooks, sub-agents, plugins, ultimately connects to one thing: the context window.

The context window is the total amount of text the LLM can "see" at any given moment. It includes everything: the system prompt, your rules, MCP tool descriptions, the conversation history, file contents the agent has read, and your latest message. When the context window fills up, older information gets pushed out or compressed, and the model's performance degrades.

Imagine the context window as your employee's desk. The culture handbook, the tool manuals, the SOPs, and the project brief all need to fit on it. A small desk means you can only have a few documents open at once. If you pile on too many, things fall off the edge. A larger desk helps, but it's still finite, and a cluttered desk makes it harder to find what matters.

The context window is your most precious resource when working with AI coding agents. Every configuration choice you make either preserves it or consumes it.

The Context Budget

Let's say your model has a 200,000 token context window (common for Claude and GPT-4 models). Roughly how it gets allocated:

System prompt & tool overhead:    ~5,000 tokens
User-level rules:                 ~500-1,000 tokens
Project-level rules (always-on):  ~1,000-3,000 tokens
MCP tool descriptions:            ~2,000-10,000 tokens (depends on how many)
─────────────────────────────────────────────────────
Available for actual work:        ~186,000-191,500 tokens

That "available for actual work" bucket covers: conversation history, file contents the agent reads, code it generates, skill instructions when invoked, and MCP tool results. The more you consume with always-on overhead, the less room you have for actual work.

When context gets tight, the model:

• Forgets instructions from earlier in the conversation
• Produces lower quality code
• Loses track of the overall task
• Makes mistakes it wouldn't make with more room

Practical Tips for Context Management

1. Audit your always-on context regularly. Combined rules + MCP tool descriptions should ideally stay under 10,000 tokens. If you're over that, trim.

2. Disable unused MCPs. If you're not using the image generation MCP today, disable it. Every disabled MCP is context saved.

3. Keep skills lean. A skill that injects 5,000 tokens of instructions is a context hog. Reference external files instead of including everything inline.

4. Prefer hooks over rules for enforcement. A hook that runs Prettier after every save consumes zero context and guarantees the result. A rule that says "always format code with Prettier" consumes context and only works if the agent follows it.

📋 Cheat Sheet

Building Blocks at a Glance

Essential MCP Stack (Starter Kit)

The tools will keep evolving, but these six patterns won't change much. Configure them well and everything else gets easier.

If you have feedback or want to discuss, reach out at julien@argil.io or on X (@JBerthom).

Written with ❤️ by a human (still)