When teams start building agent frameworks, they make the same mistake: they put everything in one place. One big instructions file. One enormous system prompt. Everything the agent might ever need, always loaded.
This feels safe. The agent will always have the right context, right?
Wrong. Context is not free. Every line you load competes for the model’s attention. And every rule that’s irrelevant to the current task is noise that dilutes the rules that are.
After six months building a production agent framework, we landed on three distinct layers of agent knowledge — and clear rules for which layer each piece of context belongs in.
Instructions: always-on, scoped by file type
Instructions are rules that should apply automatically, without the agent deciding to load them. They’re the guardrails for your codebase’s conventions.
The critical design decision: scope them by applyTo glob pattern. C# naming conventions load only for .cs files. React component patterns load only for .tsx files. API endpoint patterns load only in the API directory.
A rule belongs in instructions if you’d be frustrated to discover the agent violated it during routine editing — and it applies to a specific, bounded file context.
What doesn’t belong in instructions: everything else. Test strategy. PR review checklists. New endpoint scaffolding. Loading these into instructions means they’re loaded for every file edit, forever. That’s the mistake.
Skills: on-demand, task-scoped
Skills are SKILL.md files that agents load when the task domain matches. A test agent loads test skills. A code agent loads the new-endpoint skill when creating an endpoint. A review agent loads the PR review skill.
The difference from instructions: you’d never think about a skill until you’re doing that specific task. Test patterns are irrelevant when you’re refactoring a data model. PR review checklists are irrelevant when you’re writing unit tests.
Skills let you encode deep, specific knowledge — twenty checklist items for reviewing a C# API endpoint — without that knowledge cluttering every other context.
The rule: if you’d only think about this during a named, specific task — it’s a skill.
The trap: writing skills that are accurate today but wrong in six months when the codebase evolves. Skills need validation loops. (See: drift detection.)
Scripts: deterministic operations, no prose needed
Some operations have a single correct answer given known inputs. Does this branch name match the convention? Does this type exist in the codebase? How many tests reference this pattern? Are these skill examples valid?
For these, writing an instruction or skill is the wrong tool. You’re asking a language model to reason about something that doesn’t need reasoning — it needs computation.
Scripts do this deterministically, with zero tokens spent on inference. In our framework, PowerShell scripts handle drift detection, pattern counting, example validation, and other checks that would otherwise be expensive agent tasks.
The rule: if the output is deterministic given known inputs — it’s a script, not a prompt.
The decision tree
Is it a rule that applies automatically to a specific file type?
→ Instruction (with applyTo glob)
Is it knowledge you'd only need for a specific, named task?
→ Skill (SKILL.md, loaded on demand)
Is the answer deterministic given known inputs?
→ Script (PowerShell/bash)
Does it need to persist across sessions, shared between agents?
→ Memory Bank (markdown file, read selectively)Why this matters
The payoff is compound. Each layer being clean makes every other layer more effective:
- Clean instructions mean the agent has sharp, relevant guardrails for the files it’s editing
- Clean skills mean task-specific knowledge is deep and accurate without being present all the time
- Clean scripts mean deterministic checks happen reliably without consuming model capacity
- Clean memory bank means persistent state is structured and readable rather than accumulated chat history
The alternative — everything in instructions — gives you an agent that’s technically aware of every rule but pays attention to none of them. Specificity is leverage. Load what you need, when you need it.
These three layers are your instruction architecture. Getting the separation right is what makes the Instruct phase (bootstrap setup) and the ongoing Refine phase of the ADLC — The Missing Lifecycle for AI-Assisted Engineering productive rather than chaotic.