Prompt Layering

Agent instructions stack across four layers — system prompt, project instructions such as AGENTS.md and CLAUDE.md, skill content such as SKILL.md, and the user message — with specificity generally determining precedence when layers conflict, according to an Agent Patterns guide on prompt layering. The guide notes the ordering is a behavioral tendency rather than a formal rule enforced by the model, and that contradictions between layers produce unpredictable outputs. It also warns that subagents do not inherit the parent agent's context, starting fresh with their own system prompt unless constraints are explicitly passed, and cites Purpura et al., 2026 in reporting that constraints near the start of a prompt are followed more reliably than those buried in the middle.

context-engineering ../../tags/ tag:context-engineering instructions ../../tags/ tag:instructions tool-agnostic ../../tags/ tag:tool-agnostic Prompt Layering: How Instructions Stack and Override ¶ prompt-layering-how-instructions-stack-and-override Prompt layering stacks agent instructions across four sources — system prompt, project instructions, skill content, user message — where specificity determines precedence on conflicts. Learn it hands-on with The Layer Stack https://learn.agentpatterns.ai/context-engineering/prompt-layering/ , a guided lesson with quizzes. The layer stack ¶ the-layer-stack Instructions reach an agent from several sources, each loaded at a different point in the session lifecycle: php graph TD A System Prompt<br Platform / tool default -- B Project Instructions<br AGENTS.md / CLAUDE.md B -- C Skill Content<br Task-specific knowledge C -- D User Message<br Immediate intent D -- E Agent Response Each layer is more specific than the one above it. Specificity generally determines precedence when layers conflict: the user message overrides the skill, which overrides project instructions AGENTS.md , CLAUDE.md , which overrides the system prompt. The more specific instruction wins because it sits closer to the actual task. This is a behavioral tendency, not a formal rule enforced by the model. Contradictions between layers produce unpredictable outputs. What each layer is for ¶ what-each-layer-is-for The system prompt is the outermost layer, set by the tool or platform. It defines the agent's role, permissions, and baseline constraints. Project instructions live in AGENTS.md , CLAUDE.md , and .github/copilot-instructions.md ../../tools/copilot/copilot-instructions-md-convention/ . They load at session start and apply to every task in the project: conventions, constraints, and tooling preferences. This layer must apply universally. If a rule is task-specific, it does not belong here. Skill content is task-specific knowledge that loads when a skill runs, such as a SKILL.md file. A code review skill carries review conventions; a documentation skill carries writing standards. Skills extend or refine project instructions for a specific task type. They do not repeat them. Repeating project conventions in a skill creates a second source of truth that can drift ../../instructions/instruction-file-ecosystem/ . The user message is the immediate task. It overrides everything below it because it represents the most specific current intent. If the user message contradicts a higher layer, the agent typically follows the user message. That is correct for the immediate task, but it may violate project conventions. Subagents break the stack ¶ subagents-break-the-stack Subagents do not inherit the parent agent's context. A subagent invoked by a parent agent starts fresh with its own system prompt, typically one injected at invocation time Claude Code sub-agents docs https://code.claude.com/docs/en/sub-agents . The parent's project instructions, loaded skills, and conversation history are not present unless explicitly passed. A subagent can violate project conventions the parent was following unless the parent explicitly passes the relevant constraints. Debugging requires knowing what the subagent received at invocation, not what the parent had. Conflicts and debugging ¶ conflicts-and-debugging When an agent ignores an instruction, diagnose by layer: 1. Which layer does the instruction come from? An instruction buried in the middle of a long AGENTS.md competes with positional bias. Instruction compliance varies significantly with a constraint's position in the prompt, with measured primacy and recency effects Purpura et al., 2026 https://arxiv.org/abs/2601.18554 . Constraints near the start are followed more reliably than those buried in the middle. For critical rules, repeat them at both ends ../../instructions/critical-instruction-repetition/ . 2. Is there a conflicting instruction closer to the task? A user message that says "skip tests for now" overrides a project instruction to always write tests. 3. Is the agent a subagent? If so, the project-level instructions may not be in its context. 4. Is the instruction past the compliance ceiling? The more rules in the stack, the more likely lower-priority rules are ignored. Designing for the stack ¶ designing-for-the-stack Avoid duplicating instructions across layers. If a convention is in both AGENTS.md and a skill, changing one without the other produces a contradiction. The convention belongs in one layer; other layers refer to it or omit it. Scope each layer tightly: - Project layer: only what applies to every task - Skill layer: only what applies to this task type - User message: only the immediate task Instructions that belong in the skill layer but sit in the project layer crowd context for every task, including those where the skill is not running. Example ¶ example A team configures Claude Code with a project-level CLAUDE.md that says: "Always write tests for new functions." A developer runs a code-generation task and adds a user message: "Generate the helper function — skip the tests for now, I'll add them later." The user message overrides the project instruction. Claude Code generates the function without tests. The more specific instruction immediate task takes precedence over the less specific one project convention . Now the team adds a code-review skill that includes the rule Flag any function without a corresponding test . When this skill runs on the same helper function, it flags the missing test. The skill layer is more specific than the project layer for that task type. The instruction to flag does not conflict with the earlier user message, which was about generation, not review. The gap is intentional: the project layer sets policy, the skill layer enforces it contextually, and the user message scopes the immediate action. Keeping these concerns in separate layers prevents the skill from being silenced by a user message that was not meant to apply to it. Key Takeaways ¶ key-takeaways - The layer closest to the task usually wins a conflict, but that is a tendency, not an enforced rule, so repeat critical constraints instead of relying on position alone - Before dispatching a subagent, explicitly pass any project convention it must follow, since it starts fresh with no parent context - If you find the same convention duplicated across layers, delete the copy and let the other layer reference it, since the duplicate is what drifts when only one copy gets updated - When an agent ignores an instruction, check: layer position, conflicting instructions closer to the task, subagent context isolation, total compliance ceiling When this backfires ¶ when-this-backfires Prompt layering assumes the model will respect layer precedence, but that assumption fails: - Silent contradictions go undetected. When project instructions and a skill both define a convention differently, the model picks one without signaling the conflict. A flat single-layer system prompt makes contradictions at least visible in one file. - Compliance degrades with stack depth ../../instructions/instruction-compliance-ceiling/ . Each added layer increases total instruction volume. Beyond the compliance ceiling, low-priority rules typically the project layer are silently dropped. Ten critical rules in a flat prompt outperform forty rules spread across four layers. - Subagent isolation amplifies drift. Subagents ../../patterns/multi-agent/sub-agents-fan-out/ start fresh. If the parent's project layer is not explicitly passed, the subagent ignores those conventions entirely. Layering without an explicit injection protocol is operationally equivalent to having no project layer for subagents. Related ¶ related - AGENTS.md: A README for AI Coding Agents ../../standards/agents-md/ - Project Instruction File Ecosystem: CLAUDE.md, copilot-instructions, AGENTS.md ../../instructions/instruction-file-ecosystem/ - The Instruction Compliance Ceiling ../../instructions/instruction-compliance-ceiling/ - Phase-Specific Context Assembly ../phase-specific-context-assembly/ - Dynamic System Prompt Composition ../dynamic-system-prompt-composition/ - Layered Context Architecture ../layered-context-architecture/ - Lost in the Middle: The U-Shaped Attention Curve ../lost-in-the-middle/ - Agent Debugging: Diagnosing Bad Agent Output ../../observability/agent-debugging/ — diagnosing instruction conflicts using the layer stack