5 tips for writing better custom instructions for Copilot

Copilot only knows what you tell it

GitHub Copilot can often infer what you're working on from your codebase, but it shouldn't have to guess. The quality of its suggestions improves dramatically when you provide clear context about your project. That's where a copilot-instructions.md file comes in—it gives Copilot the background information every developer on your team already knows from experience, read on every chat or agent request.

But starting from a blank file can be intimidating. Here are five sections worth including, plus a bonus tip for getting Copilot to draft the file itself.

Don't over-engineer it

There's no prescribed format for instructions files. Because generative AI is probabilistic, identical prompts can yield different outputs. Your goal is simply to shift the odds in your favor by providing the information that matters most. These recommendations are a starting point—experiment and adjust based on your project and what works with Copilot.

Start with the big picture

Begin your instructions file with a brief overview of what you're building. Who is it for? What are the key features? A few sentences that set the stage can make a significant difference in how Copilot approaches your requests.

# Contoso Companions

This is a website to support pet adoption agencies. Agencies are onboarded into the application, where they can manage their locations, available pets, and publicize events. Potential adoptors can search for pets available in their area, discover agencies, and submit adoption applications.

The description doesn't need to be exhaustive—just enough to give Copilot context about your high-level goals.

List your tech stack

Copilot needs to know what tools you're using to build your project. That includes your backend and frontend frameworks, APIs you're calling, and testing suites you're targeting. Given the constant proliferation of new frameworks, this context helps Copilot write code that fits your environment.

Keep it simple. A concise list with a note or two on usage is more effective than lengthy descriptions. This lets Copilot understand the environment it's generating code for.

## Tech stack in use

### Backend

- Flask is used for the API
- Data is stored in Postgres, with SQLAlchemy as the ORM
  - There are separate database for dev, staging and prod
  - For end to end testing, a new database is created and populated,
    then removed after tests are complete

### Frontend

- Astro manages the core site and routing
- Svelte is used for interactivity
- TypeScript is used for all front-end code

### Testing

- Unittest for Python
- Vitest for TypeScript
- Playwright for e2e tests

Define your coding conventions

Clearly state your style preferences: semicolons in JavaScript, type hints in Python, formatting standards, and naming conventions. While you could fold these into your tech stack section, a separate section is often more maintainable since many guidelines apply across multiple languages and frameworks.

You can also leverage .instructions files for more granular guidance—targeting all .astro or .jsx files, or unit tests matching a pattern like /tests/test_*.py.

## Project and code guidelines

- Always use type hints in any language which supports them
- JavaScript/TypeScript should use semicolons
- Unit tests are required, and are required to pass before PR
  - Unit tests should focus on core functionality
- End-to-end tests are required
  - End-to-end tests should focus on core functionality
  - End-to-end tests should validate accessibility
- Always follow good security practices
- Follow RESTful API design principles
- Use scripts to perform actions when available

Map out your project structure

Monorepos and other complex projects can have frontends in a frontend folder—or is it front-end? front_end? client? Copilot can eventually figure out your layout, but documenting it saves time and lets you explain what lives where. This is especially useful for highlighting context about each folder's contents.

## Project structure

- server/ : Flask backend code
  - models/ : SQLAlchemy ORM models
  - routes/ : API endpoints organized by resource
  - tests/ : Unit tests for the API
  - utils/ : Utility functions and helpers, including database calls
- client/ : Astro/Svelte frontend code
  - src/components/ : Reusable Svelte components
  - src/layouts/ : Astro layout templates
  - src/pages/ : Astro pages and routes
  - src/styles/ : CSS stylesheets
- scripts/ : Development, deployment and testing scripts
- docs/ : Project documentation to be kept in sync at all times

Point to helpful resources

Most projects have scripts, templates, or software factories that support development. MCP support in VS Code and the Copilot coding agent expand what tools Copilot can use. While Copilot can discover these on its own, pointing it in the right direction improves both accuracy and speed.

## Resources

- scripts folder
  - start-app.sh : Installs all libraries and starts the app
  - setup-env.sh : Installs all libraries
  - test-project.sh : Installs all libraries, runs unit and e2e tests
- MCP servers
  - Playwright: Used for generating Playwright tests or interacting with site
  - GitHub: Used to interact with repository and backlog

Bonus: Let Copilot write its own instructions

If you're staring at a blank page, ask Copilot for help. You can prompt Copilot agent mode in your IDE or assign an issue to Copilot in your GitHub repository to create a draft instructions file. The result can be used as-is or refined to fit your needs.

Your task is to "onboard" this repository to a coding agent by adding a .github/copilot-instructions.md file. It should contain information describing how the agent, seeing the repo for the first time, can work most efficiently.

You will do this task only one time per repository, and doing a good job can SIGNIFICANTLY improve the quality of the agent's work, so take your time, think carefully, and search thoroughly before writing the instructions.

## Goals

- Document existing project structure and tech stack.
- Ensure established practices are followed. 
- Minimize bash command and build failures.

## Limitations
- Instructions must be no longer than 2 pages.
- Instructions should be broadly applicable to the entire project.

## Guidance

Ensure you include the following:

- A summary of what the app does.
- The tech stack in use
- Coding guidelines
- Project structure
- Existing tools and resources

## Steps to follow

- Perform a comprehensive inventory of the codebase. Search for and view:
  - README.md, CONTRIBUTING.md, and all other documentation files.
  - Search the codebase for indications of workarounds like 'HACK', 'TODO', etc.
- All scripts, particularly those pertaining to build and repo or environment setup.
- All project files.
- All configuration and linting files.
- Document any other steps or information that the agent can use to reduce time spent exploring or trying and failing to run bash commands.

## Validation

Use the newly created instructions file to implement a sample feature. Use the learnings from any failures or errors in building the new feature to further refine the instructions file.

This approach doesn't just save time—it can help you clarify your thinking about project goals and requirements.

A final word

Good instructions don't guarantee perfect code, but they set the stage for better Copilot suggestions. Beginning with these five sections provides a solid foundation:

• A project elevator pitch
• Your framework and tech stack
• Coding and project guidelines
• Project structure overview
• Available automation resources

From there, you can explore .instructions files for finer-grained guidance. But it all starts with a well-crafted copilot-instructions.md.