copilot-file-specs

name	copilot-file-specs
description	Contains the complete specifications for AI coding assistant customization files including agents, skills, prompts, and instructions. Works with GitHub Copilot, Claude Code, Codex, OpenCode, and other providers. Use this skill when you need to reference the correct file format, required fields, supported attributes, or file locations for any customization file.

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:

Provider	Base Folder	Notes
GitHub Copilot	.github/	Most common, widely documented
Claude Code	.claude/	Anthropic's Claude in VS Code
Codex	.codex/	OpenAI Codex-based tools
OpenCode	.config/opencode/	Open-source alternatives

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

File Types Overview

Type	Extension	Location	Purpose
Agent	.agent.md or .md	<provider>/agents/	Custom AI personas with specialized behaviors
Sub-Agent	.subagent.agent.md	<provider>/agents/	Workflow component agents (not user-invokable)
Skill	SKILL.md	<provider>/skills/<name>/	Reusable capabilities (directory-based)
Prompt	.prompt.md	<provider>/prompts/	Reusable prompt templates
Instruction	.instructions.md	<provider>/instructions/	Contextual guidance for file types

---

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

Attribute	Required	Description
name	No	Agent name. If not specified, filename is used
description	Yes (recommended)	Brief description shown as placeholder text in chat input field
user-invokable	No	Set to false for sub-agents that shouldn't appear in agent picker (default: true)
argument-hint	No	Hint text shown in chat input to guide users
tools	No	List of tool/tool set names available to this agent. Use <server>/* for all MCP server tools. tools availabe: ['vscode/extensions', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/openSimpleBrowser', 'vscode/runCommand', 'vscode/askQuestions', 'vscode/vscodeAPI', 'execute/getTerminalOutput', 'execute/awaitTerminal', 'execute/killTerminal', 'execute/createAndRunTask', 'execute/runInTerminal', 'execute/runNotebookCell', 'execute/testFailure', 'read/terminalSelection', 'read/terminalLastCommand', 'read/getNotebookSummary', 'read/problems', 'read/readFile', 'agent/runSubagent', 'edit/createDirectory', 'edit/createFile', 'edit/createJupyterNotebook', 'edit/editFiles', 'edit/editNotebook', 'search/changes', 'search/codebase', 'search/fileSearch', 'search/listDirectory', 'search/searchResults', 'search/textSearch', 'search/usages', 'web/fetch', 'web/githubRepo', 'todo']
agents	No	List of agent names available as subagents. Use * for all, [] for none. Requires agent tool in tools list
model	No	AI model to use. Can be a string or array (prioritized fallback list). If not specified, uses currently selected model
disable-model-invocation	No	Set to true to prevent this agent from being invoked as a subagent by other agents (default: false)
infer	No	Deprecated. Use user-invokable and disable-model-invocation instead
target

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

Attribute	Required	Description
label	Yes	Display text shown on the handoff button
agent	Yes	Target agent identifier to switch to
prompt	No	Prompt text to send to the target agent
send	No	Auto-submit the prompt if true (default: false)
model	No	Language model for the handoff. Use format Model Name (vendor), e.g., GPT-5 (copilot)

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

Attribute	Required	Constraints
name	Yes	1-64 chars, lowercase alphanumeric + hyphens, must match directory name
description	Yes	1-1024 chars, describes function and trigger keywords
license	No	License name or reference to bundled file
compatibility	No	1-500 chars, environment requirements
metadata	No	Key-value pairs for additional info
allowed-tools	No	Space-delimited pre-approved tools (experimental)

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

Attribute	Required	Description
name	No	Prompt name used after / in chat. Defaults to filename
description	No	Short description of the prompt
argument-hint	No	Hint text for user input guidance
agent	No	Agent to use: ask, edit, agent, or custom agent name
model	No	Language model to use. Defaults to selected model
tools	No	List of available tools for this prompt

Body Content

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

Variables

Variable Type	Syntax	Examples
Workspace	${workspaceFolder}, ${workspaceFolderBasename}	Project paths
Selection	${selection}, ${selectedText}	Editor selection
File Context	${file}, ${fileBasename}, ${fileDirname}, ${fileBasenameNoExtension}	Current file info
Input	${input:varName}, ${input:varName:placeholder}	User-provided values

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

Attribute	Required	Description
name	No	Display name in UI. Defaults to filename
description	No	Short description of the instructions
applyTo	No*	Glob pattern(s) for automatic application

*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