Customize Copilot for your project

This quickstart walks you through customizing GitHub Copilot for a repository. By the end, Copilot will know your project's conventions, have a specialized agent for common tasks, and have curated project context.

Scenario: You work on a team's web application repository with an established test suite, coding conventions, and active issues. You want Copilot to work effectively with the codebase from day one.

Prerequisites

• Any paid Copilot plan. For more information, see AUTOTITLE.
• Cloud agent enabled for your organization or account. For more information, see AUTOTITLE.
• Write access to a GitHub repository.

Step 1: Teach Copilot your project's conventions

Repository custom instructions give Copilot persistent context about your project—its structure, coding standards, and how to build and test code. Every Copilot interaction in the repository uses these instructions automatically.

Ask Copilot cloud agent to generate a copilot-instructions.md file:

1. Go to github.com/copilot/agents.

2. Select your repository from the dropdown menu in the prompt field.

3. Enter the following prompt:

   Onboard this repository to Copilot cloud agent by adding a
   .github/copilot-instructions.md file. Include information about project
   structure, coding conventions, the test framework, and how to build and
   run the project.

4. Review the generated file and merge the pull request.

Copilot now understands your project's conventions across chat, code review, and agent sessions. See AUTOTITLE.

Step 2: Create a specialized agent

Custom agents let you create focused assistants for recurring tasks. In this example, create an agent that diagnoses and fixes bugs.

1. Go to github.com/copilot/agents and select your repository.

2. In the prompt field, click Select a custom agent. Then click Plus button Create a custom agent.

3. Rename the file to bug-fixer.agent.md.

4. Replace the template content with:

   ---
   name: Bug Fixer
   description: Diagnoses and fixes bugs reported in GitHub issues.
   tools:
     - read
     - edit
     - terminal
     - search
   ---
   
   You are a bug-fixing specialist. When given a bug report or issue:
   
   1. Reproduce the bug by writing a failing test.
   2. Identify the root cause.
   3. Fix the code.
   4. Verify the fix passes the test and doesn't break existing tests.
   
   Always follow the project's testing conventions and coding standards.

5. Commit the file and merge it into the default branch.

Your bug-fixer agent now appears in the agents dropdown on the agents tab. Select it before pasting an issue URL to start a focused debugging session. See AUTOTITLE.

Step 3: Organize project context with a space

Copilot Spaces let you curate the exact context Copilot needs for a specific area of your project. Answers are grounded in relevant files, issues, and documentation.

1. Go to github.com/copilot/spaces and click Create space.
2. Name the space (for example, "API Architecture") and choose an owner.
3. Click plus Add sources, then add context that's relevant to your project:
   • file-code Add files and repositories — Add architecture docs, API schemas, or key configuration files.
   • link Link files, pull requests, and issues — Paste URLs for active issues or design discussions.
4. In the space's chat, ask a question like: "What patterns does our API use for error handling?"

Copilot answers using only the context you've curated. See AUTOTITLE.

Next steps

• AUTOTITLE — Set personal preferences that apply across all your repositories.
• AUTOTITLE — Add new capabilities to your agents.
• AUTOTITLE — Configure repository MCP servers used by Copilot cloud agent and Copilot code review.
• AUTOTITLE — Share your spaces with teammates.