Skip to content

Copilot Custom Instructions

This skill provides comprehensive guidance for creating custom instructions that tailor GitHub Copilot's responses to your personal preferences, team workflows, project requirements, or organization standards. Custom instructions help Copilot generate higher quality, more relevant responses without needing to repeat context in every interaction.

When to Use This Skill

Use this skill when: - Setting up personal custom instructions for consistent Copilot behavior - Creating repository-wide instructions for project-specific standards - Developing organization-level instructions for company-wide preferences - Configuring path-specific instructions for different file types or directories - Optimizing Copilot responses for coding standards, frameworks, or workflows - Ensuring consistent AI assistance across team members

Prerequisites

  • Always check the latest GitHub documentation: https://docs.github.com/en/copilot/concepts/prompting/response-customization
  • Access to GitHub Copilot (Pro, Pro+, Business, or Enterprise plan)
  • Understanding of your project, team, or organization's needs
  • Knowledge of the context where instructions will be applied

Latest Information Check

IMPORTANT: Before creating any custom instructions, always check the official GitHub documentation for the latest information: https://docs.github.com/en/copilot/concepts/prompting/response-customization

Key points from the latest documentation: - Three types: Personal, Repository, and Organization instructions - Repository instructions include repository-wide, path-specific, and agent instructions - Precedence: Personal > Repository > Organization - Instructions should be short, self-contained statements - Support varies across different Copilot features and environments

Instructions

Step 1: Determine Instruction Scope and Type

  1. Identify the scope: Personal, repository, or organization level?
  2. Choose instruction type:
  3. Personal: Individual preferences on GitHub.com
  4. Repository-wide: .github/copilot-instructions.md for entire repository
  5. Path-specific: .github/instructions/NAME.instructions.md for specific paths
  6. Agent instructions: AGENTS.md, CLAUDE.md, or GEMINI.md files

  7. Organization: Organization-wide settings (owners only, Enterprise required)

  8. Assess requirements: What behaviors need to be customized?

Step 2: Analyze Context and Requirements

  1. Gather project information:
  2. Project purpose and goals
  3. Technology stack and frameworks
  4. Coding standards and conventions

  5. Team workflows and processes

  6. Identify pain points:

  7. Common Copilot suggestions that need correction
  8. Missing context that causes poor responses

  9. Inconsistent behavior across team members

  10. Define success criteria:

  11. What should Copilot always/never do?
  12. What standards must be followed?
  13. What context is always relevant?

Step 3: Structure Your Instructions

  1. Start with project overview: 

    # Project Overview
This project is a [description]. It is built using [technologies] and uses [databases/frameworks].

  2. Document folder structure: 

    ## Folder Structure
- `/src`: Contains the source code for the [component]
- `/tests`: Contains test files
- `/docs`: Contains documentation

  3. Specify coding standards: 

    ## Coding Standards
- Use [naming convention] for variables/functions
- Follow [style guide] for formatting
- Use [patterns] for [specific cases]

  4. List libraries and frameworks: 

    ## Libraries and Frameworks
- [Library] v[version] for [purpose]
- [Framework] with [configuration]

Step 4: Write Effective Instructions

Guidelines for writing instructions: - Keep statements short and self-contained - Use natural language - Focus on broadly applicable information - Avoid conflicting instructions - Test for effectiveness

Common instruction patterns: - Language preferences: Always respond in [language]. - Coding standards: Use [convention] for [element]. - Framework usage: Use [framework] with [library]. - Response style: Be clear and concise. - Context requirements: Always consider [requirement].

Step 5: Create the Instruction Files

For Repository Instructions:

  1. Repository-wide instructions:
  2. Create .github/copilot-instructions.md

  3. Include all broadly applicable instructions

  4. Path-specific instructions:

  5. Create .github/instructions/ directory
  6. Add NAME.instructions.md files (e.g., frontend.instructions.md)

  7. Use specific instructions for particular paths

  8. Agent instructions:

  9. Create AGENTS.md, CLAUDE.md, or GEMINI.md
  10. Include agent-specific customizations

For Personal Instructions:

  1. Go to Copilot Chat on GitHub.com
  2. Access the custom instructions popup
  3. Add your personal preferences

For Organization Instructions:

  1. Organization owners only (Enterprise required)
  2. Access organization Copilot settings
  3. Configure organization-wide instructions

Step 6: Test and Refine

  1. Test in different contexts:
  2. Try Copilot Chat with various queries
  3. Test in different files and scenarios

  4. Verify behavior across team members

  5. Monitor effectiveness:

  6. Check if responses follow instructions
  7. Identify areas needing clarification

  8. Gather feedback from team members

  9. Iterate and improve:

  10. Refine wording for clarity
  11. Add missing context
  12. Remove ineffective instructions

Step 7: Maintain and Update

  1. Regular review: Check instructions periodically
  2. Update with changes: Modify when project standards change
  3. Version control: Track changes to instruction files
  4. Team communication: Ensure team knows about updates

Examples

Example 1: Repository-Wide Instructions for a React Project

Create .github/copilot-instructions.md:

# Project Overview

This project is a modern web application built with React and TypeScript. It provides a task management interface for teams to collaborate on projects and track progress.

## Folder Structure

- `/src/components`: Reusable React components
- `/src/hooks`: Custom React hooks
- `/src/utils`: Utility functions and helpers
- `/src/types`: TypeScript type definitions
- `/tests`: Unit and integration tests
- `/docs`: Project documentation

## Libraries and Frameworks

- React 18 with TypeScript
- React Router for navigation
- Axios for API calls
- React Query for data fetching
- Tailwind CSS for styling
- Jest and React Testing Library for testing

## Coding Standards

- Use functional components with hooks
- Prefer custom hooks over class components
- Use TypeScript interfaces for all data structures
- Follow the single responsibility principle
- Write descriptive variable and function names
- Use early returns in functions
- Handle errors gracefully with try-catch blocks

## UI Guidelines

- Use Tailwind CSS classes for styling
- Maintain consistent spacing and typography
- Ensure responsive design for mobile and desktop
- Follow accessibility best practices (WCAG guidelines)
- Use semantic HTML elements

## API Guidelines

- Use RESTful API design principles
- Include proper error handling for API calls
- Implement loading states for async operations
- Cache data appropriately with React Query
- Validate API responses before using data

Example 2: Path-Specific Instructions for Tests

Create .github/instructions/tests.instructions.md:

# Testing Instructions

These instructions apply to all test files in the repository.

## Testing Framework

- Use Jest as the testing framework
- Use React Testing Library for component testing
- Write tests in TypeScript (.test.tsx files)

## Test Structure

- Group related tests in describe blocks
- Use descriptive test names (it should...)
- Follow the Arrange-Act-Assert pattern
- Test one behavior per test case

## Testing Best Practices

- Test component behavior, not implementation details
- Mock external dependencies (API calls, hooks)
- Test error states and edge cases
- Aim for high test coverage (>80%)
- Write integration tests for critical user flows

## Naming Conventions

- Test files: `ComponentName.test.tsx`
- Test cases: descriptive sentences
- Mock files: `ComponentName.mock.tsx`

Example 3: Personal Instructions

In Copilot Chat settings on GitHub.com:

Always respond in clear, concise English.
Explain code concepts with practical examples.
Prefer modern JavaScript/TypeScript features.
When suggesting code, include brief comments for complex logic.
Focus on readable, maintainable solutions over clever optimizations.

Example 4: Organization Instructions

For organization owners (Enterprise plan):

Always respond in English unless specifically requested otherwise.
For security-related questions, reference the company security guidelines.
Use the organization's approved coding standards.
When suggesting code, ensure it follows our accessibility requirements.
Prefer our standard technology stack unless there's a specific reason to deviate.

Best Practices

Writing Effective Instructions

  • Be specific: Use concrete examples rather than vague guidance
  • Keep it concise: Short statements are more effective than long explanations
  • Test thoroughly: Verify instructions work as intended
  • Avoid conflicts: Ensure instructions don't contradict each other
  • Update regularly: Review and update as project needs change

Repository Instructions

  • Broad applicability: Focus on information relevant to most repository interactions
  • Version control: Track instruction files in git
  • Team alignment: Ensure instructions reflect team consensus
  • Documentation: Reference instruction files in project README

Personal Instructions

  • Individual preferences: Focus on your personal workflow preferences
  • Complement repository: Don't override important project standards
  • Minimal but effective: Few high-impact instructions are better than many

Organization Instructions

  • Company standards: Enforce organization-wide policies and preferences
  • Cultural alignment: Reflect company values and communication style
  • Security first: Include security-related guidelines
  • Scalable: Work across different teams and projects

Common Issues

Issue: Copilot not following instructions Solution: Check precedence (personal > repository > organization), ensure instructions are clear and specific

Issue: Instructions too broad or conflicting Solution: Refine wording, remove contradictions, test in different contexts

Issue: Instructions not applying to certain features Solution: Check support matrix at https://docs.github.com/en/copilot/reference/custom-instructions-support

Issue: Team members getting different responses Solution: Ensure repository instructions are consistent, check for personal overrides

Issue: Instructions becoming outdated Solution: Regular review process, update when project standards change

Additional Resources

Testing Checklist

  • Instructions follow the correct file naming and location conventions
  • Content is clear, concise, and self-contained
  • Instructions don't conflict with each other
  • Tested across different Copilot features and contexts
  • Team members can access and understand the instructions
  • Instructions remain effective over time
  • Documentation updated to reference instruction files