The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →For GitHub Copilot, put shared project context in .github/copilot-instructions.md, add narrowly scoped .instructions.md files under .github/instructions/ when different paths need different rules, and use verified workflow controls when a requirement must be enforced. Instructions guide an agent; they are not a security boundary by themselves.
This guide shows how to design, install, inspect, and maintain that setup across Copilot’s IDE, CLI, cloud-agent, and code-review surfaces, whose supported files and loading behavior are not identical.
As an Amazon Associate I earn from qualifying purchases.
What repository instructions do—and what they do not do
Repository instructions are Markdown guidance that gives an AI coding agent the context a new contributor would otherwise need to discover. Typical content includes the project’s architecture, directory roles, coding conventions, build and test workflow, and the checks expected before a change is submitted. For GitHub Copilot, the documented repository-wide file is .github/copilot-instructions.md at the repository root. GitHub describes it as repository-wide context, not as an executable policy engine.
That distinction matters for guardrails. A sentence such as “never modify production data” can influence a Copilot response, but it does not technically prevent a command or file edit. If a rule has to be mechanically enforced, pair the instruction with a verified checker, protected branch rule, CI job, permission boundary, or another workflow control supported by your environment. GitHub documents hooks as shell commands run at defined workflow points; they are a separate customization mechanism from prose instructions. See the Copilot customization cheat sheet for the product’s current separation of instructions, prompts, agents, skills, and hooks.
Support is surface-specific. The IDE extension, Copilot CLI, cloud agent, and code review can discover different files or apply them at different times. Confirm the current documentation for the exact surface and version you use instead of assuming that one file is read everywhere. GitHub’s overview of supported customization locations is in About customizing GitHub Copilot responses.
Choose a structure that matches the rule’s scope
| Need | Recommended location or mechanism | What to verify |
|---|---|---|
| Context that applies to the whole repository | .github/copilot-instructions.md |
Whether the Copilot surface you use reads repository instructions |
| Rules for a particular directory, language, or file class | .github/instructions/*.instructions.md with an applyTo glob |
That the glob matches only intended paths and that the selected surface supports path-specific files |
| A reusable task wording or prompt | A prompt file or another reusable prompt facility | How that product invokes and scopes prompts |
| A specialized role or repeatable capability | A custom agent or skill | Availability and loading rules in the product and version in use |
| A deterministic action at a workflow point | A documented hook, CI check, branch protection rule, or other workflow control | Its trigger, permissions, failure behavior, and audit trail |
Keep common rules in the broad file and create path-specific files only for genuine differences. This lowers maintenance cost and makes it easier to find the rule that applies. Do not create separate files merely to restate the same advice in different words.
Step 1: create the repository-wide instruction file
Place it at the documented path
- At the repository root, create the directory
.githubif it does not exist. - Create a file named
copilot-instructions.mdinside it:.github/copilot-instructions.md. - Commit the file on the branch where the team wants the guidance to apply.
Use ordinary Markdown and write for an agent that has not seen the project before. The file should explain facts that can be verified from the repository, not aspirational rules that conflict with the code.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsInclude the facts an unfamiliar agent needs
- Repository map: identify the application, library, service, test, configuration, migration, generated-code, and documentation directories, and explain which are authoritative.
- Architecture: describe the major layers, dependency direction, public interfaces, and patterns that new code must follow.
- Build and test workflow: record the commands the repository itself documents or uses in automation. If commands differ by package or platform, state the condition rather than inventing one universal command.
- Formatting and linting: name the configured tools and the files or scripts that invoke them.
- Validation expectations: say which tests, type checks, linters, generated-file checks, or documentation updates are expected for each kind of change.
- Change boundaries: identify generated files, vendored code, secrets, deployment manifests, and other areas that should not be edited directly or require a maintainer.
- Compatibility rules: record supported language, runtime, API, database, or browser versions when the repository establishes them.
These are recommendations for useful context, not a checklist GitHub requires verbatim. Inspect the target repository before writing them. A command that is not present in the repository’s scripts, Makefile, task runner, or CI configuration should not be presented as a project requirement.
Example of a useful, repository-specific shape
# Project context
- `src/` contains application code; `tests/` contains automated tests.
- Generated client files under `src/generated/` are produced by the documented generator; edit the schema, then regenerate.
# Validation
- Use the repository's documented format, lint, type-check, and test commands for the files you change.
- Report any check you could not run and why.
# Change boundaries
- Do not commit secrets or edit generated output by hand.
- Preserve the public API compatibility policy documented in `docs/compatibility.md`.
The example shows organization and specificity only. Replace every statement with the project’s actual facts; do not copy commands or directory names that are not real in your repository.
Step 2: add path-specific instructions when scope really differs
Use the documented file format
GitHub documents modular files ending in .instructions.md under .github/instructions/. A YAML frontmatter field named applyTo contains a glob that selects matching files. A matching path can receive both repository-wide guidance and the path-specific guidance. GitHub.com currently documents this path-specific support for Copilot cloud agent and code review; check the support matrix for other surfaces before relying on it. The repository-instructions details and examples are in Adding repository custom instructions for GitHub Copilot.
---
applyTo: "src/**/*.py"
---
Follow the Python conventions documented in this repository. For changes under this path, run the repository's documented Python validation command and update tests for changed behavior.
This is a format illustration, not a tested configuration for every repository. Keep the pattern narrow enough to express the intended scope. For example, a rule for Python application code should not accidentally match documentation, generated code, or a second package with different conventions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Design the rule around a real difference
- Use a language-specific file when the formatter, type checker, error-handling style, or test command genuinely differs by language.
- Use a generated-code rule when contributors must change a source schema and regenerate rather than edit output.
- Use a deployment or infrastructure rule when review, testing, or approval requirements differ from application code.
- Keep cross-cutting principles—security review, compatibility policy, and reporting of skipped checks—in the repository-wide file so they are not duplicated.
After adding a glob, inspect representative paths, including files just outside the intended directory. A broad pattern can silently give unrelated files instructions they should not receive.
Rank #3
Step 3: inspect what Copilot CLI actually loads
Copilot CLI has its own documented discovery rules for repository and user instruction locations, including nested and parent repository locations and modular *.instructions.md files. It combines applicable instruction files, but its documentation does not define a universal precedence order among them. Do not rely on an assumed “nearest file wins” or “later file wins” rule.
In a Copilot CLI session, use /instructions to view discovered instruction files and enable or disable individual files. This is the first diagnostic step when the agent appears to ignore a rule or follows contradictory advice. The CLI-specific locations and command are documented in Adding custom instructions for GitHub Copilot CLI.
- Start the CLI in the repository or workspace whose files you want to inspect.
- Run
/instructions. - Review the discovered list and confirm that the expected repository and path-specific files are present.
- Disable an instruction temporarily only when isolating a conflict, then restore the intended set.
- Make conflicting files consistent rather than depending on an undocumented ordering.
CLI discovery behavior is not a universal rule for every Copilot surface. An instruction that appears in CLI output may still require separate verification in an IDE, cloud-agent task, or code review.
Step 4: write guardrails as clear guidance, then add enforcement where needed
Make instructions actionable
Prefer a short rule with a reason and a validation action over vague language. “For changes under src/payments, preserve the documented idempotency contract and run the payment test target” gives an agent a scope, constraint, and check. “Write high-quality code” gives it none of those.
State how the agent should behave when information is missing: inspect the repository’s scripts and CI configuration, ask for clarification when two conventions conflict, and report checks it could not run. This improves transparency without pretending the instruction is a technical block.
Separate guidance from controls
| Requirement | Instruction can provide | Use a deterministic control when |
|---|---|---|
| Use the project formatter | Name the configured formatter and tell the agent to run it | Unformatted code must be rejected automatically; enforce it in CI or a verified pre-commit workflow |
| Do not commit secrets | Tell the agent where secrets must not appear and how to handle them | Credentials must be blocked; add a verified secret scanner, protected secrets, and repository permissions |
| Update generated files correctly | Explain the source-of-truth file and regeneration process | Output must match the generator; add a reproducible generation check in CI |
| Require review for risky changes | Identify sensitive directories and request the appropriate review | Approval is mandatory; configure branch protection or code-owner controls supported by the host |
| Run tests before submission | List the relevant checks and ask the agent to report results | A merge must be blocked when checks fail; make those checks required in the repository workflow |
GitHub’s customization documentation describes hooks as shell commands executed at defined workflow points, but the exact hook names, triggers, and permissions depend on the product surface. Verify those details in the version you operate before treating a hook as a control.
Step 5: account for Copilot code-review branch behavior
During Copilot code review, GitHub says repository custom instructions and skills are read from the pull request’s head branch. Consequently, a pull request that changes an instruction file can also change the guidance used to review that same proposed branch. This is important for both maintenance and trust.
- Review instruction-file changes as part of the code change, not as harmless documentation edits.
- Keep changes to review guidance visible, focused, and attributable.
- Have a human verify that a new rule does not weaken required checks or create contradictory scope.
- Do not assume the default branch’s instructions govern a review of a different head branch.
The product-specific review behavior is described in Using GitHub Copilot code review. This behavior should not be generalized to other coding-agent products.
Best Value
How to organize a maintainable instruction set
Use a precedence-neutral layering model
- Repository-wide file: stable architecture, universal validation expectations, security and compatibility principles, and reporting requirements.
- Path-specific files: only the rules that differ for a matched language, package, generated area, or operational directory.
- Task-specific mechanisms: reusable prompts, custom agents, or skills for a repeatable role or workflow.
- Workflow controls: CI, branch protection, permissions, and verified hooks for requirements that cannot depend on an agent’s compliance.
This model remains understandable even where a product does not publish a general instruction precedence order. Avoid contradictory wording such as “always edit generated files” in one file and “never edit generated files” in another. Put the exception next to the broad rule and state its scope explicitly.
Keep files concise and testable
- Use headings and bullets so an agent can locate the relevant rule.
- Give one preferred command or documented entry point where the repository has one; explain alternatives only when they are real and maintained.
- State expected outputs, such as “report the test command and result,” rather than claiming a check ran when it was not run.
- Link to an in-repository document for long architecture explanations instead of duplicating it.
- Remove obsolete rules when the build system, directory layout, or supported runtime changes.
Instruction files are part of the codebase. Review them, attribute changes, and update them in the same change that alters the convention they describe.
Troubleshooting: when an agent appears to ignore instructions
The file is not discovered
- Check the exact path and spelling: repository-wide Copilot guidance is
.github/copilot-instructions.md, while modular files end in.instructions.mdunder.github/instructions/. - Confirm the file is committed to the branch and repository the agent is using.
- For CLI, run
/instructionsand verify discovery directly. - For other surfaces, consult that surface’s current documentation; do not infer support from CLI behavior.
The path-specific rule does not apply
- Check the frontmatter delimiter and the
applyTokey. - Test the glob against the actual file path, including whether the path is relative to the repository root.
- Look for an overly narrow pattern or an unintended directory name.
- Confirm that the chosen Copilot surface documents support for path-specific instructions.
Two files give conflicting advice
- Use CLI’s
/instructionsview when debugging a CLI session. - Compare the repository-wide and matching path-specific text line by line.
- Rewrite the rules so the broad file states the default and the narrow file states a clearly scoped exception.
- Do not depend on an undocumented precedence order to resolve the conflict.
The agent follows the rule but the repository still accepts a bad change
That is expected when the requirement exists only as prose. Add or verify the corresponding CI check, branch protection requirement, permission setting, secret scanner, generator check, or other deterministic control. Then document the control’s purpose in the instruction file so the agent knows what to run and how to interpret failures.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →A practical review checklist
- Scope: Is each rule repository-wide, path-specific, task-specific, or workflow-enforced?
- Support: Does the exact Copilot surface and version support the file or mechanism?
- Discovery: Can you see the expected files in the surface’s inspection or configuration view?
- Consistency: Are there contradictory rules across files or between instructions and CI?
- Specificity: Does each important rule name the affected path, action, and validation step?
- Truthfulness: Are commands, directories, tools, and compatibility claims present in the repository’s actual configuration?
- Enforcement: Is a mechanical control present for every requirement that must block a change?
- Review safety: Are instruction changes reviewed as code, especially when Copilot code review reads them from the pull request head branch?
- Maintenance: Is obsolete guidance removed when the project changes?
What this setup can and cannot promise
A well-maintained instruction set reduces the context an agent must infer and makes expected validation easier to follow. It can explain architecture, point to the right commands, keep path-specific conventions visible, and tell the agent how to report uncertainty. It cannot, by itself, guarantee that an agent will obey a rule, prevent access to a resource, or make a pull request safe.
For those guarantees, combine clear instructions with controls whose behavior you have verified in your repository and Copilot surface. Recheck GitHub’s documentation when features change: customization support, CLI discovery, repository and path-specific files, mechanism boundaries, and cloud-agent guidance are product documentation, not permanent guarantees for every future release.
Quick Recap
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.
