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:

.github/

.claude/

.codex/

.config/opencode/

Throughout this document,

<provider>/

File Types Overview

.agent.md

.md

<provider>/agents/

.subagent.agent.md

<provider>/agents/

SKILL.md

<provider>/skills/<name>/

.prompt.md

<provider>/prompts/

.instructions.md

<provider>/instructions/

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

name

description

user-invokable

false

true

argument-hint

tools

<server>/*

agents

*

[]

agent

model

disable-model-invocation

true

false

infer

user-invokable

disable-model-invocation

target

vscode

github-copilot

mcp-servers

handoffs

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

label

agent

prompt

send

true

false

model

Model Name (vendor)

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

name

description

license

compatibility

metadata

allowed-tools

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

name

/

description

argument-hint

agent

ask

edit

agent

model

tools

Body Content

• Markdown formatted prompt template
• Reference workspace files with relative Markdown links
• Reference tools with

  #tool:<tool-name>

  syntax

Variables

${workspaceFolder}

${workspaceFolderBasename}

${selection}

${selectedText}

${file}

${fileBasename}

${fileDirname}

${fileBasenameNoExtension}

${input:varName}

${input:varName:placeholder}

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

name

description

applyTo

*If

applyTo

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

github.copilot.chat.commitMessageGeneration.instructions

github.copilot.chat.pullRequestDescriptionGeneration.instructions

Format: Array of objects with

text

file

{
  "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

<provider>/copilot-instructions.md

chat.instructionsFilesLocations

chat.promptFilesLocations

chat.agentFilesLocations

chat.useAgentsMdFile

AGENTS.md

chat.useNestedAgentsMdFiles

AGENTS.md

chat.useAgentSkills

.claude/skills/

.github/skills/

Instruction Behavior Settings

| Setting | Purpose | |---------|---------|| |

chat.includeApplyingInstructions

applyTo

chat.includeReferencedInstructions

github.copilot.chat.organizationInstructions.enabled

github.copilot.chat.organizationCustomAgents.enabled

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