Chapter 2: Instructions for AI agents
Introduces instructions as the context source that sets rules and behavioral expectations for LLM-based systems.
After this chapter you will be able to
- Role of instruction layers. Explain how instructions shape an LLM-based system’s behavior by establishing rules, constraints, and behavioral expectations that apply when it interprets an interaction.
- Instructions as operating rules. Explain how instructions set an LLM-based system’s role, behavior, boundaries, formatting, and policies, and how those rules shape its response to user requests.
- Three complementary instruction mechanisms. Distinguish the system prompt, agent skills, and instruction artifacts by the kind of guidance each provides.
- System prompt baseline control. Explain that the system prompt, or system message, is the initial instruction layer supplied to an LLM and sets baseline behavior, tone, and constraints across a session or request.
- System prompt as specification. Explain why a system prompt should specify what the model should optimize, avoid, do in common edge cases, and produce as an answer.
- Product and API prompt control. Distinguish how system prompts are controlled in production assistants versus developer-facing APIs, including how end users can still influence an assistant within its boundaries.
- System prompt instruction scope. Explain why a system prompt should contain instructions that apply to every user request rather than a large collection of specialized procedures.
- Modular skill packages. Explain what an agent skill packages and why it is an alternative to putting all specialized procedures in the system prompt.
- Progressive skill disclosure. Describe how progressive disclosure keeps skills discoverable while limiting the instructions in active context.
- Harness-based skill activation. Trace the agent harness’s role in finding and loading a skill, and explain why discovery matters.
- Skill file and discovery metadata. Describe the required structure of a skill and explain how its frontmatter identifies the skill and helps an agent decide when to load it.
- Procedural skill body. Explain what the body of SKILL.md provides and illustrate its role using the commit-message example.
- Explicit skill activation conditions. Explain why a skill’s frontmatter description should say both when to use the skill and when to ignore it.
- Code and model responsibilities. Distinguish work that belongs in deterministic code from work that benefits from the model’s contextual judgment.
- SKILL.md operational contract. Describe how SKILL.md should state enforceable requirements rather than optional advice.
- Outputs for chained workflows. Explain why diagnostic, investigative, or auditing skills should produce structured, actionable outputs.
- Instruction artifacts and scalability. Explain what instruction artifacts are and why projects use them instead of putting all operational guidance in one global system prompt.
- Durable repository guidance. Explain why coding agents use instruction artifacts for repository rules and where that guidance belongs.
- Concrete decision guidance. Explain why directives should specify actions, locations, or boundaries rather than broad advice.
- Appropriate instruction layers. Distinguish where shared repository rules, tool-specific adaptations, and personal or private settings belong.
- Local subproject instructions. Describe how nested instruction artifacts serve modular repositories and relate to root guidelines.
- Ongoing artifact maintenance. Explain why teams should review and prune instruction artifacts as software changes.
- System Prompt Response Effects. Explain how the example isolates the effect of a system prompt: both calls use the same user prompt, but only one includes instructions to correct grammar and answer in one sentence.
- Custom skill instructions. Describe what goes in SKILL.md for the project-notetaker skill and why those instructions live in a dedicated file.
- Skill discovery and activation. Explain how a custom skill becomes available to a compatible agent and how it can be activated.
- Benefits of skill reuse. Explain how adopting pre-built agent skills saves teams from writing every procedure from scratch and provides standardized workflows for recurring tasks.
- Third-party skill vetting. Justify security checks before adding an unfamiliar skill to a workspace, and state what teams should inspect.
- Portable project instruction setup. Describe how a repository-root AGENTS.md provides shared rules to coding agents, and distinguish native discovery from Claude Code’s adapter approach.
- Cross-agent instruction verification. Explain how to test the artifact with the same coding task across agents and what behavior indicates that the project rules were followed.
What it builds on
- Instructions (chapter 1) · Introduces instructions as a source of context.
Section by section
Introduction
Introduces instructions as the context source that sets rules and behavioral expectations for LLM-based systems.
- Role of instruction layers: Explain how instructions shape an LLM-based system’s behavior by establishing rules, constraints, and behavioral expectations that apply when it interprets an interaction.
Why it matters: Instructions are part of the context in which the model interprets a request, not just a response to that request.
Key terms: instructions, instruction layers
2.1 Instructions
This section explains what instructions do in LLM-based systems, distinguishes three ways agents receive them, and sketches how an agent assembles them into context.
- Instructions as operating rules: Explain how instructions set an LLM-based system’s role, behavior, boundaries, formatting, and policies, and how those rules shape its response to user requests.
Why it matters: This explains why a user request is not the only guidance an agent follows. - Three complementary instruction mechanisms: Distinguish the system prompt, agent skills, and instruction artifacts by the kind of guidance each provides.
Why it matters: These mechanisms serve different scopes, so an agent need not put every instruction in one place. - Staged assembly of agent context: Trace the high-level sequence by which the context manager makes instruction material available, including when full skill instructions are loaded.
Why it matters: Loading compact skill descriptions first avoids spending context-window tokens on full instructions before they are needed.
Key terms: instructions, operating rules, safety boundaries, system prompt, agent skills, instruction artifacts, context manager, context window, skill frontmatter, token budget
2.2 The system prompt
Defines the system prompt as the initial instruction layer that sets an LLM’s baseline behavior.
- System prompt baseline control: Explain that the system prompt, or system message, is the initial instruction layer supplied to an LLM and sets baseline behavior, tone, and constraints across a session or request.
Why it matters: It establishes what the developer wants the model to do consistently, rather than only in a single reply.
Key terms: system prompt, system message, baseline behavior, tone, constraints
2.2.1 Content of the system prompt
This section explains how to write a system prompt as an operational specification using distinct instruction components.
- System prompt as specification: Explain why a system prompt should specify what the model should optimize, avoid, do in common edge cases, and produce as an answer.
Why it matters: Operational detail makes the intended behavior clearer than a broad instruction alone. - Persona and task goal: Distinguish the persona, which sets the model’s role and manner of communication, from the goal, which sets its primary objective and helps it prioritize relevant responses.
Why it matters: Separating role from objective helps a prompt guide both how the model communicates and what it tries to accomplish. - Required process and boundaries: Distinguish rules, which specify mandatory procedures for achieving the goal, from constraints, which set boundaries the model must respect.
Why it matters: A prompt can separately specify the steps to follow and the limits that apply throughout the task. - Concrete input output examples: Explain how examples show the desired input-output relationship and ground the model in concrete patterns.
Why it matters: Concrete examples make an intended output pattern easier to convey.
Key terms: system prompt, operational specifications, persona, goal, rules, constraints, examples, input-output relationship
2.2.2 System prompts in products and APIs
This section contrasts who controls system prompts in products and APIs, then explains why system prompts should contain only instructions that apply to every request.
- Product and API prompt control: Distinguish how system prompts are controlled in production assistants versus developer-facing APIs, including how end users can still influence an assistant within its boundaries.
Why it matters: It clarifies whose instructions can be changed directly in each setting. - System prompt instruction scope: Explain why a system prompt should contain instructions that apply to every user request rather than a large collection of specialized procedures.
Why it matters: Keeping general instructions separate from specialized ones makes guidance easier to maintain and find.
Key terms: system prompt, system message, developer-facing APIs, specialized procedures, modular instruction packages, agent skills
2.3 Agent skills
This section explains how agent skills package specialized instructions for on-demand loading instead of placing every procedure in a global system prompt.
- Modular skill packages: Explain what an agent skill packages and why it is an alternative to putting all specialized procedures in the system prompt.
Why it matters: Packaging procedures separately lets an agent have specialized capabilities without carrying every instruction in its global context. - Progressive skill disclosure: Describe how progressive disclosure keeps skills discoverable while limiting the instructions in active context.
Why it matters: The agent can find a relevant capability without making the model sift through every procedure on every task. - Harness-based skill activation: Trace the agent harness’s role in finding and loading a skill, and explain why discovery matters.
Why it matters: A packaged procedure can help only if the harness reliably finds and activates it for the right task.
Key terms: agent skills, system prompts, procedural knowledge, progressive disclosure, lightweight metadata, active context, agent harness, skill descriptions, activation triggers, working context
2.3.1 The anatomy of a skill
This section explains the required SKILL.md file, how its metadata and instructions work, and the purposes of optional files in a skill directory.
- Skill file and discovery metadata: Describe the required structure of a skill and explain how its frontmatter identifies the skill and helps an agent decide when to load it.
Why it matters: The description helps the agent load a skill when it is relevant rather than on every task. - Procedural skill body: Explain what the body of SKILL.md provides and illustrate its role using the commit-message example.
Why it matters: The body turns a discovered skill into instructions the agent can follow for a task. - Optional skill directory resources: Distinguish the purposes of the optional scripts, references, assets, and tests directories within a skill.
Why it matters: Keeping these resources distinct makes it clearer what the agent should run, consult, reuse, or check.
Key terms: skill, SKILL.md, YAML frontmatter, name, description, skill body, Markdown, procedure, conventional commit message, scripts/
2.3.2 Best practices for designing agent skills
This section explains how to design agent skills that activate appropriately, divide work between code and the model, enforce requirements, support follow-on work, and remain reliable in production.
- Explicit skill activation conditions: Explain why a skill’s frontmatter description should say both when to use the skill and when to ignore it.
Why it matters: Clear activation boundaries help the agent use a skill when it is useful without adding irrelevant context. - Code and model responsibilities: Distinguish work that belongs in deterministic code from work that benefits from the model’s contextual judgment.
Why it matters: The division makes exact operations repeatable without giving up the model’s ability to respond to context. - SKILL.md operational contract: Describe how SKILL.md should state enforceable requirements rather than optional advice.
Why it matters: An explicit contract makes the skill’s required behavior harder for the agent to reinterpret. - Outputs for chained workflows: Explain why diagnostic, investigative, or auditing skills should produce structured, actionable outputs.
Why it matters: A finding is more useful when the next agent action can directly work from it. - Predeployment skill verification: Describe how teams can check a skill before using it in production workflows.
Why it matters: Checking realistic cases and the skill definition can expose problems before deployment. - Versioned skill assets: Explain why teams should keep skill files in source control.
Why it matters: Versioning gives teams a way to review and track changes to skills like other engineering assets.
Key terms: activation conditions, description field, frontmatter, overactivation, underactivation, deterministic logic, probabilistic reasoning, orchestration, contextual reasoning, SKILL.md
2.4 Instruction artifacts
This section explains how instruction artifacts make project-specific guidance available to agents without overloading a global system prompt.
- Instruction artifacts and scalability: Explain what instruction artifacts are and why projects use them instead of putting all operational guidance in one global system prompt.
Why it matters: It gives agents a scalable way to access guidance specific to the project they are working on. - Explicit project policy boundary: Describe how instruction artifacts turn team conventions into reusable agent context and distinguish lasting project policy from conversation-specific prompts.
Why it matters: Shared, durable guidance helps teams avoid restating rules and getting inconsistent agent behavior.
Key terms: instruction artifacts, global system prompt, version-controlled files, implicit team conventions, machine-readable context, permanent project policy, ephemeral conversation prompts
2.4.1 Instruction artifacts in coding agents
This section explains why coding agents use repository-adjacent instruction files and how file conventions vary across agent environments.
- Durable repository guidance: Explain why coding agents use instruction artifacts for repository rules and where that guidance belongs.
Why it matters: This lets repository guidance persist across coding sessions instead of depending on repeated prompts. - Coding agent file conventions: Distinguish examples of instruction-file conventions and explain why no single file format determines what every coding agent receives.
Why it matters: The file an agent uses—and how much guidance it receives—depends on its environment.
Key terms: instruction artifacts, durable guidance, version-controlled files, AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/*.mdc, active context
2.4.2 Best practices for designing instruction artifacts
The section gives four practices for making instruction artifacts useful to agents and maintainable as a codebase changes.
- Concrete decision guidance: Explain why directives should specify actions, locations, or boundaries rather than broad advice.
Why it matters: Concrete directions help an agent decide what to do without wasting its context budget. - Appropriate instruction layers: Distinguish where shared repository rules, tool-specific adaptations, and personal or private settings belong.
Why it matters: Choosing the right layer keeps shared guidance available without committing private or personal settings. - Local subproject instructions: Describe how nested instruction artifacts serve modular repositories and relate to root guidelines.
Why it matters: Local files can give an agent relevant subproject rules without making repository-wide guidance unwieldy. - Ongoing artifact maintenance: Explain why teams should review and prune instruction artifacts as software changes.
Why it matters: Keeping instructions current prevents an agent from acting on guidance the codebase has outgrown.
Key terms: instruction artifacts, actionable command, specific location, explicit boundary, token budget, AGENTS.md, CLAUDE.md, untracked local configurations, directory locality, nested instruction artifacts
2.5 Hands-on
2.5.1 Using system prompts
A two-call example shows how a system prompt changes an LLM’s response to the same user request.
- System Prompt Response Effects: Explain how the example isolates the effect of a system prompt: both calls use the same user prompt, but only one includes instructions to correct grammar and answer in one sentence.
Why it matters: The comparison makes the system prompt’s influence visible without changing the user’s request.
Key terms: system prompt, user prompt, persona and style constraints
2.5.2 Creating custom agent skills
This section shows how to create a custom agent skill in SKILL.md, make it discoverable by an agent, and activate it when needed.
- Custom skill instructions: Describe what goes in SKILL.md for the project-notetaker skill and why those instructions live in a dedicated file.
Why it matters: Separating reusable instructions from conversation prompts makes a specialized behavior available when the task calls for it. - Skill discovery and activation: Explain how a custom skill becomes available to a compatible agent and how it can be activated.
Why it matters: A well-written skill is usable only if the agent can find it and has a way to activate it.
Key terms: custom skills, SKILL.md, frontmatter description, Markdown body, output template, skill directory, agent harness, discovery locations, slash syntax, description
2.5.3 Using existing agent skills
This section explains why teams reuse existing agent skills, how they find and install them, and why they must vet third-party skills before use.
- Benefits of skill reuse: Explain how adopting pre-built agent skills saves teams from writing every procedure from scratch and provides standardized workflows for recurring tasks.
Why it matters: Reusable skills let teams spend less time rebuilding common procedures. - Skill discovery and installation: Describe where teams can find community-maintained skills and how dedicated CLI utilities help add them to local workspaces.
Why it matters: Knowing the available discovery and installation routes makes reuse practical. - Third-party skill vetting: Justify security checks before adding an unfamiliar skill to a workspace, and state what teams should inspect.
Why it matters: A convenient third-party skill can also change what an agent does or runs.
Key terms: pre-built agent skills, standardized workflows, curated catalogs, registries, CLI utilities, project-aware installer, third-party skills, external software dependencies, SKILL.md, tool permissions
2.5.4 Creating custom instruction artifacts
Shows how to share project instructions across coding agents and test whether they follow the same guidance.
- Portable project instruction setup: Describe how a repository-root AGENTS.md provides shared rules to coding agents, and distinguish native discovery from Claude Code’s adapter approach.
Why it matters: One shared file can keep project rules consistent without requiring every agent to use the same instruction-file format. - Cross-agent instruction verification: Explain how to test the artifact with the same coding task across agents and what behavior indicates that the project rules were followed.
Why it matters: Comparing responses to one task checks whether the shared guidance influences each agent’s work. - Roles of instruction layers: Distinguish the roles of system prompts, skills, and project instruction artifacts in controlling an agent’s behavior.
Why it matters: The distinction clarifies why this exercise stores repository rules in a project artifact rather than treating all instructions alike.
Key terms: AGENTS.md, CLAUDE.md, adapter, @path/to/file, project guidance, validation commands, repository rules, system prompts, skills, instruction artifacts
2.6 Summary
Where this is used later
- Context selection (chapter 7) · Develops selection of material for context.
- CLI with an agent skill (chapter 4) · Assumes familiarity with an agent skill as a reusable instruction artifact.
- Agent skills for the SDLC (chapter 11) · The earlier discussion of designing agent skills.
- CLI tools in agent skills (chapter 4) · Provides the rationale for using executable tools within agent skills.
- Context orchestration (chapter 7) · Structured outputs support passing useful context between coordinated actions.
- Context as code (chapter 9) · Develops the context-as-code discipline mentioned for versioned skills.
- Instruction artifacts in coding agents (chapter 11) · Introduces instruction artifacts in coding agents.
- Cursor with instructions (chapter 11) · Instruction artifacts in coding agents
Concepts explained in this chapter
- agent skillA reusable set of instructions and resources that extends an agent's capabilities for a specialized workflow.
- instruction fileA project-specific document or configuration that gives operational instructions to an AI agent.
- AGENTS.mdA portable Markdown file that provides project-specific instructions for AI coding agents.
- SKILL.mdA Markdown file that defines an agent skill's metadata and procedural instructions.
- instructionA directive supplied to an AI system that specifies desired behavior, constraints, or task requirements.
- demonstrationA demonstration supplied in a model's context to guide its response to a task.
- context rotContext rot is degradation in the usefulness of accumulated context as a task evolves and its information loses relevance, structure, or priority.
- context-as-codeAn approach that treats persistent instructions for AI agents as maintainable engineering artifacts.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
