GitHub Copilot Instructions: A Deep Dive
GitHub Copilot's instruction system represents a pragmatic approach to contextual AI assistance: provide global guidance for the entire repository while allowing fine-grained control for specific code paths. Unlike other formats that emphasize single-file simplicity or multi-file organization by domain, Copilot's design reflects its IDE-integrated nature and focus on code completion at scale.
Format Specification
💡 Additional Format Support (GitHub Copilot)
GitHub Copilot also supports alternative instruction file formats:
- •AGENTS.md: You can create one or more
AGENTS.mdfiles stored anywhere within the repository. When Copilot is working, the nearestAGENTS.mdfile in the directory tree will take precedence. See the openai/agents.md repository for more information. - •CLAUDE.md / GEMINI.md: Alternatively, you can use a single
CLAUDE.mdorGEMINI.mdfile stored in the root of the repository.
Note: PRPM currently supports conversion to/from .github/copilot-instructions.md and .github/instructions/*.instructions.md formats. Support for AGENTS.md, CLAUDE.md, and GEMINI.md as Copilot-compatible formats is planned for a future release. AGENTS.md is currently supported as a separate format.
Repository-Wide Instructions
Location: .github/copilot-instructions.md
Purpose: Provide global context that applies to all code in the repository
Structure: Plain markdown, no frontmatter required
# Project Guidelines This is a TypeScript monorepo using pnpm workspaces. ## Code Style - Use functional components with TypeScript - Prefer named exports over default exports - Keep functions pure when possible - Extract custom hooks for reusable logic ## Testing - Write tests using Vitest - Co-locate tests with source files - Use descriptive test names that explain behavior
Path-Specific Instructions
Location: .github/instructions/*.instructions.md
Purpose: Provide targeted guidance for specific file patterns (e.g., API routes, React components, database migrations)
Structure: Markdown with optional YAML frontmatter containing applyTo field
| Field | Type | Required | Description |
|---|---|---|---|
applyTo | string[] | No | Glob patterns specifying which files this instruction applies to |
Two-Tier Instruction System
GitHub Copilot's design reflects a key insight: not all guidance applies equally to all code. The two-tier system balances global consistency with contextual specificity.
Repository-Wide Layer
The .github/copilot-instructions.md file provides tech stack declaration, coding standards, project philosophy, and general patterns.
Path-Specific Layer
The .github/instructions/*.instructions.md files provide contextual patterns, domain rules, file-type conventions, and technology-specific guidance.
The applyTo Field:
Uses glob patterns to specify which files an instruction applies to:
PRPM's Implementation
PRPM's implementation handles both repository-wide and path-specific instructions with optional frontmatter parsing, applyTo storage, auto-tagging, and single instructions section for maximum fidelity.
Key Design Decisions
- 1.Optional Frontmatter: Repository-wide instructions don't need frontmatter (they apply everywhere)
- 2.applyTo as Array: Allows one instruction file to cover multiple patterns
- 3.Single Instructions Section: Preserves perfect fidelity (lossless conversion)
- 4.Automatic Tagging: Auto-adds "repository-wide" or "path-specific" tags
Best Practices
Repository-Wide Instructions
Provide high-level, project-wide guidance like tech stack, coding standards, and testing approach. Avoid file-type-specific patterns (those belong in path-specific instructions).
Path-Specific Instructions
Target specific file patterns with contextual guidance. Use specific patterns that match your project structure, not overly broad patterns.
Conclusion
GitHub Copilot's two-tier system (repository-wide + path-specific) balances simplicity with flexibility. PRPM's implementation focuses on fidelity, flexibility, and interoperability with seamless conversion to/from other formats.
Key Takeaways
- •Optional frontmatter reduces friction for repository-wide instructions
- •applyTo glob patterns enable precise targeting without duplication
- •Single Instructions section preserves perfect fidelity (lossless conversion)
- •Automatic tagging ensures consistent metadata across packages
- •Format conversion works seamlessly (Copilot ↔ Cursor ↔ Claude ↔ Kiro)