Advanced GitHub Copilot Guide: Mastering Custom Instructions, AGENTS.md, and SKILL.md Automation

TL;DR: A quick look at the GitHub Copilot extension ecosystem. This guide explores how to build a high-performance Vibe Coding workflow using a three-tiered system: rules configuration, agent orchestration, and programmatic skill extensions.

• Layer 1: Copilot Custom Instructions — Passive rule enforcement that sets guidelines for everyday code generation.
• Layer 2: Agent System — Autonomous task planning and proximity-based context handling that gives AI active reasoning capabilities.
• Layer 3: Agent Skills System — Programmatic extensions that provide tools, resource bundles, and on-demand specialized skills.

I. Instruction Architecture & Priority Hierarchy

GitHub Copilot stacks and overrides instruction rules based on a clear priority model, depending on its operational mode (Chat mode vs. Agent mode).

1. Rule Precedence

Chat Mode (Context-Fill Model)

[User-Level VS Code Settings]     (Highest Priority - Overrides repository defaults)
          ↓
[.instructions.md]                 (Path & filetype conditional instructions)
          ↓
[copilot-instructions.md]          (Repository-wide default instructions)

Agent Mode (Agentic Dispatch Model)

[User-Level VS Code Settings]     (Highest Priority)
          ↓
[AGENTS.md]                        (Proximity-based agent instructions for task orchestration)
          ↓
[.instructions.md]                 (Conditional instructions)
          ↓
[copilot-instructions.md]          (Repository-wide default instructions)

Note: User-level settings configured under github.copilot.chat.codeGeneration.instructions in VS Code reflect personal global preferences, overriding all repository configuration files.

II. Custom Instruction Configurations

1. Global Repository Instructions: copilot-instructions.md

• Path: .github/copilot-instructions.md
• Behavior: Always-on (Auto-loaded globally). Automatically applies to all coding and chat requests across the project—no need to repeat prompts in chat windows.
• Best Use Case: Project-wide baseline information, tech stack definitions, coding style preferences, and overall architecture guidelines.

2. Path-Conditional Instructions: .instructions.md

• Path: .github/instructions/*.instructions.md
• Behavior: Context-aware (Triggered on condition). Automatically loaded when the file open in your editor matches the Glob pattern defined in the frontmatter.
• Frontmatter Schema:

---
applyTo: "**/*.html, **/*.php, **/*.js, **/*.css"
description: "Frontend development standards and style guide"
---

• Example Configuration:

# Frontend Development Standards

## CSS Rules
- Define all global color variables in :root.
- Avoid using !important unless overriding unmodifiable third-party library styles.

## PHP Template Rules
- Sanitize all dynamic HTML output using htmlspecialchars().
- Enforce snake_case naming for template files (e.g., user_profile.php).

## JavaScript Rules
- Strictly use ES6+ syntax.
- Prefer async/await for asynchronous operations; uncaught raw Promises are strictly prohibited.

3. Proximity-Based Agent Rules: AGENTS.md

• Path: Project root directory or any subdirectory (e.g., backend/AGENTS.md).
• Behavior: Proximity-based high priority. In Agent mode, Copilot reads the AGENTS.md file nearest to the active file path.
• Features & Syntax Expansion: Ideal for defining complex task decomposition steps and directory-level constraints. Supports modular inclusion via the @ syntax:

# Backend Agent Rules
You are an expert PHP/MySQL developer[cite: 1].

# Include external specific instructions
@.github/instructions/backend-dbi.instructions.md[cite: 2]
@.github/instructions/api-security-sop.instructions.md[cite: 2]

# Directory-specific rule
Always use the custom 8-character alphanumeric ID generator for new records[cite: 2].

4. Custom Project Agents: .agent.md

• Path: .github/agents/{agent-name}.agent.md
• Behavior: Explicitly invoked in the chat interface using /agent-name.
• Example (.github/agents/reviewer.agent.md):

# Code Review Agent
You are a strict code review expert focused on identifying performance bottlenecks, memory leaks, and potential security vulnerabilities.

III. Agent Skills Extension System

Native GitHub Copilot Agent mode natively supports the open Agent Skills standard (built on the agentskills.io specification).

1. Automatic Discovery & Paths

In Agent mode, Copilot automatically scans the following directories at runtime to discover available skills:

2. Standard Directory Layout

Each skill lives in its own subdirectory and must contain a SKILL.md file. It can optionally include scripts and reference materials:

.github/skills/alipay-payment-integration/
├── SKILL.md       # Required: Metadata & prompt instructions (agentskills.io compliant)
├── scripts/       # Optional: Executable scripts or helper code
├── references/    # Optional: Detailed API docs or references
└── assets/        # Optional: Code templates and static assets

3. SKILL.md Specification

Skills must include YAML Frontmatter at the top of the file:

---
name: github-issues
description: Creates and manages GitHub issues following team conventions. Use when working with issue tracking, bug reports, or feature requests.
---

When creating GitHub issues:
- Use the standard title format: [Component] Brief description.
- Add appropriate labels based on issue type.
- Include reproduction steps for bug reports.
- Link related issues and PRs.

• name Restrictions: Lowercase letters, numbers, and hyphens - only. Max 64 characters. Must match the parent folder name exactly.
• description Restrictions: Clearly state "what the skill does" and "when to invoke it." Max 1024 characters. Copilot Agent uses this description to decide when to activate the skill.

IV. Recommended Project Architecture

To balance team collaboration, context isolation, and tool compatibility, structure your repository using the following layout:

your-repo/
├── .github/
│   ├── copilot-instructions.md          # 1. Global baseline instructions (Tech stack, code style)
│   ├── instructions/                    # 2. Conditional instruction library (Isolated by filetype)
│   │   ├── frontend.instructions.md     #    (applyTo: "**/*.ts, **/*.tsx, **/*.vue")
│   │   └── database.instructions.md     #    (applyTo: "**/*.sql, **/models/*.ts")
│   ├── skills/                          # 3. Dynamic Agent Skills library
│   │   └── alipay-integration/
│   │       ├── SKILL.md
│   │       └── references/
│   └── agents/                          # 4. Custom project-level agents
│       └── reviewer.agent.md
├── AGENTS.md                            # 5. Root agent workflows and task decomposition guide
└── .vscode/
    ├── copilot-instructions.md          # Local personal preferences (Do not commit to git)
    └── extensions.json                  # Recommended workspace extensions

Core Principles

1. Single Source of Truth (SSOT): Avoid defining conflicting rules across multiple .instructions.md or copilot-instructions.md files.
2. Treat AI as a Senior Executor: Skip teaching basic theory. Supply clear, authoritative execution standards and strict constraints instead.
3. Context Isolation: Use .instructions.md (with targeted applyTo patterns) or skills/ instead of cluttering global instructions, keeping your prompt context lean and scannable.

V. Verification & Debugging

Verify that your instructions and skills are loading correctly by running through these validation steps:

1. Reset Chat Context: Close your current chat session and start a fresh chat window.
2. Verify Custom Instructions: Type /instructions in the chat box to view all currently active custom instructions loaded for your workspace.
3. Verify Agent Skills: Type /skills in the chat box to inspect all discovered skills across both project and personal directories.