Copilot File Specs

AI Coding Assistant Customization File Specifications

This skill contains the authoritative specifications for all AI coding assistant customization file types. These specifications work across multiple providers.

Provider Folder Mapping

Different AI coding assistant providers use similar folder structures in their respective configuration directories:

Throughout this document, <provider>/ represents your chosen provider's base folder. Replace with the appropriate directory for your environment.

File Types Overview

Agent Files (.agent.md)

Location

• Workspace: <provider>/agents/*.agent.md or <provider>/agents/*.md
• Sub-agents: <provider>/agents/*.subagent.agent.md
• User profile: Available across workspaces

File Structure

---
name: agent-name
description: Brief description shown as placeholder in chat input
user-invokable: true
argument-hint: Optional hint for user input
tools: ['tool1', 'tool2']
agents: ['*']  # or specific agent names, or [] for none
model: Claude Sonnet 4  # or array for fallback: ['Claude Sonnet 4', 'GPT-4o']
disable-model-invocation: false
handoffs:
  - label: Button Text
    agent: target-agent
    prompt: Prompt to send
    send: false
    model: GPT-5 (copilot)
---

[Agent instructions body - Markdown content]

Frontmatter Attributes

Naming Conventions

• User-facing agents: <name>.agent.md or <name>.md
• Sub-agents (workflow components): <name>.subagent.agent.md with user-invokable: false

Handoff Configuration

handoffs:
  - label: "Display text for button"
    agent: "target-agent-name"
    prompt: "Prompt text to send to target agent"
    send: false  # true to auto-submit, false to pre-fill only
    model: "GPT-5 (copilot)"  # Optional: model for this handoff

Body Content

• Markdown formatted instructions
• Reference other files with Markdown links
• Reference tools with #tool:<tool-name> syntax
• Prepended to user chat prompt when agent is selected

Example

---
name: planner
description: Generate an implementation plan for new features
tools: ['fetch', 'githubRepo', 'search', 'usages']
model: Claude Sonnet 4
handoffs:
  - label: Implement Plan
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
---

# Planning Instructions

You are in planning mode. Generate implementation plans without making code edits.

## Plan Structure
- Overview: Brief description
- Requirements: List of requirements
- Implementation Steps: Detailed steps
- Testing: Required tests

Sub-Agent Example

---
name: due-diligence
user-invokable: false
description: Deep analysis of requirements and integration points
tools: ['search', 'fetch', 'usages']
---

# Due Diligence Analysis

You perform deep analysis on requirements before planning begins.
Identify integration points, dependencies, risks, and clarifications needed.

Skill Files (SKILL.md)

Location

• Workspace: <provider>/skills/<skill-name>/SKILL.md
• Each skill is a directory containing at minimum a SKILL.md file

Directory Structure

skill-name/
├── SKILL.md           # Required - skill definition
├── scripts/           # Optional - executable code
├── references/        # Optional - additional documentation
└── assets/            # Optional - static resources (templates, images, data)

File Structure

---
name: skill-name
description: What this skill does and when to use it.
license: Apache-2.0
compatibility: Requires specific tools or environment
metadata:
  author: org-name
  version: "1.0"
allowed-tools: Bash(git:*) Read
---

[Skill instructions body - Markdown content]

Frontmatter Attributes

Name Validation Rules

• Must be 1-64 characters
• Lowercase letters, numbers, and hyphens only (a-z, 0-9, -)
• Cannot start or end with hyphen
• Cannot contain consecutive hyphens (--)
• Must match parent directory name exactly

Body Content

• Markdown formatted instructions
• No format restrictions
• Recommended sections:
  • Step-by-step instructions
  • Examples of inputs and outputs
  • Common edge cases
• Keep under 500 lines; split longer content into reference files

Progressive Disclosure

1. Metadata (~100 tokens): name and description loaded at startup
2. Instructions (<5000 tokens recommended): Full body loaded when activated
3. Resources (as needed): Files in subdirectories loaded on demand

Example

---
name: code-review
description: Performs thorough code review focusing on security, performance, and best practices. Use when reviewing pull requests, checking code quality, or identifying potential issues.
---

# Code Review Skill

Analyzes code for quality, security, and adherence to best practices.

## Review Process

1. Check for security vulnerabilities
2. Identify performance issues
3. Verify coding standards compliance
4. Suggest improvements

## Output Format

Provide findings organized by severity: Critical, Warning, Info.

Prompt Files (.prompt.md)

Location

• Workspace: <provider>/prompts/*.prompt.md
• User profile: Available across workspaces

File Structure

---
name: prompt-name
description: What this prompt accomplishes
argument-hint: Guide for user input
agent: agent-name
model: Claude Sonnet 4
tools: ['tool1', 'tool2']
---

[Prompt template body with variables]

Frontmatter Attributes

Body Content

• Markdown formatted prompt template
• Reference workspace files with relative Markdown links
• Reference tools with #tool:<tool-name> syntax

Variables

Example

---
name: create-react-form
description: Generate a React form component with validation
agent: agent
tools: ['editFiles']
---

# Create React Form Component

Generate a React form component named ${input:formName:MyForm} with the following requirements:

- Use TypeScript
- Include form validation
- Follow project conventions in [coding standards](../instructions/react.instructions.md)

## Form Fields
${input:fields:Describe the form fields needed}

Instruction Files (.instructions.md)

Location

• Workspace: <provider>/instructions/*.instructions.md
• User profile: Available across workspaces

File Structure

---
name: Friendly Name
description: What these instructions cover
applyTo: "**/*.ts"
---

[Instruction content - Markdown]

Frontmatter Attributes

*If applyTo is not specified, instructions won't apply automatically but can be manually attached.

ApplyTo Patterns

• Single pattern: "**/*.ts"
• Multiple patterns: ["**/*.ts", "**/*.tsx"]
• Use ** to apply to all files
• Patterns are relative to workspace root
• Applied when creating/modifying files (not read operations)

Body Content

• Markdown formatted guidelines
• Reference tools with #tool:<tool-name> syntax
• Reference other files with Markdown links

Example

---
name: Python Standards
description: Coding standards for Python files
applyTo: "**/*.py"
---

# Python Coding Standards

- Follow PEP 8 style guide
- Always include type hints
- Write docstrings for all public functions
- Use 4 spaces for indentation
- Prefer f-strings over .format() or % formatting

Other Instruction Types

Global Instructions (<provider>/copilot-instructions.md)

• Single file at provider folder root
• Applies to ALL chat requests automatically
• Enable with github.copilot.chat.codeGeneration.useInstructionFiles setting (for GitHub Copilot)
• Also recognized by GitHub Copilot in Visual Studio and GitHub.com

AGENTS.md

• Place at workspace root
• Applies to all chat requests
• Useful for multi-agent workspaces
• Enable with chat.useAgentsMdFile setting
• Nested AGENTS.md files supported (experimental) with chat.useNestedAgentsMdFiles
• When nested files enabled, VS Code searches recursively in subfolders

Organization-Level Instructions

• Share instructions across multiple workspaces and repositories within a GitHub organization
• Defined at the GitHub organization level
• Enable with github.copilot.chat.organizationInstructions.enabled setting
• Automatically detected and shown alongside personal/workspace instructions

Instruction Settings for Specific Scenarios

You can configure custom instructions for specialized scenarios via VS Code settings:

| Setting | Purpose | |---------|---------|| | github.copilot.chat.reviewSelection.instructions | Code review instructions | | github.copilot.chat.commitMessageGeneration.instructions | Commit message generation | | github.copilot.chat.pullRequestDescriptionGeneration.instructions | PR title/description generation |

Format: Array of objects with text (inline) or file (reference) property:

{
  "github.copilot.chat.reviewSelection.instructions": [
    { "text": "Always check for security vulnerabilities." },
    { "file": "guidance/review-guidelines.md" }
  ]
}

Tool Reference Syntax

In any body content, reference tools using:

#tool:<tool-name>

Example: "Use #tool:githubRepo to access repository information."

File Location Summary

<provider>/                              # .github/, .claude/, .codex/, .config/opencode/, etc.
├── copilot-instructions.md             # Global instructions (single file)
├── agents/
│   ├── my-agent.agent.md               # User-facing agent
│   ├── another-agent.md                # User-facing agent (also valid)
│   └── helper.subagent.agent.md        # Sub-agent (not user-invokable)
├── skills/
│   └── my-skill/
│       ├── SKILL.md                    # Required skill definition
│       ├── scripts/                    # Optional executable code
│       ├── references/                 # Optional documentation
│       └── assets/                     # Optional static resources
├── prompts/
│   └── my-prompt.prompt.md             # Prompt template
└── instructions/
    └── python.instructions.md          # Contextual instructions

VS Code Settings Reference

Core Settings

| Setting | Purpose | |---------|---------|| | github.copilot.chat.codeGeneration.useInstructionFiles | Enable <provider>/copilot-instructions.md | | chat.instructionsFilesLocations | Additional instruction file folders | | chat.promptFilesLocations | Additional prompt file folders | | chat.agentFilesLocations | Additional agent file folders | | chat.useAgentsMdFile | Enable AGENTS.md file | | chat.useNestedAgentsMdFiles | Enable nested AGENTS.md files | | chat.useAgentSkills | Enable skills in .claude/skills/ or .github/skills/ |

Instruction Behavior Settings

| Setting | Purpose | |---------|---------|| | chat.includeApplyingInstructions | Enable instructions with applyTo patterns | | chat.includeReferencedInstructions | Enable instructions referenced via Markdown links | | github.copilot.chat.organizationInstructions.enabled | Enable organization-level instructions | | github.copilot.chat.organizationCustomAgents.enabled | Enable organization-level custom agents |

Tips for Defining Custom Instructions

• Keep instructions short and self-contained - each should be a single, simple statement
• For task or language-specific instructions, use multiple .instructions.md files with selective applyTo patterns
• Store project-specific instructions in your workspace to share with team members
• Reuse and reference instructions files in prompt files and custom agents to avoid duplication
• Instructions are applied when creating/modifying files, typically not for read operations