Recommended Setup for Organization-Wide GitHub Copilot Instructions

[skrothapalli1]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

Copilot in GitHub

Body

Hi everyone, what’s the recommended way to combine GitHub Copilot Custom Instructions, organization-wide instructions/skills, and repo-level copilot-instructions.md?

Specifically, how does precedence/inheritance work, and are these supported across Copilot Code Review and Cloud Agent? Can organization-wide instructions be centralized in .github without duplicating them across repos?

[neemlama]

GitHub Copilot: Organization-Wide vs Repository Instructions

The recommended approach is additive inheritance, not replacement.

Keep common rules at the organization level so you don't have to duplicate them across every repository. Then use repository and path-specific instructions for project-specific requirements.

1. Where to put the instructions

Scope | Location -- | -- Organization-wide | Organization .github repository or Copilot Custom Instructions in Settings Repository-specific | repo/.github/copilot-instructions.md Path-specific | repo/.github/instructions/*.instructions.md Reusable prompts | repo/.github/prompts/*.prompt.md Skills | repo/.github/skills//SKILL.md

For organization-wide instructions, you can use the special .github repository:

org/.github/.github/copilot-instructions.md

This allows you to maintain common coding, security, and engineering guidelines centrally instead of copying them into every repository.

You can also configure organization custom instructions through:

Organization Settings → Copilot → Policies / Custom Instructions

Use one central method, rather than maintaining the same instructions in both places.

2. Recommended structure

For example:

org/.github/
└── .github/
    ├── copilot-instructions.md
    └── instructions/
        └── react.instructions.md
my-repo/

└── .github/

├── copilot-instructions.md

└── instructions/

└── go.instructions.md

Keep the organization-level file relatively small and focused on general principles such as:

• Security requirements

• Coding standards

• Dependency management

• Testing expectations

• General architecture principles

Put detailed or language/framework-specific rules in instructions/.instructions.md.

For example:

---

applyTo: "**/.tsx"
Use the project's existing React patterns.

Prefer reusable components.

Add tests for significant UI behavior.

3. How inheritance works

The important point is that repository instructions don't need to duplicate the organization rules.

The effective instructions can come from multiple levels, including:

Organization instructions

+

Repository instructions

+

Matching path-specific instructions

+

Personal instructions

+

Current prompt

More specific instructions should be used for project- or file-specific requirements.

For example, organization-level instructions might say:

Always validate external input.

Never commit secrets.

Follow secure coding practices.

A repository can then add:

This project uses Next.js 15 and pnpm.

All API routes must use Zod validation.

Use Vitest for testing.

You don't need to copy the organization's security rules into every repository.

4. Different Copilot surfaces

Custom instructions can be relevant across different Copilot experiences, including:

• Copilot Chat

• Copilot Edits

• Agent Mode

• Copilot Code Review

• Copilot Coding Agent

For the Coding Agent, also be aware of AGENTS.md if your organization uses it.

The important part is to establish one canonical source of organizational guidance and avoid maintaining multiple conflicting copies.

5. Recommended setup

Step 1 — Create organization-wide instructions

Use the organization's .github repository or the organization-level Copilot Custom Instructions setting.

Keep these instructions focused on rules that should apply across projects.

Step 2 — Add minimal repository instructions

For example:

# Project X

This repository extends the organization's Copilot instructions.

Stack: TypeScript + Next.js
Package manager: pnpm
Testing: Vitest
All API routes must validate input with Zod.

The repository file should contain only project-specific requirements.

Step 3 — Add path-specific instructions when necessary

For example:

.github/instructions/

└── tests.instructions.md

---

applyTo: "**/*.test.ts"


Use Vitest.

Use vi.mock for mocking.

Keep tests close to the code they cover.

This keeps large instruction files manageable.

6. Avoid duplication

Don't copy the entire organization instruction file into every repository.

Instead:

Organization

↓

Common security + coding standards

Repository

↓

Project-specific architecture + tooling
Path-specific

↓

Language/framework/file-specific rules

This makes the instructions easier to maintain and reduces the chance that different repositories end up using outdated or conflicting versions of the same rules.

7. Verify that Copilot is using the instructions

In VS Code, you can check Copilot diagnostics through the Command Palette:

Chat: Diagnostic: Show Copilot Instructions

You can also ask Copilot:

@workspace What instructions are you following?

This can help confirm which instruction files are being applied.

Bottom line

For most organizations, the cleanest setup is:

Org .github

→ General rules, security, coding standards

Repo .github

→ Project-specific rules
.github/instructions/

→ Path/language/framework-specific rules

Don't duplicate organization-wide instructions into every repository. Keep the common rules centralized and let repositories add only what is specific to them.

Official documentation

Adding repository custom instructions for GitHub Copilot

Adding organization custom instructions

# GitHub Copilot: Organization-Wide vs Repository Instructions

The recommended approach is additive inheritance, not replacement.

Keep common rules at the organization level so you don't have to duplicate them across every repository. Then use repository and path-specific instructions for project-specific requirements.

1. Where to put the instructions

Scope	Location
Organization-wide	Organization .github repository or Copilot Custom Instructions in Settings
Repository-specific	repo/.github/copilot-instructions.md
Path-specific	repo/.github/instructions/*.instructions.md
Reusable prompts	repo/.github/prompts/*.prompt.md
Skills	repo/.github/skills/<skill>/SKILL.md

For organization-wide instructions, you can use the special .github repository:

org/.github/.github/copilot-instructions.md

This allows you to maintain common coding, security, and engineering guidelines centrally instead of copying them into every repository.

You can also configure organization custom instructions through:

Organization Settings → Copilot → Policies / Custom Instructions

Use one central method, rather than maintaining the same instructions in both places.

2. Recommended structure

For example:

org/.github/
└── .github/
    ├── copilot-instructions.md
    └── instructions/
        └── react.instructions.md

my-repo/
└── .github/
    ├── copilot-instructions.md
    └── instructions/
        └── go.instructions.md

Keep the organization-level file relatively small and focused on general principles such as:

• Security requirements
• Coding standards
• Dependency management
• Testing expectations
• General architecture principles

Put detailed or language/framework-specific rules in instructions/*.instructions.md.

For example:

---
applyTo: "**/*.tsx"
---

Use the project's existing React patterns.
Prefer reusable components.
Add tests for significant UI behavior.

3. How inheritance works

The important point is that repository instructions don't need to duplicate the organization rules.

The effective instructions can come from multiple levels, including:

Organization instructions
        +
Repository instructions
        +
Matching path-specific instructions
        +
Personal instructions
        +
Current prompt

More specific instructions should be used for project- or file-specific requirements.

For example, organization-level instructions might say:

Always validate external input.
Never commit secrets.
Follow secure coding practices.

A repository can then add:

This project uses Next.js 15 and pnpm.
All API routes must use Zod validation.
Use Vitest for testing.

You don't need to copy the organization's security rules into every repository.

4. Different Copilot surfaces

Custom instructions can be relevant across different Copilot experiences, including:

• Copilot Chat
• Copilot Edits
• Agent Mode
• Copilot Code Review
• Copilot Coding Agent

For the Coding Agent, also be aware of AGENTS.md if your organization uses it.

The important part is to establish one canonical source of organizational guidance and avoid maintaining multiple conflicting copies.

5. Recommended setup

Step 1 — Create organization-wide instructions

Use the organization's .github repository or the organization-level Copilot Custom Instructions setting.

Keep these instructions focused on rules that should apply across projects.

Step 2 — Add minimal repository instructions

For example:

# Project X

This repository extends the organization's Copilot instructions.

- Stack: TypeScript + Next.js
- Package manager: pnpm
- Testing: Vitest
- All API routes must validate input with Zod.

The repository file should contain only project-specific requirements.

Step 3 — Add path-specific instructions when necessary

For example:

.github/instructions/
└── tests.instructions.md

---
applyTo: "**/*.test.ts"
---

Use Vitest.
Use `vi.mock` for mocking.
Keep tests close to the code they cover.

This keeps large instruction files manageable.

6. Avoid duplication

Don't copy the entire organization instruction file into every repository.

Instead:

Organization
    ↓
Common security + coding standards

Repository
    ↓
Project-specific architecture + tooling

Path-specific
    ↓
Language/framework/file-specific rules

This makes the instructions easier to maintain and reduces the chance that different repositories end up using outdated or conflicting versions of the same rules.

7. Verify that Copilot is using the instructions

In VS Code, you can check Copilot diagnostics through the Command Palette:

Chat: Diagnostic: Show Copilot Instructions

You can also ask Copilot:

@workspace What instructions are you following?

This can help confirm which instruction files are being applied.

Bottom line

For most organizations, the cleanest setup is:

Org .github
    → General rules, security, coding standards

Repo .github
    → Project-specific rules

.github/instructions/
    → Path/language/framework-specific rules

Don't duplicate organization-wide instructions into every repository. Keep the common rules centralized and let repositories add only what is specific to them.

Official documentation

[Adding repository custom instructions for GitHub Copilot](https://docs.github.com/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot?utm_source=chatgpt.com)

[Adding organization custom instructions](https://docs.github.com/copilot/customizing-copilot/adding-organization-custom-instructions?utm_source=chatgpt.com)

HAPPY TO HELP YOU :)