How to Write Copilot Agent Instructions (w/Examples) + FAQs

Yes — you write Copilot agent instructions by giving the AI a clear role, a step-by-step workflow, strict response rules, named tools, and concrete examples, all stored in a system prompt or a copilot-instructions.md file. That single block of text is the brain of your agent. It tells the model who it is, what it can touch, how it should answer, and what it must never do.

The problem most makers run into is this: they treat instructions like a casual chat message. They write “be helpful and answer HR questions” and then wonder why the agent hallucinates, ignores tools, or leaks sensitive data. Microsoft’s own guidance on writing agent instructions and GitHub’s custom instructions docs both make the same point — vague prompts produce vague agents, and the consequence is real: wrong answers shipped to real users, broken tool calls, and trust erosion across your team.

A 2025 GitHub developer survey cited in the official 5 tips for writing better custom instructions post found that repositories with a well-formed .github/copilot-instructions.md file saw measurably higher acceptance rates on Copilot suggestions, with some teams reporting 30%+ fewer “throwaway” completions. That is the difference between an agent that helps and an agent that interrupts.

Here is what you will learn in this guide:

• 🧠 How to structure an instruction file that the model actually follows
• 🛠️ How to wire instructions to tools, knowledge, and connectors without breakage
• 🧪 Real, copy-ready examples for Copilot Studio, Microsoft 365, and GitHub Copilot
• ⚠️ The seven mistakes that quietly kill agent quality
• ✅ A do’s and don’ts checklist plus a pros and cons breakdown for each platform

What “Copilot Agent Instructions” Actually Mean

Copilot agent instructions are the natural-language system prompt that shapes every response your agent produces. In Microsoft Copilot Studio, you enter them in the Instructions field on the agent’s Overview page, as described in the Copilot Studio authoring instructions reference. In Microsoft 365, declarative agents store the same text in the instructions property of the declarative agent manifest. In GitHub Copilot, the equivalent lives in a markdown file called .github/copilot-instructions.md at the root of your repo, per the GitHub custom instructions guide.

The instructions sit above the user message in the model’s context. They are read first. They are weighted heavily. The plain-English explanation is simple: they are your agent’s job description, employee handbook, and escalation policy rolled into one document.

The consequence of writing them poorly is severe. The agent will guess. It will invent tools that do not exist. It will answer questions it should refuse. A common misconception is that adding more knowledge sources fixes a weak prompt. It does not. As the generative orchestration guidance explains, the model uses your instructions to decide which tool to call and when, so a fuzzy instruction set means the agent will skip the right tool entirely.

A real-world example: a finance team at a mid-size firm built an expense-policy agent and wrote “answer questions about expenses.” The agent happily answered tax questions outside its scope. After they rewrote the instructions to scope the agent to the company’s expense policy PDF and refuse off-topic questions, refusal accuracy jumped from roughly 40% to over 90%.

The Three Layers Inside Every Good Instruction Set

Every strong instruction file has three layers stacked together. The first layer is the role and objective — one or two sentences that name the agent and state its mission. The second layer is the workflow or response rules — the step-by-step logic the agent should follow on every turn. The third layer is the guardrails — what to refuse, what to escalate, and how to format output.

Microsoft’s declarative agent instruction best practices explicitly recommend this stacking pattern, and the sample they publish uses # OBJECTIVE, # RESPONSE RULES, and # WORKFLOW headers in that exact order.

The consequence of skipping a layer is predictable. Skip the role and the agent drifts in tone. Skip the workflow and the agent forgets what step it is on during multi-turn chats. Skip the guardrails and the agent overshares.

A misconception worth killing: longer is not better. Microsoft caps Copilot Studio instructions at roughly 8,000 characters, and GitHub recommends keeping copilot-instructions.md under “two pages” per the official 5 tips post. Long, repetitive instructions actually hurt performance because the model spends its attention budget rereading filler.

Where Instructions Live by Platform

The storage location matters because it changes how your team versions, reviews, and ships changes.

The consequence of choosing the wrong location is that your changes do not apply where you expect. A team that puts coding rules in the user-level file will see those rules silently ignored when teammates open the same repo. A real example: developer Maya stored her React-style rules in her personal global file and was confused when her PR reviewer’s Copilot kept producing class components — the rules never traveled with the repo.

Step-by-Step: How to Write Your First Instruction Set

The cleanest way to write instructions is to follow a fixed five-step process every time. Skip steps and you will rewrite the file three times. Microsoft’s declarative agent best practices page frames this as an “iterative refinement loop,” and the same loop applies whether you build in Copilot Studio, Microsoft 365, or GitHub.

Step 1: Name the Agent and Its One Job

Start with one sentence that says who the agent is and what single outcome it owns. Bad: “You help with HR.” Good: “You are the Acme HR Benefits Assistant. Your job is to answer benefits questions using the 2026 Acme Benefits Guide and to escalate anything outside benefits to a human HR partner.”

The plain-English reason this matters is that the model uses the role line to set tone, vocabulary, and refusal behavior. The consequence of a vague role is tone drift across turns — the agent sounds like a lawyer in turn one and a chatbot in turn three.

A real example: developer Priya named her agent “Code Reviewer Bot” and added “you review TypeScript pull requests at Acme using our eslint.config.js rules.” Reviewers immediately noticed the agent stopped suggesting deprecated React patterns because the role anchored it to the repo’s actual config.

A common misconception is that the role line should be flowery. It should not. One sentence. One job.

Step 2: List the Tools, Knowledge, and Connectors by Name

Your agent cannot use a tool it does not know exists. List every tool, knowledge source, and connector by its exact name inside the instructions, and tell the agent when to use each one. The generative orchestration guidance is explicit: “use the description to indicate what not to do” so the agent does not call the wrong tool at the wrong moment.

The consequence of skipping this is the dreaded “I cannot help with that” loop, where the agent refuses tasks it actually has the tools to perform. A real example: marketer Daniel built an agent with a SharePoint connector but never named the SharePoint site in the instructions. The agent kept telling users it had no access to marketing assets even though the connector was wired and live.

A misconception: you do not need to repeat tool schemas. The platform handles schemas. You only need to tell the agent the tool’s name and purpose in plain English.

Step 3: Write the Workflow as Numbered Steps

Spell out the happy path as a numbered list. Use precise verbs — “ask,” “search,” “send,” “check,” “use” — exactly as Microsoft recommends in the declarative agent instructions guide. For each step, name the goal, the action, and the transition to the next step.

The consequence of skipping numbered steps is that the agent collapses multi-turn flows into one giant answer. Users get walls of text instead of a guided conversation. A real example: support lead Marcus rewrote his triage agent into four numbered steps (gather details, check outages, narrow resolution, create ticket) and average handle time dropped 22% in the first week.

A misconception: workflows are only for support agents. Even a “summarize this document” agent benefits from a two-step flow (“ask for the document, then summarize in five bullets”). Structure beats vibes.

Step 4: Add Response Rules and Output Formatting

Tell the agent how to talk. Specify length, tone, format, and refusal language. The published Microsoft Learn ITSM example uses rules like “ask one clarifying question at a time,” “present information as concise bullet points or tables,” and “always confirm before moving to the next step.”

The consequence of vague formatting rules is unreadable answers. A real example: analyst Lin added “respond in tables when comparing two or more items, otherwise use bullets capped at five items” and her stakeholders stopped asking her to “make it shorter.”

A misconception: you can rely on the model’s defaults. You cannot. Defaults change between model versions, and your formatting will silently drift on the next platform update.

Step 5: Test, Iterate, and Version

Test your agent with at least ten realistic prompts, including off-topic and adversarial ones. Save each prompt and the agent’s response. When you change instructions, rerun the same prompts and diff the answers. Both the Copilot Studio authoring docs and the GitHub custom instructions docs recommend storing instruction changes in source control.

The consequence of skipping testing is regressions. A real example: a fintech team shipped a “small wording tweak” that flipped their refusal behavior from polite redirect to flat “no,” and customer satisfaction dropped two points before they noticed.

A misconception: testing is one-and-done. It is not. Every model upgrade, knowledge source change, or new connector is a regression risk.

Three Real Scenarios with Full Instruction Examples

These three scenarios are the most popular shapes I see in production agents in 2026. Each table maps the user request to what the agent must do given the instructions.

Scenario 1: HR Benefits Assistant in Copilot Studio

# ROLE
You are the Acme HR Benefits Assistant. You answer benefits questions for Acme employees using the 2026 Benefits Guide.

# KNOWLEDGE
- "2026 Acme Benefits Guide" (SharePoint)
- "Open Enrollment FAQ" (SharePoint)

# RESPONSE RULES
- Answer only benefits questions. For payroll, performance, or hiring, reply: "That is outside benefits. Please contact your HR partner."
- Cite the section title from the Benefits Guide in every answer.
- Cap answers at 120 words.

# WORKFLOW
1. If the question is about benefits, search the Benefits Guide first.
2. If the Guide does not contain the answer, search the Open Enrollment FAQ.
3. If neither has the answer, reply: "I do not have that detail. Please email [email protected]."

Scenario 2: Declarative Agent for IT Support in Microsoft 365

This pattern follows the published Microsoft Learn ITSM example and uses ServiceNow as the system of record.

Scenario 3: GitHub Copilot Coding Agent for a Next.js Repo

A .github/copilot-instructions.md file for a Next.js app following the patterns in the first custom instructions tutorial:

# Project
Acme Storefront — a Next.js 15 App Router app written in TypeScript.

# Stack
- Next.js 15, React 19, TypeScript 5
- Tailwind CSS v4, shadcn/ui
- Drizzle ORM with PostgreSQL
- Vitest for unit tests, Playwright for e2e

# Coding rules
- Use server components by default; mark client components with "use client".
- Validate all inputs with Zod schemas in /lib/validators.
- Never import from "src/legacy/**".
- Tests live next to source as *.test.ts.

# Commands
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
- Lint: pnpm lint

Mistakes to Avoid

These are the seven mistakes I see most often, drawn from Microsoft’s Copilot Studio guidance and the GitHub 5 tips post.

• Writing in negatives only. “Do not be rude. Do not hallucinate.” gives the model nothing to do. Always pair every “don’t” with a “do.”
• Stacking knowledge without scoping. Adding ten SharePoint sites without telling the agent which to use first creates retrieval chaos and slow answers.
• Forgetting refusal language. Without an exact refusal sentence, the agent invents one, and the tone drifts off-brand.
• Hardcoding dates that age out. “As of 2024” inside instructions ages badly. Use “as of the current plan year” and let the knowledge source carry the date.
• One giant paragraph. Walls of text reduce instruction-following accuracy. Use headers and numbered steps.
• No examples. Models learn from one or two short examples faster than from ten rules. Always include at least one input/output pair.
• Skipping version control. Instructions are code. Store them in Git, review changes in PRs, and roll back when something breaks.

Do’s and Don’ts

• Do start with a one-sentence role line that names the agent and its single job.
• Do name every tool and knowledge source by its exact title so the orchestrator can route correctly.
• Do use precise action verbs like “ask,” “search,” “send,” “check,” and “use” as Microsoft recommends.
• Do include a refusal sentence the agent must use word-for-word for out-of-scope requests.

• Do keep the file under two pages or roughly 8,000 characters so attention is not wasted.

• Don’t rely on the model’s defaults for tone, length, or format — they shift between versions.

• Don’t mix instructions for two different agents in one file; split them into separate manifests.
• Don’t paste full policy documents into the instructions; load them as knowledge instead.
• Don’t use vague verbs like “help,” “handle,” or “deal with” — they invite drift.
• Don’t ship instruction changes without rerunning your saved test prompts.

Pros and Cons of Each Copilot Platform for Instruction Authoring

• Pro: Copilot Studio’s generative orchestration auto-picks tools when descriptions are sharp.
• Pro: GitHub’s copilot-instructions.md is plain markdown — no special syntax to learn.
• Pro: Declarative agents are distributable as Teams app packages for org-wide rollout.
• Pro: Instructions are model-agnostic — switching from one Copilot model to the next does not require a rewrite.

• Pro: A single well-written file can replace dozens of one-off prompt templates.

• Con: Each platform has its own character or page cap to respect.

• Con: Knowledge source naming differs across platforms, so copy-paste between them is risky.
• Con: Refusal behavior varies between models; you must retest after every model upgrade.
• Con: Generative orchestration can over-call tools if descriptions are too broad.
• Con: Path-specific .instructions.md files are still maturing and not supported everywhere.

Anatomy of a High-Quality Instruction File

A high-quality file has five parts in order: role, knowledge, response rules, workflow, and examples. The published Microsoft ITSM example uses exactly this skeleton.

Role

One or two sentences. Name the agent. Name its one job. Name its audience. The plain-English reason: the model uses this to set tone and refusal posture.

The consequence of a fuzzy role is tone drift. A real example: support engineer Carla wrote “you are a friendly assistant” and the agent kept signing off with “xoxo.” Rewriting the role to “you are the Acme Tier-1 support agent for enterprise customers” fixed it instantly.

A misconception is that the role should describe the model. It should not. It should describe the agent.

Knowledge

List every knowledge source by exact name and say when to use each. Microsoft’s generative orchestration guidance calls this out as the single biggest lever for retrieval quality.

The consequence of unscoped knowledge is the agent reading the wrong document and citing it confidently. A real example: PM Jin had two SharePoint sites — one for product specs and one for marketing copy — and the agent kept quoting marketing in technical answers until she scoped each by topic.

Response Rules

Specify length, tone, format, citation style, and refusal language. The misconception that “the model knows” is wrong; you must spell it out.

Workflow

Numbered steps with goal, action, and transition. The consequence of skipping numbered steps is collapsed conversations.

Examples

One or two short input/output pairs. The model imitates examples faster than it follows rules.

Iteration Loop: How to Improve Instructions Over Time

The official declarative agent instructions guide describes the loop as: design, test, observe, refine. Treat your instruction file the same way you treat production code.

Run a fixed test set after every change. Save the prompts and the answers. Diff the answers when the file changes. Roll back if quality drops. The consequence of skipping the loop is silent regression, which is the worst kind of regression because it shows up as user complaints weeks later.

A real example: at a healthcare SaaS company, the team set up a nightly job that sent 50 canned prompts to their staging Copilot Studio agent and saved the responses. When a new instruction tweak dropped refusal accuracy below 95%, the job alerted Slack and the team rolled back inside an hour.

A common misconception is that you need a fancy eval framework. You do not. A spreadsheet with prompts in column A, expected behavior in column B, and last-run output in column C is enough for most teams.

Hooking Instructions to Tools and Connectors

Instructions and tools are a two-way contract. Your instructions must name the tool, and the tool’s description must match what the instructions promise. The generative orchestration guidance is explicit: “the name and description must be accurate and specific.”

The consequence of mismatched names is the orchestrator either skipping the tool or calling it on the wrong turn. A real example: a sales team named a tool LookupAccount but described it as “search CRM for any customer record.” The agent called it for support tickets too. Renaming the tool to LookupSalesAccount and tightening the description fixed routing immediately.

A misconception is that the agent reads the tool’s underlying schema. It mostly does not — it reads the name and description. So write those two fields like marketing copy: short, specific, and unambiguous.

Security and Compliance Guardrails

Instructions are also where you encode refusal and escalation policy. For regulated industries, this matters more than the happy path.

Spell out what the agent must never reveal — for example, “never quote internal salary bands” or “never share unredacted customer PII.” Spell out the exact refusal sentence. Spell out the escalation contact. The consequence of leaving this implicit is data leakage, which in 2026 carries real fines under U.S. state privacy laws and sector regulations.

A real example: a regional bank’s Copilot Studio agent was scoped to public product info only, and the instructions included the line “if the user asks about another customer’s account, reply: ‘I cannot share account details. Please call 1-800-…’” The agent followed that script in over 99% of red-team tests.

A misconception is that compliance lives in the platform’s content filters. Filters help, but instruction-level rules are your first and most controllable layer.

FAQs

Can Copilot Studio agents read instructions longer than 8,000 characters?

No. Copilot Studio enforces a character cap on the Instructions field. If you need more, move detail into knowledge sources or split the agent into two scoped agents.

Do GitHub Copilot custom instructions apply to every editor?

Yes. Repo-wide .github/copilot-instructions.md files apply across VS Code, Visual Studio, JetBrains IDEs, and the Copilot coding agent, per the GitHub custom instructions docs.

Should I include the model name in my instructions?

No. The model can change between platform updates. Write instructions about behavior, not about the underlying model, so your file survives upgrades.

Can declarative agents call external APIs?

Yes. Declarative agents support actions defined via plugin manifests, as described in the declarative agent overview, and the instructions tell the agent when to call them.

Do path-specific .instructions.md files override repo-wide instructions?

Yes. Path-specific files with an applyTo field take precedence inside the matched paths, per the first custom instructions tutorial.

Is it okay to paste a full policy PDF into the Instructions field?

No. Load policy documents as knowledge sources and reference them by name in instructions, so retrieval can scale without bloating the prompt.

Can I use markdown formatting inside Copilot Studio instructions?

Yes. Headers, bullets, and bold text are honored and improve the agent’s instruction-following accuracy by giving the model visual structure.

Do agents follow refusal rules 100% of the time?

No. Refusal accuracy is high with explicit scripts but never absolute. Always test refusal behavior after every model or platform upgrade.

Should every agent have examples in the instructions?

Yes. One or two short input/output pairs improve consistency more than adding extra rules, and Microsoft’s declarative agent guide recommends supplementing rules with examples.

Can I version-control Copilot Studio instructions?

Yes. Export the agent as a solution and store the solution file in Git, so instruction changes flow through normal pull-request review.

Do I need separate instructions for voice and chat agents?

Yes. Voice agents need shorter sentences and explicit pause cues, while chat agents can use bullets and tables, so split the files.

Will writing instructions in another language work?

Yes. Copilot models are multilingual, but mixing languages inside one file reduces accuracy, so pick one language per agent and stick with it.