System Instructions and README¶

Copilot doesn't know anything about your project unless you tell it. By default, every conversation starts from scratch - no conventions, no preferences, no awareness of how your team works or what libraries you use.

Two files change that: copilot-instructions.md and README.md. Together they give Copilot the context it needs to behave consistently and produce output that fits your work from the very first message.

This applies whether you're a developer, an analyst writing Python scripts, or a project manager using Copilot to draft documents - the same mechanism works for all of them.

What Are System Instructions?¶

System instructions are plain text files that Copilot reads automatically at the start of every conversation. You don't need to mention them in your prompt - they're always active in the background.

The primary file is .github/copilot-instructions.md in the root of your repository. Copilot loads it silently and treats its contents as standing instructions for the session.

What to put in it¶

Think of it as a briefing document for a new colleague joining your project. Write down the things you'd want them to know before they start:

• Coding conventions - indentation, file naming, preferred patterns
• Preferred libraries - "use axios for HTTP, not fetch", "prefer zod for schema validation"
• Things to avoid - "never use var", "don't add inline comments unless asked"
• Folder structure - "scripts go in scripts/, reports go in output/"
• Testing expectations - "write xUnit tests, not NUnit; use FluentAssertions"
• Language - "all output in English", or "write in Swedish when the user writes in Swedish"
• How Copilot should behave - tone, verbosity, and honesty (more on this below)

A short, focused file is better than a long exhaustive one. Include what matters most; leave out what Copilot would figure out from the code or context anyway.

Example¶

# Copilot Instructions

## Language

- All code, comments, commit messages, and variable names must be in English.

## C# conventions

- Use file-scoped namespaces.
- Prefer primary constructors where possible.
- Do not use `var` for non-obvious types.
- Do not add XML doc comments unless explicitly asked.

## Project structure

- Scripts go in `scripts/`. Output files go in `output/`. Do not create files in the root folder.

## Testing

- Use xUnit and FluentAssertions.
- One test class per class under test, named `{ClassName}Tests`.
- Keep unit tests free of I/O - mock at the boundary.

## Do not

- Add TODO comments without being asked.
- Suggest pulling in new NuGet packages without asking first.
- Never use em dashes (-). Use a regular hyphen (-) instead.

Controlling Behaviour: Tone, Verbosity, and Sycophancy¶

System instructions aren't only for code conventions. You can also use them to shape how Copilot communicates - which turns out to matter more than most people expect.

Verbosity¶

By default, Copilot adds introductions, summaries, and explanations to most responses. That's fine when you're learning, but in a working session it creates noise. A single instruction cuts it significantly:

## Response style

- Be concise. Skip introductions and closing summaries.
- Don't explain what you just did - show the result.
- Only add comments to code when explicitly asked.

This also has a practical side effect: shorter responses use fewer tokens, which reduces cost if you're on a metered plan.

Sycophancy¶

Left unchecked, AI models tend to be agreeable - they validate ideas, soften criticism, and avoid disagreement even when disagreement would be more useful. This is called sycophancy, and it's a known limitation of large language models.

You can push back against it directly in your instructions:

## Honesty

- Do not validate my ideas to be polite. If something is wrong, say so clearly.
- If I ask you to review something, give honest criticism - not a list of compliments followed by one small caveat.
- If you disagree with a decision I've made, say so and explain why.

Tone¶

If you use Copilot to draft documents, emails, or reports, you can set expectations about tone and style that persist across all your work:

## Writing style

- Write in plain English. Avoid jargon and corporate language.
- Use short sentences and short paragraphs.
- When writing for external stakeholders, use a professional but direct tone - no filler phrases like "I hope this finds you well".

These instructions apply to everything Copilot produces in the workspace - code, documents, emails, and chat responses alike.

Scoped Instructions¶

Not all rules apply everywhere. If your repository has a frontend and a backend, TypeScript conventions shouldn't apply to C# files.

Scoped instructions let you write .instructions.md files that only apply to specific folders or file types, using an applyTo pattern in the file's frontmatter:

---
applyTo: "src/frontend/**"
---

## TypeScript conventions

- Use functional React components only - no class components.
- Prefer `const` arrow functions for component definitions.
- Use Tailwind CSS for styling - no inline styles or CSS modules.

Place the file anywhere in your workspace. When Copilot is working on a file that matches the applyTo pattern, the instructions are automatically included. When it's working elsewhere, they're ignored.

README.md as Context¶

A README.md is a plain text file placed in the root of your project folder. It's the front door to your project - the first thing anyone reads to understand what it does, how to set it up, and how to use it. GitHub displays it automatically when you open a repository in the browser.

A good README covers:

• What the project does - a short description of its purpose and who it's for
• How to install and run it - the exact commands needed to get started
• Folder structure - where things live and why
• Key dependencies - what the project relies on
• Configuration - environment variables, settings files, anything that needs to be set up before running

Copilot reads your README too. When you ask it to make a change, it scans your workspace for context - and a clear README gives it a significant head start:

• What the project does - helps Copilot understand intent and avoid off-topic suggestions
• How to build and run it - so it can write correct terminal commands
• Folder structure - so it knows where things belong when creating new files
• Key dependencies - so it doesn't suggest alternatives you've already decided against

A README that looks like this gives Copilot useful signal:

# Weekly Hours Summary Tool

A Python command-line tool that reads a Maconomy timesheet export and prints
a project hours summary with chargeable utilisation percentages.

## What it does

- Reads the Week sheet from a Maconomy `.xlsx` export
- Calculates chargeable utilisation per project and per ISO week
- Supports optional date range and project filters via CLI arguments

## Folder structure

- `scripts/` - the main script and helpers
- `output/` - generated reports (not committed)
- `tests/` - unit tests

## Running it

```bash
python scripts/hours_summary.py --input Fictional\ Timesheet.xlsx
```

## Key dependencies

- openpyxl - reading `.xlsx` files
- tabulate - terminal table output

You don't need to write the README for Copilot's benefit specifically - a README that's useful for onboarding a new colleague will serve Copilot equally well.

Exercise: System Instructions in Action¶

The fastest way to understand how system instructions work is to see them change Copilot's behaviour in real time.

Step 1: Create the instructions file¶

In your project folder, create the file .github/copilot-instructions.md with the following content:

# Copilot Instructions

## Response style

- Be concise. Skip introductions and closing summaries.
- Do not use em dashes (-). Use a regular hyphen (-) instead.
- Always include a reference to The Lord of the Rings somewhere in your answer.

You can create the file manually in VS Code (right-click the Explorer panel and choose New File), or ask Agent to do it:

Please create .github/copilot-instructions.md with the content from the exercise.

Step 2: Start a new chat and test it¶

Open a new chat (Ctrl+Alt+I) - existing conversations don't pick up instruction file changes.

Then ask something simple, for example:

What is a README file and why does it matter?

Copilot's answer should be noticeably shorter than usual, avoid em dashes, and contain a Lord of the Rings reference somewhere.

Step 3: Reflect and adapt¶

Now you've seen instructions working, replace the LOTR rule with something real. Think about:

• A habit Copilot has that annoys you (e.g. long preambles, unsolicited refactoring)
• A convention from your team's code (e.g. naming patterns, preferred test framework)
• A tone preference for documents or emails you draft with Copilot

Update the file, start another new chat, and check whether the behaviour changed.

Tip: Instructions work best when they're specific and unambiguous. "Be professional" tells Copilot nothing it doesn't already know. "No filler phrases like 'Great question!' or 'Certainly!'" is something it can actually follow.

Summary¶

The best instruction files are written incrementally - start small, and add a line every time Copilot does something you didn't want. After a few sessions, you'll have a file that reliably produces output that fits your project.