Onboarding, Going Deeper

The 5 Authoring Layers

The five files you can write to shape how Copilot behaves on your project. One you already know. Four more to go.

Note
This page is different from the five layers covered in scene 7 of the onboarding module. That page answers "where does Copilot get its context?" This page answers "what files do I write to customize Copilot?" Same number, different question.
The Map

One file you wrote. Four more you can.

The onboarding module taught you Layer 1: the always-on instructions file. That single file already makes Copilot noticeably better. The next four layers let you scope, package, restrict, and enforce behavior without bloating that file.

You do not need all five on day one. Add a layer when you feel a real friction point. Each one is opt-in.

01
Always-on instructions
.github/copilot-instructions.md Loads every time, on every request.
Always
02
Path-scoped instructions
.github/instructions/*.instructions.md Loads only when you touch matching files.
Conditional
03
Skills
.github/skills/<name>/SKILL.md Loads when invoked or matched by keyword.
On match
04
Custom agents
.github/agents/<name>.agent.md Loads only when you explicitly pick one.
Opt-in
05
Hooks
hooks.json Runs deterministically at lifecycle moments.
Deterministic
LAYER 01
Always-On Instructions

The file Copilot reads on every request

A plain Markdown file at the root of your project. Whatever you write inside it becomes Copilot's permanent context. Project identity, tech stack, code standards, communication style. If a rule should apply to every file in the project, it lives here.

Loads every time
When to use: always. This is the foundation. Build this file first before reaching for any of the other four layers.
.github/copilot-instructions.md
# Project Instructions ## About Internal mortgage calculator. Built for client-facing advisors, not engineers. ## Standards - Always respond in plain English. - Spell out acronyms on first use. - Ask clarifying questions before generating code.
.github/instructions/python.instructions.md
--- applyTo: "src/**/*.py" --- # Python rules - 4-space indentation, never tabs. - Type hints on every public function. - Black formatter, line length 100. - No bare `except:`. Catch by type.
LAYER 02
Path-Scoped Instructions

Rules that only fire for specific files

Same shape as Layer 1, except it has an applyTo line at the top that names a file pattern. The rules in the file load only when Copilot touches a file matching that pattern. Python rules for Python files. SQL rules for SQL files.

Loads when files match
When to use: when a rule is true for one part of the project but not the rest. Stops you from cramming language-specific or folder-specific rules into the always-on file, where they apply too broadly.
LAYER 03
Skills

Reusable procedures, packaged once

A folder under .github/skills/ with a SKILL.md inside. The first lines describe when the skill should run. Copilot loads the rest of the file only when the description matches what you are asking for, or when you invoke the skill by name.

Loads on keyword match or invocation
When to use: when you find yourself repeating the same multi-step procedure (format meeting notes, write a release email, build a status report). Package it as a skill so Copilot does the same thing every time, the same way.
.github/skills/format-meeting-notes/SKILL.md
--- name: format-meeting-notes description: Use when the user pastes raw meeting notes and asks for a clean summary. --- # Procedure 1. Pull date and attendees from the top. 2. Group decisions made into bullets. 3. List action items with owner and date.
.github/agents/doc-reviewer.agent.md
--- description: Reviews Markdown for clarity. Suggests rewrites without changing intent. tools: read, edit --- You review Markdown documents only. Flag and propose fixes for: - Sentences over 30 words. - Acronyms used before defined. - Passive voice in headlines.
LAYER 04
Custom Agents

A specialist with a fixed job and limited tools

A Markdown file that defines a focused role. The header lists what tools the agent can use. The body is the agent's personality and instructions. You pick this agent explicitly when you want narrow, predictable help, not the full-range Copilot.

Loads only when you pick it
When to use: when you want a specialist that cannot wander. A doc reviewer that only edits Markdown. A SQL query optimizer that only reads files. The tool list is enforced, not a suggestion.
LAYER 05
Hooks

Scripts that run at fixed moments, no matter what

A small JSON file that lists scripts to run at lifecycle events. Stop fires when Copilot finishes a reply. PreToolUse fires before Copilot edits a file. The script runs every single time. The model cannot skip it, forget it, or work around it.

Runs deterministically at lifecycle moments
When to use: when a check must happen every time. Run a linter after every reply. Scan a file for sensitive content before it gets written. This is the only layer where the rule is enforced by infrastructure, not by the AI choosing to follow it.
hooks.json
{ "hooks": { "Stop": [ { "command": "npm run lint", "blocking": true } ] } } // Runs `npm run lint` after every // Copilot reply. If lint fails, the // turn does not end until it passes.
When Each Layer Loads

Five layers. Five loading rules.

The whole architecture lives in one column of this table. If you remember the loading rule, you remember when to reach for which layer.

# Layer Loads Pick this when
01 Always-on Every time, on every request. The rule applies to the whole project.
02 Path-scoped Only when you touch matching files. The rule applies to one folder or file type.
03 Skills When you (or Copilot) invoke it by description match. You repeat the same multi-step procedure often.
04 Custom agents Only when you explicitly pick one. You want a specialist that cannot wander outside its tools.
05 Hooks Deterministically at lifecycle events. The check must happen every time, no exceptions.
Get Started

Create your first instructions file in five steps

The most useful thing you can do today is build Layer 1. The other four layers can wait until you feel a real need.

  • 1
    Open VS Code and open the folder for your project. File > Open Folder.
  • 2
    Create the folder and file. In the Explorer panel, create a folder named .github at the root of your project, then create a file inside it named copilot-instructions.md.
  • 3
    Paste this starter and edit it for your project.
# Project Instructions ## About [One sentence: what this project is and who it serves.] ## Communication - Always respond in plain English. - Avoid jargon. Spell out acronyms on first use. - Ask clarifying questions before generating code. ## Stack [List the technologies you use here.] ## Standards [Two or three non-negotiable rules for this project.]
  • 4
    Reload Copilot Chat by closing the panel and opening it again with Ctrl+Shift+I. The instructions file is read on the next request.
  • 5
    Ask a question that proves the file is loaded. Try: "Following the rules in my project instructions, write a one-paragraph summary of what this project does." If Copilot writes plain English without jargon, the file is working.

Layer 1 alone covers most of what most projects need. Reach for Layers 2 through 5 only when you feel a friction point that the always-on file cannot solve.

Sources

Where this comes from

Every primitive on this page is documented by GitHub or Microsoft. The five-layer organizing concept is adapted from a public principal-engineer reference. Each source below backs a specific section.

  1. [1]
    VS Code Docs Use custom instructions in VS Code

    Backs Layers 1 and 2. Documents .github/copilot-instructions.md, the path-scoped *.instructions.md pattern, and the applyTo frontmatter glob.

    code.visualstudio.com/docs/copilot/customization/custom-instructions
  2. [2]
    VS Code Docs Use Agent Skills in VS Code

    Backs Layer 3. Documents the .github/skills/<name>/SKILL.md structure, the description-match invocation pattern, and the progressive-disclosure loading model.

    code.visualstudio.com/docs/copilot/customization/agent-skills
  3. [3]
    GitHub Blog GitHub Copilot now supports Agent Skills (changelog 2025-12-18)

    Establishes when Copilot officially gained skills support. Useful for the historical context behind Layer 3.

    github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/
  4. [4]
    GitHub Docs About custom agents

    Backs Layer 4. Documents the custom agent file format, the tool-restriction model, and how an agent is selected at invocation time.

    docs.github.com/en/copilot/concepts/agents/cloud-agent/about-custom-agents
  5. [5]
    VS Code Docs Hooks in VS Code

    Backs Layer 5. Documents the hooks.json file, lifecycle event names (Stop, PreToolUse, etc.), the deterministic-execution guarantee, and exit-code behavior.

    code.visualstudio.com/docs/copilot/customization/hooks
  6. [6]
    VS Code Docs Customize AI in Visual Studio Code (overview)

    Umbrella reference. The VS Code-side index of every customization surface this page covers.

    code.visualstudio.com/docs/copilot/customization/overview
  7. [7]
    Public gist GitHub Copilot Customization Architecture (Lawrence Hwang)

    Origin of the layered framing used on this page. The five-layer ordering and "always-on / conditional / on-match / opt-in / deterministic" loading model is adapted from this principal-engineer reference. Cited because it is the conceptual ancestor, not the technical documentation.

    gist.github.com/LawrenceHwang/6194421c3bb4208fff84452b403e191a