Halloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix NowHalloween DealsAmazon USOctober picks are moving - compare before checkoutAmazon US: current deals, useful picks and tech finds.See Picks×
FREEDOM251

Freedom251 › Blog › Copilot CLI

How to Give GitHub Copilot the Right Context for Your Repository

By Freedom251 Team · · 11 min read

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The most reliable starting point is a short, repository-wide .github/copilot-instructions.md file that explains conventions Copilot should follow everywhere. Add path-specific files in .github/instructions/ only when a directory or language needs different guidance. Then verify that the Copilot surface you use supports those files and that it actually discovered them.

GitHub describes repository custom instructions as files that give Copilot additional context about how to understand a project and build, test and validate changes. That context is useful only when its scope, activation and supported feature are clear.

As an Amazon Associate I earn from qualifying purchases.

Start by identifying the Copilot surface

“GitHub Copilot” is not one execution environment. A developer may be using Copilot Chat in VS Code, Copilot in another IDE, Copilot on GitHub.com, the cloud agent, code review, or Copilot CLI. Each surface can support a different set of instruction files.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Before writing rules, open GitHub’s support reference for custom instructions. Treat it as a compatibility checklist for the exact combination you use. The reference distinguishes GitHub.com, VS Code, Visual Studio, JetBrains, Eclipse, Xcode and Copilot CLI, and it separates features such as Copilot Chat, cloud agent and code review.

#1 Best Overall
Sale
TOZO A1 Wireless Earbuds Bluetooth 5.3 Light Weight in Ear Headphones | IPX5 Waterproof,2 Mics for AI Calls,Immersive Premium Sound Bass Headset with Charging Case,32 EQ via App Black
  • [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
  • [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
  • [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
  • [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
  • [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.
  • Record the surface and feature you want to influence, such as Copilot Chat in VS Code or Copilot CLI.
  • Check whether that feature supports repository-wide instructions, path-specific instructions, AGENTS.md, prompt files or custom agents.
  • Check whether a documented capability is in public preview. Preview behavior can change, so recheck the current page when your IDE or extension updates.

Do not assume that a file recognized by one surface is automatically read by another. A statement such as “Copilot always reads AGENTS.md” is too broad to be dependable.

Use a repository-wide file as the baseline

Where the file goes

Create this file at the repository root:

.github/copilot-instructions.md

GitHub’s IDE documentation describes this as a natural-language Markdown file. Requests made in repository context can use the guidance in it. Put only rules that are useful across the repository: project conventions, supported frameworks, important tools and the way changes are validated.

What belongs in the baseline

A useful baseline tells Copilot how the project is organized and what “done” means. For example, you can state which framework the application uses, where production code and tests live, which package manager is authoritative, the naming conventions the team follows, and the commands used to lint, test or build.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Write instructions as direct, testable guidance rather than as a long description of the project. A concise file is easier to maintain and less likely to contain contradictory directions. An illustrative structure might look like this:

# Repository guidance

- Use the existing TypeScript and React patterns in this repository.
- Keep reusable UI components in the established components directory.
- Add or update tests for behavior changes.
- Run the repository's lint and test commands before proposing a change.
- Follow the package manager and scripts already defined in package.json.

The example is a template, not a prescribed set of commands. Replace it with the conventions and validation steps that are true for your repository. Do not write a global rule for a language, directory or deployment process that exists only in one part of the codebase; scope that guidance more narrowly instead.

Keep global guidance stable

Repository-wide instructions are automatic context, so every task can encounter them. That makes them a poor place for a one-off migration, a temporary branch rule or a detailed checklist for a single ticket. Put durable policy in the global file and leave task-specific requests to a manually invoked prompt file or to the prompt you send in the current conversation.

Instructions should explain preferences and constraints, not promise an outcome. GitHub’s documentation does not publish a universal improvement percentage or guarantee that custom instructions produce better code. Their purpose is to provide additional project context.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Scope different rules with path-specific files

Directory and filename

In VS Code, path-specific instruction files live under:

Rank #2
Sale
Smart Watch for Men Women Compatible with iPhone Samsung Android Phone 1.69 inch Full Touch Screen IP68 Waterproof Bluetooh Fitness Tracker Heart Rate/Sleep Monitor (Black)
  • 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
  • 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
  • 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
  • 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
  • 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.
.github/instructions/

Each filename ends in .instructions.md. The file starts with frontmatter containing an applyTo glob that identifies the paths where it applies. For example:

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

Use the repository's TypeScript conventions for these files. Keep components consistent with the existing test and accessibility patterns.

The glob is the scope boundary. A rule intended for TypeScript and TSX should not be placed in a file that matches every file in the repository. You can create separate files for genuinely different areas, such as backend code, infrastructure definitions or documentation, as long as each file has a clear path pattern.

How the scopes combine

When a target file matches a path-specific instruction and repository-wide instructions also exist, both sets are used. This is additive context, not an automatic replacement of the global file. Keep the global file general enough that the narrower guidance can extend it without creating a conflict.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For example, a global rule can require tests for behavior changes, while a backend-specific file explains the service’s test command and error-handling convention. The backend file should not silently reverse a repository-wide requirement unless the supported Copilot feature documents how that conflict is resolved.

When not to split a file

Do not create a path-specific file merely to make the repository look organized. A second file adds another document to review whenever conventions change. Split only when the guidance truly differs by path or when a global file would become cluttered with exceptions.

Understand the available customization mechanisms

Custom instructions, prompt files and custom agents solve different problems. Choosing among them by filename alone leads to missing context or rules that activate at the wrong time.

Mechanism Scope and activation Best use Important qualification
Repository-wide custom instructions Broad repository context; applied automatically where the target feature supports the file Project conventions, frameworks, tools and validation expectations shared across the codebase Use the documented support entry for the actual IDE or feature
Path-specific instruction files Automatic guidance for files matching an applyTo glob Language-, directory- or subsystem-specific rules In VS Code, matching path-specific and repository-wide instructions are both used
AGENTS.md and related agent instruction files Directory-scoped agent guidance when the target Copilot feature supports it Instructions that should follow a directory tree or apply to a particular agent workflow Support is feature-specific; it is not a universal replacement for .github/copilot-instructions.md
Prompt files Focused templates selected manually for a request Repeatable tasks such as a review checklist or test-generation prompt They are invoked for a task rather than being general repository policy
Custom agents A distinct process or role with specialized capabilities or handoffs Workflows that need a defined role, tools or transfer between steps Use them for process differences, not as another name for ordinary repository context

Compare mechanisms on four questions: how wide the scope is, whether activation is automatic, which Copilot surface supports it, and how much maintenance it adds. GitHub’s customization cheat sheet summarizes these distinctions.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Add AGENTS.md only when the workflow supports it

Agent instruction files can be useful for directory-specific work, but their behavior depends on the feature. Consult the support matrix before adding one as a team-wide assumption.

Rank #3
New Bee Guitar Cable 10ft Electric Instrument Bass AMP Cord | 6.35mm Jack, Durable Design, Stage and Home Studio Use, Low Noise Shielded Electric Cord for Bass, Keyboard, Amp, Mixer
  • [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
  • [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
  • [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
  • [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
  • [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by

For the documented VS Code setup, the nearest AGENTS.md in the directory tree takes precedence when Copilot is working. Support for agent files outside the workspace root is off by default in that workflow. That means a file in a parent directory or another location should not be treated as automatically active.

Other surfaces may support a different set of agent files or no agent-file behavior for the feature you are using. Keep the instructions aligned with the repository-wide file where the same rules apply, and avoid placing contradictory requirements in files that can be combined.

Check support before copying a VS Code setup elsewhere

VS Code documentation describes repository-wide and path-specific files in detail, but those details should not be transferred wholesale to JetBrains, Xcode, Visual Studio, Eclipse, GitHub.com or CLI. GitHub’s support page is the authoritative place to check the current combination of surface and feature.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For example, the documentation describes a single repository-wide file in the JetBrains and Xcode sections, while support for path-specific or agent instructions varies by feature. The same filename can therefore have different practical coverage depending on where Copilot is running.

  1. Open the support matrix.
  2. Find your client: IDE, GitHub.com or CLI.
  3. Find the feature: chat, cloud agent, code review or another workflow.
  4. Confirm each instruction type you plan to use.
  5. Note any preview label and recheck after major extension or product updates.

Verify that Copilot actually picked up the files

Verification in VS Code

GitHub says the custom-instructions feature is enabled by default in VS Code. After asking Copilot for help in the repository, inspect the Chat response’s References list. The list should show .github/copilot-instructions.md when that file was included.

If the file is absent, check the basics in this order:

  • Confirm the filename and capitalization exactly match .github/copilot-instructions.md.
  • Confirm the file is at the repository root, not in a nested project directory.
  • Confirm the request is operating in the repository context you intended.
  • For a path-specific rule, check that the target file matches the applyTo glob and that the file ends in .instructions.md.
  • Check the support entry for the exact Copilot feature you used.

Reference visibility is a practical discovery check; it is not a measurement of response quality.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Verification in Copilot CLI

Copilot CLI documents the /instructions command. Run it to view the instruction files the CLI discovered and to enable or disable individual files.

Rank #4
BSIMB 15.6" Digital Family Calendar & Chore Chart, No Subscription Fees
  • Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
  • Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
  • All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
  • Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
  • Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
/instructions

Use this command when a rule appears not to apply, when you are changing repositories, or when you need to confirm which files are active for a session. The CLI documentation says applicable files are combined and does not define a general precedence order among them. Avoid conflicting directions instead of relying on an assumed ranking.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Design instructions that remain useful

Describe conventions, not every implementation detail

Copilot needs the decisions that are hard to infer from a single file: the supported framework, preferred patterns, validation commands and boundaries between parts of the system. It does not need a prose copy of the entire README or a rule for every identifier.

Prefer statements that a reviewer can verify, such as “add tests for behavior changes” or “use the existing package scripts.” Avoid vague requests such as “write clean code” unless you define what clean means in this repository.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Separate universal rules from exceptions

Put a rule in the global file only if it is valid throughout the repository. If an exception is tied to a file pattern, move it into a path-specific file with an explicit glob. This keeps automatic context smaller and reduces the chance that a frontend rule is applied to backend or infrastructure code.

Keep instructions consistent across files

When several instruction files can be discovered together, contradictory requirements create ambiguity. Use the same terminology for commands, directories and architectural boundaries. If a policy changes, update every affected file in the same change and remove obsolete wording.

Make validation explicit

State which checks should be run and what a successful change must satisfy, using the commands that already exist in the repository. If different paths use different checks, put the relevant command in the matching path-specific file. This gives Copilot a concrete completion condition without inventing a new toolchain.

A practical setup sequence

  1. Choose the target workflow. Decide whether the immediate goal is Copilot Chat in an IDE, a GitHub cloud-agent task, code review or CLI assistance.
  2. Read the support entry. Use GitHub’s support matrix to confirm the instruction types available for that workflow.
  3. Create the baseline. Add .github/copilot-instructions.md at the repository root with concise Markdown covering shared conventions, frameworks, tools and validation expectations.
  4. Scope real differences. In VS Code, add files such as .github/instructions/typescript.instructions.md only when a path needs separate guidance. Start each with frontmatter and an applyTo glob.
  5. Evaluate agent files separately. Add AGENTS.md only where the target feature supports it, and account for the documented nearest-file behavior in VS Code.
  6. Choose prompts for repeatable tasks. Put a review checklist or test-generation template in a prompt file when a user should invoke it deliberately.
  7. Use custom agents for distinct processes. Reserve them for specialized roles, capabilities or handoffs rather than ordinary coding conventions.
  8. Verify discovery. In VS Code, inspect the Chat response References list. In CLI, run /instructions and review the discovered files.
  9. Resolve ambiguity by simplifying. If two files give different directions and the feature has no documented precedence rule, rewrite them so the applicable instructions agree.

Common mistakes and how to correct them

Putting everything in the global file

Symptom: Instructions for one language or service appear in unrelated tasks. Correction: Keep repository-wide policy in .github/copilot-instructions.md and move narrow guidance to a matching path-specific file.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Assuming a filename guarantees support

Symptom: A carefully written AGENTS.md has no visible effect in a particular client. Correction: Check the matrix for the exact feature. A supported file in one surface is not proof of support in another.

Using a prompt file as permanent policy

Symptom: Developers forget to invoke the prompt, so important repository conventions are missing. Correction: Move automatic, broadly applicable rules to custom instructions; keep the prompt for a deliberate, focused task.

Relying on undocumented precedence

Symptom: Two files issue incompatible commands and the result changes between workflows. Correction: Remove the conflict. In particular, Copilot CLI documents combined applicable files but does not publish a general precedence order.

Never checking discovery

Symptom: The team debates whether a rule is active without looking at the client. Correction: Use the VS Code References list or CLI’s /instructions command, then check path, filename, glob and support.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Maintain the context as the repository changes

Treat instruction files as versioned project configuration. Review them when the framework, package manager, directory layout, test commands or validation policy changes. Remove rules that no longer describe the repository; stale context can be as confusing as missing context.

Keep each file short enough that a maintainer can audit it during an ordinary pull request. Use headings and lists for scanability, and name the paths a rule covers. When a rule is intentionally limited to a surface, document that limitation in the file or its surrounding team documentation so developers do not mistake it for universal behavior.

After changing instructions, verify discovery again in every supported workflow your team relies on. A repository can have correct files and still produce different context in an IDE, on GitHub.com and in CLI because support differs by surface and feature.

What “the right context” means

The right context is not the largest possible instruction set. It is the smallest set of accurate, discoverable and appropriately scoped rules that tells Copilot how this repository is built, tested and maintained.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  • Use .github/copilot-instructions.md for durable repository-wide guidance.
  • Use .github/instructions/*.instructions.md with applyTo patterns for genuine path-specific differences in VS Code.
  • Use AGENTS.md only where the target feature documents support and scope.
  • Use prompt files for manually invoked task templates and custom agents for distinct workflows.
  • Check the support matrix and verify discovery instead of assuming every Copilot surface behaves alike.

That structure gives each rule a clear home, makes activation understandable and leaves you with a repeatable way to diagnose missing or conflicting context.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Copilot CLIDeveloper ToolsGitHub Copilotrepository configurationVS Code

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
Outdated Drivers Are Slowing You DownFree scan - exact matches
PC Slower Than It Used to Be?Free scan - under a minute

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.