github / github/copilot-cli

CLI should load .github/ selectively, not bulk-load all files into context

Ouverte
#2,544 0 commentaires 3 réactions 0 personnes assignées Voir sur GitHub
area:configuration area:context-memory
Langage dominant
Shell
Étoiles
11.2k
Forks
1.9k
Merge moyen
14 h 16 min
PR mergées (30 j)
6

Description

### Problem

When `.github/` is not gitignored, Copilot CLI includes **all** files from `.github/` in the initial context payload without selective filtering — treating them as general repository content rather than structured AI guidance artifacts. VS Code Copilot handles the same directory correctly by loading content selectively (only what's relevant to the current task).

This creates an impossible choice for teams that maintain AI guidance artifacts in `.github/`:
- **Un-ignore `.github/`** → CLI context explodes, leaving almost no room for actual work
- **Keep `.github/` gitignored** → CLI works, but instructions and skills that should be available are invisible

### Root Cause

The CLI lacks selective loading logic for `.github/` content. VS Code implements staged loading (instructions scoped by glob, skills loaded on demand); the CLI does not — it includes all non-ignored files as undifferentiated context.

### Trigger (verified)

Two `.gitignore` lines that un-ignore `.github/` expose the missing feature:

```gitignore
!.github/
!.github/**
```

Adding only these two lines to a working repo's `.gitignore` reproduces the issue. Removing them resolves it. No other file changes are involved.

### Evidence

Isolated via binary search on a large monorepo. The only variable is the `.gitignore` change above — no other file differences.

**Representative magnitude** (illustrative, based on observed behavior in a real monorepo):

| Configuration | Context tokens |
|---------------|---------------|
| `.github/` gitignored (baseline) | ~60k |
| `.github/` un-ignored via `!.github/` | ~220k |
| Un-ignored, then `!.github/` lines removed | ~60k |
| Baseline + only `!.github/` lines added | ~220k |

A `.github/` directory with a few hundred files of AI guidance artifacts (instructions, skills, agents, prompts, standards, reference docs) can easily add 150k+ tokens to the CLI context. The structure follows documented conventions:

- `copilot-instructions.md` (repo-wide instructions)
- `instructions/*.instructions.md` (path-scoped, with `applyTo` globs)
- `skills/*/SKILL.md` (on-demand skill files with `references/` subdirectories)
- `agents/*.md`, `prompts/*.md`, `hooks/*.py`, `standards/*.md`

### VS Code Behavior (documented, correct)

VS Code Copilot loads `.github/` content **selectively**, per official documentation:

**Custom Instructions** ([VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/custom-instructions), [GitHub Docs](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions?tool=vscode)):
1. **Always loaded:** `copilot-instructions.md` (repo-wide)
2. **Loaded when editing matching files:** `instructions/*.instructions.md` based on `applyTo` metadata (a glob pattern specifying which file paths the instruction applies to)

**Agent Skills** ([VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/agent-skills), [Microsoft Learn](https://learn.microsoft.com/en-us/agent-framework/agents/skills), [Progressive Disclosure Pattern](https://deepwiki.com/microsoft/agent-skills/5.3-progressive-disclosure-pattern)):

Skills use a staged loading model ("progressive disclosure" — load only what's needed, when it's needed):
3. **Startup:** Only metadata (name + description from YAML header) is scanned for discovery (~50-100 tokens per skill)
4. **On match:** Full `SKILL.md` body loaded only when the skill is invoked
5. **On need:** `references/`, `scripts/` loaded only when the skill explicitly requests them

**Never bulk-loaded:** `standards/`, `hooks/`, and other supporting content

This staged loading keeps context usage proportional to the task at hand.

### CLI Behavior (current)

CLI treats un-ignored `.github/` files as general repository content and includes **all of them** in the initial context payload. There is no differentiation between:
- Instruction files that should be auto-loaded
- Skill files that should be loaded on demand
- Reference/standards docs that should only be loaded when a skill requests them

### Requested Behavior

Copilot CLI should implement the same selective loading strategy as VS Code:

1. **Auto-load** `copilot-instructions.md` (already works when visible)
2. **Scope-load** `instructions/*.instructions.md` based on `applyTo` metadata and current working context (using the same glob syntax VS Code accepts)
3. **On-demand load** `skills/*/SKILL.md` only when a skill is invoked (CLI already has skill invocation support)
4. **Exclude from bulk context** `references/`, `standards/`, `hooks/`, and other supporting files unless explicitly requested

This would allow teams to un-ignore `.github/` for git tracking without overwhelming the CLI context window.

### Workarounds Considered (all insufficient)

| Workaround | Why it fails |
|------------|-------------|
| `.copilotignore` to exclude `.github/` subdirs | Binary — hides content completely, prevents on-demand loading |
| Keep `.github/` gitignored | Instruction files in `instructions/` don't load (see #713) |
| `respectGitignore: false` | Opposite direction — would expose even more ignored files |
| Work from subdirectory | Doesn't help — `.github/` is at repo root |

### Environment

- **Copilot CLI version:** 1.0.19
- **OS:** Windows 11
- **Repo type:** Large monorepo with extensive `.github/` AI guidance artifacts

### Related Issues

- #1423 — Path-specific instructions bloat context (same root cause — CLI doesn't respect `applyTo`; our issue extends to skills, agents, prompts, and standards)
- #713 — Instructions not loaded when `.github/` is gitignored (same root tension, different symptom)
- #567 — Custom instructions truncated at startup (related context-loading issue, different symptom)
- #2084 — Related gitignore behavior; requests opt-in override for glob on ignored files

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

Commencez par suivre la collecte initiale du contexte de la CLI et le comportement existant d’invocation des skills, puis comparez la manière dont elle traite .github/copilot-instructions.md, instructions/*.instructions.md et skills/*/SKILL.md. Définissez des tests de chargement et d’exclusion pour les instructions à portée définie, les skills à la demande et les fichiers complémentaires tels que references/, standards/ et hooks/. Le travail est terminé lorsque le contenu non ignoré de .github/ n’est plus chargé en bloc, tout en laissant les instructions pertinentes disponibles.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
git, github, shell
Domaine
cli, developer-experience, tooling
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
Calme
Clarté
Plutôt claire
Accessibilité débutants
45/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.