If you have spent any time configuring an AI coding agent, you have probably figured out that rules and skills are different things. Rules are always loaded. Skills are invoked on demand. Rules handle recognition; skills handle procedure. Most people get this far and stop.
The interesting problems start after you have internalized that distinction and started building on it. When your configuration grows past a handful of files, patterns emerge that the basic mental model does not prepare you for. I have been working with AI coding tools for over two years now, starting with Windsurf and building progressively more sophisticated systems with Claude Code. The rule-versus-skill distinction was foundational, but what I want to talk about is what comes next.
The Failure Modes Tell You Everything
The basic distinction is useful, but it becomes powerful when you frame it through failure modes.
If you miss the moment to act, that is a rule problem. The rule was not in context when the trigger fired, so the agent did not recognize that something should happen. The moment passed silently. This is why rules need to be always loaded. A rule that is not present when its trigger fires is a rule that does not exist.
If you miss a step in how to act, that is a skill problem. The agent recognized the situation but did not have the detailed procedure available. This is why skills load on demand. They contain the instructions for how to do something, and they only need to be present when that something is actively happening.
Two failure modes, two tools, two loading strategies. Once you see it this way, every configuration decision becomes a question about which failure mode you are guarding against.
The Tax You Do Not See
Here is where it gets interesting. Context is not free. Every line of configuration that loads into an agent's context competes with the actual task for the model's attention. I have watched output quality degrade based on what else is in context. A lean, targeted context produces sharper work than a bloated one carrying instructions the agent does not currently need.
When I audited my own configuration recently, I found rules that were 30 to 50 lines long, loaded into every conversation, relevant to maybe 5% of sessions. Hundreds of tokens of procedural detail sitting in context, occupying space that could have been serving the task at hand.
The instinct is to put everything in rules because rules are always there. It feels safer. What if the agent needs this information and it is not loaded? The answer is straightforward: that is what skills are for. The agent invokes the skill when it needs the procedure. The procedure loads just in time. Context stays clean the rest of the time.
This is the tax that is easy to miss. You may be paying for configuration you are not using, and the cost is not just tokens. It is attention.
The Split Pattern
The most common problem I found was a single file trying to handle both recognition and procedure. The pattern looked like this: a section called "When to apply" at the top, three to five lines, followed by a section called "How to do it" filling the rest of the file. Thirty, forty, fifty lines of detailed instructions that loaded into every conversation because the three-line trigger at the top needed to be always present.
The fix is a split. Take the recognition concern and leave it as a rule. Three to five lines, always loaded, lightweight. It recognizes the situation and points to the procedure. Take the procedural concern and move it to a separate file that loads only when the agent is working in that context.
I applied this to five rules. The split saved roughly 120 lines of always-loaded context. The recognition still fires every time. The procedure loads only when relevant. Same behavior, dramatically less overhead.
This is separation of concerns. The recognition concern and the procedure concern have different lifecycles. They change for different reasons. They have different performance characteristics. Bundling them into one artifact creates the same problems that bundling unrelated code into a single module creates: unnecessary coupling and wasted resources.
Config Is Code
Once you start seeing configuration through this lens, the software engineering parallels are everywhere.
Single responsibility: each configuration artifact should do one thing. A rule that both recognizes a trigger and contains the full procedure for handling it is doing two things. Split them.
Open-closed: you should be able to extend behavior without modifying existing artifacts. A rule that points to a convention file lets you update the procedure without touching the trigger. A skill that reads from a settings file lets you change parameters without rewriting the skill.
Interface segregation: load only what is needed. An agent working on a blog post does not need the rules for database migrations. Path-scoped configuration and on-demand skills keep context targeted.
These are decades-old principles applied to a domain where many people are still treating configuration as prose they paste into a file and forget about. The configuration that composes well, that stays maintainable as the system grows, follows the same design principles we already know from code. If it would be a code smell in your codebase, it is a code smell in your configuration.
A Decision Framework
When I add new behavior to my system, I ask three questions.
Does this need to be recognized before it is invoked? If yes, the trigger belongs in a rule. Keep it short. Just enough for pattern matching.
Does this require detailed procedural steps? If yes, those steps belong in a skill or convention file that loads on demand.
Is this artifact earning its context cost? If a rule is more than ten lines, something procedural has probably crept in. If a skill is being referenced in a rule with "see the skill for details," the split is already happening. Make it explicit.
The goal is not fewer files. It is the right information in context at the right time. Every token should be there because the current task needs it, not because it might be needed someday.
There Is a Third Piece
Rules handle recognition. Skills handle procedure. There is a third mechanism in Claude Code that handles neither. It handles the things that should happen automatically, without judgment, every single time. No recognition needed, no procedure to follow. Just a deterministic response to a specific event.
Think of it as the autonomic nervous system of your configuration. Your rules are conscious decisions. Your skills are learned procedures you invoke deliberately. Hooks are your heartbeat and your reflexes — the responses that fire without you thinking about them, because if you had to think about them, you would eventually forget.
That deserves its own post. For now, just know that if you find yourself writing a rule that says "every time X happens, always do Y" — you are probably describing a hook, not a rule. The difference between "remember to do this" and "this just happens" is the difference between compliance and architecture.
Why This Matters
AI coding agents are getting more capable, and the instinct is to configure them more heavily. More rules, more instructions, more guardrails. The problem is that configuration has a runtime cost many people are not thinking about.
Treating AI configuration as an engineering discipline is not over-optimization. It is the difference between a system that stays sharp as it scales and one that gradually drowns in its own instructions. The model does not get smarter when you add more context. It gets smarter when the context it has is precisely what it needs.
Rules are for recognition. Skills are for procedure. Hooks are for guarantees. The rest is just good engineering.
Top comments (0)