# Instruction files in Copilot CLI

Give Copilot CLI standing knowledge of ticket-service with a repository-wide instruction file and a path-scoped one for src/db/.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files/copilot-cli

This page covers Copilot CLI. The same `.github/` files also serve Copilot on GitHub and in IDEs, with differences per product.

## At a glance

| | Copilot CLI |
|---|---|
| Term | Custom instructions |
| Configured in | `.github/copilot-instructions.md`, `.github/instructions/**/*.instructions.md`, `AGENTS.md`, `~/.copilot/` |
| Loads / runs | Session start; edits need a resumed or new session |
| Scope & precedence | User and repository files are merged; the docs define no general precedence order |

## Build the scenario

| Step | What you write or run | Where |
|---|---|---|
| 1 | Draft the project file with `/init` (or `copilot init`), then review and trim it | `.github/copilot-instructions.md` |
| 2 | Add the path-scoped file with an `applyTo` glob | `.github/instructions/db.instructions.md` |
| 3 | Resume with `copilot --continue`, then run `/instructions` | Terminal |

`.github/copilot-instructions.md`:

```markdown
# ticket-service
Fastify + TypeScript API on PostgreSQL (Drizzle). Package manager: pnpm.
## Commands
- `pnpm install`, `pnpm dev`, `pnpm test` (Vitest), `pnpm lint`
- `pnpm db:generate` (new migration), `pnpm db:migrate` (apply)
## Layout
- `src/routes/` HTTP handlers · `src/db/` schema and migrations
- `test/` Vitest specs · `docs/` API notes
## Conventions
- Named exports only; every route change needs a test in `test/`.
- Never hand-edit `src/db/migrations/`; generate them with `pnpm db:generate`.
```

`.github/instructions/db.instructions.md`:

```markdown
---
applyTo: "src/db/**"
---

- Change `schema.ts`, then run `pnpm db:generate`.
- Review the generated SQL before running `pnpm db:migrate`.
- Never edit or rename files in `migrations/`.
```

## Specifics

### File names and locations

| Location | Kind |
|---|---|
| `.github/copilot-instructions.md` | Repository-wide |
| `.github/instructions/**/*.instructions.md` | Path-specific |
| `AGENTS.md`, `CLAUDE.md` (also `.claude/CLAUDE.md`), `GEMINI.md` | Agent instructions |
| `.claude/rules/**/*.md` | Claude-style rules, read like `*.instructions.md` |
| `~/.copilot/copilot-instructions.md`, `~/.copilot/instructions/**/*.instructions.md` | User-level, all repositories |
| Directories in `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | Extra `AGENTS.md` and `*.instructions.md` (comma-separated) |

`COPILOT_HOME` replaces `~/.copilot` for the user-level files. The command reference describes the repository locations as "in Git root and cwd"; the how-to also lists intermediate and nested directories.

### How files load and combine

| Topic | Behavior |
|---|---|
| Combining | All applicable files are merged |
| Duplicates | Identical user-level, repository-wide and agent instructions are dropped |
| Precedence | No general order is defined; avoid conflicting instructions |
| Imports | `@relative/path` line inlines a file in `copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`; not in `GEMINI.md` or `*.instructions.md` |
| Subagents | Custom agents get repository files only if allowed (see Gotchas) |
| Changes | Not picked up by a running session |

The how-to says absolute and `~/` import paths are not loaded; the command reference says absolute paths work. Use relative paths inside the repository.

### Scoping to paths

| Item | Detail |
|---|---|
| Key | `applyTo` in frontmatter: one glob or several, comma-separated (`"**/*.ts,**/*.tsx"`) |
| Applies when | The glob matches a file Copilot CLI is working with |
| Discovery | Not found in intermediate directories |
| Organize | Subdirectories under `.github/instructions/` are allowed; file name ends in `.instructions.md` |
| Other products | `excludeAgent` (`"code-review"` or `"cloud-agent"`) limits which Copilot features read the file |

### Size and context cost

| Item | Detail |
|---|---|
| Size limit | The documentation doesn't specify one for the CLI |
| Cost | Loaded instructions occupy the context window; `/context` shows them as "Custom Instructions" |

### See what loaded

| Tool | What it does |
|---|---|
| `/instructions` | Lists discovered files; enable or disable each one |
| `copilot instruction list [--json]` | Non-interactive list for the current directory |
| `/context` | Token usage for custom instructions |
| `/env` | Loaded environment details, including instructions |
| `--no-custom-instructions` | Starts a session without loading them |

## Gotchas

- Instructions guide the model; they do not enforce. To make the migrations boundary a guarantee, add a [hook](https://ai-sw-factory.mellicci.dev/fundamentals/hooks/copilot-cli) or a `--deny-tool` rule.
- Custom-agent subagents skip repository instruction files by default; the built-in `general-purpose` subagent gets them. A custom agent needs `include-custom-instructions: true`; built-in `explore`, `task` and `code-review` agents never get them.
- `--no-custom-instructions` wins over everything, even `include-custom-instructions: true`.
- `.github/instructions/` files are not discovered in intermediate directories, and they do not expand `@` imports.
- If you already keep an `AGENTS.md`, you don't need a copy in `.github/copilot-instructions.md`; the docs treat both as valid.