How to Configure Instruction Files for Copilot Behavior Customization in HVE Core

HVE Core uses VS Code Copilot instruction files ending in .instructions.md located under .github/instructions/ with mandatory YAML front-matter to customize AI coding behavior, which are then compiled into plugin metadata via npm run plugin:generate to activate the rules.

The microsoft/hve-core repository implements a structured approach to configure instruction files for Copilot behavior customization in HVE Core. By leveraging specialized markdown files with strict schema validation, developers can enforce coding standards and automate AI-driven workflows. This configuration system relies on YAML front-matter and a plugin generation pipeline to integrate custom rules into the Copilot ecosystem.

Understanding the Instruction File Hierarchy

Repository-Wide Priority Rules

The foundation of Copilot customization in HVE Core starts with .github/copilot-instructions.md. This file defines the highest-priority rules that govern project-wide AI behavior. According to the source code, individual instruction files can override conflicting guidance defined in this generic file, creating a layered configuration system.

Individual Instruction Files

Specific behavioral guidelines live under the .github/instructions/ directory hierarchy. Files placed directly under .github/ are ignored for collection manifests; only those within the instructions subdirectory are discovered recursively. The file name (minus the .instructions.md suffix) becomes the UI name unless overridden by front-matter.

Creating Valid Instruction Files

Required Front-Matter Schema

Every instruction file must begin with a YAML front-matter block conforming to the Instruction Frontmatter Schema defined in scripts/linting/schemas/instruction-frontmatter.schema.json. The schema requires a non-empty description field:

{
  "required": ["description"],
  "properties": {
    "description": {"type":"string"},
    "name": {"type":"string"},
    "applyTo": {"type":"string"}
  }
}

Optional Configuration Fields

Beyond the mandatory description, the schema supports two optional fields:

• name – An explicit UI label; if omitted, the system uses the file name (e.g., pull-request).
• applyTo – A glob pattern that tells Copilot to automatically apply instructions to matching workspace files, such as **/*.cs for all C# files.

Practical Configuration Examples

Commit Message Style Guidelines

Create .github/instructions/hve-core/commit-message.instructions.md to enforce commit conventions:

--- 
description: "Enforce a consistent commit‑message format for the HVE Core project"
name: "Commit Message Style"
applyTo: "**/*.md"
---

# Commit‑Message Instructions

- The first line must be ≤ 72 characters and start with a capital letter.
- Use the imperative mood (e.g. *Add* instead of *Added*).
- Separate the subject from the body with a blank line.
- Reference related issue numbers with `#<id>` at the end of the body.

Pull Request Description Standards

Define .github/instructions/pull-request.instructions.md for PR templates:

--- 
description: "Guidelines for writing pull‑request descriptions"
applyTo: "**/*.md"
---

# Pull‑Request Instructions

- Summarize the change in 1‑2 sentences.
- Include a **What** and **Why** section.
- Add screenshots or logs when relevant.
- Tag appropriate reviewers using `@`.

Compiling Instructions with Plugin Generation

After creating or modifying instruction files, you must regenerate the plugin metadata. The npm run plugin:generate command executes scripts/plugins/Generate-Plugins.ps1 to discover files recursively under .github/instructions/ and bake the new metadata into the plugins/ directory.

Follow these steps to activate your configuration:

1. Create or modify a <topic>.instructions.md file under .github/instructions/.
2. Add YAML front-matter satisfying the JSON schema with a mandatory description.
3. Optionally set applyTo to target specific file types.
4. Commit the file to the repository.
5. Run npm run plugin:generate to refresh generated metadata.
6. Execute npm run plugin:validate to ensure schema compliance.

Without this generation step, Copilot cannot see the new instructions, regardless of file placement or front-matter validity.

Summary

• Instruction files use the .instructions.md extension and must reside under .github/instructions/.
• YAML front-matter is mandatory with a description field conforming to the schema in scripts/linting/schemas/instruction-frontmatter.schema.json.
• applyTo glob patterns enable automatic application to specific file types.
• npm run plugin:generate compiles instruction files into plugin metadata required by Copilot.
• Priority rules in .github/copilot-instructions.md can be overridden by specific instruction files for granular control.

Frequently Asked Questions

What is the required file extension for HVE Core instruction files?

Instruction files must end with .instructions.md to be recognized by the plugin generation system. Files lacking this suffix or placed outside .github/instructions/ are ignored during the discovery process executed by Generate-Plugins.ps1.

How do I apply instruction files to specific file types?

Use the applyTo field in the YAML front-matter with a glob pattern. For example, setting applyTo: "**/*.cs" automatically applies the instructions to all C# files in the workspace when Copilot generates or updates code.

What happens if I forget to run the plugin generation step?

Copilot will not recognize new or updated instruction files. The npm run plugin:generate command must execute to bake the metadata into the plugins/ directory and update the collection manifests that Copilot references for behavior customization.

Can I override repository-wide Copilot instructions?

Yes. Rules defined in individual instruction files under .github/instructions/ override conflicting guidance from the repository-wide .github/copilot-instructions.md file. This allows granular customization while maintaining baseline project standards defined in the priority rules file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}