📢 Just a Heads Up

I’ve started sharing these at work as well, so what you’re seeing here is the more relaxed, public-friendly, and slightly filtered version. Just keeping it transparent!

Hey, everyone! Thanks for checking back. For those of you in the US, I hope you have a great holiday week! If you’re outside the US, enjoy the week and celebrate something fun in your own style! 🥳🎇

This is a to-date collection of everything I’ve learned about custom instructions for GitHub Copilot — whether at the personal level, inside a repository, or across an entire organization.

If you've ever wished Copilot could "just get better at xyz," instructions are how you teach it your version of xyz.

This is your chance to tell Copilot exactly what behaviors you require given a user, repository, or organization in context (or a combination of each). It's 100% up to you how strict or lenient you want to be.

🧭 Where These Tips Apply

This guide assumes you're using VS Code Insiders, where the instruction functionality is most advanced. If you’re not using it yet… well, I’ll try to convert you later 😄

Regardless of IDE, you should always take advantage of repo-level instructions, which work anywhere Copilot is enabled — including GitHub.com.

📈 I saw a post somewhere that GitHub recently started supporting user-level instructions outside of VS Code. You'll have to pull that one yourself, though - I've never tried it!

✨ Three Layers of Copilot Instructions

In order of priority (highest wins, sort of - this gets a bit tricky):

1. User-Specific Instructions – What you personally want from Copilot
2. Repo-Level Instructions – Shared expectations for a specific codebase
3. Org-Level Instructions – Global standards across an entire org

⚠️ These do not behave like you expect them to and since Copilot is non-deterministic by design, it's also not supposed to.

📚 There's a ton of theory at play here (among other things), but I'll save you the specifics (unless you ask for them - then, game on!)

👉 The problem

Knowing how a million other things handle this exact same sort of priority-driven criteria, it would make sense that if user instructions exist, then they always take precedence over anything else that's defined. Likewise, repo-specific instructions would override org ones.

• SPOILER: That's NOT what happens!

What really happens is that anything Copilot has in context is fair game, including custom instructions from ANY source. There's no built in

instruction.user = fileA;
instruction.repo = fileB;

You simply get

fileA && fileB;

🐰 There are some advanced things you can do to help route these so they're only applied if a corresponding glob is in context, but that's beyond the scope of this post. The over-simplified term is yaml front-matter, which should be enough to find the rabbit hole on your own 😉

In reality, if repo-instructions tell Copilot to "output all examples in Python" and the same Chat session contains user-instructions asking for "output in Javascript only", then Copilot just gets confused. Sometimes, it can do a decent job of using it's context to pick the appropriate one, but it's just as likely to ignore both and pick it's own path instead (again I stress, this is by design).

Ultimately, it's your responsibility to make sure that Copilot only receives instructions it can confidently and repeatedly act on. If at any point that changes, then update the instructions, too.

👤 User Instructions: Tailor It to You

Now that we're all on the same page with how the instructions work for GitHub Copilot, let's talk about the most common types.

Personal or user-level instructions are a somewhat new concept and prior to a few months ago, it was nearly impossible to access these outside of VS Code at all.

This is where you define preferences that (you guessed it) only apply to you. For example:

  - Always use Java in code examples
  - Keep responses under 100 characters
  - Only communicate in Hindi

⚠️ Copilot can respond in different languages, but its main training set is English. Some users report mixed results with non-English output.

I’m monolingual, so I can’t personally speak to non-English accuracy, but I’d love to hear your experiences! Comment below if you’ve used Copilot in other languages - let us know if there’s any validity to those claims.

🌟 User Instructions - Pro Tips:

Unless there's just something that makes you want to strangle Copilot every time you see it (besides the hallucinations, which we all put up with sometimes), then I recommend you skip these completely. It's really not worth the potential conflict you'll expose yourself to by setting them up.

This is not the right time to write up every tiny thing you can think of, submit a 100-line file, and forget about it. If you want to do that, then look into the Model Playground or even attach it to Copilot's Chat context as a one-time upload.

If, like me, you can get stuck on the small details, these might be worth the trade-off for your own workflow sanity.

You can mitigate risk by keeping user instructions limited to only enough keywords to specifically define your direction and never define more than 3 lines.

Be sure to define your desired output with examples to get the most out of Copilot in any of it's forms!

💡 TL;DR:

If you decide personal instructions are worth the risk, start with a maximum of 2–3 high impact rules. Any more than that and Copilot can start to get confused, especially in long running chats!

🍭 Real examples from my personal settings:

"github.copilot.chat.codeGeneration.instructions": [
  { "text": "Keep conversations short: when you respond in the chat, limit output to one sentence (unless explicitly asked to explain with details)." },
  { "text": "If a task violates standards or design, STOP IMMEDIATELY and analyze your context methodically to identify the problem. Once the primary concern is identified, list it along with any related bugs and suggestions to improve or remediate completely." },
  { "text": "Include emojis in chat to keep responses fun (never in code, comments, or docs) 😊👍" }
]

🛠️ Repo-Level Instructions: The Real Power Move

These have a permanent home in your repo’s .github/copilot-instructions.md file and can help drive consistency in Copilot's behavior for that specific codebase, regardless of IDE or user.

They help with:

• Consistency across features
• Smarter code suggestions
• Tailored code reviews
• Prompted documentation generation (yes, it can work!)

🧚‍♀️ Example Use Cases

‼️ This is another place where yaml front-matter in conjunction with specifying the right glob pattern is worth the research investment and time to set up. I don't have a good playground for this scenario without building it from scratch, so I'm not much help here.

🎨 Code Styles – The Rule of Examples

Copilot doesn’t handle formatting rules well without explicit examples. So if you insist on defining code style, give it at least two clear DO THIS/NOT THIS patterns.

Personally, I recommend skipping the styles section altogether in favor of a dependable linter + formatter. Spend that time on a tested and reliable solution instead. Bonus - you'll eliminate those PRs that always pop up with newly added/removed commas on all 10k+ lines of code because somebody's preferences got in the way of progress.

Instead of listing every style you can think of and then add another 3x lines on top of that for examples required to make a difference, this approach makes covering styles really straightforward:

## Code Style
Follow rules in `.eslintrc.js`

Better yet? Enforce it with pre-commit hooks. Let automation do the heavy lifting and leave Copilot out of it.

⚠️ One exception is worth a mention: If Copilot starts consistently violating a couple of things in your style guide, even though it's all strictly enforced with both linters and hooks. In this case, it is helpful to define temporary style examples in the instructions file. Leave them there only long enough until Copilot's behavior corrects itself. Then remove them.

Example repo-instructions:

💫 This was inspired by an early-stage hack-time project of mine — still hoping to bring it to life soon! 😜

# GitHub Copilot Instructions for Hack Time Project

## Goals for this app
- This app is an extension for GitHub Copilot that helps users create custom repository-level instructions.
- The instructions should be comprehensive and clear, guiding GitHub Copilot to the best practices for all developers.
- Users should have an interactive experience to generate and refine instructions.
- Instructions should be adaptable to different repositories, scenarios, and user needs.
- You have the flexibility to adjust the content based on the repository in context and the user's requirements.

## Copilot Persona
- You are a helpful assistant that guides users through creating comprehensive repository instructions.
- Provide suggestions based on repository context and user input.
- Ensure generated instructions are clear, concise, and actionable.
- Adapt to user feedback and refine instructions iteratively.
- If the user expresses they are finished in any way, you should IMMEDIATELY use all information to define output instructions and a final assessment of their effectiveness, along with recommendations for future improvements.
- ALWAYS ask the user if there is anything else they would like to add or modify before closing the interaction.

## Technology Stack
- Node.js v24.2.0 (ES6 modules enabled via `"type": "module"`)
- npm v11.3.0
- Express v5.1.0

## Development Guidelines
- Volta manages Node.js and npm versions.
- All code should be written in JavaScript (ES6+).
- Run `npm lint` and `npm format` to check code quality.
- Use `npm test` to run tests.
- Dotenv is used for environment variables, DO NOT TOUCH `.env` files.
- Avoid modifying dotfiles or configuration files unless you have explicit instructions.

## Testing Guidelines
- Use Vitest for unit tests and all mock scenarios.
- Use a TDD approach to ensure all features are tested before implementation.
- Place tests in the `tests` directory, mirroring the `src` structure.
- NEVER skip tests - broken tests should be fixed immediately or removed.
- Code coverage rules are defined in `vitest.config.js` and should be strictly enforced

## Documentation Guidelines
- Use JSDoc for documenting functions and classes.
- Maintain a `README.md` file with project overview and setup instructions.
- Append `Generated by AI as directed by {input:usersFullName} on <date>` to ALL generated documentation
    - DO NOT guess or make up any users' names. Instead, prompt them for it directly.
    - Documentation includes (but not limited to) Jira, Confluence, GitHub and all markdown files in this repo.

## Code Style Guidelines
- Use ESLint and Prettier for all JavaScript/TypeScript code.

## Performance Guidelines
- It is critical to maintain high performance.
- Utilize available profiling tools to identify bottlenecks.
- Optimize algorithms and data structures for efficiency.
- Avoid unnecessary computations and memory usage.

## Application Health
- This is a new hack time project, so the codebase is not yet mature.
- The code is expected to be clean, well-structured, and maintainable.
- Follow best practices for code quality and maintainability.
- NEVER assume backwards compatibility anywhere in the codebase. All refactors should be considered new development.

🏢 Org-Level Instructions (What Little I Know)

This is a newer feature for GitHub orgs — meant to enforce things like secure coding guidelines across all projects.

I haven’t had much hands-on access with these yet, but wanted to call them out as a source of potential conflicts. Watch the References section in Copilot chats — if org-instructions are active, you’ll see them there.

💻 VS Code Only: Instruction Types

VS Code Insiders (my primary playground) supports more instruction types than what is currently available in the release version of VS Code. If you don't have these yet, consider this a sneak peek (or jump on the bandwagon and download it here).

• Review Selection – Triggered by selection commands
• Code Generation – The most-used and most powerful
• Commit Message Generation – Define formats or reference tools like CommitLint
• Pull Request Descriptions – Coming into play (still testing)
• Test Generation – For TDD and beyond

💡 Pro Tip: Check in your .vscode folder to keep workspace settings consistent across your team.

🤖 Final Thought

Copilot doesn’t just “get better” on its own. It can't learn what you want (yet). But with some thoughtful instruction, you can teach it to be a better dev assistant — for you, your team, and your codebase.

🙋‍♀️ Built It? Broke It? Borrowed It?

If any of this worked for you, broke in fun ways, or just helped you write better instructions — let me know!

Better workflows are always the goal — keep sharing and supporting each other!

🚨 I got some more clarification related to premium requests, but haven't had a chance to verify it yet. If you're curious, watch the recent livestream from VS Code. I think this is the right one, but not positive. They saved any mention of it until right at the end.