YAML frontmatter reference

tech

prompt-engineering

github-copilot

reference

Complete YAML frontmatter field reference for all GitHub Copilot customization file types — prompt files, agent files, instruction files, and skill files — with field types, constraints, and examples.

Author

Dario Airoldi

Published

March 7, 2026

YAML frontmatter reference

Every GitHub Copilot customization file starts with an optional YAML frontmatter block delimited by ---. The fields in this block control how Copilot discovers, activates, and executes the file’s content. This reference consolidates all YAML schemas for the four markdown-based file types into a single lookup resource.

For practical guidance on writing each file type, see the corresponding how-to article. This article answers: “what fields can I put in the YAML header?”

📝 Prompt files (.prompt.md)
🤖 Agent files (.agent.md)
📚 Instruction files (.instructions.md)
📦 Skill files (SKILL.md)
🪝 Hook files (.json)
📊 Cross-type field comparison
🔧 The tools field: shared syntax
💡 Complete examples
🎯 Conclusion
📚 References

📝 Prompt files (`.prompt.md`)

Location: .github/prompts/*.prompt.md (workspace) or VS Code profile prompts/ folder (user)
Recognized by: VS Code, Visual Studio 17.10+, SDK apps

Fields

Field	Type	Required	Description
`name`	String	No	Slash command name. Defaults to filename without extension. Lowercase with hyphens recommended.
`description`	String	No (recommended)	Shown in the prompt picker when selecting commands. Keep under 100 characters.
`agent`	String	No	Sets the chat mode: `ask`, `edit`, `agent`, or a custom agent name (e.g., `"security-reviewer"`).
`model`	String	No	Preferred LLM. Examples: `claude-sonnet-4`, `gpt-4o`, `o3`, `claude-opus-4.6`. Overrides the user’s default model selection.
`tools`	Array of strings	No	Restricts available tools. Priority: prompt `tools` > agent `tools` > default. See tools field syntax.
`argument-hint`	String	No	Placeholder text shown in the chat input when the prompt is selected. Guides the user on what arguments to provide.

Minimal example

---
name: code-review
description: "Review code for security vulnerabilities and best practices"
---

Full example

---
name: react-form
description: "Generate a React form component from a list of fields"
agent: agent
model: claude-sonnet-4
tools: ['codebase', 'editor', 'filesystem']
argument-hint: "Describe the form fields and their types"
---

# Generate React Form Component

Create a React form component based on the user's field specification.

## Instructions
1. Parse the field list from the user's input
2. Generate a functional component with TypeScript
3. Include form validation using zod
4. Add accessibility attributes (ARIA)

Notes

The filename becomes the command name if name is omitted: create-tests.prompt.md → /create-tests
agent: ask makes the prompt read-only (no file edits); agent: agent enables autonomous editing
tools in the prompt overrides any tools defined in the active agent’s YAML
Variable substitution is available in the body: ${selection}, ${file}, ${input:variableName}

📖 How-to: How to structure content for Copilot prompt files

🤖 Agent files (`.agent.md`)

Location: .github/agents/*.agent.md
Recognized by: VS Code 1.106+, Copilot CLI

Core fields

Field	Type	Required	Description
`name`	String	No	Agent display name. Defaults to filename without extension.
`description`	String	No	Shown as placeholder text in chat input when the agent is active.
`argument-hint`	String	No	Hint text shown in the chat input field.
`tools`	Array of strings	No	Available tools. Controls what the agent can do. See tools field syntax.
`model`	String	No	Preferred LLM. BYOK models supported in v1.107+.
`target`	String	No	Execution target: `vscode` (local, default) or `github-copilot` (cloud/remote).
`user-invokable`	Boolean	No	Show in agent picker. Default: `true`. Set `false` for subagent-only agents.
`disable-model-invocation`	Boolean	No	Prevent auto-invocation as subagent. Default: `false`. Agent is only used when explicitly named.
`agents`	Array of strings	No	Agents available as subagents. `*` = all, `[]` = none. Requires `agent` or `runSubagent` in `tools`.

Handoff fields

Field	Type	Required	Description
`handoffs`	Array of objects	No	Workflow transitions to other agents.
`handoffs[].label`	String	Yes	Button text displayed for the handoff.
`handoffs[].agent`	String	Yes	Target agent identifier.
`handoffs[].prompt`	String	No	Message pre-filled for the target agent.
`handoffs[].send`	Boolean	No	Auto-submit the prompt. Default: `true`. Set `false` to let user review first.

Deprecated fields

Field	Replaced by	Notes
`infer`	`user-invokable` + `disable-model-invocation`	Removed — use the two separate fields instead

Minimal example

---
description: "Security review agent — analyzes code for vulnerabilities"
tools: ['codebase', 'problems', 'usages']
---

Full example

---
name: architect
description: "Plans implementation approach before coding begins"
model: o3
tools: ['codebase', 'filesystem', 'search', 'problems', 'changes']
agents:
  - implementer
  - reviewer
user-invokable: true
disable-model-invocation: false
handoffs:
  - label: "Start Implementation"
    agent: implementer
    prompt: "Implement the plan outlined above."
    send: false
  - label: "Request Review"
    agent: reviewer
    prompt: "Review the implementation for security and quality."
    send: false
---

# Architect Agent

You are a senior software architect. Your role is to analyze requirements,
research the codebase, and create detailed implementation plans.

## Rules
- NEVER edit files — you plan, you don't implement
- Always check existing patterns before proposing new ones
- Include effort estimates for each implementation step

Notes

tools: ['codebase'] restricts the agent to read-only — it literally can’t access create_file or replace_string_in_file
user-invokable: false hides from the picker but allows invocation as a subagent
The body acts as a full identity override in the system prompt (Layer 6 of the assembly)
Organization-shared agents (experimental, v1.107+): agents in .github/agents/ at org level require github.copilot.chat.customAgents.showOrganizationAndEnterpriseAgents

📖 How-to: How to structure content for Copilot agent files

📚 Instruction files (`.instructions.md`)

Location: .github/instructions/*.instructions.md (path-specific) or .github/copilot-instructions.md (repo-level)
Recognized by: VS Code, Visual Studio 17.10+, SDK apps

Fields

All frontmatter fields are optional. However, applyTo is highly recommended for path-specific instructions — without it, the instructions are not applied automatically.

Field	Type	Required	Description
`description`	String	No	Brief description shown in UI.
`name`	String	No	Display name. Defaults to filename without extension.
`applyTo`	String	No (highly recommended)	Glob pattern(s) for file matching. Comma-separated for multiple patterns.
`excludeAgent`	String	No	Exclude from specific agents: `"code-review"` or `"coding-agent"`.

applyTo pattern reference

Pattern	Matches
`*/.py`	All Python files recursively
`*/.ts,*/.tsx`	All TypeScript and TSX files
`src/*/.js`	JavaScript files under `src/` only
`*/test_.py`	Python test files anywhere
`docs/*/.md`	Markdown files under `docs/`
`**`	All files (use sparingly — consumes tokens on every request)

Minimal example

---
applyTo: "**/*.ts,**/*.tsx"
---

Full example

---
description: "TypeScript coding standards for the frontend team"
name: "TypeScript Standards"
applyTo: "**/*.ts,**/*.tsx"
excludeAgent: "code-review"
---

# TypeScript Coding Standards

## Naming Conventions
- Use PascalCase for types and interfaces
- Use camelCase for variables and functions
- Prefix interfaces with `I` only for service contracts

## Error Handling
- Always use typed error classes
- Never swallow errors with empty catch blocks
- Log errors with structured context

Notes

Instructions inject into the system prompt — they carry more weight than user prompt content
Multiple instruction files can match the same file — they compose additively (no guaranteed order)
The repo-level file .github/copilot-instructions.md has no applyTo — it applies to everything
excludeAgent: "code-review" prevents the instruction from being sent to the Copilot code review agent
excludeAgent: "coding-agent" excludes the instruction from the GitHub Copilot coding agent

📖 How-to: How to structure content for Copilot instruction files

📦 Skill files (`SKILL.md`)

Location: .github/skills/<skill-name>/SKILL.md
Recognized by: VS Code 1.107+, Copilot CLI, GitHub coding agent, SDK apps

Fields

Field	Type	Required	Constraints	Description
`name`	String	Yes	Lowercase, hyphens only, no spaces, max 64 chars	Skill identifier used for discovery and invocation.
`description`	String	Yes	Max 1,024 characters	Describes what the skill does. Copilot uses this for discovery matching — include action verbs and use cases.

These are the only two fields in the skill YAML — simplicity by design. The richness comes from the folder structure (templates, scripts, examples), not from YAML metadata.

Folder structure

.github/skills/<skill-name>/
+-- SKILL.md                    # Required: YAML frontmatter + instructions
+-- templates/                  # Optional: reusable file templates
├   +-- component.test.js
+-- examples/                   # Optional: real-world examples
├   +-- login-form-tests.js
+-- scripts/                    # Optional: automation scripts
└   +-- setup-test-env.sh
+-- checklists/                 # Optional: verification checklists
    +-- pre-deploy.md

Example

---
name: webapp-testing
description: >
  Generate test suites for React components using Jest and React Testing Library.
  Use when writing tests, debugging test failures, or setting up test infrastructure.
---

# Web Application Testing Skill

## When to use
- Writing new component tests
- Debugging test failures
- Setting up test infrastructure

## Workflow
1. Analyze the component's props, state, and side effects
2. Generate test file using [test template](./templates/component.test.js)
3. Add edge case tests for error states
4. Run tests to verify coverage

Name constraints

✅ webapp-testing → lowercase, hyphens
✅ react-scaffolding → descriptive, valid
❌ WebApp Testing → no spaces, no uppercase
❌ my_skill → no underscores

Description best practices

The description serves two purposes:

Discovery → Copilot lists it when showing available skills
Matching → Copilot uses it to decide when to load the skill

Include action verbs and use-case triggers: “Use when writing tests, debugging failures, or setting up infrastructure.”

📖 How-to: How to structure content for Copilot skills

🪝 Hook files (`.json`)

Location: .github/hooks/*.json (workspace) or ~/.claude/settings.json (user)
Recognized by: VS Code 1.110+ (GA), Copilot CLI, Claude Code

Hooks use JSON, not YAML frontmatter. Included here for completeness since they’re part of the customization stack.

Schema

{
  "hooks": {
    "<EventName>": [
      {
        "type": "command",
        "command": "<shell command>",
        "timeout": 15
      }
    ]
  }
}

Event names

Event	When it fires	Can block?
`SessionStart`	First prompt of a new session	No
`UserPromptSubmit`	User submits a prompt	No
`PreToolUse`	Before agent invokes any tool	Yes
`PostToolUse`	After tool completes	No
`PreCompact`	Before context compaction	No
`SubagentStart`	Subagent is spawned	No
`SubagentStop`	Subagent completes	No
`Stop`	Agent session ends	No

Example

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-tool.sh",
        "timeout": 15
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

📖 How-to: How to use agent hooks for lifecycle automation

📊 Cross-type field comparison

Field	Prompts	Agents	Instructions	Skills
`name`	Optional (defaults to filename)	Optional (defaults to filename)	Optional (defaults to filename)	Required (max 64 chars)
`description`	Optional (recommended)	Optional	Optional	Required (max 1,024 chars)
`tools`	✅ Overrides agent tools	✅ Defines available tools	❌ Not available	❌ Not available
`model`	✅ Routes to specific LLM	✅ Sets preferred model	❌ Not available	❌ Not available
`agent`	✅ Sets chat mode	➖ Not applicable	❌ Not available	❌ Not available
`applyTo`	➖ Not applicable	➖ Not applicable	✅ Glob matching pattern	➖ Not applicable
`handoffs`	❌ Not available	✅ Workflow transitions	❌ Not available	❌ Not available
`agents`	❌ Not available	✅ Subagent access control	❌ Not available	❌ Not available
`target`	❌ Not available	✅ `vscode` or `github-copilot`	❌ Not available	❌ Not available
`user-invokable`	➖ Not applicable	✅ Controls picker visibility	➖ Not applicable	➖ Not applicable
`argument-hint`	✅ Chat input hint	✅ Chat input hint	❌ Not available	❌ Not available
`excludeAgent`	❌ Not available	➖ Not applicable	✅ Exclude from agents	❌ Not available

🔧 The `tools` field: shared syntax

The tools field appears in both prompt and agent YAML. It uses the same syntax in both:

Built-in capabilities

Value	What it enables	Read-only?
`codebase`	Semantic search, grep, file search, file read	Yes
`editor`	Create, modify, delete files	No
`filesystem`	Directory listing, file metadata	Yes
`fetch`	Retrieve web content	Yes
`web_search`	Internet search	Yes
`search`	Workspace text search	Yes
`usages`	Code references, call hierarchies	Yes
`problems`	Compile errors, lint warnings	Yes
`changes`	Git changes and diffs	Yes
`agent` / `runSubagent`	Subagent delegation	N/A

MCP server tools

Reference tools from MCP servers using the @server-name prefix:

tools: ['codebase', '@github/*']       # All tools from GitHub MCP server
tools: ['editor', '@azure/deploy']      # Specific Azure tool only
tools: ['#search', '@company-wiki/*']   # Predefined set + custom MCP

Predefined tool sets

Set	Includes
`#edit`	`editor`, `filesystem`
`#search`	`codebase`, `search`, `usages`
`#reader`	`codebase`, `problems`, `changes`, `usages`

Common profiles

Profile	Declaration	Use case
Read-only	`['codebase', 'filesystem', 'search']`	Research, planning, review
Research + web	`['codebase', 'fetch', 'web_search']`	Documentation, best practices
Full local	`['codebase', 'editor', 'filesystem', 'search', 'usages', 'problems']`	Implementation
Orchestrator	`['agent', 'codebase']`	Multi-agent coordination
Unrestricted	`[]` or omit field	All tools enabled

Priority chain

When both a prompt and an agent define tools, the prompt’s declaration wins:

Prompt tools (highest priority)
    ↓ overrides
Agent tools
    ↓ overrides
Default tools (all available)

💡 Complete examples

Prompt file with all fields

---
name: security-audit
description: "Scan codebase for security vulnerabilities and generate report"
agent: agent
model: o3
tools: ['codebase', 'filesystem', 'search', 'problems', 'usages']
argument-hint: "Specify focus area: auth, injection, XSS, or all"
---

Agent file with handoffs

---
name: planner
description: "Analyze requirements and create implementation plan"
model: o3
tools: ['codebase', 'filesystem', 'search', 'problems']
user-invokable: true
agents: ['implementer', 'reviewer']
handoffs:
  - label: "Implement Plan"
    agent: implementer
    prompt: "Implement the plan above."
    send: false
---

Subagent-only agent

---
name: code-analyzer
description: "Analyze code structure and patterns"
tools: ['codebase', 'problems', 'usages']
user-invokable: false
disable-model-invocation: true
---

Instruction file with pattern

---
description: "React component standards"
applyTo: "**/*.tsx"
excludeAgent: "code-review"
---

Skill file

---
name: api-scaffolding
description: >
  Scaffold REST API endpoints following team conventions.
  Use when creating new routes, controllers, or service layers.
---

🎯 Conclusion

Key takeaways

Prompt files have 6 fields — name, description, agent, model, tools, argument-hint
Agent files have the richest schema — 12+ fields including handoffs, agents, visibility controls, and target
Instruction files are the simplest — just 4 optional fields with applyTo being the most critical
Skill files have exactly 2 required fields — name and description — simplicity by design
Hook files use JSON, not YAML — they’re the only non-Markdown customization type
The tools field uses the same syntax in prompts and agents, with prompt declarations overriding agent declarations

📚 References

Series how-to articles (detailed field documentation):

How to structure content for Copilot prompt files — Appendix A contains expanded field documentation
How to structure content for Copilot agent files — Core and advanced field tables
How to structure content for Copilot instruction files — applyTo patterns and scope
How to structure content for Copilot skills — Name constraints and description best practices
How to use agent hooks for lifecycle automation — Hook JSON schema and events
How to leverage tools in prompt orchestrations — Runtime tools catalog

Official documentation:

VS Code Copilot Customization Overview [📘 Official] — Authoritative source for file formats and field specifications

YAML frontmatter reference

Table of contents

📝 Prompt files (.prompt.md)

Fields

Minimal example

Full example

Notes

🤖 Agent files (.agent.md)

Core fields

Handoff fields

Deprecated fields

Minimal example

Full example

Notes

📚 Instruction files (.instructions.md)

Fields

applyTo pattern reference

Minimal example

Full example

Notes

📦 Skill files (SKILL.md)

Fields

Folder structure

Example

Name constraints

Description best practices

🪝 Hook files (.json)

Schema

Event names

Example

📊 Cross-type field comparison

🔧 The tools field: shared syntax

Built-in capabilities

MCP server tools

Predefined tool sets

Common profiles

Priority chain

💡 Complete examples

Prompt file with all fields

Agent file with handoffs

Subagent-only agent

Instruction file with pattern

Skill file

🎯 Conclusion

Key takeaways

📚 References

📝 Prompt files (`.prompt.md`)

🤖 Agent files (`.agent.md`)

📚 Instruction files (`.instructions.md`)

📦 Skill files (`SKILL.md`)

🪝 Hook files (`.json`)

🔧 The `tools` field: shared syntax